Agent 消息协议

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

协议概述

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

交互过程

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

消息类型

user-input

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

response-state

响应开始：

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

响应结束：

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

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

iteration-state

某次迭代开始：

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

此次迭代结束：

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

备注：

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

model-invocation-state

调用模型开始：

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

调用模型结束：

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

备注：

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

think-output

思考内容开始：

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

发送思考内容：

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

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

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

思考内容结束：

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

chat-output

聊天内容开始：

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

发送聊天内容：

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

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

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

聊天内容结束：

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

tool-call

字段说明：

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

调用工具前请发送：

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

调用工具后请发送：

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

error

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

{
  "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 - 了解如何在 Agent Manager 中创建和管理 Agent
• 开发 CLI Agent - 学习如何开发一个命令行 Agent 程序
• 开发外部 AI Agent - 学习如何开发一个外部 AI Agent 服务