# Agent 系统文档

## 文档导航

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

### 核心模块

- **[Agent Core 模块](../agent/README.md)** - Agent 核心引擎、工具系统、记忆管理
  - [架构设计](../agent/docs/architecture.md) - Agent 框架完整架构
  - [工具系统](../agent/docs/tools.md)
  - [Skills 指南](../agent/docs/skills.md)
  - [Trace API](../agent/docs/trace-api.md)
  - [多模态支持](../agent/docs/multimodal.md)
  - [设计决策](../agent/docs/decisions.md)

- **[Gateway 模块](../gateway/README.md)** - Agent 注册、消息路由、在线状态管理
  - [架构设计](../gateway/docs/architecture.md)
  - [部署指南](../gateway/docs/deployment.md)
  - [API 参考](../gateway/docs/api.md)
  - [设计决策](../gateway/docs/decisions.md)
  - [Enterprise 层](../gateway/docs/enterprise/overview.md)
  - [A2A IM 使用](../gateway/client/a2a_im.md) - Agent 间通讯工具

### 跨模块文档

- [A2A IM 系统](./a2a-im.md) - Agent 间即时通讯系统架构
- [知识管理](../knowhub/docs/knowledge-management.md) - 知识结构、API、集成方式
- [Context 管理](./context-management.md) - Goals、压缩、Plan 注入策略

### 研究文档

- [A2A 协议调研](./research/a2a-protocols.md) - 行业 A2A 通信协议和框架对比
- [A2A 跨设备通信](./research/a2a-cross-device.md) - 跨设备 Agent 通信方案（内部）
- [A2A Trace 存储](./research/a2a-trace-storage.md) - 跨设备 Trace 存储方案详细设计
- [MAMP 协议](./research/a2a-mamp-protocol.md) - 与外部 Agent 系统的通用交互协议

---

## 文档维护规范

0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
1. **文档分层，链接代码** - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：`module/file.py:function_name`
2. **简洁快照，日志分离** - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议，或大量代码；决策依据或修改日志若有必要，可在模块的 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/docs/architecture.md) |
| **agent/trace/** | 执行追踪 + 计划管理 | [Trace API](../agent/docs/trace-api.md) |
| **agent/tools/** | 与外部世界交互 | [工具系统](../agent/docs/tools.md) |
| **agent/memory/** | 跨会话知识 | [Skills 指南](../agent/docs/skills.md) |
| **agent/llm/** | LLM Provider 适配 | [架构设计](../agent/docs/architecture.md#llm-provider-适配) |
| **gateway/core/** | Agent 注册和消息路由 | [Gateway 架构](../gateway/docs/architecture.md) |
| **gateway/client/** | Gateway 客户端 SDK | [A2A IM](../gateway/client/a2a_im.md) |

---

## 快速开始

### Agent Core

```python
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](../agent/README.md)

### Gateway

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

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

详见：[Gateway README](../gateway/README.md) 和 [A2A IM 文档](../gateway/client/a2a_im.md)

---

## 相关文档

完整的文档列表见各模块的 README：
- [Agent Core 文档](../agent/README.md#文档)
- [Gateway 文档](../gateway/README.md#文档)