# echo-agent Documentation
echo-agent is a composable Agent development framework written in Rust, providing a ReAct execution engine, tool system, dual-layer memory, context compression, human-in-the-loop, multi-Agent orchestration, Skill system, MCP protocol integration, and more.
> **中文文档** → [docs/zh/README.md](../zh/README.md)
---
## Documentation Index
### Core Features
| [01 - ReAct Agent](./01-react-agent.md) | Core engine | Thought→Action→Observation, CoT, parallel tool calls, callbacks |
| [02 - Tool System](./02-tools.md) | Tools | Tool trait, ToolManager, timeout/retry, concurrency limiting |
| [03 - Memory System](./03-memory.md) | Memory | Store (long-term), Checkpointer (short-term), namespace isolation |
| [04 - Context Compression](./04-compression.md) | Compression | SlidingWindow, Summary, Hybrid pipeline, ContextManager |
| [05 - Human-in-the-Loop](./05-human-loop.md) | HIL | Approval gate, Console/Webhook/WebSocket providers |
| [06 - Multi-Agent Orchestration](./06-subagent.md) | SubAgent | Orchestrator/Worker/Planner, context isolation |
| [07 - Skill System](./07-skills.md) | Skills | Capability packs, prompt injection, external SKILL.md loading |
| [08 - MCP Integration](./08-mcp.md) | MCP | stdio/HTTP transport, tool adaptation, multi-server management |
| [09 - Task Planning](./09-tasks.md) | Tasks / DAG | DAG, topological sort, cycle detection, Mermaid visualization |
| [10 - Streaming Output](./10-streaming.md) | Streaming | execute_stream, AgentEvent, SSE, TTFT |
| [11 - Structured Output](./11-structured-output.md) | Structured Output | ResponseFormat, JsonSchema, extract(), extract_json() |
| [12 - Mock Testing Utilities](./12-mock.md) | Testing | MockLlmClient, MockTool, MockAgent, InMemoryStore |
| [13 - Multi-Turn Chat](./13-chat.md) | Chat | chat(), chat_stream(), cross-turn memory, reset() |
| [14 - Semantic Search](./14-semantic-search.md) | Semantic Search | EmbeddingStore, Embedder, vector index, cosine similarity |
| [15 - IM Channels](./15-im-channels.md) | IM Channels | QQ Bot / Feishu integration, WebSocket / Webhook, ChannelPlugin, message routing |
### Advanced Features (v1.0.0)
| [19 - Self-Reflection Agent](./19-self-reflection.md) | Self-Reflection | Generate → Critique → Refine, episodic memory, LlmCritic |
| [16 - Plan-and-Execute](./16-plan-execute.md) | Plan-Execute | Planner/Executor, incremental replanning, DAG scheduling |
| [17 - Graph Workflow](./17-graph-workflow.md) | Workflow | LangGraph-style, SharedState, conditional edges, fan-out/fan-in |
| [18 - Guard System](./18-guard-system.md) | Guards | RuleGuard, LlmGuard, input/output filtering |
| [20 - Web Tools](./20-web-tools.md) | Web Search / Fetch | DuckDuckGo / Brave / Tavily search, HTML→text |
| [21 - Common Tools](./21-common-tools.md) | Tool Guide | Web search, web fetch, browser automation, data tools |
### Knowledge Base
See [Knowledge Base](../knowledge/README.md) for in-depth concept explanations:
- [Agent Patterns](../knowledge/agent-patterns.md) — ReAct, Plan-and-Execute, Self-Reflection, Graph Workflow
- [MCP Protocol](../knowledge/mcp-protocol.md) — Model Context Protocol specification
- [Skill System Design](../knowledge/skill-system.md) — agentskills.io specification alignment
- [A2A Protocol](../knowledge/a2a-protocol.md) — Agent-to-Agent communication
---
## Quick Start
### Single-task mode (`execute`)
```rust
use echo_agent::prelude::*;
#[tokio::main]
async fn main() -> Result<()> {
let config = AgentConfig::new("qwen3-max", "assistant", "You are a helpful assistant");
let mut agent = ReactAgent::new(config);
let answer = agent.execute("Explain the concept of ownership in Rust").await?;
println!("{}", answer);
Ok(())
}
```
### Multi-turn chat mode (`chat`)
`chat()` preserves conversation history across calls, enabling natural multi-turn dialogue.
`execute()` resets context on every call and is suited for independent single-turn tasks.
```rust
use echo_agent::prelude::*;
#[tokio::main]
async fn main() -> Result<()> {
let config = AgentConfig::new("qwen3-max", "assistant", "You are a helpful assistant");
let mut agent = ReactAgent::new(config);
let r1 = agent.chat("Hi, I'm Alice and I'm a Rust developer.").await?;
println!("Agent: {r1}");
let r2 = agent.chat("Do you remember my name?").await?;
println!("Agent: {r2}"); // Agent remembers "Alice" from the prior turn
agent.reset(); // clear history, start a new session
Ok(())
}
```
---
## Architecture Overview
```
┌─────────────────────────────────────────────────────────┐
│ User / Application │
└────────────────────────┬────────────────────────────────┘
│ execute() / execute_stream() (single-task, resets context)
│ chat() / chat_stream() (multi-turn, preserves context)
┌────────────────────────▼────────────────────────────────┐
│ ReactAgent │
│ │
│ ┌──────────────┐ ┌────────────┐ ┌─────────────────┐ │
│ │ContextManager│ │ToolManager │ │ SkillManager │ │
│ │(compression) │ │(execution) │ │ (Skill metadata)│ │
│ └──────────────┘ └────────────┘ └─────────────────┘ │
│ │
│ ┌──────────────┐ ┌────────────┐ ┌─────────────────┐ │
│ │ Checkpointer│ │ Store │ │HumanApprovalMgr │ │
│ │(session hist)│ │(long-term) │ │ (approval gate) │ │
│ └──────────────┘ └────────────┘ └─────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ SubAgent Registry │ │
│ │ { "math_agent": Arc<AsyncMutex<Box<dyn Agent>>> │ │
│ │ "writer_agent": ... } │ │
│ └──────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────────┘
│ HTTP (OpenAI-compatible API)
┌────────────────────────▼────────────────────────────────┐
│ LLM Provider │
│ (OpenAI / DeepSeek / Qwen / Ollama / ...) │
└─────────────────────────────────────────────────────────┘
```
---
## Feature Matrix
| Single-task execution | `execute()` / `execute_stream()` | — |
| **Multi-turn chat** | **`chat()` / `chat_stream()`** | — |
| Tool calling | `enable_tool` | `true` |
| DAG task planning | `enable_task` | `false` |
| SubAgent orchestration | `enable_subagent` | `false` |
| Long-term memory (Store) | `enable_memory` | `false` |
| Human-in-the-loop | `enable_human_in_loop` | `false` |
| Chain-of-Thought prompt | `enable_cot` | `true` |
| Context compression | via `set_compressor()` | none |
| Thread persistence / resume | `session_id` + `checkpointer_path` | none |
| Transcript/history projection | `conversation_id` + `ConversationStore` | none |
---
## Example Files
Examples are maintained under three contracts: `Acceptance`, `Conditional acceptance`, and `Teaching`.
See `examples/README.md` for the full classification and upkeep rules.
| `examples/demo01_tools.rs` | Basic tool registration and invocation |
| `examples/demo02_tasks.rs` | DAG task planning |
| `examples/demo03_approval.rs` | Human-in-the-loop approval |
| `examples/demo04_suagent.rs` | SubAgent orchestration |
| `examples/demo05_compressor.rs` | Context compression |
| `examples/demo06_mcp.rs` | MCP protocol integration |
| `examples/demo07_skills.rs` | Skill system |
| `examples/demo08_external_skills.rs` | External SKILL.md loading |
| `examples/demo09_file_shell.rs` | File and shell tools |
| `examples/demo10_streaming.rs` | Streaming output |
| `examples/demo11_callbacks.rs` | Lifecycle callbacks |
| `examples/demo12_resilience.rs` | Fault tolerance and retries |
| `examples/demo13_tool_execution.rs` | Tool execution configuration |
| `examples/demo14_memory_isolation.rs` | Memory and context isolation |
| `examples/demo15_structured_output.rs` | Structured output (extract / JSON Schema) |
| `examples/demo16_testing.rs` | Mock testing infrastructure (zero real LLM calls) |
| `examples/demo17_chat.rs` | Multi-turn chat (chat / chat_stream / reset) |
| `examples/demo18_semantic_memory.rs` | Store semantic search (EmbeddingStore / vector retrieval) |