DevHub API 快速开始
DevHub API 让你自己的代码创建 Agent、在 Session 中与它对话、给它文件,并让它调用你的应用运行的工具。本指南走完一次完整的对话。openapi.yaml 是每个请求、应答和错误的参考。
示例使用 curl 和两个 shell 变量。DEVHUB 是 DevHub 基础地址,在 DevHub Console 中 Agent 的 API 页可以看到;本指南和参考中的每个路径都相对于它。
export DEVHUB=https://devhub.example.com # 换成你的 DevHub 基础地址export DEVHUB_KEY=ti_dev_...每个请求都以 Authorization: Bearer $DEVHUB_KEY 发送你的 DevHub Key。Key 的密钥只在签发时显示一次;把它留在你的后端,不要放进你发布的浏览器页面或应用。已吊销的 Key 立即被拒绝并返回 401,它打开的事件流在几秒内结束。
检查 Key:
curl "$DEVHUB/api/v1/me" -H "Authorization: Bearer $DEVHUB_KEY"创建 Agent 和 Session
Section titled “创建 Agent 和 Session”可以创建空白 Agent,也可以传入 GET /api/v1/examples 列出的 Official Example 的 exampleId 来复制它。用 PATCH /api/v1/agents/{agentId} 设置它的指令、默认模型、语音、Session Recall 和 Official Skill;GET /api/v1/models 列出可指定的文本和 Realtime 模型,GET /api/v1/skills 列出可选择的 Official Skill,以及每个要传入的版本。
curl -X POST "$DEVHUB/api/v1/agents" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: agent-weather-1' \ -H 'Content-Type: application/json' \ -d '{"name":"Travel helper"}'curl -X PATCH "$DEVHUB/api/v1/agents/agt_..." \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Content-Type: application/json' \ -d '{"voice":{"language":"en-US","standingTask":null},"sessionRecall":true,"skills":[{"id":"osk_...","version":1}]}'Session 是与一个 Agent 的一次对话。它以 Agent 当时的配置开始;之后对 Agent 的修改只影响新的 Session。
curl -X POST "$DEVHUB/api/v1/sessions" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: session-trip-1' \ -H 'Content-Type: application/json' \ -d '{"agentId":"agt_..."}'每个创建资源或发送输入的请求都需要一个你为每项自选的 Idempotency-Key。应答丢失时,用同一个 Key 和请求体重复请求:它会完成或返回第一次的结果,绝不会创建第二项。在已用过的 Key 下发送不同的请求体会被拒绝,返回 409 idempotency_key_reused。
发送输入并跟随 Turn
Section titled “发送输入并跟随 Turn”输入启动一个 Turn,即 Agent 对它的处理。Turn 运行期间,新的文本输入会加入这个 Turn。
curl -X POST "$DEVHUB/api/v1/sessions/ses_.../turns" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: input-1' \ -H 'Content-Type: application/json' \ -d '{"input":"What should I pack for Paris tomorrow?"}'应答带有 turnId。以 Server-Sent Events 跟随该 Turn 的事件,直到它的 turn_finished 事件,然后读取已结束的 Turn:
curl -N "$DEVHUB/api/v1/sessions/ses_.../turns/<turnId>/events" -H "Authorization: Bearer $DEVHUB_KEY"curl "$DEVHUB/api/v1/sessions/ses_.../turns/<turnId>" -H "Authorization: Bearer $DEVHUB_KEY"每个 data 行是一个 JSON 事件;参考中的 SessionEvent 列出了全部事件。每收到一个 assistant_draft 就替换草稿,而不是追加;assistant_message 是已保存的回答。GET /api/v1/sessions/{sessionId}/events 改为流式传输整个 Session,断线后可从最后一帧的 id 续接。
Session 时间线可能包含平台发起的 Handoff Turn,其 kind 为 template_handoff。userMessages 是空数组,成功后会保存一条助手摘要。可以在 Session 事件流中跟踪 Handoff。按 ID 读取、订阅或取消单个 Turn 的接口适用于通过 DevHub 启动或追加过输入的 Turn。
给 Agent 文件
Section titled “给 Agent 文件”先把文件上传到 Session,再在启动 Turn 的输入中选择它。以 application/octet-stream 发送字节,文件名和媒体类型放在查询参数中:
curl -X POST "$DEVHUB/api/v1/sessions/ses_.../files?name=itinerary.pdf&contentType=application/pdf" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: file-itinerary-1' \ -H 'Content-Type: application/octet-stream' \ --data-binary @itinerary.pdf文件存储完成后才返回应答;它的 id(file_...)放进 fileIds:
curl -X POST "$DEVHUB/api/v1/sessions/ses_.../turns" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: input-2' \ -H 'Content-Type: application/json' \ -d '{"input":"Plan my day from this itinerary.","fileIds":["file_..."]}'- 单个文件最大 20 MiB,一个 Turn 最多选择 20 个文件。
- 只有你上传文件时所在 Session 的 Turn 能使用它。
- 带文件的输入只能启动 Turn。Turn 运行期间它会被拒绝并返回 409
session_has_active_turn;等该 Turn 结束后,用新的Idempotency-Key再次发送。 - 媒体类型为
image/的文件也会作为图片展示给模型。Session 的模型必须接受图片,并受平台的图片限制约束;否则 Turn 以说明原因的turn_error失败。
让 Agent 调用你的工具
Section titled “让 Agent 调用你的工具”Client Tool 是你的应用为 Agent 运行的函数,例如读取设备传感器或你自己的数据库。在 Session 上声明它们;每个声明包括名称、Agent 读到的描述,以及参数的 JSON Schema:
curl -X PUT "$DEVHUB/api/v1/sessions/ses_.../client-tools" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Content-Type: application/json' \ -d '{"tools":[{"type":"function","name":"get_weather","description":"Current weather for a city.","parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}]}'PUT 替换整个集合,Turn 使用它启动时的集合。为避免覆盖其他客户端的修改,把你上次读取或替换得到的 ETag 作为 If-Match 发送;集合已变化时返回 412。
Agent 调用 Client Tool 时,Turn 的事件流会带有一个 agent.session.turn.requires_action 事件:
{ "type": "agent.session.turn.requires_action", "sessionId": "ses_...", "turnId": "<turnId>", "createdAt": "...", "data": { "event": "client_tool_calls", "seq": 4, "payload": { "calls": [ { "callId": "<callId>", "name": "get_weather", "arguments": { "city": "Paris" }, "deadlineAt": "..." } ] } }}运行工具,并在每个调用的 deadlineAt 之前用它的 output 应答,或者用 Agent 会看到的 error 应答:
curl -X POST "$DEVHUB/api/v1/sessions/ses_.../turns/<turnId>/client-tool-results" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Content-Type: application/json' \ -d '{"callId":"<callId>","output":"Sunny, 24 °C"}'- 以同样方式应答每个调用:Agent 自己决定是否等待结果,而 Turn 只有在 Agent 看到所有结果后才结束。
- 截止时间前没有结果的调用以未知效果结束,由 Agent 决定如何继续;平台从不自行重复调用。
- 重复发送同一个结果是安全的。已有结果的调用会拒绝任何其他结果并返回 409
client_tool_call_settled,截止时间已过的调用也一样。 - 断线后,
GET /api/v1/sessions/{sessionId}/client-tool-calls列出仍在等待结果的调用,无论你是否收到过它们的事件。读取该列表不会改变什么:截止时间前没有结果的调用都以未知效果结束。
每个错误的形式都相同:{"error":{"code":"...","message":"..."}}。根据 code 分支处理;message 可能变化。不属于你的 id 一律返回 404 not_found,无论它是否存在。503 service_unavailable 是暂时的:稍后用同一个 Idempotency-Key 重试。
启动或引导 Turn 的输入会消耗你每月的 Credits。用完后输入被拒绝并返回 429 credits_exhausted,其 resetsAt 是下一个 UTC 月份的开始,届时 Credits 重置。Client Tool 结果仍会被接受,因此运行中的 Turn 可以结束。503 credits_unavailable 表示 DevHub 暂时无法检查你的 Credits:稍后用同一个 Idempotency-Key 重试。