跳转到主要内容
POST
/
api
/
v1
/
agents
/
{agentId}
/
invoke
给智能体发消息、收回复(sync / SSE)。
curl --request POST \
  --url https://openapi.beeos.ai/api/v1/agents/{agentId}/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "context_id": "<string>",
  "timeout_ms": 57500,
  "idempotency_key": "<string>",
  "metadata": {},
  "attachments": [
    {
      "file_id": "<string>",
      "filename": "<string>",
      "content_type": "<string>"
    }
  ]
}
'
{
  "success": true,
  "data": {
    "text": "<string>",
    "context_id": "<string>",
    "is_error": true
  }
}

授权

Authorization
string
header
必填

通过 Authorization: Bearer <token> header 传用户 JWToag_ User API Key。两者都由 openapi-gateway 对 Auth service 验证。

JWT 与 API Key 都是 user-scoped:每个 key(以及每个 JWT) 绑定到唯一 owner,所有路由都自动放开该 owner 名下的全部资源。 跨租户访问由 handler 内的 owner-ACL 拦截 —— API 表面没有 per-route scope 词汇。

v1.1.0 已移除: 历史 scope 词汇(agents:* / tasks:* / files:* / instances:*)以及 403 insufficient_scope 错误码已下线。已签发的 oag_ key 自动获得 owner 全权限, 无需重建。之前显式传 scopes 调用 createAPIKey 的 SDK 客户端可以直接删除该参数。详见文末 changelog 迁移说明。

路径参数

agentId
string
必填
Maximum string length: 128

请求体

application/json
message
string
必填

发给智能体的消息。

context_id
string

多轮会话用的可选对话上下文 ID。

timeout_ms
integer<int64>

每请求超时(毫秒)。默认 120000(2 分钟)。服务端硬钳在 115000 让响应总有时间在 HTTP WriteTimeout(120s)触发 前 flush。超过 115000 的值静默钳;agent 在生效窗内没回 服务端返回 service_timeout(HTTP 504)—— 见 docs/reference/errors.md

必填范围: 0 <= x <= 115000
idempotency_key
string

可选调用方生成的幂等 key,作为 chat_message 的 idempotency_key 转发给 Message Service。同 key 的重试 在 MS 去重(channel_messages UNIQUE 索引)。省略时 gateway 生成新的 UUID。同 key 也兼作智能体回复时必须 echo 回的 in_reply_to 上的 message_id

metadata
object

不透明的调用方控制 key/value 对,合并进通道元数据 (例如 trace_iduser_id、业务标签)。预留路由 key (protocolcaller_owner_idtarget_agent_iddelivery_principal)服务端静默剥离、调用方不能覆盖。

attachments
object[]

可选的、此前通过 POST /api/v1/files/presign-upload 上传的文件列表。每个 file_id 服务端解析成 presigned 下载 URL、嵌进 chat_message 信封,接收智能体不用再 BeeOS 认证就能拿字节。

Maximum array length: 16

响应

阻塞:含智能体回复的 JSON 信封。 流式(Accept: text/event-stream):SSE 流 —— 每 frame schema 见 InvokeEventStreamdelta / error / done 类型)。

success
boolean
必填
data
object
必填