跳转到主要内容
本文档概述了通过send-message端点与AG-Kit Agent交互的协议。适用于希望用其他语言构建自定义AG-Kit或直接通过HTTP与AG-Kit服务器交互的开发者，无需局限于现有的ReactAG-Kit。

​
前提条件

本文档面向希望通过HTTP端点与AG-Kit Agent服务器交互的开发者。在开始阅读前请确认：
  • 您已运行AG-Kit Agent服务器。若未运行，请参考运行Agent。
  • 您不希望使用现有的ReactAG-Kit。如需使用，请参考运行Agent。

​
0. send-message端点

客户端与服务器通过send-message端点进行通信。 交互过程中：
  • 客户端向端点发送POST请求，请求体中以JSON字符串形式携带有效载荷
  • 服务器以SSE格式响应，流式返回一系列事件
以下章节将重点介绍请求和响应有效载荷，包括几种常见交互场景：
  • 基础对话
  • 客户端工具调用
  • 服务器工具调用
  • 中断处理
有关端点的详细说明，请参阅应用程序接口参考。

​
1. 基础对话

最简单的交互形式是客户端发送纯文本消息，Agent返回文本响应。

​
客户端请求有效载荷

客户端发送请求时，将message.type设为"text"，用户输入内容放在message.content中。对于持续对话，应包含conversationId。
conversationId用于标识对话。AG-Kit的Agent服务器会根据conversationId追踪对话历史。messages字段应携带对话的增量消息。Agent服务器会自动将其追加到对话历史中。
请求体示例： 
{
    "messages": [
        {
            "role": "user",
            "content": "hi"
        }
    ],
    "conversationId": "2da2146d-9e7e-41f3-9515-b70557e4430c"
}

​
服务器响应事件

对于纯文本响应，服务器会流式返回text事件。客户端应拼接这些事件的content字段以重构完整的Agent文本响应。 响应事件示例： 
data: {"type": "text", "content": "Hello"}

data: {"type": "text", "content": " there!"}

data: {"type": "text", "content": " How can I help you?"}

​
示意图

​
2. 客户端工具调用

在此场景中，Agent请求客户端执行工具调用。客户端负责执行工具并将结果提交回服务器。

​
客户端请求有效载荷（初始）

初始请求中，客户端发送包含可用客户端工具的消息，可能触发Agent调用客户端工具。 工具定义存放在tools字段中，该字段是包含name、description和parameters的工具定义数组。parameters应为JSON模式字符串。 请求体示例： 
{
    "messages": [
        {
            "role": "user",
            "content": "Change background color to blue."
        }
    ],
    "tools": [
        {
            "name": "change-background-color",
            "description": "Change the background color. The color should be one of the following: blue, red, green, transparent, yellow, purple, orange, pink, brown, gray, black, or white. No other colors or any variants.",
            "parameters": "{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"type\":\"object\",\"properties\":{\"color\":{\"type\":\"string\"}},\"required\":[\"color\"],\"additionalProperties\":false}"
        }
    ],
    "conversationId": "c7d334f7-d920-4dd3-91e0-53d695e79fc0"
}

​
服务器响应事件（工具调用请求）

服务器收到可用客户端工具并决定调用其中某个工具后，将流式返回一系列工具调用事件。 工具调用事件设计用于支持流式工具调用参数，包含3种变体：
  • tool-call-start: 携带toolCallId和toolCallName，表示工具调用开始
  • tool-call-args: 携带toolCallId和delta，表示工具调用参数的一个片段
  • tool-call-end: 携带toolCallId，表示工具调用完成
客户端应通过拼接tool-call-args事件的delta字段来组装参数。 客户端收到tool-call-end事件后，参数应为有效的JSON字符串，可被客户端解析并传递给客户端工具。 响应事件示例： 
data: {"type":"tool-call-start","toolCallId":"a_b_c","toolCallName":"change-background-color"}

data: {"type":"tool-call-args","toolCallId":"a_b_c","delta":"{\"color\":"}

data: {"type":"tool-call-args","toolCallId":"a_b_c","delta":" \"blue\"}"}

data: {"type":"tool-call-end","toolCallId":"a_b_c"}

​
客户端操作与请求有效载荷（工具执行与结果提交）

客户端收到工具调用事件后，可开始执行工具。
工具执行的具体实现方式不限，可以是本地函数、UI组件或外部应用程序接口调用。甚至可引入Human-in-the-loop特性，在执行工具前获取人工批准。
工具执行完成后，客户端发送携带工具消息的新请求，其中content字段包含工具执行结果，toolCallId字段包含工具调用ID。 请求体示例（提交工具结果）： 
{
    "messages": [
        {
            "role": "tool",
            "content": "Background color successfully changed to: blue",
            "toolCallId": "a_b_c"
        }
    ],
    "conversationId": "c7d334f7-d920-4dd3-91e0-53d695e79fc0"
}

​
服务器响应事件（工具结果提交后）

与常规对话类似，服务器将工具消息追加到对话历史中，并流式返回更多text事件，通常会将工具输出整合到响应中。 响应事件示例： 
data:	{"type":"text","content":"I"}	

data:	{"type":"text","content":"'ve"}	

data:	{"type":"text","content":" successfully"}	

data:	{"type":"text","content":" changed"}	

data:	{"type":"text","content":" the"}	

data:	{"type":"text","content":" background"}	

data:	{"type":"text","content":" color"}	

data:	{"type":"text","content":" to"}	

data:	{"type":"text","content":" blue"}	

data:	{"type":"text","content":" for"}	

data:	{"type":"text","content":" you"}	

data:	{"type":"text","content":"."}

​
示意图