Agent 调用约定
多轮、工具、结构化输出与长文本
型号与协议
调用前确认模型 ID、Key 和协议，并发送一次目标请求。Agent 应沿用用户指定的模型；失败时报告原因，未经确认不更换型号。
多轮与工具
应用负责保存对话历史，包括原始 assistant / model 消息、工具调用 ID、推理项和签名。工具结果与原调用逐一对应。Chat 使用 tool_call_id，Responses 使用 call_id，Claude 使用 tool_use_id，Gemini 使用 functionResponse，字段格式各不相同。
模型返回工具调用后，由应用校验 JSON Schema、函数名、路径和权限，再执行操作。有副作用的操作还需检查授权。执行结果返回模型后，继续读取最终答复；模型本身不会替应用执行外部动作。
完整程序见 tools.py。设置对应型号的 YUNQIAI_MODEL 后，运行 python tools.py responses、python tools.py messages 或 python tools.py chat。示例只读取内置订单，不访问外部系统；tool_choice 保持与推理模式兼容。当前 Gemini 接入暂不支持原生工具结果回传，示例不提交 functionResponse，也不改用其他协议。
长文本与结构化输出
上下文长度包含系统指令、消息、文件、图片、推理和工具结果。输出另有预算限制；可输入的文本长度与单次可生成的文本长度不同。
长篇写作可按章节组织，并保存人物设定、已写段落和后续情节。响应以 length / max_tokens / MAX_TOKENS / incomplete 结束时，先保存正文，再按用户需求续写；此时内容尚未完成。
http-client.py 支持 --prompt-file script.txt --stream --max-output-tokens 16384，从 UTF-8 文件读取输入并设置输出预算。预算需在所选型号的范围内。程序会检查流式结束状态，遇到截断时报错。生成长度仍需由应用核对，长篇内容还应检查章节是否完整、人物设定是否前后一致。
结构化输出使用对应协议的 JSON Schema 字段。收到响应后，先检查结束状态，再解析 JSON 并在本地校验 Schema。代码围栏、拒绝响应和工具请求都需另行处理，不能直接作为业务 JSON。
| 协议 | JSON Schema 字段 |
|---|---|
| Responses | text.format，type=json_schema，含 name、schema、strict |
| Claude Messages | output_config.format，type=json_schema，含 schema；不包含 claude-opus-5-5 |
| Gemini | 暂不支持强制 JSON Schema；通过提示词要求 JSON 时，应用仍需解析和校验 |
| Chat Completions | response_format.type=json_schema，json_schema 内含 name、schema、strict |
将 structured.py 与 http-client.py 放在同一目录，安装 requests jsonschema。使用 result.schema.json 可运行 python structured.py responses --schema result.schema.json --prompt "按 Schema 返回 code、items 和 ok"。请按所选型号设置协议。输出无法解析或不符合 Schema 时，程序会报错，保留原响应和模型 ID。
claude-opus-5-5 也暂不支持强制 JSON Schema。普通文本任务可以要求返回 JSON，但代码围栏、额外文字和 Schema 不匹配仍需按校验失败处理。本站支持范围以本页为准。
超时、流式和重试
超时分为连接超时、首字节等待、读取超时和任务总时限。解析 SSE 时按空行分帧，同一事件的 UTF-8 和 JSON 可能跨多个 TCP 数据块。除文字增量外，还需处理错误事件和结束事件。
GET 查询可以有限次数退避重试。生成类 POST 超时或断开后，服务端可能已受理，重发前应先确认状态。MJ 收到 id 后继续查询原任务；Realtime 重连前先检查旧工具和音频状态，避免重复执行或重放。
接入检查
- 请求中没有硬编码 Key，日志不包含 Authorization、Cookie 和 Base64 客户文件。
- 请求使用指定型号和协议，响应正常结束且包含所需内容。
- 工具轮次完成调用、校验、执行、回传和最终答复。
- 文件任务能读取文件独有内容，图像结果符合参考图的对应关系。
- 流式能区分完成、截断、错误与网络中断。
- 401、权限、额度、限流、无渠道及格式错误有明确提示，出错后保留原模型 ID。
- 临时文件、图片 URL、任务 ID、会话连接和密钥均有对应的存储或清理策略。