用 Open Envelope 定义可移植的 AI Agent 团队——从 Schema 到生产部署

引言：多 Agent 系统的标准化困境

团队级 AI Agent 已经不再是实验性项目——支持工单自动分类、代码审查流水线、数据管道监控等场景的多 Agent 系统正在成为真实部署模式。然而一个尴尬的现实是：每个 Team 的定义方式都散落在不同框架里。你用 LangGraph 写的一套 Agent 团队定义，搬到 CrewAI 上几乎要重写。你选了一个编排平台，就被它锁定。

这正是 Open Envelope 要解决的问题。它定义了一个开放、与框架无关的 JSON Schema，让你能用一份 .envelope.json 文件描述整个 AI Agent 团队——谁做什么、用什么模型、访问什么资源、如何协作、什么时候运行——然后把这份定义部署到任意兼容的运行时上。

让我用一个真实的团队定义来带你走一遍 Open Envelope 的 Schema 和用法。

一个完整的团队定义

假设你在开发一个技术支持工单处理系统，需要一个三 Agent 团队：分类器负责判断紧急程度，分析师处理技术问题，升级专员处理无法自动解决的工单。Open Envelope 的团队定义长这样：

{
  "$schema": "https://schema.openenvelope.org/team/v1.json",
  "name": "Support Triage Team",
  "slug": "support-triage",
  "version": "1.0.0",
  "description": "Automated support ticket triage and analysis",
  "visibility": "team",
  "agents": [
    {
      "key": "classifier",
      "name": "Ticket Classifier",
      "title": "Triage Specialist",
      "role": "specialist",
      "model": "anthropic:claude-sonnet-4-20250514",
      "prompt": "你是一个工单分类专家。将工单分为：urgent（紧急）、standard（标准）、low（低优先级）。对于 urgent 类工单，必须附加 g2 严重性标签。",
      "capabilities": ["triage", "classification"],
      "allowedHosts": ["api.ticketing.internal"]
    },
    {
      "key": "analyst",
      "name": "Issue Analyst",
      "title": "Technical Analyst",
      "role": "analyst",
      "reportsToKey": "classifier",
      "model": "anthropic:claude-sonnet-4-20250514",
      "prompt": "你是一个技术分析师。根据工单内容提供解决方案建议、相关文档链接、以及预计修复时间。",
      "capabilities": ["analysis", "documentation"],
      "accessPolicy": {
        "accessPolicyVersion": "1",
        "defaultAction": "deny",
        "rules": [
          { "host": "knowledge-base.internal", "action": "allow" },
          { "host": "docs.internal", "action": "allow" }
        ]
      }
    },
    {
      "key": "escalator",
      "name": "Escalation Handler",
      "title": "Senior Support Engineer",
      "role": "manager",
      "reportsToKey": "classifier",
      "model": "anthropic:claude-opus-4-5",
      "prompt": "你是升级处理专员。仅处理标记为 urgent 的工单。生成升级报告并路由到 on-call 工程师。",
      "capabilities": ["escalation", "routing"],
      "allowedHosts": ["pagerduty.internal", "slack.internal"]
    }
  ]
}

这份定义已经包含了完整的团队结构：拓扑关系（谁向谁汇报）、模型分配、系统提示词、以及网络级的访问控制策略。

理解核心 Schema 元素

Agent 定义的基本结构

每个 Agent 必须包含 key、name、title 和 role 四个字段。role 推荐使用 manager、specialist、analyst 等预定义值，但也可以传入自定义值——运行时会原样透传。

关键设计决策：提示词与基础设施解耦。Agent 的 prompt 字段只关心业务逻辑（”将工单分为 urgent/standard/low”），不包含对 API 端点或认证密钥的引用。这些通过 secrets 和 variables 注入。

层级关系：reportsToKey

与大多数多 Agent 框架不同，Open Envelope 使用扁平的 reportsToKey 字段建立层次结构，而不是嵌套 JSON。这让团队拓扑更容易通过编程方式生成和修改。上面的例子中，analyst 和 escalator 都向 classifier 汇报。

访问控制：两种模式

Open Envelope 提供了两种访问控制模式，可以在 Agent 级别配置：

1. 简单模式——allowedHosts 数组，直接列出允许的主机名。适用于访问范围固定的 Agent。
2. 策略模式——accessPolicy，支持规则列表和 defaultAction。defaultAction: deny 是推荐配置（白名单安全模型），然后对每个需要访问的主机添加一条 allow 规则。

关键区别：访问策略是在网络层强制执行的，而不是在提示词层。也就是说，即使升级专员 Agent 被注入提示词引导它尝试访问知识库，运行时会从网络层面拦截这个请求。这比依赖提示词的”请只使用这些工具”要可靠得多。

模型配置：从简单到精细

大多数场景只需 model 字段（"anthropic:claude-sonnet-4-20250514" 格式）。如果需要精细控制温度或 Token 限制，用 modelConfig：

{
  "modelConfig": {
    "temperature": 0.3,
    "maxTokens": 4096
  }
}

添加人工审批门控

对于生产级系统，直接让 Agent 执行所有操作风险太大。Open Envelope 在团队级别的 gates 字段中支持人工审批门控（Human-in-the-loop Gates）：

{
  "gates": [
    {
      "key": "escalation-approval",
      "label": "升级专员需要在发出通知前人工确认",
      "type": "approval",
      "agentKey": "escalator",
      "timeoutMs": 300000
    }
  ]
}

当升级专员准备发出通知时，运行时会暂停执行，等待人工确认（type: approval）。超时未确认则跳过该步骤并记录日志。所有 Gate 类型在 v1 中都是 HITL（Human-in-the-Loop），未来会支持自动化门控。

Pipeline：编排执行顺序

而非让 Agent 并行运行并自行协调（这在多 Agent 系统中是常见的问题源），你可以明确定义 pipeline：

{
  "pipeline": [
    { "key": "classify", "agentKey": "classifier" },
    { "key": "analyze", "agentKey": "analyst", "dependsOn": ["classify"] },
    { "key": "escalate", "agentKey": "escalator", "dependsOn": ["classify"] }
  ]
}

classifier 第一步运行，完成后 analyst 和 escalator 并行执行——它们都依赖 classify 完成，但彼此之间无依赖。这与许多编排系统中的 DAG 模型一致。

调度触发

不只是 API 触发，你也可以让团队定时运行：

{
  "schedule": {
    "type": "cron",
    "cron": "*/15 * * * *",
    "label": "每 15 分钟检查一次未处理的工单"
  }
}

或者设为 type: manual（默认），让团队仅在 API 或 UI 触发的按需模式下运行。

从代码中使用 Schema

Open Envelope 提供了 npm 包 @openenvelope/schema，支持 TypeScript 类型检查和运行时验证：

npm install @openenvelope/schema

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

const team: TeamDefinition = {
  name: 'Support Triage Team',
  slug: 'support-triage',
  version: '1.0.0',
  description: '工单自动分类与分析团队',
  visibility: 'team',
  agents: [
    {
      key: 'classifier',
      name: 'Ticket Classifier',
      title: 'Triage Specialist',
      role: 'specialist',
      model: 'anthropic:claude-sonnet-4-20250514',
      prompt: 'Classify tickets as urgent, standard, or low priority.',
    }
  ]
};

也可以脱离 TypeScript，直接用 JSON Schema 做验证：

npm install ajv @openenvelope/schema

import Ajv from 'ajv';
import schema from '@openenvelope/schema/schema.json';

const ajv = new Ajv();
const validate = ajv.compile(schema);
const valid = validate(myTeamDefinition);

IDE 支持

在 .envelope.json 文件顶部添加 $schema 字段后，VS Code、JetBrains 等编辑器会自动提供自动补全和实时校验——不需要额外安装任何插件。Schema 已经注册在 SchemaStore 中。

Deploy Once, Run Anywhere

Open Envelope 的理念可以用一个类比理解：Dockerfile 描述容器但不绑定到特定运行时引擎，.envelope.json 描述 Agent 团队但不绑定到特定编排平台。Schema 是 Apache 2.0 协议，任何人都可以实现兼容的运行时。官方提供托管运行时（openenvelope.org）支持直接部署，也支持导出到 Paperclip、Relevance AI、Amazon Bedrock 等平台。

这种可移植性的价值在于：你定义一次团队拓扑，就可以在开发阶段用轻量本地运行时测试，在 CI 阶段用容器化运行时验证，在生产阶段部署到企业级编排平台——而 Schema 文件本身不需要任何修改。

最佳实践与注意事项

• 访问策略优先用白名单模式——defaultAction: deny + 逐条放行，比黑名单模式安全可靠得多
• 保持提示词纯净——不要在 prompt 中硬编码密钥或主机名，用 secrets 和 variables 注入
• Pipeline 优先于隐式协调——如果 Agent 之间的协作顺序很关键，不要依赖 Agent 自行”聊出来”，明确定义 pipeline 步骤
• 版本不可变——一旦发布到 registry，version 不可更改。更新内容要发布新版本
• 善用 Fork——公有团队可被 fork，这是 Agent 团队生态的「开源模式」

总结

Open Envelope（51 HN points, Apache 2.0）解决的是一个真实且被忽视的问题：多 Agent 团队定义的可移植性。在一篇 .envelope.json 中，你就能描述完整的团队拓扑、角色分配、模型选择、访问控制、人工审批门控和调度策略。无论底层用的是什么编排框架，这份定义都能跨平台复用。

如果你正在构建或计划构建多 Agent 系统，Open Envelope 的 Schema 值得一试——即使你不打算用它的托管运行时，单独的 Schema 和 npm 包也能帮你把团队定义规范化、版本化、可审计化。