---
title: "运行输入"
description: "1.0：从应用流向智能体的唯一消息，以及每个字段带来的义务。"
---

> Documentation Index
> Fetch the complete documentation index at: https://ag-ui.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 运行输入

事件从生产者流向消费者。只有一条消息反向流动：`RunAgentInput`，每次交换开始时发送一次。生产者关于会话所知的一切都通过它到达。它请求的运行是这次交换的最后一次运行；重放线程历史的流会[在无进一步输入的情况下](https://ag-ui.ndjp.net/spec/1-0/basic/transports/#绑定契约)携带更早的运行。

[schema](https://ag-ui.ndjp.net/spec/1-0/schema-files/) 定义其形状；本页陈述每个字段的义务。生产者 MAY 在 `RUN_STARTED.input` 上回显输入，使没有发起请求的消费者也能看到智能体被问了什么。

## 身份

`threadId` 命名会话，`runId` 命名本输入请求的运行；两者都是 **REQUIRED**。流上的每次运行都在其边界事件（`RUN_STARTED` 与 `RUN_FINISHED`，承载身份的两个）上携带输入的 `threadId`，且每次运行的两个边界事件 MUST 在 `runId` 上一致。被请求的运行回显本输入的 `runId`；重放的运行携带自己的。`parentRunId` 是 OPTIONAL，命名派生本次运行的那次运行——当智能体把另一个智能体作为独立运行（而非同一运行内的[子智能体](https://ag-ui.ndjp.net/spec/1-0/events/subagents/)）启动时。

## `protocolVersion`

schema 中为 OPTIONAL，因为缺失正是识别协议版本机制之前 peer 的方式——但实现本版本的消费者 MUST 在此声明它所说的版本，除非它知道 peer 早于该字段，此时省略该成员以避免旧解析器拒绝。生产者用自己在 `RUN_STARTED` 上的声明作答；规则见[版本与兼容](https://ag-ui.ndjp.net/spec/1-0/basic/versioning/#版本协商)。

## `messages`

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

消息类型与内容形状——包括携带文本、图片、音频、视频与文档的多模态 [`ContentPart`](https://docs.ag-ui.com/spec/1-0/schema#contentpart)，可经由 URL、内联数据或[提供商文件句柄](#提供方文件句柄)，出现在用户消息与回答[前端工具调用](https://ag-ui.ndjp.net/spec/1-0/events/tool-calls/#前端工具)的工具消息上——属于 schema。两条行为规则附着其上：

- 生产者无法使用某个内容部分时——例如只支持文本的模型收到图片——MUST NOT 因此让运行失败。跳过无法使用的内容并继续是一致行为；在降级的**出站**路径上丢失内容则是另一回事，必须警告（[版本与兼容](https://ag-ui.ndjp.net/spec/1-0/basic/versioning/)）。
- **活动消息永不回流给生产者**：消费者 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`](https://docs.ag-ui.com/spec/1-0/schema#tokenusage) 使用的小写厂商 id，使 peer 在发送前就能判断句柄是否可用。
- 生产者拿到无法解析的句柄——其他提供商的、未知提供商的、已过期的——正落在第一条规则覆盖的情形：MUST NOT 让运行失败，跳过该部分并继续，且 SHOULD 说明。句柄生命周期是提供商的事；想携带过期时间的信息放在该部分的 `metadata` 中。
- 来源分支是**封闭集合**：`type` 不被识别的 source 会使验证失败，而不是被透传。这正是该分支必须在 1.0 而非后续小版本出现的原因——为 1.0 构建的消费者永远不可能把它传下去。

## `tools`

OPTIONAL。应用自己的工具——**前端工具**——为本次运行提供给智能体：名称、描述，以及（当工具接受参数时）参数 schema。执行它们的是应用，不是智能体；调用其中一个会把控制权交回运行边界之外，往返流程见[工具调用](https://ag-ui.ndjp.net/spec/1-0/events/tool-calls/#前端工具)。

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

## `context`

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

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

## `state`

OPTIONAL。运行起始状态——消费者最后同意的值，通常是上一次运行的[状态事件](https://ag-ui.ndjp.net/spec/1-0/events/state/)留下的。缺失的 `state` 表示空对象：尚未同意任何内容，而 `{}` 就是没有内容。发射状态增量的生产者 MUST 以自己的首个快照替换它之前，针对该值计算增量。

## `forwardedProps`

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

## `resume`

OPTIONAL。对结束上一次运行的中断的回答，当本次运行从中断处继续时使用。条目及其义务见[中断与恢复](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/interrupt-resume/)。

## 错误处理

生产者无法解析的输入，或格式错误的输入——已知字段携带 schema 拒绝的值——会在 `RUN_STARTED` 之前通过传输的错误路径被拒绝：运行从未开始，也不存在可供 `RUN_ERROR` 传播的流。拒绝如何投递是各[传输绑定](https://ag-ui.ndjp.net/spec/1-0/basic/transports/)的事。

**输入的未识别成员不是格式错误。** [处理模型](https://ag-ui.ndjp.net/spec/1-0/basic/processing/)的不对称性同样约束这个方向：生产者遇到不认识的输入内容时，剥离并警告后继续运行，使更新消费者的输入不会在旧生产者处弹回。

Source: https://ag-ui.ndjp.net/spec/1-0/basic/run-input/index.mdx
