大家好我是专注于AI应用开发与API集成实战的技术博主。在构建基于大模型的智能体Agent应用时我们常常面临一个难题如何高效、低成本地管理和分析不同模型、不同智能体的API调用情况与费用消耗OpenRouter作为聚合了众多主流大模型API的平台其“活动面板”Activity Panel功能一直是开发者监控使用情况的核心工具。近期其API迎来重要升级新增了按智能体Agent维度进行查询的能力这为多智能体架构的应用提供了前所未有的精细化管理视角。本文将为你完整解析这次升级从核心概念到API实战调用再到最佳实践手把手教你如何利用新特性优化你的AI应用。1. 背景与核心概念为什么需要按智能体查询在深入代码之前我们首先要理解几个关键概念以及这次升级解决的痛点。OpenRouter是一个大模型API聚合平台。你可以将其理解为一个“模型超市”它统一了诸如GPT-4、Claude、Gemini、DeepSeek等众多模型的调用接口、计费方式和认证流程。开发者只需一个API Key就可以通过OpenRouter调用其支持的所有模型极大简化了多模型选型和集成的复杂度。活动面板Activity Panel是OpenRouter提供给用户的核心管理功能之一。在Web控制台中它可以直观地展示API调用历史、费用消耗、模型使用分布等信息。而活动面板API则允许开发者以编程方式获取这些数据从而实现自动化监控、成本分析、用量告警等高级功能。那么智能体Agent在此语境下又是什么在当前的AI应用开发范式下一个复杂的系统往往由多个分工明确的智能体协作构成。例如客服系统可能有一个“意图识别Agent”、一个“知识查询Agent”和一个“情感安抚Agent”。数据分析系统可能包含“数据提取Agent”、“分析Agent”和“报告生成Agent”。 每个智能体可能根据其任务特性调用不同的大模型比如分析Agent用Claude报告生成用GPT-4或者即使调用同一模型其提示词Prompt和上下文长度也差异巨大。升级前的痛点过去的活动面板API主要按模型Model或请求Request维度进行聚合查询。虽然能看到总消耗和每个模型的消耗但无法回答“我的‘报告生成Agent’这个月花了多少钱”、“哪个智能体的平均响应Token最长”这类业务导向的问题。开发者需要自行在应用层打标签、记录日志再进行复杂的后处理流程繁琐且容易出错。升级带来的价值本次API升级允许在查询时传入agent过滤参数。这意味着开发者可以在调用OpenRouter API时为每一次请求标记一个智能体标识符后续即可直接通过API筛选出特定智能体的所有活动记录。这实现了成本精细化归因准确将API费用分摊到具体的业务模块或智能体上。性能监控分析不同智能体的平均响应时间、Token消耗等性能指标。调试与优化快速定位某个智能体出现的异常调用或高成本问题。预算控制可以为高消耗的智能体设置独立的预算告警。接下来我们将从环境准备开始逐步演示如何使用这一新功能。2. 环境准备与版本说明本次实战主要涉及HTTP API的调用因此对环境的通用性要求较高。我们将使用Python作为示例语言因为它是在AI领域最流行的语言之一且代码清晰易懂。核心环境要求操作系统Windows 10/11, macOS, 或 Linux (如Ubuntu 20.04)均可。Python版本 3.8 或更高。本文示例在 Python 3.9 上测试通过。HTTP客户端库我们将使用requests库它是Python事实上的标准HTTP库。OpenRouter账户你需要一个已注册的OpenRouter账户并已获取API Key。新注册用户通常有一定的免费额度可供测试。文本编辑器或IDE如VS Code, PyCharm等。项目结构预览我们将创建一个简单的项目目录包含配置文件和不同的示例脚本。openrouter-agent-demo/ ├── config.py # 存放API Key等配置切勿提交至Git ├── requirements.txt # 项目依赖 ├── log_activity.py # 示例1模拟带Agent标签的API调用 └── query_activity.py # 示例2查询特定Agent的活动记录首先创建项目目录并安装依赖。# 创建项目目录并进入 mkdir openrouter-agent-demo cd openrouter-agent-demo # 创建虚拟环境推荐 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Linux/macOS: source venv/bin/activate # 创建requirements.txt文件将以下内容写入requirements.txt文件requests2.28.0 python-dotenv0.19.0 # 可选用于管理环境变量安装依赖pip install -r requirements.txt接下来创建配置文件config.py。重要此文件包含敏感信息务必将其加入.gitignore中。# config.py # OpenRouter API 配置 OPENROUTER_API_KEY your-openrouter-api-key-here # 请替换为你的真实API Key OPENROUTER_API_BASE https://openrouter.ai/api/v1 # 定义一个智能体名称映射方便管理 AGENTS { intent_classifier: 意图分类智能体, knowledge_retriever: 知识检索智能体, report_generator: 报告生成智能体, }请将your-openrouter-api-key-here替换为你从OpenRouter官网获取的API Key。你可以在OpenRouter的 API Keys 页面创建和管理密钥。3. 核心API语法与参数拆解要使用按智能体查询的功能我们需要关注两个核心的API端点完成调用接口(/chat/completions): 在发起请求时如何附加智能体标签。活动查询接口(/activity): 如何过滤和查询特定智能体的活动记录。3.1 为API调用添加智能体标签OpenRouter 允许在调用/chat/completions接口时通过请求头HTTP-Referer或X-Title或在请求体的extra_body中传递元数据。为了更规范地标识智能体推荐使用extra_body中的agent字段。请求示例结构import requests from config import OPENROUTER_API_KEY, OPENROUTER_API_BASE headers { Authorization: fBearer {OPENROUTER_API_KEY}, Content-Type: application/json, # 你也可以通过HTTP-Referer或X-Title传递应用信息但agent字段更专一 # HTTP-Referer: https://your-app.com, # X-Title: Your AI Application, } data { model: openai/gpt-3.5-turbo, # 指定模型 messages: [ {role: user, content: 请用中文介绍一下你自己。} ], # 关键在extra_body中传递agent标识符 extra_body: { agent: report_generator # 这里使用我们定义的智能体ID } } response requests.post( f{OPENROUTER_API_BASE}/chat/completions, headersheaders, jsondata ) print(response.json())参数解释extra_body: 这是一个OpenRouter特有的字段用于传递不标准或平台特定的参数。agent: 在extra_body中你可以传入一个字符串用于标识本次调用的发起者。这个值应该是你业务系统中智能体的唯一标识符如report_generator、customer_service_bot等。OpenRouter会记录这个值并允许后续通过活动API进行查询。3.2 查询活动面板API支持Agent过滤活动面板API的端点通常是/activity。升级后它支持新的查询参数来过滤结果。查询请求示例与参数import requests from config import OPENROUTER_API_KEY, OPENROUTER_API_BASE from datetime import datetime, timedelta headers { Authorization: fBearer {OPENROUTER_API_KEY}, } params { limit: 50, # 返回记录数默认可能为20 offset: 0, # 分页偏移量 # 时间范围过滤 (ISO 8601格式) from: (datetime.utcnow() - timedelta(days7)).isoformat() Z, # 7天前 to: datetime.utcnow().isoformat() Z, # 现在 # 核心新功能按智能体过滤 agent: report_generator, # 只查询该智能体的活动记录 # 其他可能的过滤参数 # model: openai/gpt-4, # 按模型过滤 # status: completed, # 按状态过滤 } response requests.get( f{OPENROUTER_API_BASE}/activity, headersheaders, paramsparams ) activity_data response.json() print(f查询到 {len(activity_data.get(data, []))} 条记录) for item in activity_data.get(data, []): print(fID: {item.get(id)}, Model: {item.get(model)}, fAgent: {item.get(agent)}, Cost: ${item.get(cost, 0):.6f}, fCreated: {item.get(created_at)})关键查询参数解析agent: (新) 传入在extra_body中设置的智能体标识符字符串即可筛选出该智能体的所有调用记录。from/to: 用于指定查询的时间范围格式为ISO 8601如2024-01-01T00:00:00Z。这对于按天、周、月统计消耗至关重要。limit/offset: 用于分页避免单次请求数据量过大。model: 可以结合agent使用进一步筛选某个智能体使用的特定模型。4. 完整实战案例构建智能体成本监控脚本现在我们将把上面的知识点整合起来构建一个实用的实战案例。这个案例包含两部分模拟多个智能体向OpenRouter发起请求打上Agent标签。编写一个查询脚本按智能体统计其调用次数、总费用和平均响应时间。4.1 创建项目结构并准备配置确保你已按照第2节完成了环境准备并正确配置了config.py文件。4.2 模拟带Agent标签的API调用创建文件log_activity.py。这个脚本将模拟三个不同的智能体意图分类、知识检索、报告生成周期性地调用API。# log_activity.py import requests import time import random from datetime import datetime from config import OPENROUTER_API_KEY, OPENROUTER_API_BASE, AGENTS def call_openrouter_with_agent(prompt, agent_id, modelopenai/gpt-3.5-turbo): 使用指定的智能体标签调用OpenRouter API :param prompt: 用户提示词 :param agent_id: 智能体标识符对应config.AGENTS中的key :param model: 要使用的模型 :return: API响应内容或None headers { Authorization: fBearer {OPENROUTER_API_KEY}, Content-Type: application/json, } data { model: model, messages: [{role: user, content: prompt}], max_tokens: 150, extra_body: { agent: agent_id # 关键标记本次调用的智能体 } } try: response requests.post( f{OPENROUTER_API_BASE}/chat/completions, headersheaders, jsondata, timeout30 ) response.raise_for_status() # 如果状态码不是200抛出HTTPError result response.json() print(f[{datetime.now().strftime(%H:%M:%S)}] {AGENTS.get(agent_id, agent_id)} 调用成功。 f 模型: {model}, 消耗Token: {result.get(usage, {}).get(total_tokens, N/A)}) return result except requests.exceptions.RequestException as e: print(f[{datetime.now().strftime(%H:%M:%S)}] {AGENTS.get(agent_id, agent_id)} 调用失败: {e}) return None def main(): 模拟不同智能体的活动 # 定义不同智能体的任务和模型偏好 tasks [ {agent: intent_classifier, model: openai/gpt-3.5-turbo, prompt: 用户说‘我想查一下我的订单’这是什么意图}, {agent: knowledge_retriever, model: google/gemini-pro, prompt: 根据知识库OpenRouter支持哪些大模型}, {agent: report_generator, model: openai/gpt-4, prompt: 总结一下今天用户的反馈生成一份简要报告。}, ] print(开始模拟智能体API调用每轮间隔10-30秒共模拟5轮...) for round_num in range(1, 6): print(f\n--- 第 {round_num} 轮模拟 ---) for task in tasks: # 为增加真实性每次调用稍作随机延迟 time.sleep(random.uniform(0.5, 2)) call_openrouter_with_agent( prompttask[prompt] f (模拟轮次: {round_num}), agent_idtask[agent], modeltask[model] ) # 每轮结束后等待一段时间 if round_num 5: wait_time random.randint(10, 30) print(f等待 {wait_time} 秒后进行下一轮...) time.sleep(wait_time) print(\n模拟调用结束。请等待几分钟让OpenRouter后台处理并同步活动数据。) if __name__ __main__: main()运行此脚本前请确保config.py中的API Key已正确设置。python log_activity.py这个脚本会模拟5轮调用每轮中三个智能体各调用一次API。你会看到控制台输出调用成功或失败的信息。运行后等待几分钟让数据同步到OpenRouter的活动日志中。4.3 查询并分析特定智能体的活动创建文件query_activity.py。这个脚本将演示如何使用新的agent过滤参数并执行一些基本的分析。# query_activity.py import requests from datetime import datetime, timedelta from config import OPENROUTER_API_KEY, OPENROUTER_API_BASE, AGENTS def query_agent_activity(agent_id, hours24): 查询指定智能体在过去若干小时内的活动记录 :param agent_id: 智能体标识符 :param hours: 查询过去多少小时的数据 :return: 活动记录列表 headers {Authorization: fBearer {OPENROUTER_API_KEY}} # 计算时间范围 to_time datetime.utcnow() from_time to_time - timedelta(hourshours) params { limit: 100, # 根据需要调整 from: from_time.isoformat() Z, to: to_time.isoformat() Z, agent: agent_id, # 核心过滤条件 } try: response requests.get( f{OPENROUTER_API_BASE}/activity, headersheaders, paramsparams, timeout15 ) response.raise_for_status() data response.json() # 不同API返回结构可能略有差异这里假设数据在‘data’字段中 activities data.get(data, []) print(f查询到智能体 {AGENTS.get(agent_id, agent_id)} 在过去{hours}小时内的活动记录 {len(activities)} 条。) return activities except requests.exceptions.RequestException as e: print(f查询智能体 {agent_id} 活动失败: {e}) return [] def analyze_activities(activities): 对活动记录进行简单分析 if not activities: print(没有活动记录可供分析。) return total_cost 0.0 total_calls len(activities) model_usage {} for act in activities: # 累计成本 cost act.get(cost) if cost is not None: total_cost cost # 统计模型使用情况 model act.get(model, unknown) model_usage[model] model_usage.get(model, 0) 1 # 可以在这里添加更多分析如平均响应时间如果API返回 # response_time act.get(response_ms, 0) print(\n 分析报告 ) print(f总调用次数: {total_calls}) print(f总成本: ${total_cost:.6f}) print(f模型使用分布:) for model, count in model_usage.items(): percentage (count / total_calls) * 100 print(f - {model}: {count} 次 ({percentage:.1f}%)) print(\n) def main(): 主函数查询并分析所有已定义智能体的活动 print(开始查询各智能体活动数据...\n) # 查询每个智能体过去24小时的活动 for agent_id in AGENTS.keys(): activities query_agent_activity(agent_id, hours24) if activities: analyze_activities(activities) else: print(f智能体 {AGENTS.get(agent_id)} 暂无活动记录或查询失败。\n) # 为避免请求过快稍作停顿 import time time.sleep(1) # 示例如何查询一个不存在的智能体应返回空 print(--- 测试查询一个不存在的智能体 ---) non_existent_activities query_agent_activity(non_existent_agent, hours1) analyze_activities(non_existent_activities) if __name__ __main__: main()运行分析脚本python query_activity.py4.4 运行结果说明运行query_activity.py后你可能会看到类似下面的输出具体数据取决于你的调用记录开始查询各智能体活动数据... 查询到智能体 意图分类智能体 在过去24小时内的活动记录 5 条。 分析报告 总调用次数: 5 总成本: $0.000175 模型使用分布: - openai/gpt-3.5-turbo: 5 次 (100.0%) 查询到智能体 知识检索智能体 在过去24小时内的活动记录 5 条。 分析报告 总调用次数: 5 总成本: $0.000375 模型使用分布: - google/gemini-pro: 5 次 (100.0%) 查询到智能体 报告生成智能体 在过去24小时内的活动记录 5 条。 分析报告 总调用次数: 5 总成本: $0.001250 模型使用分布: - openai/gpt-4: 5 次 (100.0%) --- 测试查询一个不存在的智能体 --- 查询到智能体 non_existent_agent 在过去1小时内的活动记录 0 条。 没有活动记录可供分析。从输出可以清晰看出每个智能体都被独立统计。“报告生成智能体”因为使用GPT-4成本显著高于使用GPT-3.5-Turbo的“意图分类智能体”。模型使用分布统计正确。查询不存在的智能体时返回空列表符合预期。5. 常见问题与排查思路在实际集成和使用过程中你可能会遇到一些问题。下面列出了一些常见问题及其解决方法。问题现象可能原因排查思路与解决方案API调用成功但活动面板查不到记录1. 数据同步延迟。2.extra_body中的agent字段格式错误或未正确传递。3. 查询时使用了错误的时间范围或agent参数值。1.等待几分钟OpenRouter活动数据非实时通常有短暂延迟。2.检查请求体确保extra_body是一个字典且agent字段是字符串。使用网络抓包工具如浏览器开发者工具或打印日志确认发送的JSON结构。3.核对查询参数确保查询脚本中的agent参数值与调用时传入的值完全一致区分大小写。检查from/to时间是否覆盖了调用发生的时间。查询API返回401 UnauthorizedAPI Key无效、过期或未正确设置。1. 登录OpenRouter控制台确认API Key状态是否正常。2. 检查代码中的Authorization请求头格式是否正确Bearer your-api-key。3. 确保API Key有读取活动Activity的权限。查询API返回400 Bad Request查询参数格式错误。1. 检查时间参数格式是否为ISO 8601并以Z结尾如2024-01-01T00:00:00Z。2. 检查limit和offset是否为整数。3. 确认agent参数值为字符串且不是空字符串或纯空格。agent过滤似乎不生效1. 该agent值在指定时间范围内确实没有记录。2. API版本或端点可能已更新。1. 先不使用agent参数进行查询确认总活动记录中有数据。2. 查阅OpenRouter最新的官方API文档确认/activity端点是否支持agent参数及其确切名称。3. 联系OpenRouter支持确认该功能是否已对所有用户开放。如何区分不同环境如测试/生产的同一个智能体直接使用同一个agent标识符会导致数据混合。在agent标识符中加入环境后缀例如report_generator_prod和report_generator_staging。这样可以在查询时通过前缀或完整ID进行区分和聚合。成本统计与控制台显示有细微差异统计口径或时间区间可能不同。OpenRouter控制台显示的数据可能是按账单周期或UTC日切统计的。API查询是精确到秒的。应以账单为准API数据用于实时监控和趋势分析。6. 最佳实践与工程建议将按智能体查询的能力集成到生产环境中需要考虑更多工程化细节。以下是一些最佳实践建议1. 智能体标识符命名规范唯一且有意义使用能清晰反映智能体功能和归属的命名如customer_service_intent_parser、data_analysis_summarizer。包含环境信息如前所述使用_prod、_staging、_dev后缀或在标识符前加上项目前缀如projectx_agent_y。避免动态生成不要使用每次运行都变化的标识符如时间戳这会导致无法进行历史聚合查询。应使用固定的、配置化的标识符。2. 集中化管理配置不要将agent标识符硬编码在业务逻辑中。应该像管理数据库连接池一样管理它们。# agent_registry.py class AgentRegistry: _agents { prod: { intent: prod_intent_v1, knowledge: prod_knowledge_v1, report: prod_report_v1, }, staging: { intent: staging_intent_v1, # ... } } classmethod def get_agent_id(cls, agent_name, envprod): 根据环境获取智能体ID return cls._agents.get(env, {}).get(agent_name) # 在调用处使用 agent_id AgentRegistry.get_agent_id(intent, current_env) data[extra_body] {agent: agent_id}3. 实现自动化监控与告警结合活动面板API可以搭建简单的成本监控和告警系统。# monitor_agent_cost.py import schedule import time from query_activity import query_agent_activity, analyze_activities def daily_agent_cost_report(): 每日智能体成本报告 print(f\n{*50}) print(f每日智能体成本报告 - {datetime.now().strftime(%Y-%m-%d)}) print(*50) high_cost_agents [] for agent_id, agent_name in AGENTS.items(): activities query_agent_activity(agent_id, hours24) if activities: total_cost sum(act.get(cost, 0) for act in activities) if total_cost 0.01: # 假设阈值是0.01美元 high_cost_agents.append((agent_name, total_cost)) print(f{agent_name}: ${total_cost:.6f}) else: print(f{agent_name}: 无活动) # 发送告警示例打印日志实际可集成邮件、钉钉、Slack等 if high_cost_agents: print(f\n⚠️ 高消耗告警) for name, cost in high_cost_agents: print(f - {name}: ${cost:.6f}) print(f{*50}\n) # 每天上午9点运行报告 schedule.every().day.at(09:00).do(daily_agent_cost_report) if __name__ __main__: print(启动智能体成本监控...) while True: schedule.run_pending() time.sleep(60)4. 结合使用其他过滤维度agent参数可以与其他参数组合实现更精细的查询。agentmodel查询某个智能体使用特定模型的情况。agentstatus查询某个智能体失败或成功的请求。agent 时间范围进行按小时、按天、按周的趋势分析。5. 数据持久化与分析对于重要的项目建议定期如每小时将活动数据拉取并存储到自己的数据库如MySQL、PostgreSQL或时序数据库InfluxDB中。这样可以实现更长期的数据保留OpenRouter可能只保留有限时间的数据。自定义的复杂分析和报表。与内部用户系统、项目管理系统关联实现更精准的成本分摊。6. 安全与权限API Key保管永远不要在客户端代码或公开仓库中暴露你的OpenRouter API Key。使用环境变量或安全的配置管理服务。最小权限原则如果只是用于查询活动可以考虑创建一个仅有read权限的API Key而不是使用拥有完整调用权限的Key。审计日志记录谁在什么时候执行了成本查询操作。OpenRouter活动面板API对智能体查询的支持标志着AI应用运维向更精细化、业务化方向迈出了一步。通过本文的实战演练你应该已经掌握了如何为你的AI调用打上智能体标签以及如何利用API进行高效的查询与分析。接下来你可以尝试将这套监控体系集成到你的实际项目中结合告警和数据分析构建起成本可控、性能可视的智能体应用架构。如果在实践中遇到新的问题不妨回头查阅官方文档或在开发者社区交流分享你的经验。 OpenRouter API升级：按智能体维度查询实现AI应用成本精细化管理
大家好我是专注于AI应用开发与API集成实战的技术博主。在构建基于大模型的智能体Agent应用时我们常常面临一个难题如何高效、低成本地管理和分析不同模型、不同智能体的API调用情况与费用消耗OpenRouter作为聚合了众多主流大模型API的平台其“活动面板”Activity Panel功能一直是开发者监控使用情况的核心工具。近期其API迎来重要升级新增了按智能体Agent维度进行查询的能力这为多智能体架构的应用提供了前所未有的精细化管理视角。本文将为你完整解析这次升级从核心概念到API实战调用再到最佳实践手把手教你如何利用新特性优化你的AI应用。1. 背景与核心概念为什么需要按智能体查询在深入代码之前我们首先要理解几个关键概念以及这次升级解决的痛点。OpenRouter是一个大模型API聚合平台。你可以将其理解为一个“模型超市”它统一了诸如GPT-4、Claude、Gemini、DeepSeek等众多模型的调用接口、计费方式和认证流程。开发者只需一个API Key就可以通过OpenRouter调用其支持的所有模型极大简化了多模型选型和集成的复杂度。活动面板Activity Panel是OpenRouter提供给用户的核心管理功能之一。在Web控制台中它可以直观地展示API调用历史、费用消耗、模型使用分布等信息。而活动面板API则允许开发者以编程方式获取这些数据从而实现自动化监控、成本分析、用量告警等高级功能。那么智能体Agent在此语境下又是什么在当前的AI应用开发范式下一个复杂的系统往往由多个分工明确的智能体协作构成。例如客服系统可能有一个“意图识别Agent”、一个“知识查询Agent”和一个“情感安抚Agent”。数据分析系统可能包含“数据提取Agent”、“分析Agent”和“报告生成Agent”。 每个智能体可能根据其任务特性调用不同的大模型比如分析Agent用Claude报告生成用GPT-4或者即使调用同一模型其提示词Prompt和上下文长度也差异巨大。升级前的痛点过去的活动面板API主要按模型Model或请求Request维度进行聚合查询。虽然能看到总消耗和每个模型的消耗但无法回答“我的‘报告生成Agent’这个月花了多少钱”、“哪个智能体的平均响应Token最长”这类业务导向的问题。开发者需要自行在应用层打标签、记录日志再进行复杂的后处理流程繁琐且容易出错。升级带来的价值本次API升级允许在查询时传入agent过滤参数。这意味着开发者可以在调用OpenRouter API时为每一次请求标记一个智能体标识符后续即可直接通过API筛选出特定智能体的所有活动记录。这实现了成本精细化归因准确将API费用分摊到具体的业务模块或智能体上。性能监控分析不同智能体的平均响应时间、Token消耗等性能指标。调试与优化快速定位某个智能体出现的异常调用或高成本问题。预算控制可以为高消耗的智能体设置独立的预算告警。接下来我们将从环境准备开始逐步演示如何使用这一新功能。2. 环境准备与版本说明本次实战主要涉及HTTP API的调用因此对环境的通用性要求较高。我们将使用Python作为示例语言因为它是在AI领域最流行的语言之一且代码清晰易懂。核心环境要求操作系统Windows 10/11, macOS, 或 Linux (如Ubuntu 20.04)均可。Python版本 3.8 或更高。本文示例在 Python 3.9 上测试通过。HTTP客户端库我们将使用requests库它是Python事实上的标准HTTP库。OpenRouter账户你需要一个已注册的OpenRouter账户并已获取API Key。新注册用户通常有一定的免费额度可供测试。文本编辑器或IDE如VS Code, PyCharm等。项目结构预览我们将创建一个简单的项目目录包含配置文件和不同的示例脚本。openrouter-agent-demo/ ├── config.py # 存放API Key等配置切勿提交至Git ├── requirements.txt # 项目依赖 ├── log_activity.py # 示例1模拟带Agent标签的API调用 └── query_activity.py # 示例2查询特定Agent的活动记录首先创建项目目录并安装依赖。# 创建项目目录并进入 mkdir openrouter-agent-demo cd openrouter-agent-demo # 创建虚拟环境推荐 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Linux/macOS: source venv/bin/activate # 创建requirements.txt文件将以下内容写入requirements.txt文件requests2.28.0 python-dotenv0.19.0 # 可选用于管理环境变量安装依赖pip install -r requirements.txt接下来创建配置文件config.py。重要此文件包含敏感信息务必将其加入.gitignore中。# config.py # OpenRouter API 配置 OPENROUTER_API_KEY your-openrouter-api-key-here # 请替换为你的真实API Key OPENROUTER_API_BASE https://openrouter.ai/api/v1 # 定义一个智能体名称映射方便管理 AGENTS { intent_classifier: 意图分类智能体, knowledge_retriever: 知识检索智能体, report_generator: 报告生成智能体, }请将your-openrouter-api-key-here替换为你从OpenRouter官网获取的API Key。你可以在OpenRouter的 API Keys 页面创建和管理密钥。3. 核心API语法与参数拆解要使用按智能体查询的功能我们需要关注两个核心的API端点完成调用接口(/chat/completions): 在发起请求时如何附加智能体标签。活动查询接口(/activity): 如何过滤和查询特定智能体的活动记录。3.1 为API调用添加智能体标签OpenRouter 允许在调用/chat/completions接口时通过请求头HTTP-Referer或X-Title或在请求体的extra_body中传递元数据。为了更规范地标识智能体推荐使用extra_body中的agent字段。请求示例结构import requests from config import OPENROUTER_API_KEY, OPENROUTER_API_BASE headers { Authorization: fBearer {OPENROUTER_API_KEY}, Content-Type: application/json, # 你也可以通过HTTP-Referer或X-Title传递应用信息但agent字段更专一 # HTTP-Referer: https://your-app.com, # X-Title: Your AI Application, } data { model: openai/gpt-3.5-turbo, # 指定模型 messages: [ {role: user, content: 请用中文介绍一下你自己。} ], # 关键在extra_body中传递agent标识符 extra_body: { agent: report_generator # 这里使用我们定义的智能体ID } } response requests.post( f{OPENROUTER_API_BASE}/chat/completions, headersheaders, jsondata ) print(response.json())参数解释extra_body: 这是一个OpenRouter特有的字段用于传递不标准或平台特定的参数。agent: 在extra_body中你可以传入一个字符串用于标识本次调用的发起者。这个值应该是你业务系统中智能体的唯一标识符如report_generator、customer_service_bot等。OpenRouter会记录这个值并允许后续通过活动API进行查询。3.2 查询活动面板API支持Agent过滤活动面板API的端点通常是/activity。升级后它支持新的查询参数来过滤结果。查询请求示例与参数import requests from config import OPENROUTER_API_KEY, OPENROUTER_API_BASE from datetime import datetime, timedelta headers { Authorization: fBearer {OPENROUTER_API_KEY}, } params { limit: 50, # 返回记录数默认可能为20 offset: 0, # 分页偏移量 # 时间范围过滤 (ISO 8601格式) from: (datetime.utcnow() - timedelta(days7)).isoformat() Z, # 7天前 to: datetime.utcnow().isoformat() Z, # 现在 # 核心新功能按智能体过滤 agent: report_generator, # 只查询该智能体的活动记录 # 其他可能的过滤参数 # model: openai/gpt-4, # 按模型过滤 # status: completed, # 按状态过滤 } response requests.get( f{OPENROUTER_API_BASE}/activity, headersheaders, paramsparams ) activity_data response.json() print(f查询到 {len(activity_data.get(data, []))} 条记录) for item in activity_data.get(data, []): print(fID: {item.get(id)}, Model: {item.get(model)}, fAgent: {item.get(agent)}, Cost: ${item.get(cost, 0):.6f}, fCreated: {item.get(created_at)})关键查询参数解析agent: (新) 传入在extra_body中设置的智能体标识符字符串即可筛选出该智能体的所有调用记录。from/to: 用于指定查询的时间范围格式为ISO 8601如2024-01-01T00:00:00Z。这对于按天、周、月统计消耗至关重要。limit/offset: 用于分页避免单次请求数据量过大。model: 可以结合agent使用进一步筛选某个智能体使用的特定模型。4. 完整实战案例构建智能体成本监控脚本现在我们将把上面的知识点整合起来构建一个实用的实战案例。这个案例包含两部分模拟多个智能体向OpenRouter发起请求打上Agent标签。编写一个查询脚本按智能体统计其调用次数、总费用和平均响应时间。4.1 创建项目结构并准备配置确保你已按照第2节完成了环境准备并正确配置了config.py文件。4.2 模拟带Agent标签的API调用创建文件log_activity.py。这个脚本将模拟三个不同的智能体意图分类、知识检索、报告生成周期性地调用API。# log_activity.py import requests import time import random from datetime import datetime from config import OPENROUTER_API_KEY, OPENROUTER_API_BASE, AGENTS def call_openrouter_with_agent(prompt, agent_id, modelopenai/gpt-3.5-turbo): 使用指定的智能体标签调用OpenRouter API :param prompt: 用户提示词 :param agent_id: 智能体标识符对应config.AGENTS中的key :param model: 要使用的模型 :return: API响应内容或None headers { Authorization: fBearer {OPENROUTER_API_KEY}, Content-Type: application/json, } data { model: model, messages: [{role: user, content: prompt}], max_tokens: 150, extra_body: { agent: agent_id # 关键标记本次调用的智能体 } } try: response requests.post( f{OPENROUTER_API_BASE}/chat/completions, headersheaders, jsondata, timeout30 ) response.raise_for_status() # 如果状态码不是200抛出HTTPError result response.json() print(f[{datetime.now().strftime(%H:%M:%S)}] {AGENTS.get(agent_id, agent_id)} 调用成功。 f 模型: {model}, 消耗Token: {result.get(usage, {}).get(total_tokens, N/A)}) return result except requests.exceptions.RequestException as e: print(f[{datetime.now().strftime(%H:%M:%S)}] {AGENTS.get(agent_id, agent_id)} 调用失败: {e}) return None def main(): 模拟不同智能体的活动 # 定义不同智能体的任务和模型偏好 tasks [ {agent: intent_classifier, model: openai/gpt-3.5-turbo, prompt: 用户说‘我想查一下我的订单’这是什么意图}, {agent: knowledge_retriever, model: google/gemini-pro, prompt: 根据知识库OpenRouter支持哪些大模型}, {agent: report_generator, model: openai/gpt-4, prompt: 总结一下今天用户的反馈生成一份简要报告。}, ] print(开始模拟智能体API调用每轮间隔10-30秒共模拟5轮...) for round_num in range(1, 6): print(f\n--- 第 {round_num} 轮模拟 ---) for task in tasks: # 为增加真实性每次调用稍作随机延迟 time.sleep(random.uniform(0.5, 2)) call_openrouter_with_agent( prompttask[prompt] f (模拟轮次: {round_num}), agent_idtask[agent], modeltask[model] ) # 每轮结束后等待一段时间 if round_num 5: wait_time random.randint(10, 30) print(f等待 {wait_time} 秒后进行下一轮...) time.sleep(wait_time) print(\n模拟调用结束。请等待几分钟让OpenRouter后台处理并同步活动数据。) if __name__ __main__: main()运行此脚本前请确保config.py中的API Key已正确设置。python log_activity.py这个脚本会模拟5轮调用每轮中三个智能体各调用一次API。你会看到控制台输出调用成功或失败的信息。运行后等待几分钟让数据同步到OpenRouter的活动日志中。4.3 查询并分析特定智能体的活动创建文件query_activity.py。这个脚本将演示如何使用新的agent过滤参数并执行一些基本的分析。# query_activity.py import requests from datetime import datetime, timedelta from config import OPENROUTER_API_KEY, OPENROUTER_API_BASE, AGENTS def query_agent_activity(agent_id, hours24): 查询指定智能体在过去若干小时内的活动记录 :param agent_id: 智能体标识符 :param hours: 查询过去多少小时的数据 :return: 活动记录列表 headers {Authorization: fBearer {OPENROUTER_API_KEY}} # 计算时间范围 to_time datetime.utcnow() from_time to_time - timedelta(hourshours) params { limit: 100, # 根据需要调整 from: from_time.isoformat() Z, to: to_time.isoformat() Z, agent: agent_id, # 核心过滤条件 } try: response requests.get( f{OPENROUTER_API_BASE}/activity, headersheaders, paramsparams, timeout15 ) response.raise_for_status() data response.json() # 不同API返回结构可能略有差异这里假设数据在‘data’字段中 activities data.get(data, []) print(f查询到智能体 {AGENTS.get(agent_id, agent_id)} 在过去{hours}小时内的活动记录 {len(activities)} 条。) return activities except requests.exceptions.RequestException as e: print(f查询智能体 {agent_id} 活动失败: {e}) return [] def analyze_activities(activities): 对活动记录进行简单分析 if not activities: print(没有活动记录可供分析。) return total_cost 0.0 total_calls len(activities) model_usage {} for act in activities: # 累计成本 cost act.get(cost) if cost is not None: total_cost cost # 统计模型使用情况 model act.get(model, unknown) model_usage[model] model_usage.get(model, 0) 1 # 可以在这里添加更多分析如平均响应时间如果API返回 # response_time act.get(response_ms, 0) print(\n 分析报告 ) print(f总调用次数: {total_calls}) print(f总成本: ${total_cost:.6f}) print(f模型使用分布:) for model, count in model_usage.items(): percentage (count / total_calls) * 100 print(f - {model}: {count} 次 ({percentage:.1f}%)) print(\n) def main(): 主函数查询并分析所有已定义智能体的活动 print(开始查询各智能体活动数据...\n) # 查询每个智能体过去24小时的活动 for agent_id in AGENTS.keys(): activities query_agent_activity(agent_id, hours24) if activities: analyze_activities(activities) else: print(f智能体 {AGENTS.get(agent_id)} 暂无活动记录或查询失败。\n) # 为避免请求过快稍作停顿 import time time.sleep(1) # 示例如何查询一个不存在的智能体应返回空 print(--- 测试查询一个不存在的智能体 ---) non_existent_activities query_agent_activity(non_existent_agent, hours1) analyze_activities(non_existent_activities) if __name__ __main__: main()运行分析脚本python query_activity.py4.4 运行结果说明运行query_activity.py后你可能会看到类似下面的输出具体数据取决于你的调用记录开始查询各智能体活动数据... 查询到智能体 意图分类智能体 在过去24小时内的活动记录 5 条。 分析报告 总调用次数: 5 总成本: $0.000175 模型使用分布: - openai/gpt-3.5-turbo: 5 次 (100.0%) 查询到智能体 知识检索智能体 在过去24小时内的活动记录 5 条。 分析报告 总调用次数: 5 总成本: $0.000375 模型使用分布: - google/gemini-pro: 5 次 (100.0%) 查询到智能体 报告生成智能体 在过去24小时内的活动记录 5 条。 分析报告 总调用次数: 5 总成本: $0.001250 模型使用分布: - openai/gpt-4: 5 次 (100.0%) --- 测试查询一个不存在的智能体 --- 查询到智能体 non_existent_agent 在过去1小时内的活动记录 0 条。 没有活动记录可供分析。从输出可以清晰看出每个智能体都被独立统计。“报告生成智能体”因为使用GPT-4成本显著高于使用GPT-3.5-Turbo的“意图分类智能体”。模型使用分布统计正确。查询不存在的智能体时返回空列表符合预期。5. 常见问题与排查思路在实际集成和使用过程中你可能会遇到一些问题。下面列出了一些常见问题及其解决方法。问题现象可能原因排查思路与解决方案API调用成功但活动面板查不到记录1. 数据同步延迟。2.extra_body中的agent字段格式错误或未正确传递。3. 查询时使用了错误的时间范围或agent参数值。1.等待几分钟OpenRouter活动数据非实时通常有短暂延迟。2.检查请求体确保extra_body是一个字典且agent字段是字符串。使用网络抓包工具如浏览器开发者工具或打印日志确认发送的JSON结构。3.核对查询参数确保查询脚本中的agent参数值与调用时传入的值完全一致区分大小写。检查from/to时间是否覆盖了调用发生的时间。查询API返回401 UnauthorizedAPI Key无效、过期或未正确设置。1. 登录OpenRouter控制台确认API Key状态是否正常。2. 检查代码中的Authorization请求头格式是否正确Bearer your-api-key。3. 确保API Key有读取活动Activity的权限。查询API返回400 Bad Request查询参数格式错误。1. 检查时间参数格式是否为ISO 8601并以Z结尾如2024-01-01T00:00:00Z。2. 检查limit和offset是否为整数。3. 确认agent参数值为字符串且不是空字符串或纯空格。agent过滤似乎不生效1. 该agent值在指定时间范围内确实没有记录。2. API版本或端点可能已更新。1. 先不使用agent参数进行查询确认总活动记录中有数据。2. 查阅OpenRouter最新的官方API文档确认/activity端点是否支持agent参数及其确切名称。3. 联系OpenRouter支持确认该功能是否已对所有用户开放。如何区分不同环境如测试/生产的同一个智能体直接使用同一个agent标识符会导致数据混合。在agent标识符中加入环境后缀例如report_generator_prod和report_generator_staging。这样可以在查询时通过前缀或完整ID进行区分和聚合。成本统计与控制台显示有细微差异统计口径或时间区间可能不同。OpenRouter控制台显示的数据可能是按账单周期或UTC日切统计的。API查询是精确到秒的。应以账单为准API数据用于实时监控和趋势分析。6. 最佳实践与工程建议将按智能体查询的能力集成到生产环境中需要考虑更多工程化细节。以下是一些最佳实践建议1. 智能体标识符命名规范唯一且有意义使用能清晰反映智能体功能和归属的命名如customer_service_intent_parser、data_analysis_summarizer。包含环境信息如前所述使用_prod、_staging、_dev后缀或在标识符前加上项目前缀如projectx_agent_y。避免动态生成不要使用每次运行都变化的标识符如时间戳这会导致无法进行历史聚合查询。应使用固定的、配置化的标识符。2. 集中化管理配置不要将agent标识符硬编码在业务逻辑中。应该像管理数据库连接池一样管理它们。# agent_registry.py class AgentRegistry: _agents { prod: { intent: prod_intent_v1, knowledge: prod_knowledge_v1, report: prod_report_v1, }, staging: { intent: staging_intent_v1, # ... } } classmethod def get_agent_id(cls, agent_name, envprod): 根据环境获取智能体ID return cls._agents.get(env, {}).get(agent_name) # 在调用处使用 agent_id AgentRegistry.get_agent_id(intent, current_env) data[extra_body] {agent: agent_id}3. 实现自动化监控与告警结合活动面板API可以搭建简单的成本监控和告警系统。# monitor_agent_cost.py import schedule import time from query_activity import query_agent_activity, analyze_activities def daily_agent_cost_report(): 每日智能体成本报告 print(f\n{*50}) print(f每日智能体成本报告 - {datetime.now().strftime(%Y-%m-%d)}) print(*50) high_cost_agents [] for agent_id, agent_name in AGENTS.items(): activities query_agent_activity(agent_id, hours24) if activities: total_cost sum(act.get(cost, 0) for act in activities) if total_cost 0.01: # 假设阈值是0.01美元 high_cost_agents.append((agent_name, total_cost)) print(f{agent_name}: ${total_cost:.6f}) else: print(f{agent_name}: 无活动) # 发送告警示例打印日志实际可集成邮件、钉钉、Slack等 if high_cost_agents: print(f\n⚠️ 高消耗告警) for name, cost in high_cost_agents: print(f - {name}: ${cost:.6f}) print(f{*50}\n) # 每天上午9点运行报告 schedule.every().day.at(09:00).do(daily_agent_cost_report) if __name__ __main__: print(启动智能体成本监控...) while True: schedule.run_pending() time.sleep(60)4. 结合使用其他过滤维度agent参数可以与其他参数组合实现更精细的查询。agentmodel查询某个智能体使用特定模型的情况。agentstatus查询某个智能体失败或成功的请求。agent 时间范围进行按小时、按天、按周的趋势分析。5. 数据持久化与分析对于重要的项目建议定期如每小时将活动数据拉取并存储到自己的数据库如MySQL、PostgreSQL或时序数据库InfluxDB中。这样可以实现更长期的数据保留OpenRouter可能只保留有限时间的数据。自定义的复杂分析和报表。与内部用户系统、项目管理系统关联实现更精准的成本分摊。6. 安全与权限API Key保管永远不要在客户端代码或公开仓库中暴露你的OpenRouter API Key。使用环境变量或安全的配置管理服务。最小权限原则如果只是用于查询活动可以考虑创建一个仅有read权限的API Key而不是使用拥有完整调用权限的Key。审计日志记录谁在什么时候执行了成本查询操作。OpenRouter活动面板API对智能体查询的支持标志着AI应用运维向更精细化、业务化方向迈出了一步。通过本文的实战演练你应该已经掌握了如何为你的AI调用打上智能体标签以及如何利用API进行高效的查询与分析。接下来你可以尝试将这套监控体系集成到你的实际项目中结合告警和数据分析构建起成本可控、性能可视的智能体应用架构。如果在实践中遇到新的问题不妨回头查阅官方文档或在开发者社区交流分享你的经验。