AG-UI 协议参考

多模态输入

用户消息可以包含文本、图片、音频、视频或文档，实际支持情况取决于所选 Harness 和模型。

以下是一条图片消息，放在请求的 messages 数组中：

{
  "id": "message-002",
  "role": "user",
  "content": [
    {"type": "text", "text": "分析图片中的异常信息"},
    {
      "type": "image",
      "source": {
        "type": "url",
        "value": "https://example.com/error.png",
        "mimeType": "image/png"
      }
    }
  ]
}

传入 Base64 内容时，使用 source.type=data，数据填写到 source.value。其他内容类型为 audio、video 和 document。

客户端工具

tools 声明调用方提供的工具，与控制台绑定的 MCP 工具不同。单个工具示例：

{
  "name": "get_order",
  "description": "按订单号查询订单",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {"type": "string"}
    },
    "required": ["orderId"]
  }
}

所选 Harness 或 Agent 配置不支持客户端工具时，请求可能返回 EXECUTOR_INPUT_UNSUPPORTED。

SSE 格式

AG-UI 固定返回 SSE，不提供 stream:false 开关。需要一次性展示完整答案时，应用应先接收并拼接文本，确认执行成功后再展示。

响应头示例：

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
X-AgentCore-Session-ID: session-001

每个事件由 id 和 data 组成，事件之间用空行分隔。data 是 JSON；首次调用的 RUN_STARTED 使用 id: 0，后续事件 ID 递增。

文本回复示例：

id: 0
data: {"type":"RUN_STARTED","threadId":"session-001","runId":"run-001"}

id: 1
data: {"type":"TEXT_MESSAGE_START","messageId":"assistant-001","role":"assistant"}

id: 2
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"assistant-001","delta":"可以帮助处理问答、文件和工具调用。"}

id: 3
data: {"type":"TEXT_MESSAGE_END","messageId":"assistant-001"}

id: 4
data: {"type":"RUN_FINISHED","threadId":"session-001","runId":"run-001","outcome":{"type":"success"}}

事件类型

outcome.type=interrupt 表示执行需要外部输入，该行为需要所选 Harness 支持。

{
  "status": "success",
  "files": [
    {
      "fileName": "report.csv",
      "mimeType": "text/csv",
      "downloadUrl": "https://example.com/temporary-download-link",
      "expiresInSeconds": 3600
    }
  ]
}

多轮对话

会话调度与历史保存规则参见会话管理。

{
  "threadId": "session-001",
  "runId": "run-001",
  "messages": [],
  "state": {},
  "tools": [],
  "context": [],
  "forwardedProps": {
    "agentcore": {
      "attach": {"afterSequence": 12}
    }
  }
}

curl --request POST "${AGENTCORE_ENDPOINT%/}/ag-ui/agent/stop" \
  --header "x-api-key: ${AGENTCORE_ENDPOINT_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"threadId":"session-001","runId":"run-001"}'

{
  "error": {
    "code": "SESSION_ID_MISMATCH",
    "message": "X-AgentCore-Session-ID must equal RunAgentInput.threadId."
  }
}

id: 6
data: {"type":"RUN_ERROR","code":"RUN_CANCELLED","message":"Run cancelled."}