跳到主要内容

运行输入

1.0:从应用流向智能体的唯一消息,以及每个字段带来的义务。

事件从生产者流向消费者。只有一条消息反向流动:RunAgentInput,每次交换开始时发送一次。生产者关于会话所知的一切都通过它到达。它请求的运行是这次交换的最后一次运行;重放线程历史的流会在无进一步输入的情况下携带更早的运行。

schema 定义其形状;本页陈述每个字段的义务。生产者 MAY 在 RUN_STARTED.input 上回显输入,使没有发起请求的消费者也能看到智能体被问了什么。

身份

threadId 命名会话,runId 命名本输入请求的运行;两者都是 REQUIRED。流上的每次运行都在其边界事件(RUN_STARTED 与 RUN_FINISHED,承载身份的两个)上携带输入的 threadId,且每次运行的两个边界事件 MUST 在 runId 上一致。被请求的运行回显本输入的 runId;重放的运行携带自己的。parentRunId 是 OPTIONAL,命名派生本次运行的那次运行——当智能体把另一个智能体作为独立运行(而非同一运行内的子智能体)启动时。

protocolVersion

schema 中为 OPTIONAL,因为缺失正是识别协议版本机制之前 peer 的方式——但实现本版本的消费者 MUST 在此声明它所说的版本,除非它知道 peer 早于该字段,此时省略该成员以避免旧解析器拒绝。生产者用自己在 RUN_STARTED 上的声明作答;规则见版本与兼容。

messages

REQUIRED。到目前为会的话历史,按顺序。生产者 MUST 把它视为展示给它的完整历史——协议没有让更早轮次到达的旁路通道。

消息类型与内容形状——包括携带文本、图片、音频、视频与文档的多模态 ContentPart,可经由 URL、内联数据或提供商文件句柄,出现在用户消息与回答前端工具调用的工具消息上——属于 schema。两条行为规则附着其上:

  • 生产者无法使用某个内容部分时——例如只支持文本的模型收到图片——MUST NOT 因此让运行失败。跳过无法使用的内容并继续是一致行为;在降级的出站路径上丢失内容则是另一回事,必须警告(版本与兼容)。
  • 活动消息永不回流给生产者:消费者 MUST 在发送前把它们从 messages 中剥离。它们是消费者的渲染材料,不是智能体据此恢复的会话。

提供方文件句柄

媒体部分的 source 说明字节在哪里:内联携带(data)、可按 URL 获取(url),或已经在模型提供商处、以提供商签发的句柄表示(file)——OpenAI 或 Anthropic 文件 id、Gemini 文件 URI、只有该提供商能读取的存储 URL。

file 来源存在的原因是句柄既不是前两者:它不携带字节,除铸造它的提供商外无人可获取,放进 url 会诱使每个其他 peer 去抓取。

  • file 来源的 value 是不透明的。peer MUST NOT 抓取、解析或从中读出 scheme;它把句柄交给提供商,或者不使用该部分。
  • provider 在生产者知道时命名签发者。它是 OPTIONAL——智能体本就知道自己在与哪个提供商对话——存在时 SHOULD 使用 TokenUsage.provider 使用的小写厂商 id,使 peer 在发送前就能判断句柄是否可用。
  • 生产者拿到无法解析的句柄——其他提供商的、未知提供商的、已过期的——正落在第一条规则覆盖的情形:MUST NOT 让运行失败,跳过该部分并继续,且 SHOULD 说明。句柄生命周期是提供商的事;想携带过期时间的信息放在该部分的 metadata 中。
  • 来源分支是封闭集合:type 不被识别的 source 会使验证失败,而不是被透传。这正是该分支必须在 1.0 而非后续小版本出现的原因——为 1.0 构建的消费者永远不可能把它传下去。

tools

OPTIONAL。应用自己的工具——前端工具——为本次运行提供给智能体:名称、描述,以及(当工具接受参数时)参数 schema。执行它们的是应用,不是智能体;调用其中一个会把控制权交回运行边界之外,往返流程见工具调用。

缺省列表与空列表含义相同:没有工具。生产者 MUST 把缺失的 tools 完全当作空列表处理,消费者 MAY 省略空列表而不发送 []。

context

OPTIONAL。应用希望放入智能体上下文的信息,以描述–值对表示。它存在的目的是被注入:生产者 SHOULD 让每个条目作为本次运行 grounding 的一部分对模型可用。如何注入——系统提示、前言、框架如何使用上下文——是生产者的事;协议只说上下文是给模型看的,不是传输的记账。

缺失与空含义相同,与 tools 一致。

state

OPTIONAL。运行起始状态——消费者最后同意的值,通常是上一次运行的状态事件留下的。缺失的 state 表示空对象:尚未同意任何内容,而 {} 就是没有内容。发射状态增量的生产者 MUST 以自己的首个快照替换它之前,针对该值计算增量。

forwardedProps

OPTIONAL。应用特定的通道,原样传给智能体。除整个 null(表示字段省略)外的任何 JSON 值;载荷内部的 null 值被保留。协议不赋予载荷任何含义,中间层 MUST NOT 修改它。

resume

OPTIONAL。对结束上一次运行的中断的回答,当本次运行从中断处继续时使用。条目及其义务见中断与恢复。

错误处理

生产者无法解析的输入,或格式错误的输入——已知字段携带 schema 拒绝的值——会在 RUN_STARTED 之前通过传输的错误路径被拒绝:运行从未开始,也不存在可供 RUN_ERROR 传播的流。拒绝如何投递是各传输绑定的事。

输入的未识别成员不是格式错误。 处理模型的不对称性同样约束这个方向:生产者遇到不认识的输入内容时,剥离并警告后继续运行,使更新消费者的输入不会在旧生产者处弹回。

Type to search…

↑↓ navigate↵ selectEsc close