# echo-agent 文档
> **English docs** → [docs/en/README.md](../en/README.md)
---
## 文档索引
### 核心功能
| [01 - ReAct Agent](01-react-agent.md) | 核心执行引擎 | Thought→Action→Observation、CoT、并行工具调用、回调 |
| [02 - 工具系统](02-tools.md) | Tools | Tool trait、ToolManager、超时重试、并发限流 |
| [03 - 记忆系统](03-memory.md) | Memory | Store（长期）、Checkpointer（短期）、namespace 隔离 |
| [04 - 上下文压缩](04-compression.md) | Compression | SlidingWindow、Summary、Hybrid、ContextManager |
| [05 - 人工介入](05-human-loop.md) | Human-in-the-Loop | 审批 Guard、Console/Webhook/WebSocket Provider |
| [06 - 多 Agent 编排](06-subagent.md) | SubAgent / Orchestration | Orchestrator/Worker/Planner、上下文隔离 |
| [07 - Skill 系统](07-skills.md) | Skills | 能力包、系统提示词注入、外部 SKILL.md 加载 |
| [08 - MCP 协议](08-mcp.md) | MCP | stdio/HTTP 传输、工具适配、多服务端管理 |
| [09 - 任务规划](09-tasks.md) | Tasks / DAG | 有向无环图、拓扑排序、循环依赖检测、Mermaid 可视化 |
| [10 - 流式输出](10-streaming.md) | Streaming | execute_stream、AgentEvent、SSE、TTFT |
| [11 - 结构化输出](11-structured-output.md) | Structured Output | ResponseFormat、JsonSchema、extract()、extract_json() |
| [12 - Mock 测试工具](12-mock.md) | Testing | MockLlmClient、MockTool、MockAgent、InMemoryStore |
| [13 - 多轮对话](13-chat.md) | Chat | chat()、chat_stream()、跨轮记忆、reset() |
| [14 - 语义搜索](14-semantic-search.md) | Semantic Search | EmbeddingStore、Embedder、向量索引、余弦相似度 |
| [15 - IM Channels](15-im-channels.md) | IM Channels | QQ Bot / 飞书接入、WebSocket / Webhook、ChannelPlugin、消息路由 |
### 高级功能 (v1.0.0)
| [19 - Self-Reflection Agent](19-self-reflection.md) | 自我反思 | 生成 → 评估 → 修正、情景记忆、LlmCritic |
| [16 - Plan-and-Execute](16-plan-execute.md) | 规划执行 | Planner/Executor、增量重规划、DAG 调度 |
| [17 - Graph Workflow](17-graph-workflow.md) | 图工作流 | LangGraph 风格、SharedState、条件边、fan-out/fan-in |
| [18 - Guard 系统](18-guard-system.md) | 护栏系统 | RuleGuard、LlmGuard、输入/输出过滤 |
| [20 - Web 工具](20-web-tools.md) | Web 搜索 / 网页获取 | DuckDuckGo / Brave / Tavily 搜索、HTML→文本 |
| [21 - 常用工具速查](21-common-tools.md) | Tool Guide | Web 搜索、网页抓取、浏览器自动化、数据工具 |
### 知识库
参见 [知识库](../knowledge/README.md) 获取深入概念讲解：
- [Agent 模式](../knowledge/agent-patterns.md) — ReAct、Plan-and-Execute、Self-Reflection、Graph Workflow
- [MCP 协议](../knowledge/mcp-protocol.md) — Model Context Protocol 规范
- [Skill 系统设计](../knowledge/skill-system.md) — agentskills.io 规范对齐
- [A2A 协议](../knowledge/a2a-protocol.md) — Agent-to-Agent 通信
---
## 快速上手
### 单次任务模式（`execute`）
```rust
use echo_agent::prelude::*;
#[tokio::main]
async fn main() -> Result<()> {
let config = AgentConfig::new("qwen3-max", "assistant", "你是一个有帮助的助手");
let mut agent = ReactAgent::new(config);
let answer = agent.execute("你好，介绍一下自己").await?;
println!("{}", answer);
Ok(())
}
```
### 多轮对话模式（`chat`）
`chat()` 在现有上下文上追加消息，天然支持多轮连续对话；
`execute()` 每次都会重置上下文，适合独立的单次任务。
```rust
use echo_agent::prelude::*;
#[tokio::main]
async fn main() -> Result<()> {
let config = AgentConfig::new("qwen3-max", "assistant", "你是一个有帮助的助手");
let mut agent = ReactAgent::new(config);
let r1 = agent.chat("你好，我叫小明，是一名 Rust 程序员。").await?;
println!("Agent: {r1}");
let r2 = agent.chat("你还记得我的名字吗？").await?;
println!("Agent: {r2}"); // Agent 能记住上下文中的"小明"
agent.reset(); // 清除历史，开启新会话
Ok(())
}
```
---
## 架构总览
```
┌─────────────────────────────────────────────────────────┐
│ 用户 / 应用 │
└────────────────────────┬────────────────────────────────┘
│ execute() / execute_stream() （单次任务，每次重置上下文）
│ chat() / chat_stream() （多轮对话，保留历史）
┌────────────────────────▼────────────────────────────────┐
│ ReactAgent │
│ │
│ ┌──────────────┐ ┌────────────┐ ┌─────────────────┐ │
│ │ContextManager│ │ToolManager │ │ SkillManager │ │
│ │ (压缩/历史) │ │(注册/执行) │ │ (Skill 元数据) │ │
│ └──────────────┘ └────────────┘ └─────────────────┘ │
│ │
│ ┌──────────────┐ ┌────────────┐ ┌─────────────────┐ │
│ │ Checkpointer│ │ Store │ │HumanApprovalMgr │ │
│ │ (线程恢复) │ │(长期记忆) │ │ (审批 Guard) │ │
│ └──────────────┘ └────────────┘ └─────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ SubAgent 注册表 │ │
│ └──────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────────┘
│ HTTP (OpenAI API)
┌────────────────────────▼────────────────────────────────┐
│ LLM Provider │
└─────────────────────────────────────────────────────────┘
```
---
## 功能矩阵
| 单次任务执行 | `execute()` / `execute_stream()` | — |
| **多轮对话** | **`chat()` / `chat_stream()`** | — |
| 工具调用 | `enable_tool` | `true` |
| DAG 任务规划 | `enable_task` | `false` |
| SubAgent 编排 | `enable_subagent` | `false` |
| 长期记忆 (Store) | `enable_memory` | `false` |
| 人工介入 | `enable_human_in_loop` | `false` |
| Chain-of-Thought 提示词 | `enable_cot` | `true` |
| 上下文压缩 | 通过 `set_compressor()` | 无 |
| 线程持久化 / 恢复 | `session_id` + `checkpointer_path` | 无 |
| transcript/history 投影 | `conversation_id` + `ConversationStore` | 无 |
---
## 示例文件
所有示例按 `验收样例`、`条件验收样例`、`教学示例` 三类维护。
完整分层清单和维护规则见 `examples/README.md`。
| `examples/demo01_tools.rs` | 基础工具注册与调用 |
| `examples/demo02_tasks.rs` | DAG 任务规划 |
| `examples/demo03_approval.rs` | 人工审批 |
| `examples/demo04_suagent.rs` | SubAgent 编排 |
| `examples/demo05_compressor.rs` | 上下文压缩 |
| `examples/demo06_mcp.rs` | MCP 协议集成 |
| `examples/demo07_skills.rs` | Skill 系统 |
| `examples/demo08_external_skills.rs` | 外部 SKILL.md 加载 |
| `examples/demo09_file_shell.rs` | 文件和 Shell 工具 |
| `examples/demo10_streaming.rs` | 流式输出 |
| `examples/demo11_callbacks.rs` | 生命周期回调 |
| `examples/demo12_resilience.rs` | 容错与重试 |
| `examples/demo13_tool_execution.rs` | 工具执行配置 |
| `examples/demo14_memory_isolation.rs` | 记忆隔离与上下文隔离 |
| `examples/demo15_structured_output.rs` | 结构化输出（extract / JSON Schema） |
| `examples/demo16_testing.rs` | Mock 测试基础设施（零真实 LLM 调用） |
| `examples/demo17_chat.rs` | 多轮对话（chat / chat_stream / reset） |
| `examples/demo18_semantic_memory.rs` | Store 语义搜索（EmbeddingStore / 向量检索） |