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.

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

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

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"] }
  ]
}

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.

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.