AG-UI 的工具调用从 TOOL_CALL_START 开始,参数通过 TOOL_CALL_ARGS 分片传输。客户端按 toolCallId 收集片段,在 TOOL_CALL_END 后解析和校验。工具是否执行、有没有返回结果,需要看实际处理逻辑。
先声明工具名称与参数,再接收调用
以天气查询场景为例,客户端提前声明 get_weather 工具和 city 字段。实际运行时 agent 可以基于这些信息选择调用对应工具。这里我们用固定事件端点做连通性验证,终端只会组装和校验参数,不会真的发起天气查询请求。
运行能返回两段参数的示例端点
新建独立目录初始化运行环境,创建 server.py 文件,启动服务之后保持当前终端不要关闭。这个服务提前预设了工具名和分片规则,保证每次测试拿到的都是同一组确定的参数。
python3 -m venv .venv source .venv/bin/activate python -m pip install ag-ui-protocol==1.0.0 fastapi uvicorn
import asyncio
from uuid import uuid4
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from ag_ui.core import (
RunAgentInput, RunStartedEvent, RunFinishedEvent,
ToolCallStartEvent, ToolCallArgsEvent, ToolCallEndEvent,
)
from ag_ui.encoder import EventEncoder
app = FastAPI()
def stream(data, payloads):
encoder = EventEncoder()
identifiers = {"thread_id": data.thread_id, "run_id": data.run_id}
async def events():
yield encoder.encode(RunStartedEvent(**identifiers))
for event in payloads:
yield encoder.encode(event)
await asyncio.sleep(0.3)
yield encoder.encode(RunFinishedEvent(**identifiers))
return StreamingResponse(events(), media_type=encoder.get_content_type())
@app.post("/tool")
async def run_tool(data: RunAgentInput):
cid = str(uuid4())
return stream(data, [
ToolCallStartEvent(tool_call_id=cid, tool_call_name="get_weather"),
ToolCallArgsEvent(tool_call_id=cid, delta='{"city":'),
ToolCallArgsEvent(tool_call_id=cid, delta='"Shanghai"}'),
ToolCallEndEvent(tool_call_id=cid),
])
python -m uvicorn server:app --host 127.0.0.1 --port 8000
另开一个终端进入刚才的同一目录,把下方内容保存为 tool-run.json,tools 字段里已经填好工具名、描述和参数约束。随后请求/tool接口,把返回的SSE内容保存到 tool.sse。
{
"threadId": "demo-thread",
"runId": "demo-tool-01",
"state": {},
"messages": [
{
"id": "u1",
"role": "user",
"content": "Hello"
}
],
"tools": [
{
"name": "get_weather",
"description": "Look up weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
],
"additionalProperties": false
}
}
],
"context": [],
"forwardedProps": {}
}
curl -fsSN -H 'Accept: text/event-stream' \ -H 'Content-Type: application/json' --data-binary @tool-run.json \ http://127.0.0.1:8000/tool > tool.sse grep "TOOL_CALL_" tool.sse
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

参数拼接何时能开始解析
第一段分片只有JSON对象开头和键名,要等同一个toolCallId的两段参数全部收齐之后,再执行json.loads解析。保存下面的 tool_reader.py,pending字典用调用ID做索引,就算同一轮里多个工具的片段交错传输,也不会按工具名混在一起。
import json
from pathlib import Path
pending = {}
for line in Path("tool.sse").read_text().splitlines():
if not line.startswith("data: "):
continue
event = json.loads(line[6:])
kind = event["type"]
if kind == "TOOL_CALL_START":
pending[event["toolCallId"]] = [event["toolCallName"], []]
elif kind == "TOOL_CALL_ARGS":
pending[event["toolCallId"]][1].append(event["delta"])
elif kind == "TOOL_CALL_END":
name, parts = pending.pop(event["toolCallId"])
args = json.loads("".join(parts))
if name != "get_weather" or not isinstance(args, dict):
raise SystemExit("Unexpected tool or arguments")
city = args.get("city")
if set(args) != {"city"} or not isinstance(city, str) or not city.strip():
raise SystemExit("Expected a single non-empty city")
print(name, json.dumps(args, ensure_ascii=False))
if pending:
raise SystemExit("Incomplete tool call")
python3 tool_reader.py

接入真实工具时怎样提交执行结果
工具参数传输结束后,应用先核对工具名、参数类型和业务权限,再调用本地处理函数执行逻辑。TOOL_CALL_END只代表参数输出完毕,不能用来判定业务操作已经执行成功。前端集成的工具,可以按对接规则把执行结果作为tool角色消息带回后续输入,用原toolCallId做关联。如果是服务端自己执行工具,按所用的对应规范和SDK处理结果事件即可。
排查问题的时候优先核对ID:确认START、ARGS和END三个事件用的是同一个toolCallId,确认所有分片拼接后是合法JSON,确认返回结果和原始调用能对应上。你可以故意把两片参数的顺序打乱,或者删掉其中一片再运行读取脚本,就能看到解析直接报错,以此确认异常情况不会误触发本地处理函数。











