Agentic Control Plane 是一个为 AI Agent 系统打造的控制平面，借鉴 Terraform 的 plan/apply 工作流和 Kubernetes 的资源模型，通过声明式 YAML 管理 agent、工具、工作流和策略，实现版本控制、可审计和可观测的 Agent 运维。

Agentic Control Plane：用 Terraform 风格管理 AI Agent 系统\n\n## 背景：Agent 系统的运维困境\n\n随着 AI Agent 技术的快速发展，越来越多的团队开始构建复杂的 Agent 系统。然而，当前的 Agent 框架普遍存在一个根本性问题：配置和逻辑深度耦合在应用代码中。提示词（prompts）、工具绑定、权限控制等关键配置被埋藏在代码深处，导致团队难以回答一些基础的运维问题：\n\n- 这个配置是否有效？\n- 上次部署改变了什么？\n- 我们即将部署的内容是什么？\n- 实际运行了什么？\n- 策略是否允许这次执行？\n\n这种"黑盒"式的 Agent 开发与 DevOps 的最佳实践背道而驰。在基础设施领域，Terraform 通过声明式配置和 plan/apply 工作流解决了类似问题。现在，Agentic Control Plane 将这一理念引入 AI Agent 领域。\n\n## 核心设计理念\n\nAgentic Control Plane 的定位非常明确：这不是另一个不透明的 Agent 框架，而是一个控制平面。它借鉴了多个成熟技术的核心思想：\n\n| 概念 | 类比技术 |\n|------|----------|\n| Git 中的期望资源 | GitOps |\n| plan / apply / drift 检测 | Terraform |\n| 类型化资源（Project、Workflow、Policy 等） | Kubernetes 风格 API |\n| 工具和 IO 契约 | OpenAPI 式显式定义 |\n\n通过将这些理念融合，Agentic Control Plane 实现了：\n\n1. 变更审查：在配置落地前审查差异和计划\n2. 状态分离：部署状态与运行时追踪分离管理\n3. 策略执行：在执行时强制执行预算、审批、工具规则等策略\n4. 本地优先：当前以本地 SQLite 为状态存储，架构预留远程控制平面扩展空间\n\n## 架构概览\n\nAgentic Control Plane 采用分层架构，核心组件包括：\n\n### 1. 声明式资源模型（YAML）\n\n所有配置都以 YAML 形式表达，支持版本控制。主要资源类型包括：\n\n- Project：项目根资源，定义导入的文件、默认配置和提供商设置\n- Workflow：工作流定义，编排多个步骤\n- Tool：工具定义，支持 MCP 协议和 HTTP 工具\n- Policy：策略定义，控制执行权限和预算\n- Agent：Agent 定义，绑定模型、工具和策略\n\n### 2. CLI 工具（agentctl）\n\nagentctl 是主要的交互接口，提供完整的生命周期管理：\n\n- agentctl init：脚手架生成 project.yaml、策略、工具和示例工作流\n- agentctl validate：加载项目，应用默认值/环境覆盖，验证图谱、模式和引用\n- agentctl plan：对比期望图谱与 SQLite 部署状态，提供风险提示\n- agentctl apply：持久化计划（支持 TTY 确认或 --auto-approve）\n- agentctl run：本地执行工作流，支持 JSON Schema 输入验证和策略门控\n- agentctl logs：从 SQLite 读取追踪事件\n\n### 3. 本地优先的状态管理\n\n状态默认存储在项目根目录的 .agentic/state.db SQLite 文件中，包含：\n\n- 部署状态表（期望配置与实际状态的对比）\n- 运行时追踪表（执行历史、输入输出、策略决策）\n\n这种设计确保了数据主权和离线工作能力，同时支持通过 --state 参数覆盖存储位置。\n\n## 快速上手\n\n安装 Agentic Control Plane 非常简单，支持从源码构建或下载预编译二进制文件：\n\n### 从源码构建\n\nbash\ngit clone https://github.com/LAA-Software-Engineering/agentic-control-plane.git\ncd agentic-control-plane\nmake build # 生成 bin/agentctl\n\n\n### 使用预编译二进制文件\n\nGitHub Releases 提供多平台二进制文件（Linux、macOS、Windows），下载对应平台的压缩包并解压到 PATH 即可。\n\n### 基础工作流\n\nbash\n# 初始化项目\nagentctl init my-agent-system\n\n# 验证配置\nagentctl validate --project my-agent-system\n\n# 生成执行计划\nagentctl plan --project my-agent-system\n\n# 应用配置\nagentctl apply --project my-agent-system --auto-approve\n\n# 运行工作流\nagentctl run workflow/hello --project my-agent-system\n\n# 查看日志\nagentctl logs --project my-agent-system --workflow hello\n\n\n## 配置示例\n\n初始化后的 project.yaml 展示了核心配置结构：\n\nyaml\napiVersion: agentic.dev/v0\nkind: Project\nmetadata:\n name: my-agent-system\nspec:\n imports:\n - ./policies/default.yaml\n - ./tools/helper.yaml\n - ./workflows/hello.yaml\n defaults:\n policy: default\n model: openai/gpt-4o-mini\n providers:\n models:\n openai:\n type: openai\n apiKeyFrom: env:OPENAI_API_KEY\n # anthropic:\n # type: anthropic\n # apiKeyFrom: env:ANTHROPIC_API_KEY\n\n\n这种结构清晰分离了资源定义、环境配置和提供商设置，支持多环境管理和敏感信息的外部化存储。\n\n## 策略与治理\n\nAgentic Control Plane 内置了策略引擎，可以在执行时强制执行多种规则：\n\n### 预算控制\n限制单次运行或时间窗口内的资源消耗（如 API 调用次数、Token 使用量）。\n\n### 工具权限\n精细控制哪些工作流可以使用哪些工具，防止未授权的工具调用。\n\n### 审批流程\n对高风险操作（如涉及敏感数据的工具调用）实施人工或自动审批。\n\n### 审计追踪\n所有执行都被记录为结构化追踪，支持事后审计和合规检查。\n\n## 可观测性与调试\n\n项目提供了完整的可观测性支持：\n\n### 结构化日志\n所有运行都生成详细的追踪记录，包括：\n\n- 输入参数和验证结果\n- 每个步骤的执行状态和输出\n- 策略决策和拒绝原因\n- 错误堆栈和恢复尝试\n\n### 数据保留\n通过 spec.traces.retentionDays 配置自动清理旧数据，平衡存储成本和审计需求。\n\n### 多格式输出\nCLI 支持 table、JSON、YAML 三种输出格式，便于脚本集成和人工阅读。\n\n## 与现有方案的对比\n\n| 特性 | Agentic Control Plane | 传统 Agent 框架 |\n|------|----------------------|----------------|\n| 配置方式 | 声明式 YAML | 代码内嵌 |\n| 版本控制 | 原生支持 | 需额外工作 |\n| 变更审查 | plan/apply 工作流 | 通常不支持 |\n| 策略执行 | 内置策略引擎 | 需自行实现 |\n| 可观测性 | 结构化追踪 | 依赖外部工具 |\n| 状态管理 | 本地 SQLite | 通常无状态 |\n\n## 实际应用场景\n\nAgentic Control Plane 适用于多种场景：\n\n### 企业级 Agent 部署\n需要严格的变更管理、审计追踪和策略合规的企业环境。\n\n### 多环境管理\n开发、测试、生产环境的配置分离和同步。\n\n### 团队协作\n通过 Git 工作流实现配置审查和版本控制。\n\n### 合规要求\n满足金融、医疗等行业对 AI 系统可审计性的要求。\n\n## 技术实现细节\n\n项目采用 Go 语言开发，代码结构清晰：\n\n- cmd/agentctl：CLI 入口点\n- internal/cli：Cobra 命令、标志、golden 测试\n- internal/spec：YAML 类型、规范化、验证\n- internal/project：项目加载和导入解析\n- internal/plan：计划生成和风险摘要\n- internal/apply：计划应用到部署存储\n- internal/engine：工作流执行引擎\n- internal/policy：策略评估\n- internal/state/sqlite：SQLite 部署和运行时/追踪表\n\n这种模块化设计便于扩展和维护，也为社区贡献提供了清晰的接入点。\n\n## 总结与展望\n\nAgentic Control Plane 代表了一种新的 Agent 系统管理范式：将运维最佳实践从基础设施领域引入 AI 领域。通过声明式配置、版本控制、策略执行和可观测性，它为团队提供了一套完整的 Agent 生命周期管理工具。\n\n项目的当前版本（v0.1.x）已经实现了核心功能，包括完整的 CLI 工作流、SQLite 状态管理、策略引擎和结构化追踪。未来路线图包括远程控制平面、更丰富的策略类型、以及更广泛的工具生态集成。\n\n对于正在构建生产级 Agent 系统的团队来说，Agentic Control Plane 提供了一种务实且可落地的治理方案，值得深入探索。

Agentic Control Plane：用 Terraform 风格管理 AI Agent 系统\n\n背景：Agent 系统的运维困境\n\n随着 AI Agent 技术的快速发展，越来越多的团队开始构建复杂的 Agent 系统。然而，当前的 Agent 框架普遍存在一个根本性问题：配置和逻辑深度耦合在应用代码中。提示词（prompts）、工具绑定、权限控制等关键配置被埋藏在代码深处，导致团队难以回答一些基础的运维问题：\n\n- 这个配置是否有效？\n- 上次部署改变了什么？\n- 我们即将部署的内容是什么？\n- 实际运行了什么？\n- 策略是否允许这次执行？\n\n这种"黑盒"式的 Agent 开发与 DevOps 的最佳实践背道而驰。在基础设施领域，Terraform 通过声明式配置和 plan/apply 工作流解决了类似问题。现在，Agentic Control Plane 将这一理念引入 AI Agent 领域。\n\n核心设计理念\n\nAgentic Control Plane 的定位非常明确：这不是另一个不透明的 Agent 框架，而是一个控制平面。它借鉴了多个成熟技术的核心思想：\n\n| 概念 | 类比技术 |\n|------|----------|\n| Git 中的期望资源 | GitOps |\n| plan / apply / drift 检测 | Terraform |\n| 类型化资源（Project、Workflow、Policy 等） | Kubernetes 风格 API |\n| 工具和 IO 契约 | OpenAPI 式显式定义 |\n\n通过将这些理念融合，Agentic Control Plane 实现了：\n\n1. 变更审查：在配置落地前审查差异和计划\n2. 状态分离：部署状态与运行时追踪分离管理\n3. 策略执行：在执行时强制执行预算、审批、工具规则等策略\n4. 本地优先：当前以本地 SQLite 为状态存储，架构预留远程控制平面扩展空间\n\n架构概览\n\nAgentic Control Plane 采用分层架构，核心组件包括：\n\n1. 声明式资源模型（YAML）\n\n所有配置都以 YAML 形式表达，支持版本控制。主要资源类型包括：\n\n- Project：项目根资源，定义导入的文件、默认配置和提供商设置\n- Workflow：工作流定义，编排多个步骤\n- Tool：工具定义，支持 MCP 协议和 HTTP 工具\n- Policy：策略定义，控制执行权限和预算\n- Agent：Agent 定义，绑定模型、工具和策略\n\n2. CLI 工具（agentctl）\n\nagentctl 是主要的交互接口，提供完整的生命周期管理：\n\n- agentctl init：脚手架生成 project.yaml、策略、工具和示例工作流\n- agentctl validate：加载项目，应用默认值/环境覆盖，验证图谱、模式和引用\n- agentctl plan：对比期望图谱与 SQLite 部署状态，提供风险提示\n- agentctl apply：持久化计划（支持 TTY 确认或 --auto-approve）\n- agentctl run：本地执行工作流，支持 JSON Schema 输入验证和策略门控\n- agentctl logs：从 SQLite 读取追踪事件\n\n3. 本地优先的状态管理\n\n状态默认存储在项目根目录的 .agentic/state.db SQLite 文件中，包含：\n\n- 部署状态表（期望配置与实际状态的对比）\n- 运行时追踪表（执行历史、输入输出、策略决策）\n\n这种设计确保了数据主权和离线工作能力，同时支持通过 --state 参数覆盖存储位置。\n\n快速上手\n\n安装 Agentic Control Plane 非常简单，支持从源码构建或下载预编译二进制文件：\n\n从源码构建\n\nbash\ngit clone https://github.com/LAA-Software-Engineering/agentic-control-plane.git\ncd agentic-control-plane\nmake build 生成 bin/agentctl\n\n\n使用预编译二进制文件\n\nGitHub Releases 提供多平台二进制文件（Linux、macOS、Windows），下载对应平台的压缩包并解压到 PATH 即可。\n\n基础工作流\n\nbash\n初始化项目\nagentctl init my-agent-system\n\n验证配置\nagentctl validate --project my-agent-system\n\n生成执行计划\nagentctl plan --project my-agent-system\n\n应用配置\nagentctl apply --project my-agent-system --auto-approve\n\n运行工作流\nagentctl run workflow/hello --project my-agent-system\n\n查看日志\nagentctl logs --project my-agent-system --workflow hello\n\n\n配置示例\n\n初始化后的 project.yaml 展示了核心配置结构：\n\nyaml\napiVersion: agentic.dev/v0\nkind: Project\nmetadata:\n name: my-agent-system\nspec:\n imports:\n - ./policies/default.yaml\n - ./tools/helper.yaml\n - ./workflows/hello.yaml\n defaults:\n policy: default\n model: openai/gpt-4o-mini\n providers:\n models:\n openai:\n type: openai\n apiKeyFrom: env:OPENAI_API_KEY\n anthropic:\n type: anthropic\n apiKeyFrom: env:ANTHROPIC_API_KEY\n\n\n这种结构清晰分离了资源定义、环境配置和提供商设置，支持多环境管理和敏感信息的外部化存储。\n\n策略与治理\n\nAgentic Control Plane 内置了策略引擎，可以在执行时强制执行多种规则：\n\n预算控制\n限制单次运行或时间窗口内的资源消耗（如 API 调用次数、Token 使用量）。\n\n工具权限\n精细控制哪些工作流可以使用哪些工具，防止未授权的工具调用。\n\n审批流程\n对高风险操作（如涉及敏感数据的工具调用）实施人工或自动审批。\n\n审计追踪\n所有执行都被记录为结构化追踪，支持事后审计和合规检查。\n\n可观测性与调试\n\n项目提供了完整的可观测性支持：\n\n结构化日志\n所有运行都生成详细的追踪记录，包括：\n\n- 输入参数和验证结果\n- 每个步骤的执行状态和输出\n- 策略决策和拒绝原因\n- 错误堆栈和恢复尝试\n\n数据保留\n通过 spec.traces.retentionDays 配置自动清理旧数据，平衡存储成本和审计需求。\n\n多格式输出\nCLI 支持 table、JSON、YAML 三种输出格式，便于脚本集成和人工阅读。\n\n与现有方案的对比\n\n| 特性 | Agentic Control Plane | 传统 Agent 框架 |\n|------|----------------------|----------------|\n| 配置方式 | 声明式 YAML | 代码内嵌 |\n| 版本控制 | 原生支持 | 需额外工作 |\n| 变更审查 | plan/apply 工作流 | 通常不支持 |\n| 策略执行 | 内置策略引擎 | 需自行实现 |\n| 可观测性 | 结构化追踪 | 依赖外部工具 |\n| 状态管理 | 本地 SQLite | 通常无状态 |\n\n实际应用场景\n\nAgentic Control Plane 适用于多种场景：\n\n企业级 Agent 部署\n需要严格的变更管理、审计追踪和策略合规的企业环境。\n\n多环境管理\n开发、测试、生产环境的配置分离和同步。\n\n团队协作\n通过 Git 工作流实现配置审查和版本控制。\n\n合规要求\n满足金融、医疗等行业对 AI 系统可审计性的要求。\n\n技术实现细节\n\n项目采用 Go 语言开发，代码结构清晰：\n\n- cmd/agentctl：CLI 入口点\n- internal/cli：Cobra 命令、标志、golden 测试\n- internal/spec：YAML 类型、规范化、验证\n- internal/project：项目加载和导入解析\n- internal/plan：计划生成和风险摘要\n- internal/apply：计划应用到部署存储\n- internal/engine：工作流执行引擎\n- internal/policy：策略评估\n- internal/state/sqlite：SQLite 部署和运行时/追踪表\n\n这种模块化设计便于扩展和维护，也为社区贡献提供了清晰的接入点。\n\n总结与展望\n\nAgentic Control Plane 代表了一种新的 Agent 系统管理范式：将运维最佳实践从基础设施领域引入 AI 领域。通过声明式配置、版本控制、策略执行和可观测性，它为团队提供了一套完整的 Agent 生命周期管理工具。\n\n项目的当前版本（v0.1.x）已经实现了核心功能，包括完整的 CLI 工作流、SQLite 状态管理、策略引擎和结构化追踪。未来路线图包括远程控制平面、更丰富的策略类型、以及更广泛的工具生态集成。\n\n对于正在构建生产级 Agent 系统的团队来说，Agentic Control Plane 提供了一种务实且可落地的治理方案，值得深入探索。