47Ag agnose

Agnose API 与 MCP

在你的代码或其他 AI 智能体中使用你的智能体：列出实例、发送消息、读取回复和用量。

身份验证

在账户中创建个人密钥，每次调用时以 Authorization: Bearer <密钥> 发送。每个密钥都有权限范围（scopes），可随时撤销。

创建密钥

端点

方法路径权限
GET/api/v1/instancesinstances:read
POST/api/v1/instances/{id}/messagesmessages:write
GET/api/v1/instances/{id}/runs/{runId}runs:read
GET/api/v1/usage?days=30usage:read

典型流程

发送消息（返回 202 和运行 id），然后查询运行，直到状态为 done 或 failed。也可以订阅 webhook，由我们通知你。

curl -X POST https://agneos.com/api/v1/instances/$INSTANCE/messages \
  -H "Authorization: Bearer $AGNOSE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"text": "Hola"}'
# 202 {"id": "run_…", "status": "queued", …}

curl https://agneos.com/api/v1/instances/$INSTANCE/runs/$RUN \
  -H "Authorization: Bearer $AGNOSE_API_KEY"
# 200 {"status": "done", "reply": "…"}

OpenAPI 3.1 规范

MCP 服务器

Agnose 通过 HTTP（streamable HTTP）提供 MCP。工具：list_agents、send_message 和 get_run。若只针对一个实例，请使用 /api/mcp/<实例 id>。

{
  "mcpServers": {
    "agnose": {
      "type": "http",
      "url": "https://agneos.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${AGNOSE_API_KEY}"
      }
    }
  }
}

Webhooks

当运行完成（run.completed）、失败（run.failed）或你取消实例（instance.cancelled）时，我们会发送签名的 POST。如果你的服务器没有返回 2xx，我们会以递增间隔重试，最多 8 次。

验证签名

agnose-signature 头包含 t=<unix 秒>,v1=<用你的密钥对 "t.正文" 计算的 HMAC-SHA256 十六进制>。拒绝超过 5 分钟的签名。

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, body, header) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const want = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return v1.length === want.length && timingSafeEqual(Buffer.from(v1), Buffer.from(want));
}

限制

每个密钥每分钟 60 次调用，每个 IP 120 次。超出后返回 429 和 Retry-After。各套餐的每日消息上限同样适用。

错误

错误格式为 {"error": {"code", "message"}}：unauthorized (401)、forbidden (403)、not_found (404)、invalid (400)、plan_limit 和 rate_limited (429)。