We built an open schema for structuring multi-agent teams — here's what we learned

Building a team of agents — each with a defined role, each potentially running a different model — is harder than it looks. And once you've built it, the definition is locked to whatever platform you built it in. Move to a different runtime or vendor and you're rewriting from scratch.

Every project reinvents the same structure. Nothing is portable.

So we built something portable.

The core problem

When you put agents together to complete a task, you need answers to questions that most frameworks don't address at the schema level:

• Who does this agent report to?
• What has to finish before this agent can start?
• What's this agent's role — and which model is best suited to it?

Without explicit answers, you end up with implicit structure baked into prompts. Which works until it doesn't.

What the schema looks like

An agent requires four fields: key, name, title, and role. Here's a minimal valid team definition — with different models per agent:

{
  "$schema": "https://schema.openenvelope.org/team/v1.json",
  "name": "Content Team",
  "slug": "content-team",
  "version": "1.0.0",
  "description": "A two-agent content pipeline.",
  "visibility": "public",
  "agents": [
    {
      "key": "researcher",
      "name": "Research Agent",
      "title": "Senior Researcher",
      "role": "Finds and summarises source material",
      "model": "openai:gpt-4o-mini"
    },
    {
      "key": "writer",
      "name": "Writing Agent",
      "title": "Content Writer",
      "role": "Drafts content from research",
      "model": "anthropic:claude-opus-4-5",
      "reportsToKey": "researcher"
    }
  ]
}

reportsToKey gives you the hierarchy. For execution order, add a pipeline with dependsOn:

{
  "pipeline": [
    { "key": "step-research", "agentKey": "researcher" },
    { "key": "step-write", "agentKey": "writer", "dependsOn": ["step-research"] }
  ]
}

What we deliberately left out

For now, runtime concerns — memory and shared state — stay out of the schema. Those belong in the runtime, not the spec. The schema is just structure: who the agents are, how they relate, and in what order they run.

Why open source it

We want this to be a shared foundation, not a proprietary format. If you're building multi-agent tooling and want to be compatible, or if you see gaps in the spec, we'd love to hear from you.

• GitHub: github.com/openenvelope/schema
• NPM: npmjs.com/package/@openenvelope/schema
• Schema: schema.openenvelope.org