通用 Agent

如果你的工具不在 接入指南 列表里，用 通用 Agent 模板。原则很简单：本地 Agent 只保存 ATM key，所有模型流量都路由到 ATM Gateway。

何时用

• 你有一个 ATM 没自动检测到的 CLI、IDE 插件或自研 Agent。
• 你想把它的 key、日志、用量集中归到 ATM。
• 这个工具能配 baseUrl 和 apiKey。

如果你的工具的 API 跟所有四个协议家族（OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini generateContent）都不兼容，ATM 没办法路由——这种情况罕见。

第 1 步 — 选对入口

看你工具是怎么调模型的。匹配下表之一：

关键：不要把 base URL 设成上游 Provider 地址。如果 URL 是 https://api.openai.com/v1，请求绕过 ATM，什么也没记。

第 2 步 — 签发 key

curl -s -X POST http://127.0.0.1:4317/api/keys/issue \
  -H 'Content-Type: application/json' \
  -d '{
    "employeeName": "Alice Example",
    "employeeContact": "alice@example.com",
    "employeeTeam": "Agent Platform",
    "agentName": "My Custom Agent",
    "agentType": "generic_agent",
    "sourceTool": "My Custom Agent",
    "configPath": "~/.my-agent/config.json",
    "policyId": "direct"
  }'

返回里的 keyValue 就是要粘到工具 API key 字段里的 atm-… 值。

用 agentType: "generic_agent"。 这告诉 ATM 把这个 Agent 渲染到 Agents 页"Generic"分组下。

第 3 步 — 配置工具

大多数工具接受 JSON 配置或环境变量。

JSON（最常见）

{
  "baseUrl": "http://127.0.0.1:4317/v1",
  "apiKey": "atm-xxxxxxxxxxxx",
  "model": "<your-model-id>"
}

Anthropic 风格环境变量

ANTHROPIC_BASE_URL=http://127.0.0.1:4317
ANTHROPIC_AUTH_TOKEN=atm-xxxxxxxxxxxx
ANTHROPIC_API_KEY=atm-xxxxxxxxxxxx

Gemini 风格环境变量

GOOGLE_GENAI_API_ENDPOINT=http://127.0.0.1:4317
GOOGLE_GENAI_API_KEY=atm-xxxxxxxxxxxx

第 4 步 — 重启并验证

重启工具让它重读配置。然后：

1. 发一次真实请求。
2. GET http://127.0.0.1:4317/api/logs?limit=5，确认有新行。
3. 打开 Usage 页，看你的通用 Agent 行下面有没有花费记录。

通用 Agent 的特化角色

如果自定义工具有多角色，把每个角色定义成 General 之下的特化 Agent。用 agentType: "generic_agent_specialized"，并传 General 的 parentAgentId。

curl -s -X POST http://127.0.0.1:4317/api/keys/issue \
  -H 'Content-Type: application/json' \
  -d '{
    "employeeName": "Alice Example",
    "employeeContact": "alice@example.com",
    "agentName": "My Code Specialist",
    "agentType": "generic_agent_specialized",
    "sourceTool": "My Custom Agent",
    "parentAgentId": "agent_self_generic_general_xxx",
    "policyId": "auto"
  }'

之后通过 Auto 策略给特化 Agent 路由到更强的模型，General Agent 保持 Direct。

建议

• 从 policyId: "direct" 开始。明确知道想要哪些意图桶时再切某个 Agent 到 auto。
• 保持 configPath 准确——这是"重置配置"功能依赖的字段。
• 如果工具自己有 5xx 重试机制，留着就行。ATM 熔断器处理 Provider 持续不健康；单次重试是工具的事。

限制

• 不要伪造 atm-… key —— 无效 key 会被拒绝。
• 任何模型入口不带 key 返回 401。
• 带格式不对的 key 返回 400。
• /api/keys/issue 同 Agent 5 秒一次限流。批量脚本注意 sleep。