OpenAgentPack

# OpenAgentPack | 简体中文 | [English](./README.md) > **管理、审查和迁移云 AI 代理，使用 Git 和 YAML。** > > 面向托管 AI 代理的开源基础设施即代码（IaC）控制平面。 [](./LICENSE) [](https://github.com/modelstudioai/OpenAgentPack/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@openagentpack/cli) [](./CONTRIBUTING.md) > [!IMPORTANT] > OpenAgentPack 处于测试阶段。公共 API 和 `agents.yaml` 模式可能会在 1.0 版本之前发生变化。请参阅 [更新日志](./CHANGELOG.md)。 <p align="center"> <img src="https://img.alicdn.com/imgextra/i3/O1CN01xWDp5P1EP90HOZx9q_!!6000000000343-2-tps-1254-1254.png" width="360" alt="OpenAgentPack：一个 agents.yaml 文件对应多个托管代理提供商"> </p> 一个 `agents.yaml` 文件定义了一个代理的环境、模型、指令、工具、技能、MCP 服务器、保险库和凭证。在 PR 中审查每项更改，使用 `plan` 预览，然后在准备好时应用 — 而不是通过控制台点击重新构建相同的代理。 - **可审查的代理资产** — 将提示、工具、技能和配置保存在 Git 中；重复使用、回滚和移交。 - **可预测的更改** — `validate → plan → apply` 预览创建、更新和删除，然后再更改远程资源。 - **可移植的核心声明** — 使用明确的[提供商能力契约](./docs/reference/providers.md)针对 Bailian、Qoder、Claude 或 Volcengine Ark。 ```bash npm install -g @openagentpack/cli agents init # 配置某提供商的凭证，然后： agents validate && agents plan ``` [运行 5 分钟快速入门](./docs/getting-started.md) · [查看提供商支持](./docs/reference/providers.md) · [浏览可运行的示例](./docs/examples.md) · [路线图](./ROADMAP.md) ## 为什么现在 代理正在从个人工具转向企业数字化工作者。但是，使代理有价值的因素 — 其提示、技能、知识文件、工具和运行时配置 — 仍然主要存在于云提供商的控制台中。 这些是商业资产。它们应该像代码、数据和文档一样进行管理、审查、移交、复制和迁移 — 而不是像一堆控制台点击操作。 ## 为什么选择 OpenAgentPack OpenAgentPack 在代理和云平台之间提供了一个声明式控制平面。企业拥有声明；提供商适配器将其渲染成 Bailian、Qoder、Claude 或 Volcengine Ark 上的真实托管代理。 目标是使代理成为企业控制的、可移植的和可继承的数字资产。 ### 声明和可移植性：代理作为蓝图 借鉴 Docker 的声明式理念，OpenAgentPack 将决定代理是什么的所有内容 — 模型、指令、工具、技能、环境、文件和凭证引用 — 放入一个 `agents.yaml` 蓝图中。该蓝图可以存放在 Git 中，经过拉取请求审查，复制代理，并在提供商之间移动。 ### 状态和治理：执行前规划 借鉴 Terraform 的状态驱动工作流，OpenAgentPack 保持期望配置、本地状态和远程状态的明确性。`plan` 预览创建、更新和删除；`apply` 按依赖顺序执行它们；漂移检测发现控制台侧的更改；并且可以从以前的声明中恢复已知良好的配置。 ### 验证和体验：Playground 作为展示厅 即使是一个精确的蓝图也需要被体验。Playground 从同一个声明中运行真实的会话，并允许团队针对不同的提供商测试相同的场景。提供商比较成为一个可观察的结果，而不仅仅是一个功能矩阵。 > OpenAgentPack 使用类似 Docker 的声明来绘制代理蓝图，使用类似 Terraform 的状态模型来管理构建和验收，并使用 Playground 作为展示厅 — 因此企业可以像管理代码一样管理代理。 机制是一个 `agents.yaml` 文件，一个 `validate → plan → apply` 工作流，一个内容哈希差异更新，一个依赖感知排序和一个漂移恢复。YAML 始终是单一的事实来源。有关思维模型，请参见 [代理即代码](./docs/concepts/agents-as-code.md)；有关精确词汇，请参见 [CONTEXT.md](./CONTEXT.md)。 - **声明式** — 一个 `agents.yaml` 文件描述整个代理堆栈。提交它，在 PR 中审查它，回滚它。 - **Terraform 式工作流** — `validate → plan → apply`。在更改发生之前预览每个创建/更新/删除。 - **多提供商** — 在 Bailian、Qoder、Claude 和 Volcengine Ark 之间重复使用核心声明；[能力契约](./docs/reference/providers.md) 使原生、模拟和不支持的差异明确。 - **增量式** — 内容哈希差异更新仅更改实际更改的内容；无需冗余的 API 调用。 - **依赖感知** — 环境 → 技能 → 代理按拓扑顺序创建；如果依赖失败，则跳过其依赖项，而不是留下半构建状态。 - **漂移恢复** — 检测远程配置何时已偏离声明并使其协调一致。YAML 始终是单一的事实来源。 ## 演示 ### CLI 工作流  ### 本地 Playground `agents playground` 启动一个本地 WebUI，按需获取匹配的 `@openagentpack/playground` 包，并在浏览器中打开它。使用 `--provider` 参数针对 `bailian`、`qoder`、`ark` 或 `claude`。 [观看 Playground 演示视频](https://github.com/user-attachments/assets/bf51b8d8-f2ed-464b-bca9-0709fefcc44d) ## 快速入门 ```bash agents init # 交互式向导写入起始 agents.yaml agents validate # 离线 YAML 检查，无 API 调用 agents plan # 预览创建/更新/删除 agents apply -y # 应用更改 agents destroy # 拆除托管资源 ``` 最小配置： ```yaml version: "1" providers: bailian: api_key: ${DASHSCOPE_API_KEY} workspace_id: ${BAILIAN_WORKSPACE_ID} defaults: provider: bailian environments: dev: config: type: cloud networking: type: unrestricted agents: assistant: description: "通用编码助手" model: qwen3.7-max instructions: | 您是一个编码助手。 environment: dev tools: builtin: [bash, read, glob, grep] ``` 机密信息通过 `${VAR_NAME}` 引用，并从 `.env` 加载 — 它们永远不会存储在配置本身中。有关完整的操作指南，请参见 [入门](./docs/getting-started.md)。 ## 安装 全局安装 CLI： ```bash # 使用 Bun bun add -g @openagentpack/cli # 或使用 npm npm install -g @openagentpack/cli ``` 这提供了 `agents` 命令。要从源代码运行，请参见 [贡献](./CONTRIBUTING.md)。 ## 提供商支持 | 功能 | Bailian | Qoder | Claude | Volcengine Ark | |---------|:-------:|:-----:|:------:|:--------------:| | 环境 | 原生 | 原生 | 原生 | 原生 | | 保险库 | 原生 | 原生 | 原生 | 原生 | | 技能 | 原生 | 原生 | 原生 | 原生 | | 代理 | 原生 | 原生 | 原生 | 原生 | | MCP 服务器 | 原生 | 原生 | 原生 | 原生 | | 内存存储 | 不支持 | 原生 | 不支持 | 原生 | | 多代理 | 不支持 | 不支持 | 原生 | 原生 | | 部署 | 模拟 | 模拟 | 原生 | 模拟 | | 会话 | 原生 | 原生 | 原生 | 原生 | 完整的能力矩阵和每个提供商的差异在 [提供商参考](./docs/reference/providers.md) 中。 ## 文档 | 文档 | 内容 | |-----|---------------| | [入门](./docs/getting-started.md) | 从安装到运行会话的最短路径。 | | [配置指南](./docs/guides/configure-an-agent.md) | 从最小配置到完整配置的渐进式教程。 | | [配置参考](./docs/reference/configuration.md) | 每个 `agents.yaml` 字段，类型化和解释。 | | [CLI 参考](./docs/reference/cli.md) | 每个 `agents` 命令、选项和行为。 | | [提供商参考](./docs/reference/providers.md) | 能力矩阵和每个提供商的配置。 | | [工作原理](./docs/architecture/how-it-works.md) | 状态、依赖图、增量差异。 | | [示例](./docs/examples.md) | 可运行的配置，按您要执行的操作索引。 | [文档索引](./docs/README.md) 按读者目标组织其他内容：概念、指南、参考、架构和贡献。 ## 示例 [`examples/`](./examples) 目录中有每个提供商的可运行配置，从最小代理到全功能堆栈（技能、MCP、保险库、多代理、部署）。从 `examples/bailian/basic/` 开始。 ## 使用 SDK CLI 执行的所有操作都可通过 `@openagentpack/sdk` 以编程方式获得： ```ts import { resolveProjectConfig, planProjectContext } from "@openagentpack/sdk"; const config = await resolveProjectConfig({ configPath: "agents.yaml" }); const plan = await planProjectContext(config); console.log(plan); ``` 有关公共 API 接口，请参见 [SDK 参考](./docs/reference/sdk.md)。 ## WebUI `apps/webui` 是一个 Vite 单页应用，用于浏览剧本和驱动代理会话；`apps/server` 通过 OpenAPI 接口公开 SDK。两者均可在存储库根目录下运行： ```bash bun install bun run dev # 服务器 + WebUI 一起 ``` 或使用 `agents playground --provider <bailian|qoder|ark|claude>` 启动一个打包的本地 UI。 ## 贡献 欢迎贡献。请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md) 以获取开发设置、合并要求和如何添加新提供商。所有参与者都应遵守我们的 [行为准则](./CODE_OF_CONDUCT.md)。 使用 [GitHub Discussions](https://github.com/modelstudioai/OpenAgentPack/discussions) 进行问题和设计提案，使用 [GitHub Issues](https://github.com/modelstudioai/OpenAgentPack/issues) 进行可复制的错误和已接受的工作。当前优先级在 [公共路线图](./ROADMAP.md) 中跟踪。 ## 安全 发现漏洞？请遵循 [SECURITY.md](./SECURITY.md) 中的流程 — 不要公开问题。 ## 许可证 在 [Apache License, Version 2.0](./LICENSE) 下许可。