{"slug": "we-built-an-open-schema-for-structuring-multi-agent-teams-here-s-what-we-learned", "title": "We built an open schema for structuring multi-agent teams — here's what we learned", "summary": "A developer built an open schema for structuring multi-agent teams, addressing the lack of portability across platforms. The schema defines agents with fields like key, name, title, role, and model, and supports hierarchy via reportsToKey and execution order via pipeline with dependsOn. The goal is to create a shared foundation for multi-agent tooling.", "body_md": "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.\n\nEvery project reinvents the same structure. Nothing is portable.\n\nSo we built something portable.\n\nWhen you put agents together to complete a task, you need answers to questions that most frameworks don't address at the schema level:\n\nWithout explicit answers, you end up with implicit structure baked into prompts. Which works until it doesn't.\n\nAn agent requires four fields: `key`\n\n, `name`\n\n, `title`\n\n, and `role`\n\n. Here's a minimal valid team definition — with different models per agent:\n\n```\n{\n  \"$schema\": \"https://schema.openenvelope.org/team/v1.json\",\n  \"name\": \"Content Team\",\n  \"slug\": \"content-team\",\n  \"version\": \"1.0.0\",\n  \"description\": \"A two-agent content pipeline.\",\n  \"visibility\": \"public\",\n  \"agents\": [\n    {\n      \"key\": \"researcher\",\n      \"name\": \"Research Agent\",\n      \"title\": \"Senior Researcher\",\n      \"role\": \"Finds and summarises source material\",\n      \"model\": \"openai:gpt-4o-mini\"\n    },\n    {\n      \"key\": \"writer\",\n      \"name\": \"Writing Agent\",\n      \"title\": \"Content Writer\",\n      \"role\": \"Drafts content from research\",\n      \"model\": \"anthropic:claude-opus-4-5\",\n      \"reportsToKey\": \"researcher\"\n    }\n  ]\n}\n```\n\n`reportsToKey`\n\ngives you the hierarchy. For execution order, add a `pipeline`\n\nwith `dependsOn`\n\n:\n\n```\n{\n  \"pipeline\": [\n    { \"key\": \"step-research\", \"agentKey\": \"researcher\" },\n    { \"key\": \"step-write\", \"agentKey\": \"writer\", \"dependsOn\": [\"step-research\"] }\n  ]\n}\n```\n\nFor 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.\n\nWe 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.", "url": "https://wpnews.pro/news/we-built-an-open-schema-for-structuring-multi-agent-teams-here-s-what-we-learned", "canonical_source": "https://dev.to/ashconway/we-built-an-open-schema-for-structuring-multi-agent-teams-heres-what-we-learned-6k4", "published_at": "2026-06-17 22:21:29+00:00", "updated_at": "2026-06-17 22:51:55.983036+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models"], "entities": ["OpenEnvelope", "OpenAI", "Anthropic", "GPT-4o-mini", "Claude Opus 4.5"], "alternates": {"html": "https://wpnews.pro/news/we-built-an-open-schema-for-structuring-multi-agent-teams-here-s-what-we-learned", "markdown": "https://wpnews.pro/news/we-built-an-open-schema-for-structuring-multi-agent-teams-here-s-what-we-learned.md", "text": "https://wpnews.pro/news/we-built-an-open-schema-for-structuring-multi-agent-teams-here-s-what-we-learned.txt", "jsonld": "https://wpnews.pro/news/we-built-an-open-schema-for-structuring-multi-agent-teams-here-s-what-we-learned.jsonld"}}