/ README.md
README.md
1 # Erlang Agent Framework 2 3 基于 Erlang/OTP 的高性能 AI Agent 应用框架。 4 5 ## 特性 6 7 - **🤖 Simple Agent**: 基于 Graph 引擎的 ReAct Agent 8 - 支持自定义工具和系统提示词 9 - 内置 Scratchpad 执行历史 10 - 支持 Checkpoint 持久化 11 - 完整的回调系统 12 13 - **🔄 协调器模式**: 统一的多 Agent 协调 14 - **Multi 模式**: 顺序协调（研究员 → 写作者 → 审核员） 15 - **Supervisor 模式**: 并行协调（多个专家同时工作） 16 17 - **🧠 Deep Agent**: 递归规划 Agent 18 - 支持任务规划（Planning） 19 - 支持自我反思（Reflection） 20 - 支持子任务分发 21 22 - **📦 Output Parser**: 结构化输出 23 - JSON Schema 解析 24 - 自动重试机制 25 26 ## 快速开始 27 28 ### 1. 启动 Shell 29 30 ```bash 31 export ZHIPU_API_KEY=your_key_here 32 rebar3 shell 33 ``` 34 35 ### 2. Simple Agent 36 37 ```erlang 38 %% 创建 Agent 39 {ok, Agent} = beamai_agent:start_link(<<"my_agent">>, #{ 40 system_prompt => <<"你是一个有帮助的助手。"/utf8>>, 41 tools => [ 42 #{ 43 name => <<"search">>, 44 description => <<"搜索信息"/utf8>>, 45 input_schema => #{ 46 type => object, 47 properties => #{ 48 <<"query">> => #{ 49 type => string, 50 description => <<"搜索关键词"/utf8>> 51 } 52 }, 53 required => [<<"query">>] 54 }, 55 handler => fun(#{<<"query">> := Query}) -> 56 %% 你的搜索逻辑 57 {ok, <<"搜索结果: ", Query/binary>>} 58 end 59 } 60 ], 61 llm => #{ 62 provider => anthropic, 63 model => <<"glm-4.7">>, 64 api_key => list_to_binary(os:getenv("ZHIPU_API_KEY")), 65 base_url => <<"https://open.bigmodel.cn/api/anthropic">> 66 } 67 }). 68 69 %% 运行 Agent 70 {ok, Result} = beamai_agent:run(Agent, <<"搜索 Erlang 教程"/utf8>>). 71 72 %% 查看结果 73 Response = maps:get(final_response, Result). 74 ``` 75 76 ### 3. Multi 模式协调器（顺序协调） 77 78 ```erlang 79 %% 创建研究团队（研究员 → 写作者 → 审核员） 80 {ok, Team} = beamai_agent:start_multi(<<"content_team">>, #{ 81 agents => [ 82 #{ 83 name => <<"researcher">>, 84 role => <<"研究员"/utf8>>, 85 system_prompt => <<"你是研究员，负责收集资料。"/utf8>> 86 }, 87 #{ 88 name => <<"writer">>, 89 role => <<"写作者"/utf8>>, 90 system_prompt => <<"你是写作者，负责撰写文章。"/utf8>> 91 }, 92 #{ 93 name => <<"reviewer">>, 94 role => <<"审核员"/utf8>>, 95 system_prompt => <<"你是审核员，负责质量检查。"/utf8>> 96 } 97 ], 98 llm => LLMConfig 99 }). 100 101 %% 运行任务 102 {ok, Result} = beamai_agent:run(Team, 103 <<"研究并撰写一篇关于 Erlang 并发模型的 100 字介绍。"/utf8>>). 104 ``` 105 106 ### 4. Supervisor 模式协调器（并行协调） 107 108 ```erlang 109 %% 创建开发团队（前端 + 后端并行工作） 110 {ok, Team} = beamai_agent:start_supervisor(<<"dev_team">>, #{ 111 agents => [ 112 #{ 113 name => <<"frontend">>, 114 role => <<"前端专家"/utf8>>, 115 system_prompt => <<"你是前端开发专家。"/utf8>> 116 }, 117 #{ 118 name => <<"backend">>, 119 role => <<"后端专家"/utf8>>, 120 system_prompt => <<"你是后端开发专家。"/utf8>> 121 } 122 ], 123 llm => LLMConfig 124 }). 125 126 %% 运行任务 127 {ok, Result} = beamai_agent:run(Team, 128 <<"从不同角度介绍 RESTful API 的设计。"/utf8>>). 129 ``` 130 131 ### 5. Deep Agent（规划 + 反思） 132 133 ```erlang 134 %% 创建带规划的深度 Agent 135 {ok, Agent} = beamai_deepagent:start_link(<<"deep_agent">>, #{ 136 max_depth => 3, 137 planning_enabled => true, 138 reflection_enabled => true, 139 system_prompt => <<"你是一个研究专家。"/utf8>>, 140 tools => [...], 141 llm => LLMConfig 142 }). 143 144 %% 运行复杂任务 145 {ok, Result} = beamai_deepagent:run(Agent, 146 <<"分析这个代码库的架构并给出优化建议。"/utf8>>). 147 148 %% 查看执行计划 149 {ok, Plan} = beamai_deepagent:get_plan(Agent). 150 151 %% 查看执行轨迹 152 {ok, Trace} = beamai_deepagent:get_execution_trace(Agent). 153 ``` 154 155 ## 架构 156 157 ### 应用结构 158 159 ``` 160 apps/ 161 ├── beamai_core/ # 核心功能 + Persistence 162 │ ├── Behaviours # beamai_behaviour, agent_persistence_behaviour 163 │ ├── HTTP # beamai_http (Hackney 客户端) 164 │ ├── Graph # Graph 执行引擎 165 │ ├── Pregel # Pregel 分布式计算 166 │ └── Persistence # agent_storage_ets, agent_storage_sup 167 │ 168 ├── beamai_llm/ # LLM 客户端 169 │ └── Providers # OpenAI, Anthropic, Zhipu, Ollama 170 │ 171 ├── beamai_rag/ # RAG 功能 172 │ ├── Embeddings # 向量嵌入 173 │ └── Vector Store # 向量存储 174 │ 175 ├── beamai_memory/ # 内存和上下文存储 176 │ ├── Context # 上下文管理 177 │ └── Store # ETS/SQLite 存储后端 178 │ 179 ├── beamai_a2a/ # A2A 协议实现 180 │ ├── Server # A2A 服务端 181 │ └── Client # A2A 客户端 182 │ 183 ├── beamai_mcp/ # MCP 协议实现 184 │ ├── Server # MCP 服务端 185 │ └── Client # MCP 客户端 186 │ 187 ├── beamai_agent/ # Simple Agent + 协调器 188 │ ├── Graph Engine # 基于 Graph 的执行 189 │ ├── Scratchpad # 执行历史 190 │ ├── Checkpoint # 状态持久化 191 │ ├── Callbacks # 回调系统 192 │ └── Coordinator # Multi/Supervisor 协调器 193 │ 194 └── beamai_deepagent/ # Deep Agent 195 ├── Planning # 任务规划 196 ├── Reflection # 自我反思 197 └── Router # 智能路由 198 ``` 199 200 ### 依赖关系 201 202 ``` 203 ┌─────────────────────────────────┐ 204 │ Agent 实现 │ 205 │ (beamai_agent, beamai_deepagent) │ 206 └────────────┬────────────────────┘ 207 │ 208 ┌────────────┴────────────────────┐ 209 │ 服务层 │ 210 │ (beamai_llm, beamai_rag, │ 211 │ beamai_a2a, beamai_mcp) │ 212 └────────────┬────────────────────┘ 213 │ 214 ┌────────────┴────────────────────┐ 215 │ 核心层 │ 216 │ (beamai_core, beamai_memory) │ 217 └─────────────────────────────────┘ 218 ``` 219 220 详见 [DEPENDENCIES.md](DEPENDENCIES.md) 221 222 ## 核心概念 223 224 ### 1. Graph 执行引擎 225 226 beamai_agent 使用 Graph 引擎执行 Agent： 227 228 ```erlang 229 %% Graph 定义 230 Graph = #{ 231 nodes => #{ 232 llm => {beamai_llm_node, #{}}, 233 tools => {beamai_tools_node, #{}} 234 }, 235 edges => [ 236 {llm, tools, {condition, fun should_use_tools/1}} 237 ] 238 } 239 240 %% 执行 Graph 241 {ok, Result} = graph_runner:run(Graph, Input). 242 ``` 243 244 ### 2. Scratchpad（执行历史） 245 246 Scratchpad 记录每一步的执行过程： 247 248 ```erlang 249 %% 获取 Scratchpad 250 {ok, Steps} = beamai_agent:get_scratchpad(Agent). 251 252 %% 每一步包含： 253 %% - step_id: 步骤 ID 254 %% - type: 步骤类型 (llm_call, tool_use, tool_result) 255 %% - content: 内容 256 %% - timestamp: 时间戳 257 ``` 258 259 ### 3. Checkpoint（状态持久化） 260 261 保存和恢复 Agent 状态： 262 263 ```erlang 264 %% 保存检查点 265 {ok, CheckpointId} = beamai_agent:save_checkpoint(Agent, #{ 266 metadata => #{tag => <<"v1">>} 267 }). 268 269 %% 列出所有检查点 270 {ok, Checkpoints} = beamai_agent:list_checkpoints(Agent). 271 272 %% 从检查点恢复 273 ok = beamai_agent:restore_from_checkpoint(Agent, CheckpointId). 274 ``` 275 276 ### 4. Callbacks（回调系统） 277 278 监听 Agent 执行事件： 279 280 ```erlang 281 {ok, Agent} = beamai_agent:start_link(<<"my_agent">>, #{ 282 callbacks => #{ 283 on_llm_start => fun(Prompts, Meta) -> 284 io:format("LLM 调用开始...~n") 285 end, 286 on_llm_end => fun(Response, Meta) -> 287 io:format("LLM 响应收到~n") 288 end, 289 on_tool_use => fun(ToolName, Args, Meta) -> 290 io:format("使用工具: ~ts~n", [ToolName]) 291 end 292 } 293 }). 294 ``` 295 296 ## 配置 297 298 ### LLM 配置 299 300 ```erlang 301 %% 方式 1: GLM-4.7 + Anthropic Provider 302 LLMConfig = #{ 303 provider => anthropic, 304 model => <<"glm-4.7">>, 305 api_key => ApiKey, 306 base_url => <<"https://open.bigmodel.cn/api/anthropic">>, 307 timeout => 60000 308 }. 309 310 %% 方式 2: GLM-4.6 + Zhipu Provider 311 LLMConfig = #{ 312 provider => zhipu, 313 model => <<"glm-4.6">>, 314 api_key => ApiKey, 315 timeout => 60000 316 }. 317 ``` 318 319 ### Agent 配置选项 320 321 ```erlang 322 Opts = #{ 323 %% 基础配置 324 id => <<"agent_id">>, 325 system_prompt => Prompt, 326 tools => [Tool1, Tool2], 327 328 %% LLM 配置 329 llm => LLMConfig, 330 331 %% 执行配置 332 max_iterations => 10, %% 最大迭代次数 333 timeout => 300000, %% 超时时间 334 335 %% Checkpoint 配置 336 enable_storage => true, %% 启用存储 337 auto_save => true, %% 自动保存检查点 338 339 %% 回调配置 340 callbacks => #{ 341 on_llm_start => fun(...), ... 342 } 343 }. 344 ``` 345 346 ## 高级功能 347 348 ### 自定义工具 349 350 ```erlang 351 #{name => <<"my_tool">>, 352 description => <<"工具描述"/utf8>>, 353 input_schema => #{ 354 type => object, 355 properties => #{ 356 <<"param1">> => #{type => string}, 357 <<"param2">> => #{type => integer} 358 }, 359 required => [<<"param1">>] 360 }, 361 handler => fun(Args, Context) -> 362 %% 工具逻辑 363 {ok, Result} 364 end} 365 ``` 366 367 ### Output Parser 368 369 ```erlang 370 %% 定义输出 schema 371 Schema = #{ 372 type => object, 373 properties => #{ 374 <<"title">> => #{type => string}, 375 <<"count">> => #{type => integer}, 376 <<"items">> => #{ 377 type => array, 378 items => #{type => string} 379 } 380 }, 381 required => [<<"title">>, <<"count">>] 382 }. 383 384 %% 使用 Parser 385 {ok, Parsed} = agent_output_parser:parse( 386 LLMResponse, 387 Schema, 388 #{max_retries => 3} 389 ). 390 ``` 391 392 ## 文档 393 394 ### 核心文档 395 396 - **[doc/API_REFERENCE.md](doc/API_REFERENCE.md)** - API 参考文档 397 - **[doc/MIDDLEWARE.md](doc/MIDDLEWARE.md)** - Middleware 系统文档 398 - **[doc/ARCHITECTURE.md](doc/ARCHITECTURE.md)** - 架构设计 399 - **[doc/QUICK_START.md](doc/QUICK_START.md)** - 快速开始 400 - **[DEPENDENCIES.md](DEPENDENCIES.md)** - 依赖关系详解 401 402 ### 模块文档 403 404 | 模块 | 说明 | 文档 | 405 |------|------|------| 406 | **beamai_core** | 核心框架：Graph 引擎、Pregel 分布式计算、行为定义 | [README](apps/beamai_core/README.md) | 407 | **beamai_llm** | LLM 客户端：支持 OpenAI、Anthropic、Zhipu、Ollama | [README](apps/beamai_llm/README.md) | 408 | **beamai_agent** | Simple Agent：ReAct 模式、回调系统、Checkpoint | [README](apps/beamai_agent/README.md) | 409 | **beamai_deepagent** | Deep Agent：任务规划、并行执行、自我反思 | [README](apps/beamai_deepagent/README.md) | 410 | **beamai_memory** | 记忆管理：Checkpoint、Store、时间旅行 | [README](apps/beamai_memory/README.md) | 411 | **beamai_tools** | 工具库：Provider 机制、工具注册表、内置工具 | [README](apps/beamai_tools/README.md) | 412 | **beamai_a2a** | A2A 协议：Agent 间通信、服务端/客户端 | [README](apps/beamai_a2a/README.md) | 413 | **beamai_mcp** | MCP 协议：Model Context Protocol 实现 | [README](apps/beamai_mcp/README.md) | 414 | **beamai_rag** | RAG 功能：向量嵌入、相似度搜索 | [README](apps/beamai_rag/README.md) | 415 416 ### 其他文档 417 418 - **[doc/DESIGN_PATTERNS.md](doc/DESIGN_PATTERNS.md)** - 设计模式 419 - **[doc/OUTPUT_PARSER.md](doc/OUTPUT_PARSER.md)** - Output Parser 指南 420 - **[REFACTORING_REPORT.md](REFACTORING_REPORT.md)** - 重构总结报告 421 422 ## 运行示例 423 424 ```bash 425 # 编译 426 rebar3 compile 427 428 # 启动 Shell 429 rebar3 shell 430 431 # 运行交互式 Deep Agent 432 examples/interactive_deep_agent.erl 433 ``` 434 435 ## 项目统计 436 437 - **应用数量**: 8 个 438 - **代码行数**: ~15,000 行 439 - **测试覆盖**: 持续改进中 440 - **文档**: 完整的 API 和架构文档 441 442 ## 性能 443 444 - ✅ 基于 Erlang/OTP 轻量级进程 445 - ✅ Graph 引擎优化执行路径 446 - ✅ 并发工具调用 447 - ✅ HTTP 连接池（Hackney） 448 - ✅ ETS 高速存储 449 450 ## 设计原则 451 452 - **简单**: 清晰的 API，易于理解 453 - **模块化**: 每个模块职责单一 454 - **可扩展**: Behaviour 设计，易于自定义 455 - **高性能**: 利用 Erlang 并发特性 456 - **可观测**: 完善的日志、追踪、监控 457 458 ## 许可证 459 460 Apache-2.0 461 462 ## 贡献 463 464 欢迎提交 Issue 和 Pull Request！ 465 466 --- 467 468 **开始构建你的 AI Agent 应用！** 🚀