BeamAI Extra - Erlang Agent Framework 扩展

June 10, 2026 · View on GitHub

基于 BeamAI 的高性能 AI Agent 扩展框架，提供完整的 Agent 开发工具链。

本项目依赖 BeamAI 核心库的 main 分支，包含以下扩展功能：

特性

Kernel/Tool 架构: 语义化的工具注册和调用系统
- 基于 Semantic Kernel 理念的 Kernel 核心
- 统一的 Tool 定义和管理
- Filter 过滤器和安全验证
Simple Agent: 基于工具循环的 ReAct Agent
- 纯函数式 API（new/1 → run/2 → 新状态）
- 支持自定义工具、Plugin 加载、系统提示词
- 8 个回调钩子（turn/llm/tool/token/interrupt/resume）
- 流式输出（stream/2）
- 中断和恢复支持（Human-in-the-Loop）
- 内置 Memory 持久化（save/1, restore/2）
Deep Agent: 基于 SubAgent 架构的递归规划 Agent
- Planner（规划器）→ Executor（执行器）→ Reflector（反思器）
- 支持并行子任务执行
- Coordinator 多 Agent 协调
协议支持: A2A 和 MCP
- Agent-to-Agent 通信协议
- Model Context Protocol 集成
RAG: 检索增强生成
- 向量嵌入和相似度搜索
- 文本分割

快速开始

1. 启动 Shell

export ZHIPU_API_KEY=your_key_here
# 可选：自定义 Anthropic 兼容 API 地址（默认: https://open.bigmodel.cn/api/anthropic）
export ZHIPU_ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
rebar3 shell

2. Simple Agent（基本用法）

%% 创建 LLM 配置（使用 beamai_chat_completion:create/2）
LLM = beamai_chat_completion:create(anthropic, #{
    model => <<"glm-4.7">>,
    api_key => list_to_binary(os:getenv("ZHIPU_API_KEY")),
    base_url => <<"https://open.bigmodel.cn/api/anthropic">>
}),

%% 创建 Agent（纯函数 API，返回不可变状态）
{ok, Agent0} = beamai_agent:new(#{
    system_prompt => <<"你是一个有帮助的助手。"/utf8>>,
    llm => LLM
}),

%% 运行 Agent（返回结果和新状态）
{ok, Result, _Agent1} = beamai_agent:run(Agent0, <<"你好！"/utf8>>),

%% 查看结果
Content = maps:get(content, Result).

3. Simple Agent（多轮对话）

%% 多轮对话通过状态传递实现，消息历史自动累积
{ok, Agent0} = beamai_agent:new(#{
    llm => LLM,
    system_prompt => <<"你是一个记忆助手。"/utf8>>
}),
{ok, _, Agent1} = beamai_agent:run(Agent0, <<"我叫张三"/utf8>>),
{ok, Result, _Agent2} = beamai_agent:run(Agent1, <<"我叫什么名字？"/utf8>>).
%% Agent 会记得用户叫张三

%% 查看对话状态
beamai_agent:turn_count(Agent1).    %% => 1
beamai_agent:messages(Agent1).      %% => 消息历史列表
beamai_agent:last_response(Agent1). %% => 上一次助手回复

4. Simple Agent（使用 Kernel + Tool 注册工具）

%% 方式一：直接在 Agent 中定义工具（通过 Kernel 自动构建）
Kernel0 = beamai_kernel:new(),
LlmConfig = beamai_chat_completion:create(anthropic, #{
    api_key => list_to_binary(os:getenv("ZHIPU_API_KEY")),
    base_url => <<"https://open.bigmodel.cn/api/anthropic">>,
    model => <<"glm-4.7">>
}),
K1 = beamai_kernel:add_service(Kernel0, LlmConfig),
K2 = beamai_kernel:add_tool(K1, #{
    name => <<"get_weather">>,
    description => <<"获取城市天气"/utf8>>,
    parameters => #{
        <<"city">> => #{type => string, required => true, description => <<"城市名称"/utf8>>}
    },
    handler => fun(#{<<"city">> := City}, _Ctx) ->
        {ok, #{city => City, temp => 25, condition => <<"Sunny">>}}
    end
}),

%% 使用预构建 Kernel 创建 Agent
{ok, Agent0} = beamai_agent:new(#{
    kernel => K2,
    system_prompt => <<"你是天气助手。"/utf8>>
}),
{ok, Result, _} = beamai_agent:run(Agent0, <<"北京天气怎么样？"/utf8>>).

%% 方式二：使用 plugins 加载内置工具模块
{ok, Agent0} = beamai_agent:new(#{
    llm => LlmConfig,
    plugins => [beamai_tool_file],
    system_prompt => <<"你是文件助手。"/utf8>>
}),
{ok, Result, _} = beamai_agent:run(Agent0, <<"列出 src 目录下的文件"/utf8>>).

5. Simple Agent（带 Memory 持久化）

%% 创建存储后端
{ok, _} = beamai_store_ets:start_link(my_store, #{}),
StateStore = beamai_state_store:new({beamai_store_ets, my_store}),
Mgr = beamai_process_snapshot:new(StateStore),
Memory = {Mgr, #{thread_id => <<"my-session">>}},

%% 创建带 Memory 的 Agent（auto_save 启用后每轮自动保存）
{ok, Agent0} = beamai_agent:new(#{
    llm => LLM,
    system_prompt => <<"你是持久化助手。"/utf8>>,
    memory => Memory,
    auto_save => true
}),

%% 对话（自动保存）
{ok, _, Agent1} = beamai_agent:run(Agent0, <<"记住：密码是 12345"/utf8>>),
{ok, _, _Agent2} = beamai_agent:run(Agent1, <<"好的"/utf8>>),

%% 手动保存
ok = beamai_agent:save(Agent1),

%% 稍后恢复会话
{ok, RestoredAgent} = beamai_agent:restore(#{llm => LLM}, Memory),
{ok, Result, _} = beamai_agent:run(RestoredAgent, <<"密码是多少？"/utf8>>).
%% Agent 会记得密码是 12345

6. Deep Agent（SubAgent 编排）

%% 创建 Deep Agent 配置（new/1 直接返回 config map）
Config = beamai_deepagent:new(#{
    llm => LLM,
    max_depth => 3,
    planning_enabled => true,
    reflection_enabled => true,
    system_prompt => <<"你是一个研究专家。"/utf8>>,
    %% 使用 Tool 模块提供工具
    plugins => [beamai_tool_file, beamai_tool_shell]
}),

%% 运行复杂任务（Planner → Executor → Reflector）
{ok, Result} = beamai_deepagent:run(Config,
    <<"分析这个代码库的架构并给出优化建议。"/utf8>>),

%% 查看执行计划和轨迹
Plan = beamai_deepagent:get_plan(Result),
Trace = beamai_deepagent:get_trace(Result).

架构

应用结构

核心依赖（来自 BeamAI）：

beamai (外部依赖)
├── beamai_core/        # 核心框架
│   ├── Kernel         # beamai_kernel, beamai_tool, beamai_context,
│   │                  # beamai_filter, beamai_prompt, beamai_result
│   ├── LLM            # beamai_llm_response (统一 LLM 响应访问器)
│   ├── Process        # beamai_process, beamai_process_builder,
│   │                  # beamai_process_runtime, beamai_process_step,
│   │                  # beamai_process_executor, beamai_process_event
│   ├── HTTP           # beamai_http, beamai_http_gun, beamai_http_hackney,
│   │                  # beamai_http_pool
│   ├── Behaviours     # beamai_llm_behaviour, beamai_http_behaviour,
│   │                  # beamai_step_behaviour, beamai_process_store_behaviour
│   ├── Graph          # graph, graph_node, graph_edge, graph_builder, graph_dsl,
│   │                  # graph_runner, graph_snapshot, graph_state, graph_command
│   ├── Pregel         # pregel, pregel_master, pregel_worker, pregel_vertex,
│   │                  # pregel_dispatch_worker
│   └── Utils          # beamai_id, beamai_jsonrpc, beamai_sse, beamai_utils
│
├── beamai_llm/         # LLM 客户端
│   ├── Chat           # beamai_chat_completion
│   ├── Parser         # beamai_output_parser, beamai_parser_json
│   ├── Adapters       # llm_message_adapter, llm_response_adapter, llm_tool_adapter
│   └── Providers      # OpenAI, Anthropic, DeepSeek, Zhipu, DashScope, Ollama
│
└── beamai_memory/      # 内存和上下文存储
    ├── Context        # 上下文管理
    ├── Store          # ETS/SQLite 存储后端
    └── Snapshot       # 快照、分支、时间旅行

本项目扩展：

apps/
├── beamai_tools/       # 工具和中间件系统
│   ├── Core           # beamai_tools, beamai_tool_behaviour
│   ├── Middleware     # beamai_middleware, beamai_middleware_runner,
│   │                  # middleware_call_limit, middleware_tool_retry
│   ├── Security       # beamai_tool_security
│   └── Tools          # beamai_tool_file, beamai_tool_shell,
│                      # beamai_tool_human, beamai_tool_todo
│
├── beamai_agent/       # Agent 实现
│   ├── Core           # beamai_agent, beamai_agent_state, beamai_agent_callbacks
│   ├── Memory         # beamai_agent_memory
│   ├── Execution      # beamai_agent_tool_loop, beamai_agent_interrupt
│   └── Process Agent  # beamai_process_agent, beamai_process_agent_llm_step,
│                      # beamai_process_agent_tool_step
│
├── beamai_deepagent/   # Deep Agent（SubAgent 架构）
│   ├── Core           # beamai_deepagent, beamai_deepagent_plan,
│   │                  # beamai_deepagent_dependencies, beamai_deepagent_trace
│   └── SubAgents      # beamai_deepagent_planner, beamai_deepagent_executor,
│                      # beamai_deepagent_reflector, beamai_deepagent_parallel,
│                      # beamai_deepagent_coordinator
│
├── beamai_a2a/         # A2A 协议实现
│   ├── Server         # A2A 服务端
│   └── Client         # A2A 客户端
│
├── beamai_mcp/         # MCP 协议实现
│   ├── Server         # MCP 服务端
│   └── Client         # MCP 客户端
│
└── beamai_rag/         # RAG 功能
    ├── Embeddings     # 向量嵌入
    └── Vector Store   # 向量存储

依赖关系

┌─────────────────────────────────────────────────────┐
│   Agent 实现层 (本项目扩展)                          │
│  (beamai_agent, beamai_deepagent)                   │
└────────────────┬────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────┐
│   服务层 (本项目扩展)                               │
│  (beamai_tools, beamai_rag, beamai_a2a, beamai_mcp) │
└────────────────┬────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────┐
│   核心层 (来自 BeamAI 外部依赖)                     │
│  (beamai_core, beamai_llm, beamai_memory)           │
│       https://github.com/TTalkPro/beamai            │
└─────────────────────────────────────────────────────┘

依赖说明：

本项目通过 rebar.config 依赖 BeamAI 的 main 分支
核心功能（Kernel、Process Framework、Graph、LLM、Memory）由 BeamAI 提供
本项目专注于 Agent 实现、协议支持（A2A、MCP）、工具系统和 RAG 功能

详见 DEPENDENCIES.md

核心概念

1. Kernel 架构

Kernel 是 BeamAI 的核心抽象，管理 Tool 的注册与调用：

%% 创建 Kernel 实例
Kernel = beamai_kernel:new(),

%% 从 Tool 模块加载工具
Kernel1 = beamai_kernel:add_tool_module(Kernel, beamai_tool_file),

%% 或添加单个工具
Tool = #{
    name => <<"read_file">>,
    description => <<"读取文件内容"/utf8>>,
    parameters => #{
        <<"path">> => #{type => string, required => true}
    },
    handler => fun(#{<<"path">> := Path}, _Ctx) ->
        file:read_file(Path)
    end
},
Kernel2 = beamai_kernel:add_tool(Kernel1, Tool),

%% 调用注册的工具
{ok, Result, _NewCtx} = beamai_kernel:invoke_tool(Kernel2, <<"read_file">>, #{
    <<"path">> => <<"/tmp/test.txt">>
}, beamai_context:new()).

2. Memory 持久化

使用存储后端实现会话持久化：

%% 创建 Memory（使用 ETS 存储后端）
{ok, _} = beamai_store_ets:start_link(my_store, #{}),
StateStore = beamai_state_store:new({beamai_store_ets, my_store}),
Mgr = beamai_process_snapshot:new(StateStore),
Memory = {Mgr, #{thread_id => <<"my-session">>}},

%% 创建带 memory 的 Agent（auto_save 启用后每轮自动保存）
{ok, Agent0} = beamai_agent:new(#{llm => LLM, memory => Memory, auto_save => true}),
{ok, _, Agent1} = beamai_agent:run(Agent0, <<"你好"/utf8>>),

%% 手动保存
ok = beamai_agent:save(Agent1),

%% 从 Memory 恢复会话
{ok, RestoredAgent} = beamai_agent:restore(#{llm => LLM}, Memory).

3. Callbacks（回调系统）

监听 Agent 执行过程中的 8 个事件：

{ok, Agent0} = beamai_agent:new(#{
    llm => LLM,
    system_prompt => <<"你是助手"/utf8>>,
    callbacks => #{
        on_turn_start => fun(Meta) ->
            io:format("Turn 开始: ~p~n", [maps:get(turn_count, Meta)])
        end,
        on_turn_end => fun(Meta) ->
            io:format("Turn 结束~n")
        end,
        on_turn_error => fun(Reason, Meta) ->
            io:format("Turn 出错: ~p~n", [Reason])
        end,
        on_llm_call => fun(Messages, Meta) ->
            io:format("LLM 调用: ~B 条消息~n", [length(Messages)])
        end,
        on_tool_call => fun(Name, Args) ->
            io:format("工具调用: ~s~n", [Name])
            %% 返回 {interrupt, Reason} 可触发中断
        end,
        on_token => fun(Token, Meta) ->
            io:format("~s", [Token])  %% 流式 token
        end,
        on_interrupt => fun(InterruptState, Meta) ->
            io:format("Agent 中断~n")
        end,
        on_resume => fun(InterruptState, Meta) ->
            io:format("Agent 恢复~n")
        end
    }
}).

配置

LLM 配置

LLM 配置使用 beamai_chat_completion:create/2 创建：

%% 方式一：直接创建 LLM 配置
LLM = beamai_chat_completion:create(anthropic, #{
    model => <<"glm-4.7">>,
    api_key => list_to_binary(os:getenv("ZHIPU_API_KEY")),
    base_url => <<"https://open.bigmodel.cn/api/anthropic">>,
    max_tokens => 2048
}),

%% 方式二：使用 example_llm_config 辅助模块（从环境变量自动读取配置）
LLM = example_llm_config:anthropic().     %% Zhipu Anthropic 兼容 API（ZHIPU_API_KEY）
LLM = example_llm_config:claude().        %% Anthropic 原生 API（ANTHROPIC_API_KEY）
LLM = example_llm_config:zhipu().         %% Zhipu 原生 API（ZHIPU_API_KEY）
LLM = example_llm_config:openai_glm().    %% Zhipu OpenAI 兼容 API（ZHIPU_API_KEY）
LLM = example_llm_config:deepseek().      %% DeepSeek API（DEEPSEEK_API_KEY）
LLM = example_llm_config:openai().        %% OpenAI API（OPENAI_API_KEY）

%% 方式三：使用 test_zhipu_anthropic 模块（支持 ZHIPU_ANTHROPIC_BASE_URL 环境变量）
LLM = test_zhipu_anthropic:create_llm().  %% 从 ZHIPU_API_KEY + ZHIPU_ANTHROPIC_BASE_URL 构建

%% 配置可在多个 Agent 间复用
{ok, Agent1} = beamai_agent:new(#{llm => LLM, system_prompt => <<"研究助手"/utf8>>}),
{ok, Agent2} = beamai_agent:new(#{llm => LLM, system_prompt => <<"写作助手"/utf8>>}).

环境变量：

环境变量	说明	必填
`ZHIPU_API_KEY`	智谱 API Key	使用智谱相关 Provider 时必填
`ZHIPU_ANTHROPIC_BASE_URL`	Zhipu Anthropic 兼容 API 地址（默认 `https://open.bigmodel.cn/api/anthropic`）	可选
`ANTHROPIC_API_KEY`	Anthropic 原生 API Key	使用 Claude 时必填
`DEEPSEEK_API_KEY`	DeepSeek API Key	使用 DeepSeek 时必填
`OPENAI_API_KEY`	OpenAI API Key	使用 OpenAI 时必填

支持的 Provider：

Provider	模块	API 模式	说明
`anthropic`	llm_provider_anthropic	Anthropic	Anthropic Claude API
`openai`	llm_provider_openai	OpenAI	OpenAI API
`deepseek`	llm_provider_deepseek	OpenAI 兼容	DeepSeek API
`zhipu`	llm_provider_zhipu	OpenAI 兼容	智谱 AI (GLM 系列)
`dashscope`	llm_provider_dashscope	DashScope 原生	阿里云百炼 (通义千问系列)
`ollama`	llm_provider_ollama	OpenAI 兼容	Ollama 本地模型
`mock`	llm_provider_mock	内置	测试用 Mock LLM

HTTP 后端配置

BeamAI 支持 Gun 和 Hackney 两种 HTTP 后端，默认使用 Gun（支持 HTTP/2）。

%% 在 sys.config 中配置（可选）
{beamai_core, [
    {http_backend, beamai_http_gun},
    {http_pool, #{
        max_connections => 100,
        connection_timeout => 30000
    }}
]}.

特性	Gun（默认）	Hackney
HTTP/2	支持	不支持
连接池	内置 beamai_http_pool	依赖 hackney 池
TLS	自动使用系统 CA 证书	hackney 默认配置
适用场景	推荐生产环境	兼容旧系统

文档

核心文档

doc/API_REFERENCE.md - API 参考文档
doc/MIDDLEWARE.md - Middleware 系统文档
doc/CALLBACKS.md - Callback 回调系统文档
doc/ARCHITECTURE.md - 架构设计
DEPENDENCIES.md - 依赖关系详解

模块文档

模块	说明	来源	文档
beamai_core	核心框架：Kernel、Process Framework、Graph 引擎、HTTP、Behaviours	BeamAI	外部文档
beamai_llm	LLM 客户端：支持 OpenAI、Anthropic、DeepSeek、Zhipu、DashScope、Ollama	BeamAI	外部文档
beamai_memory	记忆管理：Checkpoint、Store、时间旅行、分支	BeamAI	外部文档
beamai_tools	工具和中间件系统：Tool 模块、Middleware、安全验证	本项目	README
beamai_agent	Agent 实现：ReAct 模式、回调系统、Process Agent	本项目	README
beamai_deepagent	Deep Agent：SubAgent 编排、任务规划、并行执行、自我反思	本项目	README
beamai_a2a	A2A 协议：Agent 间通信、服务端/客户端	本项目	README
beamai_mcp	MCP 协议：Model Context Protocol 实现	本项目	README
beamai_rag	RAG 功能：向量嵌入、相似度搜索	本项目	README

运行示例

# 编译
rebar3 compile

# 启动 Shell
rebar3 shell

示例文件

文件	说明	需要 LLM
`example_llm_config.erl`	LLM 配置辅助模块	-
`example_agent.erl`	Agent 基本用法（单轮、多轮、工具调用、流式）	部分
`example_agent_hitl.erl`	Agent Human-in-the-Loop 中断恢复	否（Mock）
`example_agent_scenarios.erl`	Agent 高级场景（回调、并发、Coordinator）	部分
`example_deepagent.erl`	DeepAgent 规划执行、反思、轨迹检查	部分
`example_deepagent_tools.erl`	DeepAgent 工具集成（文件、Shell、自定义）	是
`test_anthropic_agent.erl`	Agent 和 DeepAgent 端到端测试	是
`test_zhipu_anthropic.erl`	Zhipu Anthropic 兼容 API 集成测试	是

集成测试（Agent + DeepAgent）

使用 test_zhipu_anthropic 模块对 Agent 和 DeepAgent 进行端到端测试：

export ZHIPU_API_KEY=your_key_here
# 可选：自定义 Anthropic 兼容 API 地址
export ZHIPU_ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
rebar3 shell

%% 运行所有集成测试（5 个测试用例）
test_zhipu_anthropic:run_all().

%% 或单独运行
test_zhipu_anthropic:test_agent_simple().       %% Agent 单轮对话
test_zhipu_anthropic:test_agent_multi_turn().   %% Agent 多轮对话（上下文记忆）
test_zhipu_anthropic:test_agent_with_tools().   %% Agent 工具调用
test_zhipu_anthropic:test_deepagent_simple().   %% DeepAgent 简单任务
test_zhipu_anthropic:test_deepagent_planned().  %% DeepAgent 规划执行

项目统计

指标	数量
OTP 应用（本项目）	6 个
核心依赖（BeamAI）	3 个
源代码模块（本项目）	~80 个

本项目应用：

beamai_tools
beamai_agent
beamai_deepagent
beamai_a2a
beamai_mcp
beamai_rag

核心依赖（来自 BeamAI）：

beamai_core
beamai_llm
beamai_memory

测试运行

# 运行所有测试
rebar3 eunit

# 运行特定应用的测试
rebar3 eunit --app=beamai_agent

# 运行代码检查
rebar3 dialyzer

性能

基于 Erlang/OTP 轻量级进程
并发工具调用
HTTP 连接池（Gun，支持 HTTP/2）
ETS 高速存储

设计原则

简单: 清晰的 API，易于理解
模块化: 每个模块职责单一
可扩展: Behaviour 设计，易于自定义
高性能: 利用 Erlang 并发特性
可观测: 完善的日志、追踪、监控

许可证

Apache-2.0

贡献

欢迎提交 Issue 和 Pull Request！