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
Top comments (1)
A schema for teams matters when it encodes responsibilities, not just names. The interesting fields are things like authority, inputs, outputs, escalation path, and what evidence counts as done.
Multi-agent systems get messy when agents overlap politely. A boring schema that makes ownership explicit can prevent a lot of circular delegation and duplicated work.