---
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.

# 能力（规范）

一次运行向消费者展示智能体**做了什么**。能力让消费者在要求智能体做事之前了解它**能做什么**：是否流式输出推理、是否会为审批暂停、接受哪些模态、可能委派给哪些子智能体。应用据此塑造界面——只在接受文件处显示文件选择器，只在支持中断处显示审批控件——而不是靠试错发现支持情况。

[schema](https://docs.ag-ui.com/spec/1-0/schema#agentcapabilities) 定义形状：`AgentCapabilities`，一组 OPTIONAL 分组，每组是由 OPTIONAL 字段构成的对象。本页陈述声明带来的义务，并刻意**不**规定消费者如何**获得**声明。

## 声明

**省略字段表示未声明，而不是不支持。** 对 `reasoning` 只字未提的智能体并没有说自己不能推理；消费者 MUST NOT 从缺少声明推断缺少能力。智能体若想表示某能力**不**支持，布尔字段的存在正是为了显式携带 `false`。

生产者 SHOULD 只声明它实际会做的。声明是对应用关于如何为运行做准备的陈述；智能体不遵守的声明会误导基于它构建的界面。没有义务把所有能力都声明为 true——最小声明也是一致的——但已声明的内容 SHOULD 成立。

**声明是信息性的，不是约束性的。** 事件流才是权威：消费者 MUST NOT 因为出现了声明未预期的事件，或因为已声明能力未被使用，就拒绝流或把运行视为失败。在 `reasoning: { supported: false }` 下发射推理事件的运行，其生产者值得抱怨，但流不值得拒绝。

## 分组

各分组划分协议特性。当某分组描述的是事件族时，该族页面规定事件本身的义务；声明只是对其作出预期。

| 分组 | 声明内容 | 受谁约束 |
| --- | --- | --- |
| `identity` | 名称、框架、版本、提供商、文档，以及开放的 `metadata` 对象 | 本页 |
| `transport` | 智能体提供哪些[传输绑定](https://ag-ui.ndjp.net/spec/1-0/basic/transports/) | [传输](https://ag-ui.ndjp.net/spec/1-0/basic/transports/) |
| `tools` | 是否调用工具、**提供**哪些工具、是否接受应用的工具 | [工具调用](https://ag-ui.ndjp.net/spec/1-0/events/tool-calls/) |
| `output` | 结构化输出与可生成的 MIME 类型 | — |
| `state` | 快照、增量、跨运行持久化、长期记忆 | [状态](https://ag-ui.ndjp.net/spec/1-0/events/state/) |
| `multiAgent` | 委派、交接，以及可调用的 `subagents` | [子智能体](https://ag-ui.ndjp.net/spec/1-0/events/subagents/) |
| `reasoning` | 是否发射推理、是否流式、是否加密 | [推理](https://ag-ui.ndjp.net/spec/1-0/events/reasoning/) |
| `multimodal` | 作为 `input` 接受、作为 `output` 产生的模态 | `input` 见[运行输入](https://ag-ui.ndjp.net/spec/1-0/basic/run-input/#messages)；`output` 见下 |
| `execution` | 代码执行、沙箱、迭代与时间限制 | — |
| `humanInTheLoop` | 审批、干预、反馈，以及是否参与中断–恢复 | [中断与恢复](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/interrupt-resume/) |
| `custom` | 标准分组未覆盖的任何内容 | — |

### 声明了但本版本不承载的内容

`output.structuredOutput` 声明智能体可以把回答塑造成 schema，但本版本协议没有让消费者提供 schema 的字段，也没有把输出标识为结构化的事件。声明告诉应用智能体有能力；schema 如何到达智能体、塑造后的回答如何返回，属于集成特定细节，消费者 MUST NOT 期望标准事件携带任一方。

`multimodal.output` 声明智能体能**产生**什么，但本版本协议未定义图片或音频输出：助手消息内容与 `TEXT_MESSAGE_CONTENT` 的 delta 都是文本。该声明是给应用的——应用可能通过集成特定通道收到此类输出——本规范不规定它如何传输。消费者 MUST NOT 期望标准事件携带它。

`tools.items` 列出**智能体**提供的工具——它自己的函数、搜索、代码执行——与 `RunAgentInput.tools`（应用为一次运行提供的工具）不同。两者永不合并：智能体自己的工具不是应用要执行的，应用的工具也不在此声明。

两个 `transport` 标志同样描述本版本未定义的机制。`transport.resumable` 指按序列号恢复中断的流，`transport.pushNotifications` 指运行结束后的投递；两个 [HTTP 绑定](https://ag-ui.ndjp.net/spec/1-0/basic/transports/)都不携带序列号、不恢复流，也未定义运行后通道。智能体 MAY 为其自有传输声明它们；消费者 MUST NOT 期望标准绑定兑现。

## `identity.metadata` 与 `custom`

两个开放对象承载标准字段未覆盖的内容。`identity.metadata` 是协议的 [Metadata](https://ag-ui.ndjp.net/spec/1-0/basic/metadata/) 形状——按 key 开放、key 下任意 JSON 值——用于集成特定的身份信息。`custom` 是不适合任何标准分组的能力的逃生舱。两者都按 key 开放：消费者 MUST 保留其中不认识的内容，而不是像元数据一样剥离。协议不赋予两者任何含义。

## 获取（Retrieval）

本规范定义声明的形状及其义务，**不**定义消费者如何获得声明。本版本没有任何传输绑定携带能力交换，本页也不创建它：能力是从客户端智能体对象的方法读取、从应用定义的端点获取，还是静态配置，都是实现的事。

这是刻意的。发现协议比声明形状是更大的承诺，而形状本身在没有发现协议时也有用。以任何方式暴露能力的实现 MUST 使用该形状。

## 错误处理

能力对象不经事件管道传输，因此[处理模型](https://ag-ui.ndjp.net/spec/1-0/basic/processing/)的剥离义务不适用于它；但该模型对**未识别**与**格式错误**的区分适用。未识别成员——本版本未定义的分组或字段——是严格层的事，不是消费者的事：schema 封闭每个能力对象，因此这样的文档无法通过验证，但消费者 MUST NOT 因声明携带它们而拒绝，使更新智能体的声明不会在旧消费者处弹回。能力不经过事件管道的执行阶段，因此消费者保留还是丢弃未识别成员是实现的事，一致实现之间可以不同。已知字段携带 schema 拒绝的值——布尔位置出现字符串——是格式错误，消费者 MUST NOT 使用无法验证的声明。

由于声明是信息性的，被拒绝或缺省的声明 MUST NOT 阻止运行。无法获得或验证能力的消费者，按智能体未声明任何内容那样继续。

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