AG-UI 协议中的智能体可以通过**能力发现(capability discovery)**在运行时声明它支持什么。这使客户端可以查询智能体,并基于可用特性调整行为——无需猜测或硬编码假设。
工作原理
AbstractAgent 声明一个可选的 getCapabilities() 方法,返回智能体当前支持内容的类型化快照。它由了解自身能力的智能体子类实现——LangGraph 与 ADK 集成,或你自己的实现——而不是裸 HttpAgent,后者只是传输层,没有可询问的发现端点。对未实现该方法的智能体,下面的可选调用返回 undefined:
// 任何实现 getCapabilities() 的 AbstractAgent 子类;
// 普通 HttpAgent 不实现,这里会得到 undefined。
const agent = new LangGraphAgent({ url: "https://my-agent.example.com/api" })
const capabilities = await agent.getCapabilities?.()
if (capabilities?.tools?.supported) {
console.log(`Agent provides ${capabilities.tools.items?.length} tools`)
}
if (capabilities?.reasoning?.supported) {
// 显示推理 UI 开关
}关键原则
- 仅发现 —— 智能体声明它能做什么,没有协商
- 动态 —— 返回调用时刻的当前状态(例如新增工具后,下次调用会反映)
- 可选 —— 未实现的智能体返回
undefined - 缺省 = 未知 —— 只声明你支持的;省略字段表示该能力未被声明
AgentCapabilities 接口
能力按类型化类别组织,每类代表智能体功能的不同方面:
interface AgentCapabilities {
/** 智能体身份与元数据 */
identity?: IdentityCapabilities
/** 支持的传输机制(SSE、WebSocket、binary 等) */
transport?: TransportCapabilities
/** 智能体提供的工具与工具调用配置 */
tools?: ToolsCapabilities
/** 输出格式支持(结构化输出、MIME 类型) */
output?: OutputCapabilities
/** 状态与记忆管理(快照、增量、持久化) */
state?: StateCapabilities
/** 多智能体协调(委派、交接、子智能体) */
multiAgent?: MultiAgentCapabilities
/** 推理与思考支持(思维链、加密思考) */
reasoning?: ReasoningCapabilities
/** 按方向组织(输入 vs 输出)的多模态支持 */
multimodal?: MultimodalCapabilities
/** 执行控制与限制(代码执行、超时、迭代上限) */
execution?: ExecutionCapabilities
/** 人机协同支持(审批、干预、反馈) */
humanInTheLoop?: HumanInTheLoopCapabilities
/** 标准类别未覆盖的集成特定能力 */
custom?: Record<string, unknown>
}custom 字段是集成特定能力的逃生舱。
能力类别
身份(Identity)
智能体的基本元数据。适用于发现 UI、智能体市场与调试。
interface IdentityCapabilities {
name?: string // UI 与选择器中显示的人类可读名称
type?: string // 驱动该智能体的框架或平台(如 "langgraph")
description?: string // 这个智能体做什么
version?: string // 语义化版本,用于兼容性检查
provider?: string // 维护该智能体的组织或团队
documentationUrl?: string // 文档或主页 URL
metadata?: Record<string, unknown>
}传输(Transport)
声明智能体支持的传输机制。客户端据此选择最佳连接策略。只对实际支持的传输设为 true。
interface TransportCapabilities {
streaming?: boolean // 通过 SSE 流式返回
websocket?: boolean // 接受持久 WebSocket 连接
httpBinary?: boolean // 支持 AG-UI 二进制协议(protobuf over HTTP)
pushNotifications?: boolean // 运行结束后通过 webhook 发送异步更新
resumable?: boolean // 支持通过序列号恢复中断的流
}工具(Tools)
工具调用能力。区分智能体自身提供的工具(列在 items 中)与客户端在运行时通过 RunAgentInput.tools 传入的工具。
interface ToolsCapabilities {
supported?: boolean // 是否可进行工具调用;false 表示显式禁用
items?: Tool[] // 智能体自身提供的工具(完整 JSON Schema)
parallelCalls?: boolean // 单步内是否可并发调用多个工具
clientProvided?: boolean// 是否接受并使用客户端在运行时提供的工具
}输出(Output)
输出格式支持。当智能体能返回符合 JSON schema 的响应时启用 structuredOutput,便于程序化消费。
interface OutputCapabilities {
structuredOutput?: boolean // 可生成符合所提供 schema 的结构化 JSON
supportedMimeTypes?: string[] // 可生成的 MIME 类型
}状态(State)
状态与记忆管理能力,告诉客户端智能体如何处理共享状态,以及会话上下文是否跨运行持久化。
interface StateCapabilities {
snapshots?: boolean // 发射 STATE_SNAPSHOT(完整状态替换)
deltas?: boolean // 发射 STATE_DELTA(JSON Patch 增量)
memory?: boolean // 当前线程之外有长期记忆
persistentState?: boolean // 状态在同一线程的多次运行间保留;false 则每次重置
}多智能体(Multi-Agent)
多智能体协调能力。当智能体能编排或交接给其他智能体时启用。
interface MultiAgentCapabilities {
supported?: boolean // 参与任多智能体协调
delegation?: boolean // 可委派子任务并保留控制权
handoffs?: boolean // 可把会话完全转交给另一个智能体
subagents?: Array<{ name: string; description?: string }> // 可调用的子智能体
}推理(Reasoning)
推理与思考能力。当智能体暴露内部思考过程时启用。
interface ReasoningCapabilities {
supported?: boolean // 产生对客户端可见的推理/思考 token
streaming?: boolean // 推理 token 增量流式输出(而非一次性返回)
encrypted?: boolean // 推理内容加密(零数据保留模式)
}多模态(Multimodal)
输入与输出支持,按 input 与 output 子对象组织,使客户端可独立查询智能体接受什么、产生什么。客户端据此显示/隐藏文件上传按钮、音频录制器、图片选择器等。
interface MultimodalInputCapabilities {
image?: boolean // 可处理图片输入
audio?: boolean // 可处理音频输入
video?: boolean // 可处理视频输入
pdf?: boolean // 可处理 PDF 文档
file?: boolean // 可处理任意文件上传
}
interface MultimodalOutputCapabilities {
image?: boolean // 可生成图片
audio?: boolean // 可产生音频输出(TTS、音频文件)
}
interface MultimodalCapabilities {
input?: MultimodalInputCapabilities
output?: MultimodalOutputCapabilities
}执行(Execution)
执行控制与限制。声明这些让客户端对运行可能持续多久、多少步建立预期。
interface ExecutionCapabilities {
codeExecution?: boolean // 运行期间可执行代码(如 Python、JS)
sandboxed?: boolean // 代码执行在沙箱/隔离环境中(仅在 codeExecution 为 true 时有意义)
maxIterations?: number // 每次运行最大的工具调用/推理迭代次数
maxExecutionTime?: number // 超时前的最大墙钟时间(毫秒)
}人机协同(Human-in-the-Loop)
当智能体可暂停执行以请求人工输入、审批或反馈时启用。
interface HumanInTheLoopCapabilities {
supported?: boolean // 支持任人机协同交互
approvals?: boolean // 可在敏感操作前暂停并请求明确审批
interventions?: boolean // 允许人工在执行中途干预并修改计划
feedback?: boolean // 可纳入用户反馈(点赞/点踩、纠正)
interrupts?: boolean // 参与 AG-UI 中断协议
approveWithEdits?: boolean// 工具调用中断的 resume 载荷接受 editedArgs
}完整协议规范见中断。
实现 getCapabilities()
自定义智能体
在智能体子类上实现 getCapabilities(),只返回你实际支持的能力:
import { AbstractAgent, AgentCapabilities } from "@ag-ui/client"
class MyAgent extends AbstractAgent {
async getCapabilities(): Promise<AgentCapabilities> {
return {
identity: {
name: "my-agent",
description: "A custom agent with tool support",
version: "1.0.0",
},
transport: { streaming: true },
tools: {
supported: true,
items: this.getRegisteredTools(),
clientProvided: true,
},
state: { snapshots: true, deltas: true },
}
}
// ... run() 实现
}动态能力
由于 getCapabilities() 返回实时快照,它会反映智能体当前状态:
const agent = new MyAgent(config)
let caps = await agent.getCapabilities()
console.log(caps.tools?.items?.length) // 5
// 运行时注册更多工具
agent.registerTool(newTool)
caps = await agent.getCapabilities()
console.log(caps.tools?.items?.length) // 6客户端使用模式
自适应 UI
根据智能体支持的能力渲染 UI 组件:
const capabilities = await agent.getCapabilities?.()
if (capabilities?.reasoning?.supported) {
showReasoningPanel()
}
if (capabilities?.multiAgent?.subagents?.length) {
showSubAgentSelector(capabilities.multiAgent.subagents)
}
if (capabilities?.humanInTheLoop?.approvals) {
enableApprovalWorkflow()
}功能门控
禁用以智能体不支持的功能,而不是在运行时失败:
const capabilities = await agent.getCapabilities?.()
// 基于显式声明做门控:省略字段表示未声明,而不是“不支持”
const canUseStructuredOutput = capabilities?.output?.structuredOutput === true
const canStream = capabilities?.transport?.streaming === true自定义能力
通过 custom 字段访问集成特定能力:
const capabilities = await agent.getCapabilities?.()
const rateLimit = capabilities?.custom?.rateLimit as
| { maxRequestsPerMinute: number }
| undefined
if (rateLimit) {
configureThrottling(rateLimit.maxRequestsPerMinute)
}