Agent/im-client

IM Client - Agent 即时通讯客户端

Agent 的通信客户端工具，管理消息历史、联系人、消息收发。

概述

IM Client 是每个 Agent 的通信客户端，负责：

• 消息收发：与 IM Server 通信，发送和接收消息
• 消息历史：存储该 Agent 的所有对话消息历史
• 联系人管理：管理该 Agent 的联系人列表
• 消息队列：管理待处理的消息（特别是数字员工型 Agent）

核心功能

• 连接 IM Server：建立和维护与 IM Server 的连接
• 发送消息：发送消息给指定联系人（Agent 或用户）
• 接收消息：接收来自其他主体的消息
• 消息历史存储：本地存储消息历史（在 Workspace 内）
• 联系人管理：维护联系人列表和信息

存储位置

IM Client 的数据存储在 Agent 的 Workspace 内：

~/.gateway/workspaces/{workspace_id}/
├── im_client/
│   ├── config.json              # IM Client 配置
│   ├── contacts.json            # 联系人列表
│   ├── conversations/           # 对话历史
│   │   ├── {conversation_id}.jsonl
│   │   └── ...
│   └── queue/                   # 消息队列（数字员工型）
│       └── pending.json

架构

┌─────────────────────────────────────────────────────────┐
│                    IM Client                             │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │ Connection Manager（连接管理）                      │ │
│  │ - 连接 IM Server                                    │ │
│  │ - 心跳保活                                          │ │
│  │ - 断线重连                                          │ │
│  └────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │ Message Handler（消息处理）                         │ │
│  │ - 发送消息                                          │ │
│  │ - 接收消息                                          │ │
│  │ - 消息确认                                          │ │
│  └────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │ Storage Manager（存储管理）                         │ │
│  │ - 消息历史存储                                      │ │
│  │ - 联系人管理                                        │ │
│  │ - 消息队列管理                                      │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
                         ↑
                         │ IM Protocol
                         │
                    ┌────▼────┐
                    │IM Server│
                    └─────────┘

目录结构

im-client/
├── core/                          # 核心功能
│   ├── connection.py              # 连接管理
│   ├── message_handler.py         # 消息处理
│   └── storage.py                 # 存储管理
│
├── api/                           # Python API
│   └── client.py                  # IMClient 类
│
└── docs/                          # 文档
    ├── architecture.md            # 架构设计
    ├── api.md                     # API 文档
    └── storage.md                 # 存储格式文档

快速开始

创建 IM Client 实例

from im_client.api.client import IMClient

# 创建 IM Client
client = IMClient(
    workspace_path="~/.gateway/workspaces/user_001",
    im_server_url="http://im-server:8080",
    agent_id="agent_001"
)

# 连接 IM Server
client.connect()

发送消息

# 发送消息给指定联系人
client.send_message(
    to="agent_002",
    text="你好，我需要你的帮助"
)

接收消息

# 注册消息处理回调
def on_message(message):
    print(f"收到消息：{message['text']}")
    print(f"来自：{message['from']}")

client.on_message(on_message)

# 或者主动查询消息队列（数字员工型）
messages = client.get_pending_messages()
for msg in messages:
    print(msg)

查询消息历史

# 查询与指定联系人的对话历史
messages = client.get_conversation_history(
    contact_id="agent_002",
    limit=50
)

for msg in messages:
    print(f"{msg['from']}: {msg['text']}")

管理联系人

# 添加联系人
client.add_contact(
    contact_id="agent_002",
    name="助理 Agent",
    description="负责数据分析的助理"
)

# 查询联系人列表
contacts = client.list_contacts()
for contact in contacts:
    print(f"{contact['name']}: {contact['description']}")

文档

核心文档

• 架构设计：IM Client 架构和核心模块
• API 文档：Python API 参考
• 存储格式：消息历史和联系人的存储格式

开发状态

待设计 📋

• 架构设计
• API 设计
• 存储格式设计
• IM 协议实现

待实现 📋

• 核心代码实现
• Python API 实现
• 存储管理实现

相关项目

• IM Server：IM 通信服务器
• Gateway：Agent 管理系统
• Agent Core：Agent 核心框架