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筛选出特定智能体的所有活动记录。这实现了：

1. 成本精细化归因：准确将API费用分摊到具体的业务模块或智能体上。
2. 性能监控：分析不同智能体的平均响应时间、Token消耗等性能指标。
3. 调试与优化：快速定位某个智能体出现的异常调用或高成本问题。
4. 预算控制：可以为高消耗的智能体设置独立的预算告警。

接下来，我们将从环境准备开始，逐步演示如何使用这一新功能。

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文件：

requests>=2.28.0 python-dotenv>=0.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端点：

1. 完成调用接口(/chat/completions): 在发起请求时，如何附加智能体标签。
2. 活动查询接口(/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": f"Bearer {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", headers=headers, json=data ) 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": f"Bearer {OPENROUTER_API_KEY}", } params = { 'limit': 50, # 返回记录数，默认可能为20 'offset': 0, # 分页偏移量 # 时间范围过滤 (ISO 8601格式) 'from': (datetime.utcnow() - timedelta(days=7)).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", headers=headers, params=params ) activity_data = response.json() print(f"查询到 {len(activity_data.get('data', []))} 条记录") for item in activity_data.get('data', []): print(f"ID: {item.get('id')}, Model: {item.get('model')}, " f"Agent: {item.get('agent')}, Cost: ${item.get('cost', 0):.6f}, " f"Created: {item.get('created_at')}")

关键查询参数解析：

• agent: (新) 传入在extra_body中设置的智能体标识符字符串，即可筛选出该智能体的所有调用记录。
• from/to: 用于指定查询的时间范围，格式为ISO 8601（如2024-01-01T00:00:00Z）。这对于按天、周、月统计消耗至关重要。
• limit/offset: 用于分页，避免单次请求数据量过大。
• model: 可以结合agent使用，进一步筛选某个智能体使用的特定模型。

4. 完整实战案例：构建智能体成本监控脚本

现在，我们将把上面的知识点整合起来，构建一个实用的实战案例。这个案例包含两部分：

1. 模拟多个智能体向OpenRouter发起请求（打上Agent标签）。
2. 编写一个查询脚本，按智能体统计其调用次数、总费用和平均响应时间。

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, model="openai/gpt-3.5-turbo"): """ 使用指定的智能体标签调用OpenRouter API :param prompt: 用户提示词 :param agent_id: 智能体标识符，对应config.AGENTS中的key :param model: 要使用的模型 :return: API响应内容或None """ headers = { "Authorization": f"Bearer {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", headers=headers, json=data, timeout=30 ) 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( prompt=task['prompt'] + f" (模拟轮次: {round_num})", agent_id=task['agent'], model=task['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, hours=24): """ 查询指定智能体在过去若干小时内的活动记录 :param agent_id: 智能体标识符 :param hours: 查询过去多少小时的数据 :return: 活动记录列表 """ headers = {"Authorization": f"Bearer {OPENROUTER_API_KEY}"} # 计算时间范围 to_time = datetime.utcnow() from_time = to_time - timedelta(hours=hours) 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", headers=headers, params=params, timeout=15 ) 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, hours=24) 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", hours=1) analyze_activities(non_existent_activities) if __name__ == "__main__": main()

运行分析脚本：

python query_activity.py

4.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. 常见问题与排查思路

在实际集成和使用过程中，你可能会遇到一些问题。下面列出了一些常见问题及其解决方法。

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, env="prod"): """根据环境获取智能体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, hours=24) 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参数可以与其他参数组合，实现更精细的查询。

• agent+model：查询某个智能体使用特定模型的情况。
• agent+status：查询某个智能体失败或成功的请求。
• agent+ 时间范围：进行按小时、按天、按周的趋势分析。

5. 数据持久化与分析对于重要的项目，建议定期（如每小时）将活动数据拉取并存储到自己的数据库（如MySQL、PostgreSQL或时序数据库InfluxDB）中。这样可以实现：

• 更长期的数据保留（OpenRouter可能只保留有限时间的数据）。
• 自定义的复杂分析和报表。
• 与内部用户系统、项目管理系统关联，实现更精准的成本分摊。

6. 安全与权限

• API Key保管：永远不要在客户端代码或公开仓库中暴露你的OpenRouter API Key。使用环境变量或安全的配置管理服务。
• 最小权限原则：如果只是用于查询活动，可以考虑创建一个仅有read权限的API Key，而不是使用拥有完整调用权限的Key。
• 审计日志：记录谁在什么时候执行了成本查询操作。

OpenRouter活动面板API对智能体查询的支持，标志着AI应用运维向更精细化、业务化方向迈出了一步。通过本文的实战演练，你应该已经掌握了如何为你的AI调用打上智能体标签，以及如何利用API进行高效的查询与分析。接下来，你可以尝试将这套监控体系集成到你的实际项目中，结合告警和数据分析，构建起成本可控、性能可视的智能体应用架构。如果在实践中遇到新的问题，不妨回头查阅官方文档，或在开发者社区交流分享你的经验。