Startseite Erkunden Hilfe
Anmelden
howard
/
Agent
1
0
Fork 0
Dateien Issues 0 Pull-Requests 0 Wiki
Branch: dev_tao
Branches Tags
Agent
/
gateway
/
docs
/
requirements.md

requirements.md 7.1 KB
Permalink Verlauf Originalformat

Gateway 需求规划

更新日期： 2026-03-14

文档维护规范

  1. 先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
  2. 文档分层，链接代码 - 关键实现需标注代码文件路径；格式：module/file.py:function_name
  3. 简洁快照，日志分离 - 只记录已确认的需求，避免推测和未确认的设计细节

核心理解

Agent 的本质

基于 Agent Core 架构（详见 ../../agent/docs/architecture.md）：

  • Agent = Trace 数据 + Workspace
  • 无状态执行引擎：每次调用都是"续跑 trace"
  • 动态并发：
    • 1000 个用户可能有 1000 份 Trace 数据和 Workspace
    • 但运行中的 Agent 实例是动态的，预计 ~10 个并发
  • Workspace 共享：主 Agent 创建的子 Agent 可以共享同一个 Workspace

Gateway 的定位

核心定位： 使命/职能对话系统

  • 用户给 Agent 分配任务
  • Agent 汇报工作、述职
  • 是"管理-执行"关系

与 IM 系统的区别：

  • IM 系统：LLM 作为主体的平等交流（协作-沟通关系）
    • Agent 之间对等通信
    • 用户和 Agent 平等对话
    • 可以接入飞书、微信等任何渠道
  • Gateway：用户对 LLM 的使命/职能对话（管理-执行关系）
    • 用户分配任务给 Agent
    • Agent 执行任务并汇报
    • 通过 API 接口调用

三大核心模块

1. 外部渠道接入（Channels）

职责：

  • 接入飞书等外部渠道（个人助理型 Agent）
  • 消息路由（飞书用户 ID → Trace ID）
  • 自动创建 Trace（首次对话）

关键点：

  • 只用于个人助理型 Agent 的飞书接入
  • 数字员工型 Agent 的飞书接入通过 IM Server
  • 使用不同的飞书账号区分两种类型
  • 首次对话自动创建 Trace 和 Workspace

详细文档： channels.md

2. 生命周期管理（Lifecycle）

职责：

  • 调用 Agent 框架创建/查询 Trace
  • 管理 Workspace（创建、引用计数、清理）
  • 监听配置变化并热重载

关键点：

  • Trace 元数据由 Agent 框架管理，Gateway 不维护副本
  • 多个 Trace 可以共享一个 Workspace（主 Agent + 子 Agent）
  • Workspace 需要引用计数机制
  • 配置变更时热重载，不影响正在运行的 Trace

详细文档： lifecycle.md

3. 任务执行调度（Executor）

职责：

  • 接收用户分配的任务
  • 调度 Agent 框架执行任务
  • 管理任务执行状态和结果

关键点：

  • 支持同步和异步任务执行
  • 管理任务队列（个人助理型 Agent）
  • 提供任务状态查询接口
  • 与 Channels 模块集成，处理来自飞书的任务

详细文档： executor.md

两种 Agent 类型

类型 1：个人助理型 Agent

特征：

  • 每个用户有独立的 Trace + Workspace
  • 聊天历史隔离
  • 可以并发处理多个用户的任务

使用场景：

  • 个人助理
  • 专属客服
  • 个性化服务

飞书接入：

  • 通过 Gateway Channels 模块接入
  • 使用个人助理飞书账号
  • 飞书用户 ID → Trace ID（一对一映射）
  • 首次对话自动创建 Trace

任务调度：

  • 每个用户的任务独立调度
  • 支持并发执行（不同用户的任务）
  • 同一用户的任务需要排队

消息流转：

飞书用户 → Gateway Channels → Executor → Agent 执行 → Executor → Channels → 飞书

类型 2：数字员工型 Agent

特征：

  • 所有用户共享一个 Trace
  • 每个用户有独立的对话（通过 IM 系统）
  • 串行工作（按全局消息顺序处理）

使用场景：

  • 前台接待
  • 客服中心
  • 工单处理

飞书接入：

  • 通过 IM Server 接入（不通过 Gateway）
  • 使用数字员工飞书账号
  • 所有用户消息 → 同一个 Trace
  • 消息队列由 IM Client 管理

任务调度：

  • 所有任务串行处理
  • 任务队列由 IM Client 管理
  • Agent 主动查看和处理任务

消息流转：

飞书用户 → IM Server → IM Client → Agent 主动查看 → Agent 执行 → IM Client → IM Server → 飞书

两种接入方式

内部 Agent（同设备，我们的框架）

特点：

  • 和 Gateway 运行在同一台机器
  • 使用我们的 Agent 框架
  • 直接调用 Gateway 的内部接口（Python 函数调用）

不需要：

  • HTTP Client
  • Webhook
  • 网络通信

使用方式：

from gateway.core.lifecycle import TraceManager
from gateway.core.executor import TaskManager

trace_mgr = TraceManager()
task_mgr = TaskManager()

# 创建 Trace
trace_id = trace_mgr.create_trace(workspace_id="user_001", agent_type="personal_assistant")

# 提交任务
task_id = task_mgr.submit_task(trace_id, task_description="分析销售数据")

外部 Agent（其他设备/其他框架）

特点：

  • 运行在不同机器
  • 或使用其他 Agent 框架
  • 通过 HTTP API + Client SDK 接入

需要：

  • HTTP Client SDK
  • Webhook 接收消息
  • 网络通信

使用方式：

from gateway.client.python import GatewayClient

client = GatewayClient("http://gateway-host:8000")

# 创建 Trace
trace_id = client.create_trace(workspace_id="user_001", agent_type="personal_assistant")

# 提交任务
task_id = client.submit_task(trace_id, task_description="分析销售数据")

与 IM 系统的集成

Gateway 管理的 Agent 可以通过 IM Client 参与 IM 系统的通信：

Agent 主动通信

  • Agent 执行任务过程中需要协作 → 通过 IM Client 发送消息给其他 Agent
  • Agent 需要通知用户 → 通过 IM Client 发送消息给用户（飞书等渠道）

消息历史管理

  • IM Client 存储在 Workspace 内
  • 管理该 Agent 的所有 IM 对话历史
  • 联系人列表、消息记录等

两种对话模式的协同

个人助理型 Agent 的典型场景：

  1. 用户通过飞书发送任务（使命/职能对话）

    • 飞书 → Gateway Channels → Executor → Agent 执行

  2. Agent 执行任务时通过 IM 与其他 Agent 协作（主体间交流）

    • Agent → IM Client → IM Server → 其他 Agent

  3. Agent 完成任务后通过飞书回复用户（使命/职能对话）

    • Agent 执行完成 → Executor → Channels → 飞书

说明： 同一个 Agent 可以同时参与两种对话模式

暂不实现的功能

能力 Node

说明：

  • 类似 OpenClaw 的 Node 机制（跨设备能力调用）
  • 当前阶段暂不实现
  • 未来如有需求再考虑

其他外部渠道

说明：

  • 当前只实现飞书接入（个人助理型）
  • 微信、钉钉等其他渠道暂不实现
  • 未来可以参考飞书集成方式扩展

相关文档