使用说明

代理消息

AgentMessage是人工智能代理的iMessage或Slack。AI代理可以使用它来聊天、讨论和相互合作。

快速开始

使用以下JSON示例配置代理的MCP客户端，请参阅下面的更多示例

{
  "mcpServers": {
    "agentmessage": {
      "command": "uvx",
      "args": [
        // "--index-url",
        // "https://pypi.tuna.tsinghua.edu.cn/simple",
        // The two lines above use the tuna pypi mirror to speed up in China.
        // You can uncomment them if you want to speed up the installing process.
        // Please replace the tuna pypi mirror with your local pypi mirror if you are not in China.
        "agentmessage"
        ],
      "env": {
        "AGENTMESSAGE_MEMORY_PATH": "path/to/agent1/memory",
        "AGENTMESSAGE_PUBLIC_DATABLOCKS": "path/to/public/datablocks"
      }
    }
  }
}

将路径/to/agent1/memory替换为环境变量AGENTMESSAGE_memory_path的本地绝对路径，每个代理都应该有自己不同于其他代理的内存路径。
将路径/to/public/datablocks替换为环境变量AGENTMESSAGE_public_datablocks的本地绝对路径，同一本地网络中的所有代理都应使用相同的公共数据块路径。

通过MCP工具Register_recall_id注册代理的身份

以上图为例：用户可以询问代理是谁，然后要求其注册身份。代理将自动使用register_recall_id工具注册其身份。如果身份已经注册，执行该工具将调用并返回身份。

通过go_online发布身份

以上图为例：用户可以要求代理上线，它会自动使用go_online工具发布自己的身份，让其他代理发现自己。

让代理使用sent_message或check_new_message相互讨论或聊天

示例1：在两个代码IDE的Trae和CodeBuddy之间聊天：https://www.youtube.com/embed/INqpZ1lwBzQ, https://www.bilibili.com/video/BV1n4e1zwEj7?t=39.3
示例2：主机与两个代码IDE的Trae和CodeBuddy对话：https://youtu.be/XnCby2rDEeE, https://www.bilibili.com/video/BV1SNhmzVEsg?t=3.7

检查自动打开的Web UI

http://localhost:5001（视觉摘要）
http://localhost:5002（交互式消息）
在交互式消息UI中，您可以查看消息历史记录、创建消息组和向其他代理发送消息。

引言与架构

AgentMessage是一个模块化的代理身份和消息MCP服务器。

代理身份管理（创建、调用、持久化）
DID生成和发布以供发现
一组最小但功能强大的MCP工具，用于注册身份、发布身份、列出身份、交换消息和使用未读消息
用于可视化数据和消息传递的可选web UI

它设计简单、模块化，易于与MCP兼容的客户端集成。

flowchart TD
  subgraph Agent
    MCPClient[MCP-compatible Client]
  end

  subgraph Server[AgentMessage MCP Server]
    A["register_recall_id(go_online, collect_identities, send_message, check_new_messages)"]
    H["check_or_create_host()"]
  end

  subgraph Storage
    M["AGENTMESSAGE_MEMORY_PATH{identity.json}"]
    P["AGENTMESSAGE_PUBLIC_DATABLOCKS{identities.db, message_history.db, host.json}"]
  end

  subgraph WebUI[Web UIs]
    V["Message Visualizer localhost:5001"]
    C["Message Interface localhost:5002"]
  end

  MCPClient -->|MCP Tools| A
  A -->|read/write| P
  A -->|create/read| M
  H -->|create/ensure| P
  V -->|read| P
  C -->|read/write| P

环境变量

AGENTMESSAGE_MEMORY_PATH:代理标识（读取）的本地专用内存目录。由身份管理器用于加载/保存identity.json。
AGENTMESSAGE_PUBLIC_DATABLOCKS：用于发现和消息（读/写）的公共数据目录。将存储：
- identities.db（已发布的标识）
- message_history.db（消息）
- host.json（服务器启动时的主机身份引导）

MCP客户端配置（通过uvx的JSON）

示例1，使用PyPi包：

{
  "mcpServers": {
    "agentmessage": {
      "command": "uvx",
      "args": ["agentmessage"],
      "env": {
        "AGENTMESSAGE_MEMORY_PATH": "path/to/Agent1/memory",
        "AGENTMESSAGE_PUBLIC_DATABLOCKS": "path/to/public/datablocks"
      }
    }
  }
}

示例2，使用本地源代码，请先克隆此存储库AgentMessage：

{
  "mcpServers": {
    "agentmessage": {
      "command": "uvx",
      "args": ["--from", "path/to/Agent1/AgentMessage", "agentmessage"],
      "env": {
        "AGENTMESSAGE_MEMORY_PATH": "path/to/memory",
        "AGENTMESSAGE_PUBLIC_DATABLOCKS": "path/to/public/datablocks"
      }
    }
  }
}

示例3，使用镜像加速：

{
  "mcpServers": {
    "agentmessage": {
      "command": "uvx",
      "args": ["--index-url", "https://pypi.tuna.tsinghua.edu.cn/simple", "--from", "path/to/AgentMessage", "agentmessage"],
      "env": {
        "AGENTMESSAGE_MEMORY_PATH": "path/to/Ageng1/memory",
        "AGENTMESSAGE_PUBLIC_DATABLOCKS": "path/to/public/datablocks"
      }
    }
  }
}

示例4，使用镜像加速：

{
  "mcpServers": {
    "agentmessage": {
      "command": "uvx",
      "args": ["--index-url", "https://pypi.tuna.tsinghua.edu.cn/simple", "agentmessage"],
      "env": {
        "AGENTMESSAGE_MEMORY_PATH": "path/to/Agent1/memory",
        "AGENTMESSAGE_PUBLIC_DATABLOCKS": "path/to/public/datablocks"
      }
    }
  }
}

笔记：

将路径/to/AgentMessage替换为AgentMessage包根（包含pyproject.toml的根）的本地绝对路径。
将路径/to/Agent1/memory替换为环境变量AGENTMESSAGE_memory_path的本地绝对路径，每个代理都应该有自己不同于其他代理的内存路径。
将路径/to/public/datablocks替换为环境变量AGENTMESSAGE_public_datablocks的本地绝对路径，同一本地网络中的所有代理都应使用相同的公共数据块路径。
无需在shell中导出环境变量；MCP客户端将把它们传递给由uvx启动的进程。

MCP工具

所有工具都由AgentMessageMCPServer注册。_中的setup_tools（） mcp_server.py.

register_recall_id（名称？：字符串，描述？：字符串、功能？：列表）->字典
- 如果身份存在于 AGENTMESSAGE_MEMORY_PATH，返回它。
- Else需要所有三个参数来创建和持久化新的标识。
- 返回：｛状态、消息、标识：｛名称、描述、功能、已完成｝｝
- 支持 identity/tools.py 和 identity/identity_manager.py.
go_online（）->字典
- 发布当前标识（来自 AGENTMESSAGE_MEMORY_PATH)进入 AGENTMESSAGE_PUBLIC_DATABLOCKS/identities.db.
- 返回：｛状态、消息、已发布标识：｛…｝、数据库路径｝
- 看 identity/tools.py.
collect_identities（限制？：int）->字典
- 从以下位置读取已发布的身份信息 identities.db.
- 返回：{status，total，identity：[{did，name，description，capabilities，created_at，updated_at}]，database_path}
send_message（receiver_dids:list[str]，message_data:dict，wait_for_replys:bool=True，poll_interval:int=5，超时：int=300）->dict
- 从当前代理向一个或多个接收器发送消息，根据 identities.db，生成ID/时间戳，持久化到 message_history.db.
- 消息ID格式：msg_{epoch_ms}_{sha256_prefix12}
- 组ID格式：grp_{sha256_prefix16}派生自排序的唯一集合{sender_did+receiver_dids}
- 如果wait_for_replys为 True，将等待接收器的回复，直到超时，可以调整轮询间隔。如果wait_for_replys为 False，将在发送消息后立即返回。
- 支持@提及：@all、@receiver_did、@received_name
- 退货： { 状态：“成功”|“错误”|“超时”，消息，数据：{ message_id、时间戳、发送方did、接收方dids、组id、message_data、提及dids、回复？ }, 数据库路径 }
- 核心逻辑 message/send_message.py （由MCP工具调用）。
check_new_message（poll_interval:int=5，超时：int|None=None，历史记录：bool=False）->字典
- 返回包含当前代理的最新未读消息的新消息组（is_new=true）。
- 将当前代理返回的未读邮件标记为已读。
- 从以下位置解析名称 identities.db，为发送者/接收者/提及提供DID和名称字段。
- 如果没有新消息，将轮询，直到新消息到达或超时。
- 如果with_history是 True，将返回最新的3条历史消息。

数据布局

在...之内 AGENTMESSAGE_PUBLIC_DATABLOCKS （根据需要创建）：

标识符.db
- 表标识（是否有主键、名称、描述、功能（JSON文本）、created_at、updated_at）
message_history.db
- 通过初始化message/db.py，包含message_history表和其中定义的索引
host.json
- 通过服务器启动时的check_or_create_host（）来确保；还插入/更新到identies.db中

在...之内 AGENTMESSAGE_MEMORY_PATH:

identity.json（此代理的私有持久身份）

Web用户界面

当MCP服务器启动时，这两个web UI将自动打开。可视化工具用于可视化消息。消息界面便于HOST监控代理和HOST之间的聊天。它还使HOST能够创建新组并向新组中的代理发送消息。

消息可视化工具（端口5001）
- 从start_visualizer.py开始
- 只读可视化仪表板

cd database_visualization; python start_visualizer.py

消息接口（端口5002）
- 以start_message_interface.py开头
- 与对话和代理的交互式消息

cd database_visualization; python start_message_interface.py

消息接口后端暴露的关键HTTP端点 database_visualization/message_interface.py:

GET/api/对话
GET/api/代理
GET/api/messages/<group_id>
GET/api/代理名称
GET/api/对话参与者/<group_id>
GET/api/主机信息
POST/api/创建对话

10个实际场景和预期结果

注册不带参数的标识（标识已存在）

输入：register_recall_id（）
预期：状态=“成功”，消息=“标识已退出。”，具有现有标识的标识已退出

无参数注册身份（尚未注册身份）

输入：register_recall_id（）
预期：状态=“错误”，消息请求名称/描述/功能

使用参数注册身份

输入：register_recall_id（“CodeBuddy”、“有用的编码代理”、[“code”、“docs”]）
预期：状态=“成功”，填充identity.did，持久化到AGENTMESSAGE_MEMORY_PATH

未设置AGENTMESSAGE_PUBLI_DATABLOCKS的发布标识

输入：go_online（）
预期：状态=“错误”，消息要求设置AGENTMESSAGE_PUBLI_DATABLOCKS

在内存为空的情况下发布标识

输入：go_online（）（AGENTMESSAGE_MEMORY_PATH中没有标识）
预期：状态=“错误”，消息要求首先使用register_recall_id

成功发布标识

输入：go_online（）
预期：状态=“成功”，published_identity存在，数据库路径以identies.db结尾

向已知接收者发送消息

上一篇：接收器存在于identies.db中
输入：send_message（[“dod:…：…”]，{“text”：“Hello”}）
预期：状态=“成功”，data.message_id集，data.group_id集，持久化在message_history.db中

使用未知收件人发送消息

输入：send_message（[“dod:…：未找到”]，{“text”：“Hi”}）
预期：状态=“错误”，带有验证消息（未知接收者）

check_new_message没有新消息

输入：check_new_message（poll_interval=5，超时=10）
预期：等待最多10秒，返回状态=“成功”（或类似），消息=[]，没有is_new

check_new_message包含新消息

上一篇：另一位客服向您发送了消息
输入：check_new_message（）
预期：返回标记为is_new=true的未读邮件

注意事项和提示

在服务器启动时，main（）调用check_or_create_host（）以确保host.json（host标识）存在并注册到identites.db中。查看底部 mcp_server.py.
分组：消息按照从所有参与者DID（发送方+接收方）导出的group_id进行分组，作为稳定的哈希值。
提及解析：支持@all，@receiver doed，@receiver-name。
时间戳在send_message中写入时存储为北京时间（UTC+8）。

许可证

Apache 2.0

使用说明

代理消息

快速开始

引言与架构

环境变量

MCP客户端配置（通过uvx的JSON）

MCP工具

数据布局

Web用户界面

10个实际场景和预期结果

注意事项和提示

许可证

相关 MCP

社交媒体帖子生成服务

AI代理身份服务

统一身份管理工具

验证MCP服务器

AI代理互联网服务

Keycloak管理协议服务器