一次识图任务的完整流程
会话代表一段多轮上下文,Run 代表其中一次业务任务。第三方系统保存两个 ID,就能持续查询任务。
- 01创建能力会话业务方选择
vision、image_generation、image_tools,DSH 根据用户自然语言选择工具。 - 02提交图片和目标获得
run_id,任务先进入 queued 状态。 - 03选择一种结果接口按游标轮询,或建立独立的 Run SSE;出现问题时提交回答。
- 04读取交付结果vision 在 completed 后读取
result.data;其他能力按result.type读取。
一个 POST 完成命令提交与 SSE 推流
V2 面向新业务:请求体提交 JSON,同一个 HTTP 响应直接返回 SSE ReadableStream。V1 的 ACK、轮询和独立 SSE 保持不变。
/v2/sessions/messages命令 + SSEcurl -N -X POST https://agent.example.com/v2/sessions/messages \
-H "Authorization: Bearer $IMAGE_AGENT_KEY" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"session_id": "SESSION_ID",
"request_id": "creator-message-1001",
"action": "message",
"text": "识别图片中的商品和价格"
}'
id: 1
event: run.queued
data: {"session_id":"...","run_id":"...","code":"RUN_QUEUED","stage":"queued"}
id: 2
event: run.running
data: {"session_id":"...","run_id":"...","code":"ANALYZING_IMAGE","stage":"analyzing"}
id: 3
event: run.completed
data: {"session_id":"...","run_id":"...","result":{"type":"json","data":{}},"artifacts":[]}
message 创建 Run;answer 携带 question_id/text;steer 追加指令;cancel 取消;observe 携带 run_id,只恢复当前快照和后续事件。observe 外必须传全局唯一的 request_id。断流后以相同 ID 和相同请求重发不会重复执行;相同 ID 对应不同请求返回 409 idempotency_conflict。input.required、run.completed、run.failed、run.cancelled 发送后关闭响应。关闭浏览器 Stream 不会取消 Run。五种 action 的请求体
{
"session_id": "SESSION_ID",
"request_id": "req-message-1",
"action": "message",
"text": "分析图片",
"resources": [],
"time_zone": "Asia/Shanghai"
}
{"session_id":"SESSION_ID","request_id":"req-answer-1","action":"answer","question_id":"QUESTION_ID","text":"竖版,整体使用复古电影风格"}
{"session_id":"SESSION_ID","request_id":"req-steer-1","action":"steer","text":"重点分析右下角"}
{"session_id":"SESSION_ID","request_id":"req-cancel-1","action":"cancel"}
{"session_id":"SESSION_ID","action":"observe","run_id":"RUN_ID"}
message 和 steer 可以携带与 V1 相同的 resources/time_zone。旧版 images 字段仅保留兼容。observe 不执行命令,所以 request_id 可省略。其他 action 缺少合法 request_id 时返回 400 invalid_request_id。
answer.text 原样交给 Harness,并作为本批每个待回答问题的自然语言上下文提交。业务方无需拆分多个问题或匹配选项标签;信息仍不充分时,Harness 会再次返回 input.required。原有结构化 answers 继续兼容。通过 fetch 读取 ReadableStream
原生 EventSource 不能发送 POST JSON 和 Bearer Header,因此业务服务应使用 fetch()。网络 chunk 不是事件边界,必须累积到空行后再拆分 SSE block。
const response = await fetch(`${IMAGE_AGENT_URL}/v2/sessions/messages`, {
method: 'POST',
headers: {
Authorization: `Bearer ${IMAGE_AGENT_KEY}`,
'Content-Type': 'application/json',
Accept: 'text/event-stream',
},
body: JSON.stringify({
session_id,
request_id,
action: 'message',
text: '分析图片',
}),
})
if (!response.ok) throw new Error((await response.json()).error?.code)
if (!response.body) throw new Error('missing_response_stream')
const reader = response.body.getReader()
const decoder = new TextDecoder()
let buffer = ''
for (;;) {
const { value, done } = await reader.read()
buffer += decoder.decode(value || new Uint8Array(), { stream: !done })
.replaceAll('\r\n', '\n')
let boundary = buffer.indexOf('\n\n')
while (boundary >= 0) {
const block = buffer.slice(0, boundary)
buffer = buffer.slice(boundary + 2)
const lines = block.split('\n')
const type = lines.find(line => line.startsWith('event:'))?.slice(6).trim()
const dataRaw = lines.filter(line => line.startsWith('data:'))
.map(line => line.slice(5).trimStart()).join('\n')
let data
try { data = JSON.parse(dataRaw) } catch {}
if (type) handleAgentEvent({ type, dataRaw, data })
boundary = buffer.indexOf('\n\n')
}
if (done) break
}
event:。即使 data 不是 JSON,也必须保留并处理外层的 completed、failed 或 cancelled 事件。/v2/sessions/history持久化历史curl -X POST https://agent.example.com/v2/sessions/history \
-H "Authorization: Bearer $IMAGE_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{"session_id":"SESSION_ID","run_id":"RUN_ID"}'
run_id 可省略。history 返回请求摘要、受控事件、问题、结果、错误和产物,不返回 Base64 图片、模型输入、工具参数、工具原始输出或隐藏推理。最新 Run 仍在运行时,再发送 action: "observe" 继续接流。
{
"session": {"id":"SESSION_ID","status":"running","capabilities":["vision"]},
"session_id": "SESSION_ID",
"last_run_id": "RUN_ID",
"last_status": "running",
"runs": [{
"run_id": "RUN_ID",
"status": "running",
"code": "ANALYZING_IMAGE",
"stage": "analyzing",
"requests": [],
"responses": [],
"events": [],
"input_required": null,
"result": null,
"error": null,
"artifacts": []
}]
}
断流与刷新恢复
- 01查询 history使用已保存的
session_id,不要直接生成新 ID 重发 message。 - 02直接恢复边界状态completed、failed、cancelled 或 waiting_input 直接从 history 恢复页面。
- 03重新观察运行中 Runqueued、running 或 cancelling 使用 history 返回的
run_id发起action: "observe"。 - 04必要时安全重试原请求重试必须复用相同
request_id和完全相同的业务内容;新 ID 表示新的业务操作。
0. 配置业务后端
业务服务只需要保存 Image Agent 的 HTTPS 地址和一把管理员签发的 API Key。以 PhotoStyle 为例,在业务服务中配置:
IMAGE_AGENT_URL=https://agent.example.com
IMAGE_AGENT_KEY=replace-with-a-random-32-byte-secret
Image Agent 运维侧把同一个 Key 放入认证允许列表:
GATEWAY_API_KEYS=replace-with-a-random-32-byte-secret
IMAGE_AGENT_KEY 与 GATEWAY_API_KEYS 中的某一个值必须完全一致。它们是同一把逻辑 Key 在调用方和校验方的不同变量名;IMAGE_AGENT_URL 只是地址。因此跨两个服务共有 3 个环境变量,但只有 URL 和共享 Key 两项实际配置值。VISION_ONLY_API_KEYS 和 IMAGE_TOOLS_API_KEYS 仍可用于认证,但不再绑定任何能力;新部署统一使用 GATEWAY_API_KEYS。vision 和 image_generation,能力不会写入 Key。/v1/auth/check。401 unauthorized 表示 Key 缺失或两侧不一致。1. 验证访问密钥
向管理员申请身份认证 Key,将它保存为业务后端的 IMAGE_AGENT_KEY,并在每个请求的 Authorization Header 中携带。管理员可在 /admin/keys 即时签发独立 Key,无需重新部署。可以先调用检查接口确认 Key 有效。
/v1/auth/check检查 Key 是否有效curl https://agent.example.com/v1/auth/check \
-H "Authorization: Bearer $IMAGE_AGENT_KEY"
{"ok":true,"mode":"api_key","supported_capabilities":["vision","image_generation","image_tools"],"user":null}Session 独立声明图片处理能力
vision 由 GLM-5.3-Flash 主控直接查看图片,image_generation 通过 dsh-image-studio 提供文生图和图生图修改,image_tools 是仅保留确定性 image_colors 的兼容能力。
业务在创建 Session 时声明能力;Key 不携带能力信息。用户每轮直接说自然语言,Harness 自主选择工具,并通过 artifacts 返回最终回复明确选择的文件。
curl -X POST https://agent.example.com/v1/sessions \
-H "Authorization: Bearer $IMAGE_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{"capabilities":["vision","image_generation","image_tools"],"client_reference":"product-cutout-1001"}'
curl -X POST https://agent.example.com/v1/sessions \
-H "Authorization: Bearer $IMAGE_TOOLS_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{"capabilities":["vision","image_tools"],"client_reference":"product-crop-1002"}'
artifacts 数组返回 Image Studio 生成、修改或通过 vision_present 明确交付的最终图片;reply 只包含给用户看的说明。2. 创建能力会话
业务方只用 capabilities 声明 Session 可使用的能力:vision 由 GLM 主控原生看图,image_generation 生成或修改图片,旧的 image_tools 仅提供确定性取色。用户每轮只发送自然语言,具体工具由 DSH 自主选择。
/v1/sessions创建会话curl -X POST https://agent.example.com/v1/sessions \
-H "Authorization: Bearer $IMAGE_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"capabilities": ["vision", "image_generation"],
"client_reference": "order-1001"
}'
{
"id": "7a34...",
"created_at": "2026-08-17T10:00:00.000Z",
"status": "idle",
"capabilities": ["image_generation", "vision"],
"client_reference": "order-1001"
}
3. 提交消息与图片资源
text 直接发送用户本轮原话,不要再包 Planner 模板。所有图片统一放入 resources:本地图片传纯 Base64 data,已托管图片传 url,两者只能二选一。每轮最多 10 个资源,单张最大 10MB,请求体最大 16MB。
/v1/sessions/{session_id}/messages创建 Runmodequeue | steer可选,默认 queuetextstring与 resources 至少提供一项resources统一图片资源数组可选,最多 10 张;每项使用 url 或 Base64 datatime_zonestring可选,默认 Asia/Shanghaicurl -X POST \
https://agent.example.com/v1/sessions/SESSION_ID/messages \
-H "Authorization: Bearer $VISION_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "queue",
"text": "识别商品名称、价格和主要宣传文字",
"resources": [{
"resource_id": "product-v1",
"media_type": "image/jpeg",
"name": "product.jpg",
"data": "BASE64_DATA"
}]
}'
{"accepted":true,"session_id":"...","run_id":"..."}image/png、image/jpeg、image/webp、image/gif业务侧已经托管图片时,在同一个 resources 数组中改传 url 即可。Gateway 不做前置识图或下载,完整 URL 会作为原生多模态图片块直接交给 GLM;Base64 图片仍会落盘并作为持久附件发送。
curl -X POST \
https://agent.example.com/v1/sessions/SESSION_ID/messages \
-H "Authorization: Bearer $VISION_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "queue",
"text": "去掉当前杂志封面右下角的条形码",
"resources": [{
"resource_id": "cover-v1",
"url": "https://cdn.example.com/cover.png?SIGNED_QUERY",
"width": 1536,
"height": 2048
}]
}'
session_id 读取此前全部业务请求与 Agent 响应,保留各轮重复的 resources,并通过 Session 资源映射还原当前 URL 或会话内路径。历史资源的 index 只属于原轮次,本轮 referenceImageIndexes 仍只对应本轮 resources。resource_idstring必填;1–200 字符,同一 Session 内内容不可变urlstring与 data 二选一;HTTP(S),允许签名查询参数,不允许嵌入用户名或密码datastring与 url 二选一;纯 Base64,不带 data URL 前缀namestring可选;展示名称,最多 240 字符media_typestringBase64 必填;URL 可选width / heightpositive integer可选;仅作为资源元数据3A. 查询业务请求和 JSON 返回
每次消息调用都会在对应 Run 中持久化业务追踪记录。所有图片统一记录资源 ID、来源类型、URL 或会话内路径、元数据和实际提交给 Harness 的当前轮 Message;Base64 正文不会持久化。
/v1/sessions/{session_id}/runs/{run_id}/trace读取业务往返curl \
https://agent.example.com/v1/sessions/SESSION_ID/runs/RUN_ID/trace \
-H "Authorization: Bearer $VISION_AGENT_KEY"
{
"session_id": "...",
"run_id": "...",
"requests": [{
"request_id": "...",
"mode": "queue",
"text": "去掉条形码",
"resources": [{
"index": 0,
"resource_id": "cover-v1",
"source_type": "url",
"url": "https://cdn.example.com/cover.png?SIGNED_QUERY",
"width": 1536,
"height": 2048
}],
"model_input_text": "去掉条形码……完整 URL……图片已作为原生多模态内容提供……"
}],
"responses": [{
"kind": "accepted",
"http_status": 202,
"accepted": true
}, {
"kind": "agent_result",
"http_status": 200,
"result": {
"type": "json",
"data": { "reply": "已完成", "intent": "reply", "suggestedTitle": "图片任务", "generationItems": [] }
}
}]
}
4A. 轮询阶段和最终结果
运行期间建议每秒轮询一次。把响应中的 next_cursor 用作下一次 after,终态后立即停止轮询。前端使用稳定的 code 选择国际化文案,未知码按 stage 显示大阶段兜底;可选的 message 只用于日志和调试。
/v1/sessions/{session_id}/runs/{run_id}读取 Runcurl "https://agent.example.com/v1/sessions/SESSION_ID/runs/RUN_ID?after=0&limit=50" \
-H "Authorization: Bearer $VISION_AGENT_KEY"
{
"session_id": "...",
"run_id": "...",
"capabilities": ["vision"],
"status": "running",
"code": "ANALYZING_IMAGE",
"stage": "analyzing",
"events": [{
"id": 3,
"time": "2026-08-17T10:00:02.000Z",
"code": "ANALYZING_IMAGE",
"stage": "analyzing",
"state": "active",
"message": "正在分析图片内容"
}],
"next_cursor": 3,
"has_more": false,
"input_required": null,
"artifacts": [],
"result": null,
"error": null
}
{
"status": "completed",
"code": "RUN_COMPLETED",
"stage": "completed",
"artifacts": [],
"result": {
"type": "json",
"data": {
"reply": "已准备好图片处理方案",
"intent": "edit",
"suggestedTitle": "商品图编辑",
"generationItems": [{
"prompt": "完整的图片编辑提示词",
"aspectRatio": "3:4",
"referenceImageIndexes": [0]
}]
}
},
"error": null
}
after 必须是非负整数;limit 默认 50,最大 100。4B. 通过 SSE 接收结果
Run SSE 是独立接口,不要求先调用轮询接口,也不会自动降级为轮询。它只返回受控业务阶段、补充问题、最终结果、产物和安全错误,不返回工具参数、工具原始输出或隐藏思维链。
/v1/sessions/{session_id}/runs/{run_id}/events订阅 Runcurl -N \
https://agent.example.com/v1/sessions/SESSION_ID/runs/RUN_ID/events \
-H "Authorization: Bearer $VISION_AGENT_KEY" \
-H "Accept: text/event-stream"
id: 3
event: run.progress
data: {"id":3,"type":"run.progress","data":{"session_id":"...","run_id":"...","capabilities":["vision"],"status":"running","code":"ANALYZING_IMAGE","stage":"analyzing","state":"active","time":"...","message":"正在分析图片内容"}}
id: 4
event: run.completed
data: {"id":4,"type":"run.completed","data":{"session_id":"...","run_id":"...","status":"completed","code":"RUN_COMPLETED","stage":"completed","result":{"type":"json","data":{"reply":"已准备好方案","intent":"edit","suggestedTitle":"商品图编辑","generationItems":[{"prompt":"完整提示词","aspectRatio":"3:4","referenceImageIndexes":[0]}]}},"artifacts":[]}}
fetch 携带 Bearer Header;原生 EventSource 无法设置该 Header。断线后把最后处理的数字 ID 放入 Last-Event-ID,终态事件发送后连接会关闭。run.queued、run.progress、input.required、run.cancelling、run.completed、run.failed、run.cancelled5. 回答补充问题
当轮询 status 为 waiting_input,或 SSE 收到 input.required 时,读取 input_required。waiting_input 只表示 Run 暂停等待用户;前端控件由 input_required.mode 和每题的 inputType 决定。一次请求可以包含多个问题;提交答案后继续读取原来的 run_id。
{
"status": "waiting_input",
"input_required": {
"question_id": "QUESTION_ID",
"mode": "select",
"questions": [{
"id": "cover_style",
"header": "选择新风格",
"question": "您希望把封面换成哪种风格?",
"inputType": "single_select",
"options": [{
"label": "高级时装 · 极简黑白 (Recommended)",
"description": "黑白大片感、超大标题和利落留白"
}, {
"label": "复古杂志 · 70 年代",
"description": "奶油色底、复古衬线字体和暖色调"
}],
"multiSelect": false
}]
}
}
mode 为 select、text 或 mixed。每题的 inputType 为 single_select、multi_select 或 text;客户端不需要再通过 options 是否为空猜测控件类型。single_select 渲染单选卡片,multi_select 渲染复选卡片,text 渲染多行文本框;mixed 按每题的 inputType 同屏组合。卡片以 label 为主标题、description 为辅助说明,整批问题使用一个“确认并继续”按钮提交。id 和 question 必填;header 是可选短标题。选择题携带非空 options,每项包含 label 和可选的 description;文本题的 options 固定为空数组。multiSelect 是兼容字段,仅在 inputType: "multi_select" 时为 true。selected 使用选项的 label,不是数组下标,并且不能包含重复值。单选最多包含一个值,多选可以包含多个值。自由文本问题必须提交空的 selected,并把文本放入 custom;多选问题也可以同时携带 custom 作为“其他”答案。/v1/sessions/{session_id}/questions/{question_id}提交回答curl -X POST \
https://agent.example.com/v1/sessions/SESSION_ID/questions/QUESTION_ID \
-H "Authorization: Bearer $VISION_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"answers": [{
"id": "cover_style",
"selected": ["高级时装 · 极简黑白 (Recommended)"]
}]
}'
{
"question_id": "QUESTION_ID",
"mode": "text",
"questions": [{
"id": "custom_style",
"question": "请描述想要的风格",
"inputType": "text",
"options": [],
"multiSelect": false
}]
}
{
"answers": [{
"id": "custom_style",
"selected": [],
"custom": "深蓝色背景,保留人物照片"
}]
}
// 回答流程已结束;答案已接收或问题已失效
{"status":0,"data":{"next_action":"poll_run"}}
// 继续选择或输入;question_id 保持有效
{"status":1001,"data":{"run_status":"waiting_input","input_required":{"question_id":"QUESTION_ID","mode":"select","questions":[]}}}
// Harness 暂时不可用;保留问题,稍后重试
{"status":2001,"data":{"run_status":"waiting_input","input_required":{"question_id":"QUESTION_ID","mode":"select","questions":[]}}}
answers 必须覆盖全部问题,并保持与 questions 相同的顺序;每项的 id 对应同位置的问题 id。已鉴权且 JSON 合法的回答业务状态统一返回 HTTP 200,业务侧读取数字 status:0 表示回答流程已结束并继续查询原 Run,1001 表示继续展示 input_required,2001 表示保留当前问题并稍后重试。同一个 question_id 仅在 status: 0 后消费。6. 给当前任务追加指令
mode: "steer" 不创建新业务 Run,而是关联当前正在执行的 Run,响应会返回相同的 run_id。
curl -X POST \
https://agent.example.com/v1/sessions/SESSION_ID/messages \
-H "Authorization: Bearer $VISION_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "steer",
"text": "重点识别图片右下角的小字"
}'
7. 取消任务
取消请求接受后 Run 会先进入 cancelling,随后变为 cancelled。进入终态后停止轮询或结束 SSE。
/v1/sessions/{session_id}/cancel取消当前任务curl -X POST \
https://agent.example.com/v1/sessions/SESSION_ID/cancel \
-H "Authorization: Bearer $VISION_AGENT_KEY"
可直接改造的轮询后端示例
这段 Node.js 代码可直接从本地文件读取图片并执行一次完整任务。生产代码应设置请求超时,并把 session_id、run_id 与你的业务记录一起保存。
import { readFile } from 'node:fs/promises'
const BASE_URL = process.env.IMAGE_AGENT_URL
const API_KEY = process.env.IMAGE_AGENT_KEY
const imageBase64 = (await readFile('./product.jpg')).toString('base64')
async function request(path, options = {}) {
const response = await fetch(`${BASE_URL}${path}`, {
...options,
headers: {
Authorization: `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
...options.headers,
},
})
const body = await response.json()
if (!response.ok) throw new Error(body.error?.code || 'api_error')
return body
}
const session = await request('/v1/sessions', {
method: 'POST',
body: JSON.stringify({
capabilities: ['vision', 'image_generation'],
client_reference: 'order-1001',
}),
})
const accepted = await request(`/v1/sessions/${session.id}/messages`, {
method: 'POST',
body: JSON.stringify({
mode: 'queue',
text: '提取图片中的商品名称、价格和文案',
resources: [{
resource_id: 'product-v1',
media_type: 'image/jpeg',
name: 'product.jpg',
data: imageBase64,
}],
}),
})
let cursor = 0
while (true) {
const run = await request(
`/v1/sessions/${session.id}/runs/${accepted.run_id}` +
`?after=${cursor}&limit=50`
)
cursor = run.next_cursor
for (const event of run.events) console.log(event.message)
if (run.status === 'completed') {
console.log(run.result.data)
for (const artifact of run.artifacts || []) console.log(`${BASE_URL}${artifact.url}`)
break
}
if (run.status === 'waiting_input') {
console.log('需要回答:', run.input_required)
break
}
if (['failed', 'cancelled'].includes(run.status)) {
throw new Error(run.error?.code || run.status)
}
await new Promise(resolve => setTimeout(resolve, 1000))
}
状态说明
queued已接受,等待执行继续等待running正在规划、识图或整理结果继续等待waiting_input需要调用方回答问题提交 answerscancelling正在处理中断请求继续等待completed任务完成按 result.type 读取 data 或 text,并停止failed任务失败读取 error.code 并停止cancelled任务已取消停止轮询稳定进度码
code 是精确进度和国际化 key,stage 是稳定的大阶段兜底。Gateway 根据受控事件生成进度码,不解析也不依赖 Agent 文案。同一大阶段内出现不同进度码时会产生不同事件。
RUN_QUEUEDqueued任务已进入队列RUNNING未知阶段兼容未知或旧阶段的通用执行中状态PLANNING_TASKplanning理解任务并制定步骤RESUMING_TASKplanning收到补充信息后继续ANALYZING_IMAGEanalyzing查看或描述图片LOCATING_IMAGE_TARGETanalyzing定位图片目标DETECTING_IMAGE_ELEMENTSanalyzing检测图片元素EXTRACTING_IMAGE_COLORSanalyzing提取图片配色RECOGNIZING_IMAGE_TEXTanalyzing识别图片文字RECOGNIZING_LONG_IMAGE_TEXTanalyzing识别长图文字GENERATING_IMAGEgenerating生成图片EDITING_IMAGEediting编辑图片CROPPING_IMAGEediting裁剪图片COMPARING_IMAGE_DIFFERENCESediting比较图片差异VECTORIZING_IMAGEediting矢量化图片REMOVING_IMAGE_BACKGROUNDediting移除图片背景PREPARING_IMAGE_ARTIFACTediting整理图片产物VALIDATING_RESULTfinalizing校验最终交付结果RESULT_VALIDATEDfinalizing最终交付结果已通过校验SYNTHESIZING_RESULTsynthesizing整理分析结果REVISING_RESULTplanning交付校验失败后调整方案RETRYING_STEPplanning执行步骤失败后重试INPUT_REQUIREDwaiting_input等待调用方补充信息RUN_CANCELLINGcancelling正在取消任务CANCEL_REQUEST_FAILEDplanning取消未生效,任务继续RUN_COMPLETEDcompleted任务完成RUN_FAILEDfailed任务失败RUN_CANCELLEDcancelled任务已取消process.${event.code};未识别的 code 使用 stage 对应的“执行中 / 等待输入 / 已完成 / 失败”等通用文案。不要把 message 作为用户界面文案。常见错误码
HTTP 错误统一使用 { "error": { "code": "...", "message": "..." }, "request_id": "..." },同一个 ID 也会出现在 X-Request-Id 响应头。运行时 Agent 错误位于 Run 的 error 字段,并带可供服务端查日志的 incident_id。
unauthorizedKey 缺失或无效invalid_capabilitiescapabilities 缺失、为空或包含未知能力unsupported_field调用方传入了 capability 或 agent_presetinvalid_image_input图片格式、数量、Base64 或大小无效invalid_resource_inputresources 数量、resource_id、URL/Base64 来源无效steer_unavailable当前没有可追加指令的 Runrun_not_foundRun 不存在或不属于此会话invalid_cursorafter 不是非负整数invalid_limitlimit 不在 1 到 100 之间model_not_configured服务端模型凭据缺失,联系管理员处理model_migration_failed已有 Session 无法切换到 GLM 主控resource_unavailable模型服务无法读取业务提供的远程图片 URLagent_errorAgent 异步失败,向管理员提供 incident_idmissing_deliverableHarness 结束前没有提交通过校验的最终交付物service_restarted任务被 Gateway 重启中断业务接口返回什么,不返回什么
- 受控阶段状态
- 需要回答的问题
- 已验证交付结果
- 安全错误码
- 隐藏思维链
- 工具参数
- 工具原始输出
- Shell、文件或 Web 能力
Key 只负责身份认证,Session 独立声明 capabilities。认证成功后,调用方可以访问自己创建的 Session 原始 /events SSE 和受控的 Run 级 /runs/{run_id}/events;不同 Key 的 Session 仍然相互隔离。处理文件保存在当前会话的 outputs/ 内,只有最终回复明确选择的产物会通过 artifacts 下载。