Agent/docs

Agent 系统文档

文档导航

本文档是项目总览和文档导航。详细的模块文档请参考：

核心模块

• Agent Core 模块 - Agent 核心引擎、工具系统、记忆管理

  • 架构设计 - Agent 框架完整架构
  • 工具系统
  • Skills 指南
  • Trace API
  • 多模态支持
  • 设计决策

• Gateway 模块 - Agent 注册、消息路由、在线状态管理

  • 架构设计
  • 部署指南
  • API 参考
  • 设计决策
  • Enterprise 层
  • A2A IM 使用 - Agent 间通讯工具

跨模块文档

• A2A IM 系统 - Agent 间即时通讯系统架构
• 知识管理 - 知识结构、API、集成方式
• Context 管理 - Goals、压缩、Plan 注入策略

研究文档

• A2A 协议调研 - 行业 A2A 通信协议和框架对比
• A2A 跨设备通信 - 跨设备 Agent 通信方案（内部）
• A2A Trace 存储 - 跨设备 Trace 存储方案详细设计
• MAMP 协议 - 与外部 Agent 系统的通用交互协议

---

文档维护规范

1. 先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
2. 文档分层，链接代码 - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：module/file.py:function_name
3. 简洁快照，日志分离 - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议，或大量代码；决策依据或修改日志若有必要，可在模块的 decisions.md 另行记录

---

项目概览

系统架构

Agent 系统
├── agent/          # Agent Core - 核心引擎、工具、记忆
├── gateway/        # Gateway - 消息路由、Agent 注册
├── docs/           # 跨模块文档
└── examples/       # 使用示例和集成示例

核心理念

所有 Agent 都是 Trace

类型	创建方式	父子关系	状态
主 Agent	直接调用 runner.run()	无 parent	正常执行
子 Agent	通过 agent 工具	parent_trace_id / parent_goal_id 指向父	正常执行
人类协助	通过 ask_human 工具	parent_trace_id 指向父	阻塞等待

模块职责

模块	职责	详细文档
agent/core/	Agent 执行引擎 + 预设配置	架构设计
agent/trace/	执行追踪 + 计划管理	Trace API
agent/tools/	与外部世界交互	工具系统
agent/memory/	跨会话知识	Skills 指南
agent/llm/	LLM Provider 适配	架构设计
gateway/core/	Agent 注册和消息路由	Gateway 架构
gateway/client/	Gateway 客户端 SDK	A2A IM

---

快速开始

Agent Core

from agent.core import AgentRunner, RunConfig

runner = AgentRunner(...)

async for item in runner.run(
    messages=[{"role": "user", "content": "分析项目架构"}],
    config=RunConfig(model="gpt-4o")
):
    print(item)

详见：Agent Core README

Gateway

# 安装 Gateway 客户端
cd gateway
pip install -e .

# 使用 CLI
gateway-cli send --from my-agent --to target-agent --message "Hello"
gateway-cli list

详见：Gateway README 和 A2A IM 文档

---

相关文档

完整的文档列表见各模块的 README：

• Agent Core 文档
• Gateway 文档