tafreeman/agentic-runtime-platform

Agentic Runtime Platform 用于编排多智能体 AI pipeline，其中每个 agent 担任特定角色（planner、coder、reviewer），并在定义的能力层级上运行。工作流以声明式 YAML 文件编写，并编译为可执行的 DAG，支持自动并行调度、条件分支、迭代循环和故障级联传播。LLM 与确定性操作的边界在运行时得到严格隔离：高影响力的工具调用需通过故障闭合的人工审批门控，出站 HTTP 请求由默认开启的 SSRF 防护进行过滤，执行过程可通过按需启用的 OpenTelemetry tracing 进行观测。 ## 内置功能 | 组件 | 功能描述 | |-----------|-------------| | **DAG Executor** | 基于 Kahn 算法的调度，结合 `asyncio` 并行分发 —— 支持菱形依赖、条件执行和迭代优化 | | **Circuit-Breaker Model Router** | 跨 8+ 提供商的舱壁隔离与健康度加权选择，具备自适应指数退避和 HALF_OPEN 单探针熔断器 —— 无单一提供商锁定 | | **HITL Approval Gate** | 针对高影响力工具（shell、`build_app` 构建/测试运行器、文件写入、HTTP）的 human-in-the-loop 审批；**故障闭合** —— 当未注册审批提供商时，受控工具将被拒绝，绝不静默放行 | | **Bias-Aware LLM-as-Judge** | 通过植入种子的标准洗牌来缓解位置偏差，进行交换顺序的一致性检查，并使用 MAE 针对人工标记的基准数据进行校准 | | **Non-Compensatory Gated Evaluation** | YAML 定义的评分标准、受 DORA 启发的 Elite/High/Medium/Low 层级，基于所有评分维度的非补偿性底线进行门控 | | **SSRF Guard (DNS-rebinding pinning)** | 默认开启的出站防护 —— 解析 DNS，验证每个返回的 IP 地址，并固定连接以挫败重绑定攻击，包括对云元数据的黑名单过滤 | | **Self-Consistency Ensembling** | 对采样的 completions 进行多数投票/自洽性共识，适用于高风险输出 | | **Structured Human-Escalation** | 采用死信队列风格的移交路径，将无法解决或超出策略范围的 case 路由给人工审核者，而不是静默失败 | | **React Dashboard** | 实时 DAG 可视化，支持 SSE/WebSocket 流式传输、OpenTelemetry tracing 的 token 使用情况追踪以及历史记录 | | **Zero-credential dev mode** | `AGENTIC_NO_LLM=1` 通过占位后端进行端到端运行 —— 无需 API key 即可通过完整的测试套件 | **引擎默认行为**：在迁移窗口期间，CLI、服务器和 dashboard 请求会针对命名的 YAML workflow 使用 LangGraph 适配器（`adapter=langchain`）。使用 `--adapter native` 或请求 `adapter: "native"` 可切换至轻依赖的原生 DAG/Pipeline 路径。运行时生成的 DAG 默认使用原生引擎。`AGENTIC_NO_LLM=1` 会将提供商调用更改为确定性占位符；它不会更改引擎选择。 ## 快速开始 ``` # 克隆与设置 git clone https://github.com/tafreeman/agentic-runtime-platform.git cd agentic-runtime-platform just setup # 运行你的首个 workflow — 无需 API key # --input 标志接受一个 JSON 文件路径（而非内联 JSON） echo '{"input_text": "Hello World"}' > /tmp/test-input.json AGENTIC_NO_LLM=1 agentic run test_deterministic --input /tmp/test-input.json # Windows PowerShell: # '{"input_text": "Hello World"}' | Out-File -Encoding utf8 test-input.json # $env:AGENTIC_NO_LLM = "1" # agentic run test_deterministic --input test-input.json # 要使用 LLM 驱动的 workflows，请添加一个 provider key： cp .env.example .env # 在 .env 中添加至少一个 LLM provider API key # 启动 dashboard uvicorn agentic_v2.server.app:create_app --factory --reload --port 8010 # 在另一个终端中： cd ui && npm run dev ``` 请参阅[完整的入门指南](https://tafreeman.github.io/agentic-runtime-platform/ONBOARDING/)获取详细的设置说明。 ## 基于 AI 辅助构建 本项目在工程工作流中使用了 AI 开发工具。架构、实现方案、测试以及公开文档均由维护者负责审查和把控；这些工具仅作为 agentic-runtime 项目的加速器使用，而非替代设计审查或验证。 ## 工作流示例 ``` # workflows/definitions/code_review.yml steps: - name: parse_code agent: tier2_parser description: Extract structure and dependencies tools: [file_read, ast_parse] inputs: code_path: ${inputs.code_path} outputs: structure: structure - name: review_architecture # Runs in parallel agent: tier3_architect # with review_quality depends_on: [parse_code] inputs: structure: ${steps.parse_code.outputs.structure} outputs: architecture_report: report - name: review_quality # Runs in parallel agent: tier3_reviewer # with review_architecture depends_on: [parse_code] inputs: structure: ${steps.parse_code.outputs.structure} outputs: quality_report: report - name: synthesize agent: tier4_synthesizer depends_on: [review_architecture, review_quality] inputs: reports: [ ${steps.review_architecture.outputs.architecture_report}, ${steps.review_quality.outputs.quality_report} ] outputs: final_report: report ``` 运行命令： ``` from agentic_v2.workflows import run_workflow result = await run_workflow( "code_review", code_path="src/api/handlers.py" ) print(result.final_output["final_report"]) # Consolidated review print(result.metadata["agents_used"]) # ["tier2_parser", "tier3_architect", "tier3_reviewer", "tier4_synthesizer"] print(result.total_duration_ms) # Total execution time in milliseconds ``` ## 架构 ``` graph TD A[YAML Workflow DSL] --> B[Workflow Loader] B --> C[Workflow Model / Step DAG] C --> D[Native DAG Executor] C --> G[LangGraph Compiler] G --> H[LangGraph Runtime] D --> E[Tiered Model Router] H --> E E --> F[Provider Backends] subgraph Router E E1[Tier 1: flash-lite, 4o-mini] E2[Tier 2: flash, haiku] E3[Tier 3: 2.5-flash, gpt-4o] E4[Tier 4: 2.5-pro, claude-sonnet] E5[Health-weighted selection] E6[Circuit breakers] end subgraph Providers F F1[OpenAI] F2[Anthropic] F3[Google Gemini] F4[Azure OpenAI] F5[GitHub Models] F6[Ollama / Local] end ``` ## 关键设计决策 ### 为什么选择 DAG 而不是 Pipeline？ 多智能体工作流很少以纯线性方式执行。在规划阶段之后，两个专家分析员会针对相同的证据**并行**运行。它们的输出汇总到验证阶段，验证阶段会根据条件触发下一轮研究。如果是 pipeline 架构会导致不必要的串行化；而使用带有 `asyncio.wait(FIRST_COMPLETED)` 的 DAG 则能最大化吞吐量。 ### 为什么选择分层模型路由？ 按名称将工作流步骤映射到模型会造成脆弱性：模型名称会变、endpoint 会宕机、定价也会波动。相反，每个 agent 都会被分配一个**能力层级**（例如，`tier3_analyst`）。Router 会在运行时将其解析为当前可用的最佳模型，并带有如下的 fallback 链： ``` Tier 3: gemini-2.5-flash → gh:gpt-4o → openai:gpt-4o → anthropic:claude-sonnet ``` `SmartModelRouter` 在此基础上扩展了健康度加权选择、自适应冷却（失败时的指数退避）以及熔断器模式。 ### asyncio Orchestrator 与 SDK-`Task` 编排的对比 `OrchestratorAgent` 会分解任务，根据能力集对 agent 进行评分，然后使用 `asyncio.gather` 将子任务分发出去。**SDK 原生对应方案** —— 即使用真正的 Claude Agent SDK `Task` 工具，配合 `AgentDefinition` 子智能体、动态的模型驱动选择，以及在单轮中进行并行的 `Task` 调用 —— 位于 [`examples/sdk_task_orchestrator.py`](examples/sdk_task_orchestrator.py)。关于两者的权衡（确定性的能力路由分发 vs 开放式的模型驱动委托）已在 [ADR-025](docs/adr/ADR-025-sdk-task-orchestration.md) 中记录。 ### 为什么选择基于标准的评分？ LLM 输出很难简单用二元的通过/失败来评估。评分系统使用了 YAML 定义的 rubric，包含加权标准、分数归一化以及对缺失标准的显式处理。对于复杂的评估，多维评分引擎会将输出在五个正交维度（覆盖率、来源质量、一致性、验证度、时效性）上进行分类，归入受 DORA 启发的性能层级（Elite、High、Medium、Low），并在所有维度上设置非补偿性的 High 底线进行门控。 ## 工作流定义 该引擎内置了 **6 个生产环境工作流定义**： | 工作流 | 模式 | 描述 | |----------|---------|-------------| | `code_review` | 扇出 / 扇入 | 解析代码 → 并行进行架构 + 质量审查 → 综合 | | `bug_resolution` | 带验证的串行流程 | 复现 → 根因分析 → 修复 → 测试 → 验证 | | `fullstack_generation` | 并行子步骤 | API 设计 → 并行处理前端 + 后端 → 集成 | | `iterative_review` | 有界迭代的多循环 | 审查 → 反馈 → 修改，直到通过质量门控 | | `conditional_branching` | 条件 DAG | 根据运行时条件执行或跳过步骤 | | `test_deterministic` | 仅 Tier-0 | 无需 LLM 调用的确定性测试步骤 | ## 项目结构 ``` agentic-runtime-platform/ ├── agentic-workflows-v2/ # Core runtime package │ ├── agentic_v2/ │ │ ├── engine/ # DAG executor, step runner, expression engine │ │ ├── models/ # Tiered routing, provider backends │ │ ├── agents/ # Agent implementations │ │ ├── workflows/definitions/ # 6 YAML workflow definitions │ │ ├── langchain/ # LangGraph integration │ │ ├── server/ # FastAPI backend │ │ ├── rag/ # Full RAG pipeline │ │ └── contracts/ # Pydantic I/O models │ ├── ui/ # React 19 dashboard │ └── tests/ # Full runtime test suite (unit, integration, E2E) │ ├── agentic-v2-eval/ # Evaluation framework │ └── src/agentic_v2_eval/ │ ├── evaluators/ # Rubric-based evaluators │ ├── scoring/ # Scoring utilities │ └── reporters/ # Result reporting │ └── tools/ # Shared utilities └── llm/ # Multi-provider LLM client ``` ## 功能特性 - **双执行引擎**：默认的命名 YAML 工作流运行使用 LangGraph；显式指定 `--adapter native` 的运行和运行时生成的 DAG 使用原生 DAG/Pipeline 执行 - **8+ 个 LLM 提供商**：OpenAI、Anthropic、Gemini、Azure OpenAI、Azure Foundry、GitHub Models、Ollama、本地 ONNX - **分层模型路由**：具备健康度加权选择和熔断器机制 - **可观测的执行过程**：通过 SSE/WebSocket 流式传输至 React dashboard - **基于标准的评估**：采用 YAML 定义的标准和 LLM-as-judge - **Zero-credential dev mode**：无需 API key 即可运行所有测试和工作流 - **类型安全的接口**：完全符合 Pydantic v2 契约；在 `agentic-v2-eval` 中强制执行 `mypy --strict`，更广泛的运行时覆盖正在推进中 - **生产就绪的核心组件**：DAG executor、模型路由器和评估框架已通过 pre-commit hooks（black、ruff 以及用于 `agentic-v2-eval` 的 mypy）、完整的运行时测试套件（参见 [CI](https://github.com/tafreeman/agentic-runtime-platform/actions/workflows/ci.yml) 了解当前的通过/失败状态及覆盖率），以及 80%+ 的门控覆盖率底线进行了强化。RAG、Redis 状态和部分提供商适配器明确处于开发阶段 —— 详见 [KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md) - **速率限制 + 401 锁定**：`slowapi` 全局限制器（`AGENTIC_RATE_LIMIT_DEFAULT`，默认为 `60/minute`）；在多次身份验证失败后，按 IP 进行滑动窗口锁定（`AGENTIC_AUTH_LOCKOUT_THRESHOLD`、`AGENTIC_AUTH_LOCKOUT_WINDOW_SECONDS`、`AGENTIC_AUTH_LOCKOUT_DURATION_SECONDS`） - **DAG executor 超时看门狗**：向 executor 传入 `timeout=`；正在运行的任务将被结构化取消，后续步骤将被级联跳过，并触发 `workflow.timeout_exceeded` OTEL span 属性 ## 文档 完整文档发布在 **https://tafreeman.github.io/agentic-runtime-platform/**。 - [快速开始](https://tafreeman.github.io/agentic-runtime-platform/ONBOARDING/) — 5 分钟到 1 小时的首次运行指南 - [架构概述](https://tafreeman.github.io/agentic-runtime-platform/ARCHITECTURE/) — 系统图谱与核心承载机制 - [工作流编写](https://tafreeman.github.io/agentic-runtime-platform/WORKFLOW_AUTHORING/) — YAML DSL 指南 - [模式目录](https://tafreeman.github.io/agentic-runtime-platform/PATTERN_CATALOG/) — Agentic 模式参考 - [API 参考](https://tafreeman.github.io/agentic-runtime-platform/api-contracts-runtime/) — REST endpoint 与契约 - [开发指南](https://tafreeman.github.io/agentic-runtime-platform/development-guide/) — 设置、测试、CLI ## 开发说明 ### 前置条件 - Python 3.11+ - Node.js 20+ (用于 UI) - 至少一个 LLM 提供商的 API key（或使用 `AGENTIC_NO_LLM=1` 进入占位模式） ### 安装 ``` # 克隆 repository git clone https://github.com/tafreeman/agentic-runtime-platform.git cd agentic-runtime-platform # 一键引导（安装所有 packages 和 dependencies） just setup # 或手动安装： cd agentic-workflows-v2 pip install -e ".[dev,server,langchain]" # 配置环境 cp ../.env.example ../.env # 使用你的 API keys 编辑 .env ``` ### 运行测试 ``` # Runtime 测试（全套） cd agentic-workflows-v2 pytest tests/ -v --cov=agentic_v2 # Evaluation framework 测试 cd ../agentic-v2-eval pytest tests/ -v # UI 测试 cd ../agentic-workflows-v2/ui npm test ``` ### 代码质量 本项目通过 pre-commit hooks 强制执行代码质量检查： ``` # 安装 pre-commit hooks pre-commit install # 手动运行所有 hooks pre-commit run --all-files ``` | 工具 | 用途 | |------|---------| | **black** | 代码格式化（88 字符行宽） | | **isort** | 导入排序（兼容 black） | | **ruff** | 具备自动修复的快速 linting | | **mypy** | 针对 `agentic-v2-eval` 的静态类型检查 | | **docformatter** | Docstring 格式化 | | **pydocstyle** | 强制执行 Google 风格的 Docstring | ## 与 ExecutionKit 的关系 ExecutionKit 和 Agentic Runtime Platform 处于同一技术栈的不同层： | | ExecutionKit | Agentic Runtime Platform | |---|---|---| | **角色** | 模式库 | 编排 runtime | | **范围** | 单次 LLM 调用模式 | 多智能体 DAG 工作流 | | **工作流编写** | Python 函数 | 声明式 YAML | | **依赖** | 零依赖（仅标准库） | FastAPI、LangGraph、Pydantic | | **适用场景** | 你需要推理原语时 | 你需要编排多个 agent 时 | **当 ExecutionKit 已安装时，Agentic Runtime Platform 会使用它进行步骤委托** —— 通过可选的 `[ek]` 扩展（`pip install -e "agentic-workflows-v2[ek]"`）；如果未安装，平台将回退至其原生 runtime。 ## 标准与治理 | 领域 | 制品 | 描述 | |------|----------|-------------| | 架构决策 | [ADR 索引](docs/adr/ADR-INDEX.md) | 包含传承链和实施跟踪的完整决策日志 | | 已知技术债 | [KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md) | 诚实客观的记录，包含严重程度、变通方案和上游修复字段 | | 安全性 | [SECURITY.md](agentic-workflows-v2/SECURITY.md) | 协调披露策略和加固指南；包含速率限制和 IP 的 401 锁定配置 | | 供应链 | [Dependabot](.github/dependabot.yml) | 针对 pip、npm 和 GitHub Actions 的自动更新 | | 路线图 | [ROADMAP.md](docs/ROADMAP.md) | 已交付的史诗任务、进行中的迭代以及提议的工作 | | 迁移指南 | [MIGRATIONS.md](docs/MIGRATIONS.md) | 自 v0.3.0 以来的破坏性变更 | ## 贡献指南 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解针对整个 monorepo 的贡献指南 —— 包括本地门控、提交格式、何时需要提交 ADR 以及 PR 核对清单。 ## 许可证 本项目基于 MIT 许可证授权 —— 详见 [LICENSE](LICENSE)。

标签：AI安全治理, AI智能体, DLL 劫持, MCP协议, 人工智能, 大语言模型, 工作流编排, 用户代理, 用户模式Hook绕过, 计算机取证