OpenRouter活动面板API升级：按智能体维度精细化追踪AI调用与成本

这次我们来看一个对开发者很实用的更新：OpenRouter 活动面板 API 升级，新增了按智能体（Agent）查询的功能。如果你正在使用 OpenRouter 作为大模型 API 聚合平台，或者你在开发基于 AI 智能体的应用，那么这个功能更新能帮你更精细地追踪和分析 API 调用情况，尤其是在多智能体协作或成本分摊的场景下。

简单来说，OpenRouter 本身是一个聚合了众多主流大模型（如 GPT、Claude、DeepSeek 等）API 的服务平台。它的“活动面板”（Activity Panel）是用户查看 API 调用记录、分析使用量和成本的核心界面。这次 API 升级，允许开发者通过 API 接口，直接按“智能体”这个维度来筛选和查询历史调用记录。这意味着你可以将不同的 API 调用归属到不同的业务逻辑单元（智能体）下，实现更清晰的成本核算和性能监控。

对于开发者而言，这个功能的核心价值在于可观测性和成本管理。你不用再面对一堆混杂的调用日志手动筛选，而是可以通过编程方式，快速获取某个特定智能体的所有请求、响应、耗时和费用数据。这对于搭建 AI 应用平台、进行 A/B 测试或为不同客户/项目计费，提供了极大的便利。

本文会带你快速了解这个新功能，并通过模拟示例，展示如何调用升级后的活动面板 API 来查询智能体数据。我们重点关注接口能力、请求参数、返回数据结构以及如何将其集成到你的监控或分析系统中。即使你暂时没有智能体划分的需求，了解这套机制也能为未来的架构设计提供思路。

1. 核心能力速览

在深入细节之前，我们先通过一个表格快速把握这次升级的核心要点：

2. 适用场景与使用边界

2.1 这个功能适合谁？

1. AI 应用平台开发者：如果你正在构建一个平台，允许用户创建多个 AI 智能体（例如客服机器人、内容生成助手、数据分析 Agent），你需要为每个智能体的使用量单独计费或展示给终端用户。
2. 进行 A/B 测试的团队：同时上线了多个不同策略或模型的智能体版本，需要对比它们的 API 调用成本、响应延迟和成功率。
3. 拥有复杂业务逻辑的项目：一个项目内集成了多个职责不同的智能体（如一个用于理解用户意图，一个用于生成 SQL，一个用于总结报告），需要厘清各部分的资源消耗。
4. 财务与运维人员：需要对内或对外提供清晰的、基于不同业务线或客户项目的 AI API 成本报告。

2.2 能解决什么问题？

• 成本归属模糊：所有 API 调用混在一起，无法区分是哪个功能模块或哪个客户产生的费用。
• 监控粒度太粗：只能看到整体用量和延迟，无法定位到具体某个智能体是否存在性能问题或异常调用。
• 审计追踪困难：当出现错误或争议时，难以快速回溯特定智能体的完整调用链。
• 手动处理低效：需要从控制台导出全部日志，再通过本地脚本根据自定义标识进行过滤，流程繁琐易错。

2.3 不适合什么场景？

• 单一智能体应用：如果你的应用只有一个核心 AI 功能，没有区分子智能体的需求，那么使用原有的全局查询可能就够了。
• 实时监控：活动面板 API 主要用于查询历史记录，并非高频率的实时流式数据接口。对于秒级实时监控，可能需要结合 Webhook 或其他方式。
• 修改或删除记录：此 API 仅用于查询，不能用于修改或删除任何调用记录。

2.4 合规与安全边界

• 数据隐私：调用记录中可能包含发送给大模型的提示词（Prompt）和返回的完整响应。在通过 API 查询和存储这些数据时，必须严格遵守数据隐私法规（如 GDPR、个人信息保护法），避免泄露用户隐私或敏感商业信息。
• 授权访问：API Key 是访问你账户数据的凭证，务必妥善保管，不要在客户端代码或公开仓库中暴露。建议在服务端环境调用此 API。
• 合规使用：确保你的智能体应用本身符合相关法律法规，不用于生成违法、侵权或有害内容。OpenRouter 的使用条款同样约束其上的所有调用。

3. 环境准备与前置条件

要使用按智能体查询的功能，你需要准备好以下几项：

1. OpenRouter 账户与 API Key：

   • 访问 OpenRouter 官网 注册并登录。
   • 在账户设置或 API 密钥管理页面，创建一个新的 API Key 或使用现有的。请保管好此密钥。

2. 智能体标识符：

   • 这是本次功能升级的核心。你需要在发起对 OpenRouter 模型 API 的调用时，在请求头或请求体中带上一个用于标识智能体的字段。根据 OpenRouter 的常见实践，这个字段通常是agent或x-request-id之类的自定义标识，具体字段名需要查阅 OpenRouter 最新的 API 文档确认。
   • 关键点：只有历史调用记录中包含了这个标识符，你才能通过活动面板 API 按此标识进行查询。因此，你需要先改造你的应用代码，在调用模型 API 时注入智能体信息。

3. 网络环境：

   • 确保你的调用服务器可以稳定访问api.openrouter.ai及其相关接口域名。

4. 工具准备：

   • 任何能发送 HTTP 请求的工具即可，例如：
     • 命令行：curl（推荐用于快速测试）
     • 编程语言：Python（requests库）、Node.js（axios或fetch）、Go、Java 等。
     • API 测试工具：Postman, Insomnia。

4. 安装部署与启动方式

本次活动面板 API 是云端服务，无需本地安装部署。所谓的“启动”是指你准备好调用环境。

4.1 获取并设置 API Key

将你的 OpenRouter API Key 设置为环境变量，这是安全且通用的做法。

# Linux/macOS export OPENROUTER_API_KEY='your-api-key-here' # Windows (PowerShell) $env:OPENROUTER_API_KEY='your-api-key-here' # Windows (CMD) - 临时设置 set OPENROUTER_API_KEY=your-api-key-here

4.2 验证 API Key 有效性

可以先调用一个简单的接口验证密钥是否有权限。

curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \ https://openrouter.ai/api/v1/auth/key

如果返回类似{"data": {"id": "key_...", "name": "...", ...}}的 JSON，说明密钥有效。

5. 功能测试与效果验证

我们通过模拟一个场景来测试：假设我们有两个智能体，agent_customer_service（客服）和agent_content_writer（内容创作）。我们需要查询过去24小时内客服智能体的所有调用记录。

5.1 测试目的

验证活动面板 API 的agent过滤参数是否生效，并理解返回的数据结构。

5.2 操作步骤与请求示例

根据 OpenRouter 的通用 API 设计，活动面板的查询接口可能类似于/api/v1/activity或/api/v1/requests。查询参数通常包括时间范围、分页、以及过滤条件（如agent）。

以下是一个基于常见 RESTful 设计模式的假设性请求示例。请注意，实际的端点 URL 和参数名称请务必以 OpenRouter 官方最新文档为准。

# 假设活动面板查询端点为 /api/v1/activity # 假设过滤参数名为 `agent` # 查询过去24小时，agent 为 `agent_customer_service` 的记录 curl -X GET \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Content-Type: application/json" \ "https://api.openrouter.ai/api/v1/activity?start_time=$(date -u -d '24 hours ago' +%s)&end_time=$(date -u +%s)&agent=agent_customer_service&limit=10"

参数解释：

• start_time,end_time: Unix 时间戳（秒），定义查询时间范围。
• agent: 过滤条件，指定要查询的智能体标识符。
• limit: 分页大小，限制单次返回的记录条数。

5.3 预期返回结果与解析

一个典型的成功响应可能如下所示（数据结构为示例）：

{ "object": "list", "data": [ { "id": "req_abc123", "created_at": 1681234567, "model": "openai/gpt-3.5-turbo", "agent": "agent_customer_service", "prompt": "用户说：我的订单没有收到...", "response": "您好，很抱歉给您带来不便...", "usage": { "prompt_tokens": 25, "completion_tokens": 40, "total_tokens": 65 }, "cost": 0.000065, "status_code": 200, "latency_ms": 850 }, // ... 更多记录 ], "has_more": true, "next_page": "eyJpZCI6InJlcV9kZWY0NTYiLCJjcmVhdGVkX2F0IjoxNjgxMjM0NTY3fQ==" }

关键字段说明：

• data: 数组，包含符合条件的调用记录列表。
• has_more: 布尔值，表示是否还有更多数据。
• next_page: 分页游标，当has_more为true时，用于获取下一页数据。
• 每条记录中的agent字段应与查询参数一致，cost和usage字段便于进行成本分析。

5.4 判断是否成功

1. HTTP 状态码：返回200 OK。
2. 数据过滤：响应中data数组里的每条记录的agent字段都应该是agent_customer_service，不应出现其他智能体的记录。
3. 数据完整性：记录应包含模型、用量、成本、延迟等关键信息。

5.5 常见失败原因

• 401 Unauthorized：API Key 错误、过期或未提供。
• 400 Bad Request：查询参数格式错误，例如时间戳格式不对、agent参数名错误。特别注意：网络热词中提到了api error: 400 the thinking_budget parameter must be a positive integer，这虽然是另一个接口的错误，但提醒我们调用 OpenRouter API 时需严格遵循参数要求。
• 403 Forbidden：API Key 没有访问活动面板的权限。网络热词中也出现了transport failure for /api/agentpreset.list: http 403，这同样是权限问题的体现。
• 404 Not Found：请求的端点 URL 不正确。
• data数组为空：在指定的时间范围和agent条件下，没有找到任何调用记录。请检查：
  • 时间范围是否覆盖了调用发生的时间。
  • 历史调用中是否确实包含了该agent标识符。
  • 标识符的大小写、拼写是否完全一致。

6. 接口 API 与批量任务

活动面板 API 本质上是一个查询接口，但我们可以利用它来实现“批量”获取数据的需求，例如导出所有智能体某段时间的数据用于离线分析。

6.1 分页获取所有数据

由于单次查询有数量限制，要获取大量记录需要使用分页参数。结合has_more和next_page（或类似的offset/cursor）参数，可以编写一个循环来获取全部数据。

以下是一个 Python 示例，演示如何分页获取某个智能体的所有活动记录：

import requests import os import time API_KEY = os.getenv("OPENROUTER_API_KEY") BASE_URL = "https://api.openrouter.ai/api/v1/activity" AGENT_ID = "agent_customer_service" END_TIME = int(time.time()) START_TIME = END_TIME - 7 * 24 * 3600 # 查询最近7天 headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } all_activities = [] next_cursor = None while True: params = { "start_time": START_TIME, "end_time": END_TIME, "agent": AGENT_ID, "limit": 100 # 每次最多取100条 } if next_cursor: params["cursor"] = next_cursor # 假设分页参数名为 cursor try: response = requests.get(BASE_URL, headers=headers, params=params, timeout=30) response.raise_for_status() # 检查HTTP错误 data = response.json() except requests.exceptions.RequestException as e: print(f"请求失败: {e}") break except ValueError as e: print(f"解析JSON失败: {e}") break # 假设返回结构为 {“data”: [], “has_more”: bool, “next_cursor”: str} activities = data.get("data", []) all_activities.extend(activities) print(f"已获取 {len(activities)} 条记录，总计 {len(all_activities)} 条。") if not data.get("has_more", False): print("所有数据获取完毕。") break next_cursor = data.get("next_cursor") if not next_cursor: break # 可选：避免请求过快 time.sleep(0.5) # 后续处理：可以将 all_activities 保存为 JSON 文件或导入数据库 import json with open(f"activities_{AGENT_ID}.json", "w", encoding="utf-8") as f: json.dump(all_activities, f, ensure_ascii=False, indent=2) print(f"数据已保存至 activities_{AGENT_ID}.json，共 {len(all_activities)} 条记录。")

6.2 多智能体批量查询与聚合

如果你需要同时查询多个智能体的数据并聚合统计，可以并行或串行调用上述接口。

import concurrent.futures agent_list = ["agent_customer_service", "agent_content_writer", "agent_data_analyzer"] def fetch_agent_activities(agent_id): # 这里复用上面的分页获取逻辑，封装成一个函数 # 返回该智能体的记录列表或统计摘要 # ... return {"agent_id": agent_id, "count": len(records), "total_cost": sum(r['cost'] for r in records)} # 使用线程池并行查询 with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor: future_to_agent = {executor.submit(fetch_agent_activities, agent): agent for agent in agent_list} results = [] for future in concurrent.futures.as_completed(future_to_agent): agent = future_to_agent[future] try: result = future.result() results.append(result) except Exception as exc: print(f'查询智能体 {agent} 时发生异常: {exc}') for r in results: print(f"智能体 {r['agent_id']}: 调用 {r['count']} 次，总成本 ${r['total_cost']:.6f}")

7. 资源占用与性能观察

由于调用的是云端 API，本地资源占用几乎可以忽略不计，主要需要考虑的是：

1. 网络带宽与延迟：批量查询大量历史数据时，网络传输耗时是主要因素。建议在离 OpenRouter 服务器较近的区域（如果支持）运行查询脚本，并合理设置超时时间。
2. API 速率限制：OpenRouter 对 API 调用有速率限制。在编写批量查询脚本时，需要加入适当的间隔（如time.sleep），避免触发限流导致请求失败。错误信息可能包含429 Too Many Requests。
3. 数据处理内存：如果一次性查询并加载数万甚至数十万条记录到内存中，可能会消耗较多内存。对于超大数据集，建议：
   • 使用分页查询，分批处理。
   • 将数据直接流式写入文件或数据库，而不是全部暂存在内存列表中。
4. 存储空间：定期导出的 JSON 或 CSV 文件会占用磁盘空间，需要规划归档或清理策略。

8. 常见问题与排查方法

9. 最佳实践与使用建议

1. 智能体标识设计：

   • 唯一且有意义：为每个智能体设计一个唯一标识符，最好能体现其功能或所属项目，如project_x_customer_bot_v2。
   • 避免频繁变更：标识符一旦用于生产环境，应尽量避免更改，否则历史数据查询会断裂。
   • 纳入配置管理：不要将标识符硬编码在代码中，应作为配置项或环境变量管理。

2. 成本监控与告警：

   • 利用按智能体查询的 API，可以定期（如每小时、每天）拉取数据，计算各智能体的成本。
   • 设置阈值告警。例如，当某个智能体单日成本超过预算时，自动发送邮件或 Slack 通知。

3. 数据归档与分析：

   • 定期（如每周）将活动数据导出到数据仓库（如 BigQuery, Redshift）或分析数据库（如 PostgreSQL）。
   • 结合 BI 工具（如 Metabase, Tableau）制作仪表盘，可视化展示各智能体的调用趋势、成本分布和平均延迟。

4. 集成到 DevOps 流程：

   • 在部署新的智能体版本时，可以通过 API 为其创建新的标识符（如添加版本后缀），便于进行新旧版本的性能与成本对比（A/B 测试）。

5. 错误追踪与调试：

   • 当终端用户报告某个智能体回答异常时，你可以快速通过agent标识和时间范围过滤出相关调用记录，检查当时的请求和响应，加速问题定位。

6. 安全与审计：

   • 由于活动日志包含完整的 Prompt 和 Response，访问此 API 的权限应严格控制，仅限内部运维、财务或审计人员。
   • 考虑对查询日志进行二次记录，以满足合规性审计要求。

OpenRouter 活动面板 API 支持按智能体查询，虽然是一个后端功能的增强，但它直接赋能了前端的可观测性实践。通过将抽象的 API 调用与具体的业务实体（智能体）关联，开发者能够以前所未有的清晰度洞察 AI 应用的运行状态和成本构成。建议你立即检查现有项目，规划智能体标识体系，并尝试调用此 API，为你的 AI 应用装上“成本与性能仪表盘”。