---
outline: deep
---

# Agent 消息协议

本文档详细定义了外部 AI Agent 与 Mythra Agent Studio 之间的通信协议。如果你正在开发外部 Agent，需要遵循本协议规范来实现消息的收发。

## 协议概述

外部 Agent 通过 WebSocket 协议与 Mythra Agent Studio 进行通信。通信过程采用 JSON 格式的消息，每种消息都有特定的 `type` 字段来标识其用途。

## 交互过程

1. 客户端主动向Agent发起连接。
2. 客户端向Agent发送 user-input 消息。
3. Agent处理消息并返回一系列响应消息。
4. 双方断开连接。

```mermaid
sequenceDiagram
    participant C as 客户端
    participant A as Agent
    Note over C,A: 建立连接
    C->>A: 发送 user-input 消息
    A-->>C: 返回 response-state event:start 消息
    loop 一次迭代
        A-->>C: 返回 iteration-state event:start 消息
        A-->>C: 返回 model-invocation-state event:start 消息
        activate A
        A-->>C: 发送 think-output event:start 消息
        A-->>C: 返回 think-output event:delta 消息
        A-->>C: 发送 think-output event:end 消息
        Note right of A: 调用LLM
        A-->>C: 发送 chat-output event:start 消息
        A-->>C: 返回 chat-output event:delta 消息
        A-->>C: 发送 chat-output event:end 消息
        deactivate A
        A-->>C: 返回 model-invocation-state event:end 消息
        opt
            A-->>C: 发送 tool-call event:start 消息
            activate A
            Note right of A: 调用工具
            A-->>C: 发送 tool-call event:end 消息
        end
        deactivate A
        A-->>C: 返回 iteration-state event:end 消息
    end
    A-->>C: 返回 response-state event:end 消息
    Note over C,A: 断开连接
```

## 消息类型

### user-input

```json
{
  "type": "user-input",
  "apiKey": "your WDS API key",
  "projectId": "2231",
  "workDir": "/document",
  "sessionId": "d271487972e2221eb3aa98bc1a7ae6fc",
  "userInput": "你好",
  "preferredModel": "火山引擎:doubao-seed-1-6-lite-251015"
}
```

### response-state

响应开始：

```json
{
  "id": "jgrhyohghbf",
  "type": "response-state",
  "event": "start",
}
```

响应结束：

```json
{
  "id": "jgrhyohghbf",
  "type": "response-state",
  "event": "end",
}
```

发送响应结束消息后，双方就可以断开连接了。

### iteration-state

某次迭代开始：

```json
{
  "id": "jgrhyohghbf",
  "type": "iteration-state",
  "event": "start",
  "content":"iteration 0"
}
```

此次迭代结束：

```json
{
  "id": "jgrhyohghbf",
  "type": "iteration-state",
  "event": "end",
  "content":"iteration 0"
}
```

备注：
* 此消息类型是**可选**的，Agent 可以不发送此消息。
* Agent可以根据需要发送此消息，用于标识迭代开始或结束。

### model-invocation-state

调用模型开始：

```json
{
  "id": "jgrhyohghbf",
  "type": "model-invocation-state",
  "event": "start"
}
```

调用模型结束：

```json
{
  "id": "jgrhyohghbf",
  "type": "model-invocation-state",
  "event": "end"
}
```

备注：
* 此消息类型是**可选**的，Agent 可以不发送此消息。
* Agent可以根据需要发送此消息，用于标识大语言模型调用开始或结束。

### think-output

思考内容开始：

```json
{
  "id": "erdo48cup8g",
  "type": "think-output",
  "event": "start"
}
```

发送思考内容：

```json
{
  "id": "erdo48cup8g",
  "type": "think-output",
  "event": "delta",
  "content": "这是一段",
}

{
  "id": "erdo48cup8g",
  "type": "think-output",
  "event": "delta",
  "content": "深度思考",
}

{
  "id": "erdo48cup8g",
  "type": "think-output",
  "event": "delta",
  "content": "内容。",
}
```

思考内容结束：

```json
{
  "id": "erdo48cup8g",
  "type": "think-output",
  "event": "end"
}
```

### chat-output

聊天内容开始：

```json
{
  "id": "lgoqcoarq8s",
  "type": "chat-output",
  "event": "start"
}
```

发送聊天内容：

```json
{
  "id": "lgoqcoarq8s",
  "type": "chat-output",
  "event": "delta",
  "content": "这是一段",
},

{
  "id": "lgoqcoarq8s",
  "type": "chat-output",
  "event": "delta",
  "content": "聊天输出",
},

{
  "id": "lgoqcoarq8s",
  "type": "chat-output",
  "event": "delta",
  "content": "内容。",
}
```

聊天内容结束：

```json
{
  "id": "lgoqcoarq8s",
  "type": "chat-output",
  "event": "end"
}
```

### tool-call

字段说明：
* `id` 是工具调用的唯一标识符，用于匹配调用和响应。 `start` 和 `end` 事件的 `id` 必须相同。
* `type` 必须为 `tool-call`。
* `event` 必须为 `start` 或 `end`。
* `func` 是要调用的工具函数名。
* `args` 是工具函数的参数，类型是 JSON Object.

调用工具前请发送：

```json
{
  "id": "uk2lvycfaoi",
  "type": "tool-call",
  "event": "start",
  "func": "WriteFile",
  "args": {
    "filePath": "/markdown/test.md",
  },
}
```

调用工具后请发送：

```json
{
  "id": "uk2lvycfaoi",
  "type": "tool-call",
  "event": "end",
  "func": "WriteFile",
  "args": {
    "filePath": "/markdown/test.md",
  },
}
```

### error

当Agent服务端发生错误时，可以返回 error 消息。这条错误消息会显示在聊天界面上，提示用户发生了错误。

```json
{
  "id": "uk2lvycfaoi",
  "type": "error",
  "event": "error",
  "content": "error message"
}
```

## 消息字段说明

所有消息都包含以下公共字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | string | 是 | 消息的唯一标识符，用于关联同一消息流中的消息 |
| `type` | string | 是 | 消息类型，如 `response-state`、`chat-output` 等 |
| `event` | string | 是 | 事件类型，如 `start`、`delta`、`end` |

## 最佳实践

1. **消息 ID 管理**：确保同一消息流（如一次完整的聊天输出）使用相同的 `id`
2. **流式输出**：对于长文本，使用 `delta` 事件分块发送，提升用户体验
3. **错误处理**：发生错误时及时发送 `error` 消息，让用户了解情况
4. **连接管理**：在发送 `response-state end` 消息后，可以安全地断开连接

## 相关文档

- [创建自定义 Agent](./create-custom-agent.md) - 了解如何在 Agent Manager 中创建和管理 Agent
- [开发 CLI Agent](./develop-cli-agent.md) - 学习如何开发一个命令行 Agent 程序
- [开发外部 AI Agent](./develop-external-agent.md) - 学习如何开发一个外部 AI Agent 服务