agentdag · 有界预算 + 机械关卡的 AI Agent DAG 编排器 Skill 技能

技能简介

agentdag 是一款给多节点 AI Agent 装配 DAG 编排骨架的生产级运行时。它让你把若干 Agent 节点（planner / coder / reviewer / tester 等）按有向无环图的方式串起来，自动管理任务派发、状态日志、预算闸门与失败重试。每个节点都有「机械关卡」（比如必须通过测试、必须人工 review）才能进入下一节点，避免 LLM 自主循环导致的失控烧钱与不可审计问题。目标用户是希望把 AI Agent 从 demo 推向生产的工程团队。

核心能力

• DAG 编排：用 YAML 声明节点与依赖关系，agentdag 自动按拓扑序调度
• 预算闸门（bounded spend）：可设置 token 预算 / 时间预算 / 失败次数上限，超限自动熔断
• 状态日志（journaled state）：每次任务执行都写入 journaled JSONL，可断点续跑、可重放、可审计
• 机械关卡（mechanical gates）：节点之间可插入纯确定性校验（lint、test、dry-run），通过才放行
• 可插拔 Agent 后端：内置 OpenAI、Anthropic、Ollama、vLLM 适配器，也支持自定义
• 失败重试与指数退避：节点级重试策略 + 跨 DAG 的全局回滚
• 可观测面板：CLI dashboard 实时显示 DAG 执行进度、节点耗时、token 消耗
• CI/CD 友好：可作为 GitHub Action / GitLab CI step 嵌入流水线

安装配置

• 通过 pip install agentdag 安装（需 Python ≥ 3.12）
• 在仓库根目录创建 agentdag.yaml，声明节点与依赖
• 设置环境变量 AGENTDAG_LLM_API_KEY（或对应后端的 key，如 OPENAI_API_KEY）
• 可选：安装 agentdag[otel] 启用 OpenTelemetry 追踪导出
• 可选：编辑 ~/.config/agentdag/config.toml 设置全局默认预算、并发上限、日志路径

使用步骤

1. 用 pip install agentdag 安装包，运行 agentdag --version 确认安装成功
2. 在项目根目录创建 agentdag.yaml，定义节点与边：例如 plan → implement → test → review
3. 用 agentdag validate agentdag.yaml 检查 DAG 是否无环、依赖是否完整、所有节点类型是否已注册
4. 运行 agentdag run agentdag.yaml --goal "给 Flask 项目加 OAuth2 登录" 启动首次试跑
5. CLI dashboard 实时打印每个节点的状态、token 用量与日志路径
6. 任一节点失败时，agentdag 会自动按节点配置重试；超限则熔断并写入 journal/failed-{run_id}.jsonl
7. 用 agentdag replay journal/{run_id}.jsonl 重放任意历史运行，便于 debug 与对照
8. CI 中加 agentdag run --ci --budget 5.0 让流水线在超预算时自动失败

适用场景

• 内部研发团队把「自动修 bug / 自动重构 / 自动写测试」跑成 CI 任务
• 数据团队的「清洗 → 建模 → 验证 → 报告」流水线引入 LLM 节点
• 内容团队的「选题 → 写作 → 校对 → 排版」多 Agent 协同
• 客服系统的「意图识别 → 知识库检索 → 回复生成 → 质检」串联
• 研究机构跑实验型 Agent 编排时，需要可审计与可重放
• 个人把一长串 AI 工具调用封装成可重用的 DAG 模板

适用人群

正在把 AI Agent 从原型推到生产的工程团队、DevOps 平台组、需要审计与可解释性能力的金融/医疗/政企场景工程师，以及对「Agent 烧 token 没底」有切实担忧的独立开发者。

工作原理

agentdag 在内核层实现了一个DAG 执行引擎：解析 YAML → 构建节点图 → 拓扑序入队 → 工作池拉取 → 调用 Agent 后端 → 写日志 → 检查关卡 → 推进下游。每个节点执行是事务性的（all-or-nothing）：成功则把产出物（artifact）写到共享工作区，失败则把上下文快照固化供回放。预算闸门通过「在每个 LLM 调用前后采样累计 token / 成本」实现，超阈值直接 raise 并触发熔断。状态日志采用 JSONL 追加写，便于 tail / grep / 重放。

官方链接

• PyPI: https://pypi.org/project/agentdag/
• GitHub: https://github.com/bitranox/agentdag
• Issues: https://github.com/bitranox/agentdag/issues
• License: MIT