---
title: "类型"
description: "@ag-ui/core 的核心类型：RunAgentInput、消息、内容片段、工具与状态。"
---

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

# 类型

# 核心类型

Agent User Interaction Protocol SDK 建立在一组核心类型之上，它们构成系统中使用的基础结构。本页记录这些类型及其属性。

## RunAgentInput

运行智能体的输入参数。在 HTTP API 中，它就是 `POST` 请求体。

`tools` 包含客户端为本次运行提供的工具。后端自带的工具应留在后端智能体或框架配置中，并可通过智能体能力单独公告。

```typescript
type RunAgentInput = {
  threadId: string
  runId: string
  parentRunId?: string
  state?: any // 缺省即“无状态”；裸 null 也按缺省处理
  messages: Message[]
  tools: Tool[]
  context: Context[]
  forwardedProps: any
  resume?: ResumeEntry[]
}
```

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `threadId` | `string` | 会话线程 ID |
| `runId` | `string` | 当前运行 ID |
| `parentRunId` | `string`（可选） | 派生出本次运行的运行 ID |
| `state` | `any`（可选） | 智能体当前状态；缺省表示“无状态”，裸 `null` 也读作缺省 |
| `messages` | `Message[]` | 会话中的消息数组 |
| `tools` | `Tool[]` | 本次运行可用的客户端工具 |
| `context` | `Context[]` | 提供给智能体的上下文对象数组 |
| `forwardedProps` | `any` | 转发给智能体的附加属性 |
| `resume` | `ResumeEntry[]`（可选） | 针对上个运行中断结果的逐中断响应 |

## ResumeEntry

`RunAgentInput.resume` 中每个中断对应一条，用于回应上一个运行留下的[中断](https://ag-ui.ndjp.net/concepts/interrupts/#恢复运行)。

```typescript
type ResumeEntry = {
  interruptId: string
  status: "resolved" | "cancelled"
  payload?: any
  metadata?: Record<string, any>
}
```

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `interruptId` | `string` | 本条响应对应的中断 ID |
| `status` | `"resolved" \| "cancelled"` | 用户已作答，或放弃了该中断 |
| `payload` | `any`（可选） | 响应本身，按中断的 `responseSchema` 校验 |
| `metadata` | `Record<string, any>`（可选） | 关于响应的信封数据——签名、路由键——绝不是答案本身 |

`metadata` 遵循协议各处的约定：按 key 开放，任意 JSON 值（含 `null`），对象本身可缺省但永不为 `null`，`ag-ui` 键保留给协议。resume 条目是请求字段，因此不参与合并。

## 消息类型

> **说明：** 每种消息类型都携带可选的 `metadata`（`Record<string, any>`），`ToolCall` 亦然；下表为简洁起见省略。它按 key 开放——任意 JSON 值（含 `null`）——对象可缺省但永不为 `null`。`ag-ui` 键保留给 AG-UI 自用。消息由事件构建时 metadata 会累积，合并规则见 [Metadata](https://ag-ui.ndjp.net/concepts/metadata/)。

### Role

```typescript
type Role =
  | "developer"
  | "system"
  | "assistant"
  | "user"
  | "tool"
  | "activity"
  | "reasoning"
```

### DeveloperMessage

```typescript
type DeveloperMessage = {
  id: string
  role: "developer"
  content: string
  name?: string
}
```

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `id` | `string` | 消息唯一标识 |
| `role` | `"developer"` | 固定为 `"developer"` |
| `content` | `string` | 文本内容（必填） |
| `name` | `string` | 可选发送者名称 |

### SystemMessage

```typescript
type SystemMessage = {
  id: string
  role: "system"
  content: string
  name?: string
}
```

### AssistantMessage

```typescript
type AssistantMessage = {
  id: string
  role: "assistant"
  content?: string
  name?: string
  toolCalls?: ToolCall[]
}
```

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `id` | `string` | 消息唯一标识 |
| `role` | `"assistant"` | 固定为 `"assistant"` |
| `content` | `string`（可选） | 文本内容 |
| `name` | `string`（可选） | 发送者名称 |
| `toolCalls` | `ToolCall[]`（可选） | 本消息发起的工具调用 |

### UserMessage

```typescript
type UserMessage = {
  id: string
  role: "user"
  content: string | ContentPart[]
  name?: string
}
```

`content` 既可以是纯文本，也可以是按序排列的多模态内容片段数组。

### ContentPart

支持的内容片段联合。同样的片段也可出现在 `ToolMessage` 上：工具结果是一个字符串或它们组成的列表。每个片段可带可选 `id`；`metadata` 不受约束，文本搜索命中可借此保存来源与标题。

```typescript
type ContentPart = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart
```

### PartSource

```typescript
type PartSource = DataSource | UrlSource | FileSource

type DataSource = {
  type: "data"
  value: string
  mimeType: string
}

type UrlSource = {
  type: "url"
  value: string
  mimeType?: string
}

type FileSource = {
  type: "file"
  value: string   // 句柄，与提供方签发的完全一致
  provider?: string // 签发者，例如 "openai"、"anthropic"、"google"
  mimeType?: string
}
```

`FileSource` 指向已经位于模型提供方一侧的字节——OpenAI 或 Anthropic 的文件 id、Gemini 的文件 URI。不会拉取任何内容，`value` 是不透明的：智能体把它交给自己的提供方，或丢弃该片段，绝不将其当作 URL。

### TextPart / ImagePart / AudioPart / VideoPart / DocumentPart

```typescript
type TextPart = {
  type: "text"
  id?: string
  text: string
  metadata?: unknown
}

type ImagePart = {
  type: "image"
  id?: string
  source: PartSource
  metadata?: unknown
}
```

`AudioPart`、`VideoPart`、`DocumentPart` 与 `ImagePart` 结构一致，仅 `type` 不同。

### ToolMessage

```typescript
type ToolMessage = {
  id: string
  content: string | ContentPart[]
  role: "tool"
  toolCallId: string
  error?: string
  encryptedValue?: string
}
```

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `content` | `string \| ContentPart[]` | 文本内容或内容片段 |
| `toolCallId` | `string` | 本条消息回应的工具调用 ID |
| `error` | `string`（可选） | 工具调用失败时的错误信息 |
| `encryptedValue` | `string`（可选） | 通过签名附加的加密值 |

### ActivityMessage

```typescript
type ActivityMessage = {
  id: string
  role: "activity"
  activityType: string
  content: Record<string, any>
}
```

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `activityType` | `string` | 用于选择渲染器的活动判别字段 |
| `content` | `Record<string, any>` | 表示活动状态的结构化载荷 |

### ReasoningMessage

```typescript
type ReasoningMessage = {
  id: string
  role: "reasoning"
  content: string
  encryptedValue?: string
}
```

### Message

```typescript
type Message =
  | DeveloperMessage
  | SystemMessage
  | AssistantMessage
  | UserMessage
  | ToolMessage
  | ActivityMessage
  | ReasoningMessage
```

### ToolCall

```typescript
type ToolCall = {
  id: string
  type: "function"
  function: FunctionCall
  encryptedValue?: string
}
```

#### FunctionCall

```typescript
type FunctionCall = {
  name: string
  arguments: string // JSON 编码的参数字符串
}
```

## Context

```typescript
type Context = {
  description: string
  value: string
}
```

## Tool

```typescript
type Tool = {
  name: string
  description: string
  parameters: any // JSON Schema
}
```

## State

```typescript
type State = any
```

状态类型是灵活的，可承载智能体实现所需的任意数据结构。

## AgentCapabilities

`getCapabilities()` 返回的类型化能力声明。所有字段都是可选的——智能体只声明自己支持的部分。

```typescript
interface AgentCapabilities {
  identity?: IdentityCapabilities
  transport?: TransportCapabilities
  tools?: ToolsCapabilities
  output?: OutputCapabilities
  state?: StateCapabilities
  multiAgent?: MultiAgentCapabilities
  reasoning?: ReasoningCapabilities
  multimodal?: MultimodalCapabilities
  execution?: ExecutionCapabilities
  humanInTheLoop?: HumanInTheLoopCapabilities
  custom?: Record<string, unknown>
}
```

各类别的完整类型定义与用法见[能力](https://ag-ui.ndjp.net/concepts/capabilities/)。

Source: https://ag-ui.ndjp.net/sdk/js/core/types/index.mdx
