CMDC

Production-grade AI Agent kernel for Elixir.

用 OTP 把 Agent 跑成生产服务 — Crash-safe · Observable · Multi-tenant by design.

Hex.pmDocsLicenseTestsWarnings

为什么是 CMDC

把 Agent 推到生产环境会立刻撞上三堵墙：一个子任务挂了整个会话陪葬 / LLM 在你看不见的地方烧 token / 想做前端断网重连或跨设备恢复但框架根本不支持。

CMDC 把每个会话当作一棵 OTP Supervisor 树跑在 BEAM 上，从内核就把这些问题 解决了：

主要能力

按部署关注点分组：

Runtime — OTP 容错与并发

Observability — 可观测性

Safety — 安全与合规

Cost & Performance — 成本与性能

Memory & Recovery — 记忆与恢复

Plugin Pipeline — 13 hook × 8 action

13 个生命周期 hook（session / prompt / request / response / tool / compact / steering / turn）× 8 种 action（continue / intervene / abort / skip / block_tool / replace_args / replace_result / switch_model）。 16 个内置 Plugin 覆盖审批 / 安全 / 内容拦截 / 长会话记忆 / 模型路由 / 大结果 offload / 反思 / 规划等典型场景。

安装

def deps do

  [

    {:cmdc, "~> 0.4"}

  ]

end

可选生态库：

{:cmdc_gateway, "~> 0.4"},       # HTTP / SSE / WebSocket / A2A 网关

{:cmdc_orchestrator, "~> 0.3"},  # DAG / Debate / Hierarchy / Router-LLM

{:cmdc_skill_engine, "~> 0.2"}   # Skill 自进化引擎

30 秒上手

{:ok, session} = CMDC.create_agent(

  model: "anthropic:claude-sonnet-4-5",

  api_key: System.get_env("ANTHROPIC_API_KEY")

)



CMDC.prompt(session, "用一句话介绍 Elixir 的优势。")

{:ok, reply} = CMDC.collect_reply(session)

IO.puts(reply)



CMDC.stop(session)

完整指南：5 分钟上手 / 核心概念 / 10 个生产配方

生产部署模式

defmodule MyApp.SupportAgent do

  @behaviour CMDC.Blueprint



  def build(opts) do

    %CMDC.Options{

      model: "anthropic:claude-sonnet-4-5",

      working_dir: "/tmp/support/#{opts[:tenant_id]}",

      user_data: %{tenant_id: opts[:tenant_id], user_tier: opts[:user_tier]},



      # 多 backend 路由：sandbox + 长期记忆 + 短期 ETS

      backend: CMDC.Backend.Composite.new(

        default: CMDC.Backend.Filesystem.new(

          root_dir: "/tmp/support/#{opts[:tenant_id]}",

          virtual_mode: true              # 防 traversal

        ),

        routes: %{

          "/memories/" => MyApp.PgBackend.new(),

          "/conversation_history/" => CMDC.Backend.State.new()

        }

      ),



      tools: [MyApp.QueryDB, MyApp.RefundOrder, CMDC.Tool.AskUser],



      plugins: [

        # 安全

        {CMDC.Plugin.Builtin.HumanApproval, tools: ["refund_order"]},

        {CMDC.Plugin.Builtin.ContentPolicy, []},



        # 成本

        {CMDC.Plugin.Builtin.CostGuard, max_usd: 0.50},

        {CMDC.Plugin.Builtin.ModelRouter, [

          rules: [

            %{condition: {:user_tier, :free}, model: "openai:gpt-4o-mini"},

            %{condition: {:cost_gt, 0.10}, model: "openai:gpt-4o-mini"}

          ]

        ]},



        # 大结果落盘

        {CMDC.Plugin.Builtin.LargeResultOffload, [

          backend: opts[:backend],

          tool_token_limit_before_evict: 20_000

        ]}

      ],



      # 上下文压缩 + 重连补帧

      compactor: [trigger: {:tokens, 50_000}, keep: {:messages, 10}],

      event_buffer_size: 200

    }

  end

end



{:ok, session} = CMDC.create_agent(MyApp.SupportAgent,

  tenant_id: "acme",

  user_tier: :pro

)



# 接 Langfuse 可观测

:telemetry.attach_many("cmdc-langfuse",

  CMDC.Telemetry.all_events(),

  &MyApp.LangfuseSink.handle_event/4, [])



# 业务订阅事件流

CMDC.subscribe(session)

CMDC.monitor(session)

FAQ

为什么用 Elixir / BEAM 跑 Agent

LLM Agent 的本质是长期运行的并发状态机：每个会话独立、可崩可重启、需要 被持续观察、要能在多租户场景下互不干扰。这恰好是 BEAM 三十年来的本职工作—— WhatsApp 用 Erlang 单机扛 200 万并发连接，Discord 用 Elixir 处理千万级实时消息。 把 LLM Agent 跑在 BEAM 上不是花活，是让 Agent 享受电信级容错和并发的免费午餐。

是否绑死 LLM 厂商

不。Provider 层基于 req_llm 封装，支持 Anthropic / OpenAI / Google / Mistral / Bedrock / 自建网关 / 任意 OpenAI 兼容 endpoint。switch_model/2 支持运行期热切（含 provider_opts 同步切换 base_url / api_key）。

生产可靠性证据

跟 Python Agent 框架的差别

不写对比表（写了也没意思），列三个只有 BEAM 才便宜实现的能力让你自己判断：

  1. 子代理 crash 不传染父代理——DynamicSupervisor 默认行为，零代码
  2. 跨进程跨节点会话恢复——CMDC.Checkpoint + 任意分布式 backend 即可
  3. 单机数万 Agent 进程并发——OTP 调度天然支持，无需额外协程框架

与 Langfuse / LangSmith 集成需要写多少代码

零侵入。CMDC 只发 :telemetry 标准事件，sink 由你按需挂：

:telemetry.attach_many("my-langfuse", CMDC.Telemetry.all_events(),

  &MyApp.LangfuseSink.handle_event/4, [])

3 份完整配方（Langfuse OTLP / LangSmith OTel / Grafana Tempo + Loki）见 常见配方。

数字

指标v0.4.1
Tests1219 + 21 doctests, 0 failures
编译 warnings0
Hex doc warnings0
内置 Plugin16
内置 Tool11
Plugin Pipeline13 hook × 8 action
生态 Hex 包4（cmdc / cmdc_gateway / cmdc_orchestrator / cmdc_skill_engine）
主库代码~12K 行（不含测试）

文档

开发

mix deps.get

mix compile --warnings-as-errors

mix test

mix format --check-formatted

mix credo --strict

mix docs

跑真实 LLM 端到端示例（需 ANTHROPIC_API_KEY 等环境变量）：

cd example && mix run example/simple_agent.exs

License

Apache 2.0 with Commons Clause。商用授权请联系 glggsai@qq.com。