1  # API 参考文档
  2  
  3  本文档提供 BeamAI Framework 各模块的主要 API 参考。
  4  
  5  ## 目录
  6  
  7  - [beamai_agent - Simple Agent](#beamai_agent---simple-agent)
  8  - [Middleware 系统](#middleware-系统)
  9  - [beamai_deepagent - Deep Agent](#beamai_deepagent---deep-agent)
 10  - [beamai_llm - LLM 客户端](#beamai_llm---llm-客户端)
 11  - [beamai_memory - 记忆管理](#beamai_memory---记忆管理)
 12  - [beamai_tools - 工具库](#beamai_tools---工具库)
 13  - [beamai_core - 核心模块](#beamai_core---核心模块)
 14  - [beamai_a2a - A2A 协议](#beamai_a2a---a2a-协议)
 15  - [beamai_mcp - MCP 协议](#beamai_mcp---mcp-协议)
 16  - [beamai_rag - RAG 功能](#beamai_rag---rag-功能)
 17  
 18  ---
 19  
 20  ## beamai_agent - Simple Agent
 21  
 22  ReAct 模式的简单 Agent 实现。
 23  
 24  ### 生命周期管理
 25  
 26  ```erlang
 27  %% 启动 Agent（进程模式）
 28  -spec start_link(binary(), map()) -> {ok, pid()} | {error, term()}.
 29  beamai_agent:start_link(AgentId, Config).
 30  
 31  %% 停止 Agent
 32  -spec stop(pid()) -> ok.
 33  beamai_agent:stop(Agent).
 34  ```
 35  
 36  ### 执行 API
 37  
 38  ```erlang
 39  %% 运行 Agent（进程模式）
 40  -spec run(pid(), binary()) -> {ok, map()} | {error, term()}.
 41  beamai_agent:run(Agent, Input).
 42  
 43  %% 单次执行（纯函数模式）
 44  -spec run_once(map(), binary()) -> {ok, map()} | {error, term()}.
 45  beamai_agent:run_once(Config, Input).
 46  
 47  %% 使用状态执行
 48  -spec run_with_state(state(), binary(), map()) -> {ok, map(), state()} | {error, term()}.
 49  beamai_agent:run_with_state(State, Input, Opts).
 50  ```
 51  
 52  ### 状态管理
 53  
 54  ```erlang
 55  %% 创建状态
 56  -spec create_state(map()) -> {ok, state()}.
 57  -spec create_state(binary(), map()) -> {ok, state()}.
 58  beamai_agent:create_state(Config).
 59  beamai_agent:create_state(AgentId, Config).
 60  
 61  %% 导出/导入状态
 62  -spec export_state(state()) -> map().
 63  -spec import_state(map(), map()) -> {ok, state()}.
 64  beamai_agent:export_state(State).
 65  beamai_agent:import_state(ExportedData, Config).
 66  ```
 67  
 68  ### Checkpoint 管理
 69  
 70  ```erlang
 71  %% 保存检查点
 72  -spec save_checkpoint(pid()) -> {ok, binary()} | {error, term()}.
 73  -spec save_checkpoint(pid(), map()) -> {ok, binary()} | {error, term()}.
 74  beamai_agent:save_checkpoint(Agent).
 75  beamai_agent:save_checkpoint(Agent, Metadata).
 76  
 77  %% 加载检查点
 78  -spec load_checkpoint(pid(), binary()) -> {ok, map()} | {error, term()}.
 79  -spec load_latest_checkpoint(pid()) -> {ok, map()} | {error, term()}.
 80  beamai_agent:load_checkpoint(Agent, CheckpointId).
 81  beamai_agent:load_latest_checkpoint(Agent).
 82  
 83  %% 从检查点恢复
 84  -spec restore_from_checkpoint(pid(), binary()) -> ok | {error, term()}.
 85  beamai_agent:restore_from_checkpoint(Agent, CheckpointId).
 86  
 87  %% 列出检查点
 88  -spec list_checkpoints(pid()) -> {ok, [map()]} | {error, term()}.
 89  beamai_agent:list_checkpoints(Agent).
 90  ```
 91  
 92  ### 回调管理
 93  
 94  ```erlang
 95  %% 获取/设置回调
 96  -spec get_callbacks(pid()) -> map().
 97  -spec set_callbacks(pid(), map()) -> ok.
 98  beamai_agent:get_callbacks(Agent).
 99  beamai_agent:set_callbacks(Agent, Callbacks).
100  
101  %% 触发自定义事件
102  -spec emit_custom_event(pid(), atom(), map()) -> ok.
103  beamai_agent:emit_custom_event(Agent, EventName, Data).
104  ```
105  
106  ### 配置选项
107  
108  ```erlang
109  Config = #{
110      system_prompt => binary(),           %% 系统提示词
111      tools => [tool_def()],               %% 工具列表
112      llm => llm_config(),                 %% LLM 配置
113      max_iterations => integer(),         %% 最大迭代次数，默认 10
114      storage => beamai_memory(),          %% 可选：存储实例
115      callbacks => callback_map(),         %% 可选：回调函数
116      middleware => [middleware_spec()]    %% 可选：中间件
117  }.
118  ```
119  
120  ---
121  
122  ## Middleware 系统
123  
124  Agent 执行过程中的拦截器机制。详细文档：[MIDDLEWARE.md](MIDDLEWARE.md)
125  
126  ### beamai_middleware 行为
127  
128  ```erlang
129  %% 所有回调都是可选的
130  -callback init(Opts :: map()) -> middleware_state().
131  -callback before_agent(State, MwState) -> middleware_result().
132  -callback after_agent(State, MwState) -> middleware_result().
133  -callback before_model(State, MwState) -> middleware_result().
134  -callback after_model(State, MwState) -> middleware_result().
135  -callback before_tools(State, MwState) -> middleware_result().
136  -callback after_tools(State, MwState) -> middleware_result().
137  ```
138  
139  ### 返回值类型
140  
141  ```erlang
142  -type middleware_result() ::
143      ok |                              %% 无修改
144      {update, map()} |                 %% 更新图状态
145      {goto, model | tools | '__end__'} |  %% 跳转
146      {update_goto, map(), goto_target()} |  %% 更新并跳转
147      {halt, term()} |                  %% 中止执行
148      {interrupt, interrupt_action()}.  %% 中断等待确认
149  ```
150  
151  ### beamai_middleware_runner
152  
153  ```erlang
154  %% 初始化 Middleware 链
155  -spec init([middleware_spec()]) -> middleware_chain().
156  beamai_middleware_runner:init(Specs).
157  
158  %% Middleware 规格格式
159  Specs = [
160      {middleware_module, Opts},           %% 模块 + 选项
161      {middleware_module, Opts, Priority}, %% 模块 + 选项 + 优先级
162      middleware_module                    %% 仅模块名
163  ].
164  
165  %% 执行钩子
166  -spec run_hook(hook_name(), graph_state(), middleware_chain()) -> run_result().
167  beamai_middleware_runner:run_hook(HookName, State, Middlewares).
168  
169  %% 获取 Middleware 状态
170  -spec get_middleware_state(module(), middleware_chain()) -> {ok, state()} | {error, not_found}.
171  beamai_middleware_runner:get_middleware_state(Module, Chain).
172  ```
173  
174  ### beamai_middleware_presets
175  
176  ```erlang
177  %% 预设配置
178  -spec default() -> [middleware_spec()].
179  -spec minimal() -> [middleware_spec()].
180  -spec production() -> [middleware_spec()].
181  -spec development() -> [middleware_spec()].
182  -spec human_in_loop() -> [middleware_spec()].
183  
184  %% 带选项的预设
185  -spec default(map()) -> [middleware_spec()].
186  beamai_middleware_presets:default(#{
187      call_limit => #{max_model_calls => 30},
188      summarization => #{window_size => 25}
189  }).
190  
191  %% 单独 Middleware 配置
192  -spec call_limit(map()) -> middleware_spec().
193  -spec summarization(map()) -> middleware_spec().
194  -spec human_approval(map()) -> middleware_spec().
195  -spec tool_retry(map()) -> middleware_spec().
196  ```
197  
198  ### 内置 Middleware
199  
200  | Middleware | 模块 | 主要配置 |
201  |------------|------|----------|
202  | 调用限制 | `middleware_call_limit` | `max_model_calls`, `max_tool_calls`, `max_iterations` |
203  | 上下文摘要 | `middleware_summarization` | `window_size`, `max_tokens`, `summarize` |
204  | 人工审批 | `middleware_human_approval` | `mode`, `timeout`, `tools` |
205  | 工具重试 | `middleware_tool_retry` | `max_retries`, `backoff` |
206  | 模型重试 | `middleware_model_retry` | `max_retries`, `retryable_errors` |
207  | 模型降级 | `middleware_model_fallback` | `fallback_models`, `trigger_errors` |
208  | PII 检测 | `middleware_pii_detection` | `action`, `types` |
209  | 工具选择 | `middleware_tool_selector` | `strategy`, `whitelist` |
210  
211  ### 自定义 Middleware 示例
212  
213  ```erlang
214  -module(my_logging_middleware).
215  -behaviour(beamai_middleware).
216  
217  -export([init/1, before_model/2, after_model/2]).
218  
219  init(Opts) ->
220      #{log_level => maps:get(log_level, Opts, info)}.
221  
222  before_model(State, #{log_level := Level}) ->
223      Messages = graph_state:get(State, messages, []),
224      log(Level, "LLM Request: ~p messages", [length(Messages)]),
225      {update, #{request_start => erlang:system_time(millisecond)}}.
226  
227  after_model(State, #{log_level := Level}) ->
228      Start = graph_state:get(State, request_start, 0),
229      Duration = erlang:system_time(millisecond) - Start,
230      log(Level, "LLM Response: ~pms", [Duration]),
231      ok.
232  
233  log(info, Fmt, Args) -> logger:info(Fmt, Args);
234  log(debug, Fmt, Args) -> logger:debug(Fmt, Args).
235  ```
236  
237  ---
238  
239  ## beamai_deepagent - Deep Agent
240  
241  支持规划和并行执行的深度 Agent。
242  
243  ### 创建和执行
244  
245  ```erlang
246  %% 创建配置
247  -spec new() -> config().
248  -spec new(map()) -> config().
249  beamai_deepagent:new().
250  beamai_deepagent:new(Opts).
251  
252  %% 运行 Agent
253  -spec run(config(), binary()) -> {ok, result()} | {error, term()}.
254  beamai_deepagent:run(Config, Task).
255  ```
256  
257  ### 结果查询
258  
259  ```erlang
260  %% 获取计划
261  -spec get_plan(result()) -> plan() | undefined.
262  beamai_deepagent:get_plan(Result).
263  
264  %% 获取执行轨迹
265  -spec get_trace(result()) -> trace().
266  beamai_deepagent:get_trace(Result).
267  ```
268  
269  ### 配置选项
270  
271  ```erlang
272  Config = #{
273      llm => llm_config(),                 %% LLM 配置
274      tools => [tool_def()],               %% 自定义工具
275      system_prompt => binary(),           %% 系统提示词
276      max_depth => integer(),              %% 最大递归深度，默认 3
277      max_iterations => integer(),         %% 最大迭代次数，默认 50
278      planning_enabled => boolean(),       %% 启用规划，默认 true
279      reflection_enabled => boolean(),     %% 启用反思，默认 true
280      filesystem_enabled => boolean(),     %% 启用文件系统工具
281      filesystem => filesystem_config()    %% 文件系统配置
282  }.
283  ```
284  
285  ---
286  
287  ## beamai_llm - LLM 客户端
288  
289  多 Provider 支持的 LLM 客户端。
290  
291  ### 配置和聊天
292  
293  ```erlang
294  %% 创建配置
295  -spec config(provider(), map()) -> llm_config().
296  llm_client:config(Provider, Opts).
297  
298  %% 聊天
299  -spec chat(llm_config(), [message()]) -> {ok, response()} | {error, term()}.
300  llm_client:chat(Config, Messages).
301  
302  %% 流式聊天
303  -spec stream_chat(llm_config(), [message()], callback()) -> {ok, response()} | {error, term()}.
304  llm_client:stream_chat(Config, Messages, Callback).
305  
306  %% 带工具的聊天
307  -spec with_tools(llm_config(), [message()], [tool()]) -> {ok, response()} | {error, term()}.
308  llm_client:with_tools(Config, Messages, Tools).
309  ```
310  
311  ### Provider 管理
312  
313  ```erlang
314  %% 列出 Provider
315  -spec list_providers() -> [atom()].
316  llm_client:list_providers().
317  
318  %% Provider 信息
319  -spec provider_info(atom()) -> map().
320  llm_client:provider_info(Provider).
321  ```
322  
323  ### 支持的 Provider
324  
325  | Provider | 模块 | 特性 |
326  |----------|------|------|
327  | `openai` | llm_provider_openai | 聊天、流式、工具调用 |
328  | `anthropic` | llm_provider_anthropic | 聊天、流式、工具调用 |
329  | `zhipu` | llm_provider_zhipu | 聊天、流式、工具调用、异步 |
330  | `ollama` | llm_provider_ollama | 聊天、流式 |
331  
332  ### LLM 配置
333  
334  ```erlang
335  LLMConfig = #{
336      provider => atom(),                  %% openai | anthropic | zhipu | ollama
337      model => binary(),                   %% 模型名称
338      api_key => binary(),                 %% API Key
339      base_url => binary(),                %% 可选：自定义 URL
340      timeout => integer(),                %% 可选：超时时间
341      max_tokens => integer(),             %% 可选：最大 token
342      temperature => float()               %% 可选：温度参数
343  }.
344  ```
345  
346  ---
347  
348  ## beamai_memory - 记忆管理
349  
350  统一的记忆和检查点管理系统。
351  
352  ### 创建和配置
353  
354  ```erlang
355  %% 创建 Memory 实例
356  -spec new(map()) -> {ok, memory()} | {error, term()}.
357  beamai_memory:new(Config).
358  
359  Config = #{
360      checkpointer => #{backend => ets | sqlite},
361      store => #{backend => ets | sqlite},
362      context_store => {module(), term()}
363  }.
364  ```
365  
366  ### Checkpoint 操作
367  
368  ```erlang
369  %% 保存检查点
370  -spec save_checkpoint(memory(), config(), state_data()) -> {ok, memory()}.
371  beamai_memory:save_checkpoint(Memory, Config, StateData).
372  
373  %% 加载检查点
374  -spec load_checkpoint(memory(), config()) -> {ok, state_data()} | {error, not_found}.
375  -spec load_latest_checkpoint(memory(), config()) -> {ok, state_data()} | {error, not_found}.
376  beamai_memory:load_checkpoint(Memory, Config).
377  beamai_memory:load_latest_checkpoint(Memory, Config).
378  
379  %% 列出检查点
380  -spec list_checkpoints(memory(), config()) -> {ok, [checkpoint_info()]}.
381  beamai_memory:list_checkpoints(Memory, Config).
382  
383  %% 检查点计数
384  -spec checkpoint_count(memory(), config()) -> non_neg_integer().
385  beamai_memory:checkpoint_count(Memory, Config).
386  ```
387  
388  ### Store 操作
389  
390  ```erlang
391  %% 存储数据
392  -spec put(memory(), namespace(), key(), value()) -> {ok, memory()}.
393  beamai_memory:put(Memory, Namespace, Key, Value).
394  
395  %% 搜索数据
396  -spec search(memory(), namespace(), filter()) -> {ok, [item()]}.
397  beamai_memory:search(Memory, Namespace, Filter).
398  ```
399  
400  ---
401  
402  ## beamai_tools - 工具库
403  
404  统一的工具定义和管理。
405  
406  ### 工具获取
407  
408  ```erlang
409  %% 获取工具
410  -spec get_tools(category() | [category()]) -> [tool_def()].
411  -spec get_tools(category(), map()) -> [tool_def()].
412  beamai_tools:get_tools(Categories).
413  beamai_tools:get_tools(Categories, Opts).
414  
415  %% 获取所有工具
416  -spec get_all_tools() -> [tool_def()].
417  beamai_tools:get_all_tools().
418  
419  %% 查找工具
420  -spec find_tool(binary()) -> {ok, tool_def()} | {error, not_found}.
421  beamai_tools:find_tool(Name).
422  ```
423  
424  ### 工具执行
425  
426  ```erlang
427  %% 执行工具
428  -spec execute(binary(), map()) -> {ok, term()} | {error, term()}.
429  -spec execute(binary(), map(), map()) -> {ok, term()} | {error, term()}.
430  beamai_tools:execute(ToolName, Args).
431  beamai_tools:execute(ToolName, Args, Opts).
432  ```
433  
434  ### 工具转换
435  
436  ```erlang
437  %% 转换为 LLM 格式
438  -spec to_llm_spec(tool_def()) -> map().
439  -spec to_llm_specs([tool_def()]) -> [map()].
440  beamai_tools:to_llm_spec(Tool).
441  beamai_tools:to_llm_specs(Tools).
442  ```
443  
444  ### 工具注册表
445  
446  ```erlang
447  %% 构建工具列表
448  Registry = beamai_tool_registry:new(),
449  R1 = beamai_tool_registry:add_tools(Registry, Tools),
450  R2 = beamai_tool_registry:add_provider(R1, Provider),
451  Tools = beamai_tool_registry:build(R2).
452  
453  %% 便捷函数
454  Tools = beamai_tool_registry:from_config(#{
455      tools => [Tool1, Tool2],
456      providers => [Provider1, Provider2]
457  }).
458  ```
459  
460  ---
461  
462  ## beamai_core - 核心模块
463  
464  ### Graph 执行引擎
465  
466  ```erlang
467  %% 构建 Graph
468  Graph = graph_builder:new()
469      |> graph_builder:add_node(NodeName, {Module, Opts})
470      |> graph_builder:add_edge(From, To, Condition)
471      |> graph_builder:set_entry(EntryNode)
472      |> graph_builder:build().
473  
474  %% 执行 Graph
475  -spec run(graph(), state()) -> {ok, state()} | {error, term()}.
476  graph_runner:run(Graph, InitialState).
477  
478  %% Graph DSL
479  Graph = graph_dsl:compile(#{
480      nodes => #{...},
481      edges => [...],
482      entry => atom()
483  }).
484  ```
485  
486  ### Graph State
487  
488  ```erlang
489  %% 创建状态
490  -spec new(map()) -> state().
491  graph_state:new(Data).
492  
493  %% 读写状态
494  -spec get(state(), key()) -> value().
495  -spec set(state(), key(), value()) -> state().
496  graph_state:get(State, Key).
497  graph_state:set(State, Key, Value).
498  ```
499  
500  ### Pregel 分布式计算
501  
502  ```erlang
503  %% 创建 Pregel 图
504  {ok, Graph} = pregel_graph:new(Config).
505  
506  %% 添加顶点和边
507  pregel_graph:add_vertex(Graph, VertexId, Data).
508  pregel_graph:add_edge(Graph, From, To, Weight).
509  
510  %% 运行计算
511  {ok, Result} = pregel:run(Graph, ComputeFn, MaxIterations).
512  ```
513  
514  ---
515  
516  ## beamai_a2a - A2A 协议
517  
518  Agent-to-Agent 通信协议实现。
519  
520  ### 服务端
521  
522  ```erlang
523  %% 启动服务器
524  -spec start_link(map()) -> {ok, pid()}.
525  beamai_a2a_server:start_link(Config).
526  
527  Config = #{
528      handler => module(),                 %% 请求处理器
529      port => integer(),                   %% HTTP 端口
530      auth => auth_config()                %% 认证配置
531  }.
532  ```
533  
534  ### 客户端
535  
536  ```erlang
537  %% 发现 Agent
538  -spec discover(binary()) -> {ok, agent_card()} | {error, term()}.
539  beamai_a2a_client:discover(AgentUrl).
540  
541  %% 发送消息
542  -spec send_message(binary(), message()) -> {ok, response()} | {error, term()}.
543  beamai_a2a_client:send_message(AgentUrl, Message).
544  ```
545  
546  ### Agent Card
547  
548  ```erlang
549  %% 创建 Card
550  -spec new(map()) -> agent_card().
551  beamai_a2a_card:new(#{
552      name => binary(),
553      description => binary(),
554      url => binary(),
555      capabilities => [binary()]
556  }).
557  
558  %% 验证 Card
559  -spec validate(agent_card()) -> ok | {error, term()}.
560  beamai_a2a_card:validate(Card).
561  ```
562  
563  ---
564  
565  ## beamai_mcp - MCP 协议
566  
567  Model Context Protocol 实现。
568  
569  ### 客户端
570  
571  ```erlang
572  %% 连接 MCP 服务器
573  -spec connect(config()) -> {ok, client()} | {error, term()}.
574  beamai_mcp_client:connect(Config).
575  
576  Config = #{
577      transport => stdio | http | sse,
578      command => binary(),                 %% stdio: 命令
579      url => binary()                      %% http/sse: URL
580  }.
581  
582  %% 列出工具
583  -spec list_tools(client()) -> {ok, [tool()]} | {error, term()}.
584  beamai_mcp_client:list_tools(Client).
585  
586  %% 调用工具
587  -spec call_tool(client(), binary(), map()) -> {ok, result()} | {error, term()}.
588  beamai_mcp_client:call_tool(Client, ToolName, Args).
589  
590  %% 列出资源
591  -spec list_resources(client()) -> {ok, [resource()]} | {error, term()}.
592  beamai_mcp_client:list_resources(Client).
593  ```
594  
595  ### 服务端
596  
597  ```erlang
598  %% 启动服务器
599  -spec start_link(config()) -> {ok, pid()}.
600  beamai_mcp_server:start_link(Config).
601  
602  %% 注册工具
603  -spec register_tool(pid(), tool_def()) -> ok.
604  beamai_mcp_server:register_tool(Server, Tool).
605  
606  %% 注册资源
607  -spec register_resource(pid(), resource_def()) -> ok.
608  beamai_mcp_server:register_resource(Server, Resource).
609  ```
610  
611  ---
612  
613  ## beamai_rag - RAG 功能
614  
615  检索增强生成模块。
616  
617  ### 向量嵌入
618  
619  ```erlang
620  %% 生成嵌入
621  -spec embed(binary(), config()) -> {ok, [float()]} | {error, term()}.
622  -spec embed_batch([binary()], config()) -> {ok, [[float()]]} | {error, term()}.
623  beamai_embeddings:embed(Text, Config).
624  beamai_embeddings:embed_batch(Texts, Config).
625  ```
626  
627  ### 向量存储
628  
629  ```erlang
630  %% 创建存储
631  -spec new(config()) -> {ok, store()}.
632  beamai_vector_store:new(Config).
633  
634  %% 添加向量
635  -spec add(store(), binary(), [float()], map()) -> {ok, store()}.
636  beamai_vector_store:add(Store, Id, Vector, Metadata).
637  
638  %% 相似度搜索
639  -spec search(store(), [float()], integer()) -> {ok, [result()]}.
640  beamai_vector_store:search(Store, QueryVector, TopK).
641  ```
642  
643  ### RAG 流程
644  
645  ```erlang
646  %% 初始化
647  -spec init(config()) -> {ok, rag_state()}.
648  beamai_rag:init(Config).
649  
650  %% 添加文档
651  -spec add_documents(rag_state(), [document()]) -> {ok, rag_state()}.
652  beamai_rag:add_documents(State, Documents).
653  
654  %% 检索
655  -spec retrieve(rag_state(), binary(), integer()) -> {ok, [chunk()]}.
656  beamai_rag:retrieve(State, Query, TopK).
657  
658  %% RAG 查询（检索 + 生成）
659  -spec query(rag_state(), binary()) -> {ok, response()}.
660  beamai_rag:query(State, Question).
661  ```
662  
663  ---
664  
665  ## 通用类型
666  
667  ### 工具定义
668  
669  ```erlang
670  -type tool_def() :: #{
671      name := binary(),
672      description := binary(),
673      parameters := json_schema(),
674      handler := fun((map()) -> {ok, term()} | {error, term()})
675                  | fun((map(), map()) -> {ok, term()} | {error, term()})
676  }.
677  ```
678  
679  ### 消息类型
680  
681  ```erlang
682  -type message() :: #{
683      role := user | assistant | system | tool,
684      content := binary() | null,
685      tool_calls => [tool_call()],
686      tool_call_id => binary()
687  }.
688  ```
689  
690  ### LLM 响应
691  
692  ```erlang
693  -type llm_response() :: #{
694      id := binary(),
695      model := binary(),
696      content := binary() | null,
697      tool_calls := [tool_call()],
698      finish_reason := binary(),
699      usage => usage_info()
700  }.
701  ```
702  
703  ---
704  
705  ## 错误处理
706  
707  所有 API 返回 `{ok, Result}` 或 `{error, Reason}` 格式。常见错误类型：
708  
709  | 错误 | 说明 |
710  |------|------|
711  | `{error, missing_api_key}` | API Key 未配置 |
712  | `{error, timeout}` | 请求超时 |
713  | `{error, {http_error, Code, Body}}` | HTTP 错误 |
714  | `{error, {api_error, Details}}` | API 返回错误 |
715  | `{error, not_found}` | 资源未找到 |
716  | `{error, storage_not_enabled}` | 存储未启用 |
717  
718  ---
719  
720  ## 更多文档
721  
722  - [README.md](../README.md) - 项目概述
723  - [ARCHITECTURE.md](ARCHITECTURE.md) - 架构设计
724  - [QUICK_START.md](QUICK_START.md) - 快速开始指南
725  - 各模块 README：
726    - [beamai_core](../apps/beamai_core/README.md)
727    - [beamai_llm](../apps/beamai_llm/README.md)
728    - [beamai_agent](../apps/beamai_agent/README.md)
729    - [beamai_deepagent](../apps/beamai_deepagent/README.md)
730    - [beamai_memory](../apps/beamai_memory/README.md)
731    - [beamai_tools](../apps/beamai_tools/README.md)
732    - [beamai_a2a](../apps/beamai_a2a/README.md)
733    - [beamai_mcp](../apps/beamai_mcp/README.md)
734    - [beamai_rag](../apps/beamai_rag/README.md)