AI 2026年6月6日 2 分钟阅读

Open Envelope 完全指南：像定义 Dockerfile 一样定义 AI Agent 团队

tinyash 0 条评论

当你的 AI 编码项目从单个助手进化为多 Agent 系统时，一个新的问题出现了：你如何定义这些 Agent 的角色、工具、访问权限和协作流程？ 更关键的是——这些定义能否在不同框架和运行时之间迁移？

目前的现状是：每个系统各自为政，Agent 定义被锁死在特定的实现中。用 LangGraph 定义的团队没法直接迁移到 CrewAI 上，CrewAI 的配置在 AutoGen 上也无法使用。Open Envelope 的目标就是解决这个问题——用一个开放、可移植的 JSON Schema 来定义 AI Agent 团队。

为什么需要 Agent 团队定义标准？

单个 AI Agent（如 Claude Code、Cursor）的能力已经足够强大，但真正的企业级 AI 应用往往需要多个 Agent 协作：一个写代码、一个做测试、一个管理部署流水线、一个监控生产环境。这些 Agent 需要知道彼此的职责边界、调用的工具范围、以及什么时候需要人工介入。

没有标准化定义的情况下，这些配置散落在多个地方：YAML 文件、Python 配置类、API 控制台、环境变量……每次换框架就要重写一遍。Open Envelope 的思路是为 Agent 团队定义一个类似 Dockerfile 的清单文件（.envelope.json），一份定义，任何兼容的运行时都能执行。

.envelope.json 长什么样？

一个典型的 Envelope 定义文件如下：

{
  "$schema": "https://schema.openenvelope.org/team/v1.json",
  "name": "代码质量审查团队",
  "slug": "code-quality-team",
  "version": "1.0.0",
  "description": "负责代码审查、测试和部署质检的 AI Agent 团队",
  "visibility": "public",
  "agents": [
    {
      "id": "code-reviewer",
      "name": "Code Reviewer",
      "role": "对每段代码变更进行审查，检查潜在问题",
      "model": "claude-sonnet-4-20260604",
      "tools": ["read_file", "search_files", "git_diff"],
      "access_policies": ["repo:read", "issues:write"],
      "handoffs": ["tester"]
    },
    {
      "id": "tester",
      "name": "Tester",
      "role": "为代码变更生成测试用例并运行",
      "model": "gpt-5-20260604",
      "tools": ["run_tests", "generate_mocks"],
      "access_policies": ["test:write", "ci:trigger"],
      "handoffs": ["deployment-manager"]
    }
  ],
  "human_in_the_loop": {
    "code-reviewer": ["merge-request"],
    "deployment-manager": ["prod-deploy"]
  },
  "pricing": {
    "type": "free"
  }
}

核心概念拆解

1. Agent 定义（最核心的部分）

每个 Agent 通过 id、name、role、model 和 tools 来描述。role 字段是一个自由文本提示词，告诉 Agent 它在这个团队中的职责。tools 列表声明 Agent 可以调用的工具——这些工具的具体实现由运行时提供。

2. Access Policies（访问控制）

这是 Open Envelope 的一个重要设计：访问策略在网络层面执行，而不是通过提示词来约束。传统做法是在 system prompt 里写”你只能读取代码仓库，不能修改”，但提示词可以被绕过。Envelope 的 access_policies 让运行时在网络层强制执行权限——比如 repo:read 意味着 Agent 的 HTTP 请求和文件操作都被限制在只读范围内。

3. 层级结构（Supervisor/Sub-Agent）

Agent 之间可以通过 handoffs 字段定义谁向谁传递控制权。完整的手递手链可以实现多层 supervision 架构——manager Agent 分配任务，worker Agent 执行，再将结果传递回 manager。

4. Human-in-the-Loop 门控

human_in_the_loop 字段定义了哪些关键操作需要人工审批。在这个例子里，code-reviewer 的 merge-request 操作需要人来确认——代码审查可以交给 AI，但合入代码的按钮必须由人来按。

5. 版本控制与不可变性

每个 .envelope.json 都包含一个 semver 版本号。一旦发布，该版本不可变更——这是让用户放心使用第三方 Agent 团队定义的关键设计。如果你更新了团队配置，需要创建一个新的版本号。

如何使用

第一步：安装 VS Code 支持

因为 Schema 已经在 SchemaStore 中注册，你只需创建一个 .envelope.json 文件即可获得自动补全和校验：

touch my-team.envelope.json

第二步：验证定义

npx ajv-cli validate -s team-v1.json -d my-team.envelope.json

或者使用 npm 包：

npm install @openenvelope/schema
import type { TeamDefinition } from '@openenvelope/schema';

第三步：在任何兼容的运行时上运行

将你的 .envelope.json 提交给任何实现了 Envelope 协议的运行时（如 openenvelope.org 的托管运行时，或其他框架的兼容版本），Agent 团队就会按定义初始化。

与其他方案的对比

方案格式可移植性访问控制版本管理
Open EnvelopeJSON Schema✅ 框架无关✅ 网络层实施✅ semver + 不可变
Claude Code WorkflowsYAML❌ Claude 专属❌ 提示词层❌ 无版本控制
CrewAI ConfigYAML❌ CrewAI 专属⚠️ 部分支持❌ 无版本控制
LangGraphPython❌ LangChain 生态❌ 代码层实现⚠️ 靠 git
自定义脚本各异❌ 每次重新实现❌ 不一致❌ 无标准

适用场景

Open Envelope 特别适合以下场景：

  1. 团队模板市场：像 Docker Hub 一样分享 Agent 团队定义，其他人直接 fork 修改即可
  2. CI/CD 流水线：在 CI 中定义一个包含测试 Agent、部署 Agent 和监控 Agent 的团队
  3. 客户支持：定义一级支持 Agent、二级升级 Agent 和质量审查 Agent 的分层支持团队
  4. 跨组织协作：不同团队共享标准化的 Agent 配置，确保一致的安全策略

注意事项

  • Open Envelope 目前仍是早期项目（v1.1.0），agents 数组中的工具引用和 handoffs 链路在标准运行时之外的兼容性需要验证
  • 每个 Agent 的 model 字段目前是自由文本，尚不支持版本匹配或回退策略
  • pricing 字段目前主要用于托管运行的计费展示，自建运行时可以忽略
  • 由于 Schema 定义使用 JSON Schema draft-07，枚举值不支持自定义扩展——如果你需要一个新的 category，需要向 Schema 仓库提交 PR

总结

Open Envelope 想做的是：把 AI Agent 团队定义从”一段 Python 代码”或”一个框架特有的 YAML 配置”变成一个可以在任何地方使用的开放标准。就像 Dockerfile 解耦了容器定义和运行时实现一样，.envelope.json 让 Agent 团队的定义和运行彻底分离。对于在构建多 Agent 系统的开发者来说，这是一个值得关注的方向。

AI AI 工具 开发工具 开发教程 开源

发表评论

你的邮箱地址不会被公开，带 * 的为必填项。