AG-UI 協議參考 - AgentCore

本文說明託管 Harness 的 AG-UI 介面。接入步驟參見管理 Agent。

介面與鑒權

agent_endpoint 表示 Endpoint 基礎地址。

要求標頭

操作	方法與路徑	響應
發起請求或重連	`POST {agent_endpoint}/ag-ui/agent`	SSE 事件流
停止執行	`POST {agent_endpoint}/ag-ui/agent/stop`	成功返回 `204 No Content`

名稱	要求	說明
`Content-Type`	必填	`application/json`
`Accept`	建議填寫	調用 AG-UI 時使用 `text/event-stream`
`x-api-key`	API Key 認證時必填	Agent Endpoint 的 API Key
`X-AgentCore-Session-ID`	可選	會話 ID，預設使用 `threadId`；填寫時必須與其相同

請求參數

請求體

{
  "threadId": "session-001",
  "runId": "run-001",
  "messages": [
    {
      "id": "message-001",
      "role": "user",
      "content": "請用三個要點介紹你的功能。"
    }
  ],
  "state": {},
  "tools": [],
  "context": [],
  "forwardedProps": {}
}

欄位	類型	說明
`threadId`	string	必填。會話 ID，同一段對話保留不變
`runId`	string	必填。本次執行的 ID，每次新請求使用新的值
`messages`	array	必填。提交給 Agent 的訊息，普通調用至少包含本輪使用者輸入
`state`	object	狀態資料，無需傳入時填寫 `{}`
`tools`	array	本次聲明的用戶端工具，無需傳入時填寫 `[]`
`context`	array	補充上下文，無需傳入時填寫 `[]`
`forwardedProps`	object	擴充屬性，無需傳入時填寫 `{}`；Attach 參數放在這裡
`parentRunId`	string	可選。關聯的父執行 ID

訊息欄位

developer 訊息按 system 訊息處理。activity 和 reasoning 類型的歷史訊息不會作為本輪模型輸入。

欄位	說明
`id`	訊息 ID。新訊息使用新 ID，重複攜帶已有訊息時保持原 ID
`role`	訊息角色，支援 `user`、`assistant`、`system`、`developer` 和 `tool`
`content`	文本字串，或由文本、圖片等內容組成的數組
`name`	可選。訊息發送方名稱
`toolCallId`	`tool` 訊息需要填寫，用於關聯工具調用

多模態輸入

使用者訊息可以包含文本、圖片、音頻、視頻或文檔，實際支援情況取決於所選 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 支援。

事件	主要欄位	含義及處理方式
`RUN_STARTED`	`threadId`、`runId`	本次執行開始
`TEXT_MESSAGE_START`	`messageId`、`role`	開始一條訊息
`TEXT_MESSAGE_CONTENT`	`messageId`、`delta`	將文本片段追加到對應訊息
`TEXT_MESSAGE_END`	`messageId`	這條訊息結束，繼續等待執行結果
`REASONING_START`、`REASONING_MESSAGE_START`、`REASONING_MESSAGE_CONTENT`、`REASONING_MESSAGE_END`、`REASONING_END`	`messageId`、`delta`	思考過程，單獨處理，不拼接到回答本文
`REASONING_ENCRYPTED_VALUE`	`entityId`、`encryptedValue`	加密的思考資料，不作為可讀文本展示
`TOOL_CALL_START`	`toolCallId`、`toolCallName`	開始一次工具調用
`TOOL_CALL_ARGS`	`toolCallId`、`delta`	工具參數片段，接收完整後再解析
`TOOL_CALL_END`	`toolCallId`	工具參數發送結束，不代表工具執行成功
`TOOL_CALL_RESULT`	`toolCallId`、`content`	工具執行結果，`content` 為字串
`CUSTOM`	`name`、`value`	擴充事件；`name=agentcore.usage` 時，`value` 為 Token 用量
`RUN_FINISHED`	`threadId`、`runId`、`outcome`，可選 `result`	檢查 `outcome.type`，為 `success` 時表示本次執行成功結束
`RUN_ERROR`	`code`、`message`	本次執行失敗或被取消

結果處理

檢查 HTTP 狀態代碼和響應類型，再開始解析 SSE。
按空行拆分完整事件。
按 messageId 拼接文本，按 toolCallId 拼接工具參數和記錄結果；不同訊息和工具的事件可能交錯出現。
每條事件完整處理後，儲存其 id，供斷線重連使用。
收到 RUN_FINISHED 時檢查 outcome；收到 RUN_ERROR 時記錄錯誤。

串連關閉時仍未收到結束事件，應記錄為串連中斷。

檔案結果

啟用檔案發布能力時，檔案通過臨時下載連結返回。TOOL_CALL_RESULT.content 為 JSON 字串，解析後的結構如下：

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

檔案發布失敗時返回 status=error 和錯誤資訊；未經轉換的非文本輸出可能觸發 AG_UI_OUTPUT_UNSUPPORTED。

多輪對話

會話調度與歷史儲存規則參見會話管理。

調用	`threadId`	`runId`	新訊息 ID
第一輪	`session-001`	`run-001`	`message-001`
第二輪	`session-001`	`run-002`	`message-002`
新會話	`session-002`	`run-003`	`message-003`

斷線重連

Attach 用於重新接收原請求的事件，不會重新執行請求，需要所選 Harness 支援。

向同一個 AG-UI 地址發送以下請求，保持原 threadId 和 runId，將 afterSequence 設定為最後一條已完整處理的事件 ID：

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

重連後只返回 id > afterSequence 的事件。afterSequence 必須是非負安全整數。

使用限制：

原請求仍在執行、運行進程未重啟，且事件緩衝尚未清理。
同一次執行只能有一個外部串連接收事件。

重連失敗後，應先確認原請求的執行情況。更換 runId 重發可能導致重複執行。

停止執行

明確停止執行時，調用 Stop 介面，不要僅關閉串連：

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"}'

使用最初發起請求時的 threadId 和 runId。成功返回 204 No Content，原事件流可能收到 RUN_ERROR，錯誤碼為 RUN_CANCELLED。

執行結束記錄仍保留時，重複停止返回 204；目標不存在或記錄已清理時，返回 404 RUN_NOT_FOUND。

錯誤處理

建立事件流之前

請求失敗時，通過 HTTP 狀態代碼和 JSON 返回錯誤：

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

認證、存取權限和網關限制還可能在請求到達 Agent 前返回錯誤，應同時檢查 Endpoint 配置和實際響應。

HTTP 狀態代碼	常見錯誤碼	說明
`400`	`INVALID_JSON`	請求體不是合法 JSON
`400`	`INVALID_AG_UI_REQUEST`	請求欄位或類型不符合要求
`400`	`SESSION_ID_MISMATCH`	要求標頭與請求體中的會話 ID 不一致
`400`	`INVALID_ATTACH`、`INVALID_STOP`	重連或停止參數不正確
`404`	`RUN_NOT_FOUND`	找不到要重連或停止的執行
`409`	`RUN_ALREADY_EXISTS`	本次執行 ID 已存在
`409`	`RUN_ALREADY_TERMINAL`	要重連的執行已經結束
`409`	`RUN_ALREADY_ATTACHED`	已有串連在接收本次執行的事件
`409`	`RUN_ATTACH_UNSUPPORTED`	當前 Harness 不支援重連
`409`	`SESSION_UNAVAILABLE`	會話正在關閉或不可用
`413`	`PAYLOAD_TOO_LARGE`	請求內容過大
`429`	`SESSION_QUEUE_FULL`	請求隊列已滿
`429`	`RUNTIME_CAPACITY_EXCEEDED`	執行容量已滿
`503`	`RUNTIME_NOT_READY`、`RUNTIME_DRAINING`	運行環境尚未就緒或正在停止接收新請求

建立事件流之後

執行失敗或被取消時，通過 RUN_ERROR 返回錯誤，再關閉事件流：

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

使用限制

不保證返回狀態快照、訊息快照、計劃或 Activity 事件。
state、context 等輸入欄位是否參與執行，取決於所選 Harness。
Runtime 的請求體上限為 96 MiB，單個附件解碼後上限為 64 MiB，單個 SSE 事件上限為 1 MiB；入口網關還可能設定更低的限制。

AG-UI 的通用事件定義參見官方事件說明。本文中的 Attach 參數、Stop 介面和 agentcore.usage 為 AgentCore 擴充。