Butterbase Agent Runtime 原理揭秘Python 智能体执行引擎如何驱动 AI 应用新手完整指南【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-ossButterbase Agent Runtime是 Butterbase 开源 BaaS 平台中的 Python 智能体执行引擎它把声明式的 Agent 图规范Graph Spec编译成可运行的执行流程驱动 LLM 自动调用数据库、存储、函数与 MCP 工具并支持断点续跑、人工介入HITL与实时事件流。本文将从架构、编译、工具系统、容错四个层面帮你一次看懂这个 Agent Runtime 是如何运转的。一、它在整个 Butterbase 中的位置一个只对内的 WorkerAgent Runtime 是一个内部服务它没有公网入口只接受 control-api 通过INTERNAL_SERVICE_TOKEN内部令牌通道发起的 HTTP 调用。整体链路非常简单control-api │ (内部令牌 HTTP) ▼ agent-runtime (Python / FastAPI) ├── Pydantic 图规范 → 图编译器 │ └── 工具来源: 内置 | MCP | 用户函数 ├── Postgres 检查点 (每步落盘) └── Redis 事件总线 (运行事件流式回传)上图来自官方模板 butterSupport 的工作台智能体可以配置自动解决或始终转人工的自治模式——而支撑这种暂停等人、再续跑能力的正是 Agent Runtime 内部的检查点与中断机制下面第三节详解。二、核心组件一览Python 智能体引擎的 7 块拼图源码全部位于 services/agent-runtime/ 目录核心模块分工如下模块文件职责图规范模型spec.py用 Pydantic 定义节点、边与运行限额图编译器/执行器compiler.py把规范编译成LLM 工具调用循环运行生命周期runner.py领取 run、装配工具、执行、写回结果检查点checkpoint.py每步状态写入 Postgres支持断点恢复事件总线events.py事件先落库再推 Redis供前端实时消费心跳heartbeat.py定期刷新 last_heartbeat用于失联检测故障恢复recovery.py启动时把失联 run重新入队重试2.1 声明式图规范Agent 行为写成 JSON而不是硬编码代码在 spec.py 中一个 Agent 就是一张有向图由三类节点组成llm节点指定模型、系统提示词、输入模板和可用工具模型可多轮自主调用工具tool节点确定性地直接执行某个工具不需要 LLM 决策end节点用输出模板渲染最终回答。图还自带一组硬性限额spec.py最大步数、最大工具调用次数、最大并行工具数、总超时秒数、人工等待超时等。这意味着智能体跑飞了这种事在规范层面就被掐断了。2.2 编译器一个 LLM 工具调用循环撑起整个执行引擎打开 compiler.py你会发现它并不复杂核心就是_run_llm里的一个while True循环compiler.py用系统提示词 渲染后的输入模板构造首轮消息调用 OpenRouter平台的统一 LLM 网关见 openrouter.py发起带工具列表的 chat completion模型若返回tool_calls并行派发所有工具调用asyncio.gather把结果作为tool消息追加回对话重复直到模型不再调用工具输出最终文本同时累计 token 用量。每执行完一个节点编译器都会调用checkpointer.save(step, node_id, state)把完整状态写进 Postgres——这是断电也能续跑的关键。三、工具系统三类来源 双层安全网Agent 的能力全部来自 tools/ 目录下的工具注册表工具来自三个来源内置工具builtin.pyquery_table、insert_row、read_storage、write_storage、auth_user_lookup等 8 个直接打通本应用的 Postgres 数据与对象存储MCP 服务器工具mcp_client.py连接远程 MCP Server 扩展能力其认证头在数据库中以 AES-256-GCM 加密存储运行时用AUTH_ENCRYPTION_KEY解密crypto.py⚡用户函数工具functions.py把开发者写的 Edge Function 暴露给 Agent 调用。3.1 最严格权限优先的 ACL 机制tools/acl.py 实现了最严格者胜的权限解析每个工具有read_only/read_write和developer_only/end_user两把锁规范里的覆盖项只能收紧、不能放宽。默认规则非常讲究安全边界读表对终端用户开放而删改数据类工具默认仅限开发者调用。3.2 全量审计日志每次工具派发前后都会经过审计层tools/audit.py工具名、来源、参数、耗时、成功与否全部落库出问题时可按 run 完整回放。四、生产级可靠性检查点、HITL 与故障自愈这部分是 Agent Runtime 最硬核的地方也是它区别于玩具版 Agent的关键。4.1 断点续跑Checkpointcheckpoint.py 把每一步的(step, node_id, state)以 upsert 方式写入agent_checkpoints表。服务重启或任务被重新调度时runner 会load_latest()找到最后一步跳过已执行节点直接从断点继续runner.py。4.2 人工介入HITLinterrupt 内置工具内置的interrupt工具会让 Agent 主动抛出Interrupted异常并携带 payload编译器随即保存检查点、run 状态变为paused。人工在界面上审阅后通过/internal/runs/{id}/resume端点routes/runs.py把人的输入合并进状态、重新入队引擎从断点接着跑。第二节那张自动解决 / 始终转人工的模板截图就是这个机制在产品层的体现。4.3 心跳 失联恢复Heartbeat 默认每 5 秒刷新一次agent_runs.last_heartbeat服务启动时recover_stale_runs 会把心跳超过 30 秒失联的 running run 批量重置为 queued 自动重试取消走 CancelToken Redis 发布订阅双通道保证取消指令秒级生效。4.4 事件流先落库、再推送EventEmitter 的每个事件run_start、node_start、tool_call_start/end、run_end…都先写 Postgres 拿递增 seq再 publish 到 Redis的agent_runs:{run_id}频道。即使 Redis 瞬时故障事件也已在库里订阅方重连时按 seq 补拉即可——前端因此能看到Agent 正在调用哪个工具的实时进度。上图是另一个官方模板 butterbaseCRM 的界面像这样的 AI 应用其背后的智能体编排——从查库、调工具到流式输出——都由这套 Agent Runtime 统一驱动。五、上手体验本地跑起来这个执行引擎想亲自体验的话仓库已备好开发环境详见 services/agent-runtime/README.md用 docker compose 一键拉起docker compose -f docker-compose.local.yml up agent-runtime离线开发可把OPENROUTER_BASE_URL指向 tests/live/ 里的假 OpenRouter 服务不花一分钱调试完整链路测试覆盖非常全编译、检查点、HITL、MCP、ACL、恢复等都有独立用例如 test_hitl.py、test_recovery.py。六、总结这个 Python 智能体引擎值得你学什么✅声明式优先Agent 行为是 JSON 图规范不是散落的 if-else ✅简单循环胜过复杂框架一个LLM ↔ 工具循环 并行派发就构成了完整执行引擎 ✅安全默认值最严格权限优先、工具全量审计、写操作默认对终端用户关闭 ✅为失败而设计检查点续跑、心跳检测、失联自愈、事件先落库——分布式环境下Agent 挂了怎么办都有标准答案。如果你想给产品加一个能查库、能调外部系统、还能随时让人接手的 AI 智能体这套 services/agent-runtime/ 的代码就是非常不错的参考实现。【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考