An Open Schema for AI Agents

Open a file called team.envelope.json in VS Code. Type an opening brace. Autocomplete appears — field names, descriptions, valid values, the full structure of an AI agent team.

You didn't install an extension. You didn't configure anything. It just works, because the schema is registered in SchemaStore, which VS Code ships with by default.

That's the moment we've been building toward.

Today we're announcing that the Envelope schema is registered in SchemaStore, published on npm as @openenvelope/schema, and live at schema.openenvelope.org.

The schema is an open JSON Schema (Apache 2.0) for defining AI agent teams. It covers everything you need to describe a working team: agents and their roles, how they delegate to each other, which tools and APIs they can call, what governance checkpoints require human approval, how runs are scheduled, and what secrets and variables get injected at deploy time.

You define it once in a .envelope.json file. Any compatible runtime can execute it.

Why a schema?

AI agent frameworks are proliferating fast. LangChain, CrewAI, AutoGen, LangGraph, Vertex AI — each has its own way to define an agent, its own wiring for multi-agent coordination, its own format for configuration. That's fine for the frameworks themselves. The problem is portability. A team built in one framework doesn't move to another. The definition is trapped.

A shared schema changes that. If your agent team is described in a standard format, any runtime that implements the schema can run it. The team travels — across environments, across platforms, across runtimes you haven't used yet.

This is the same move that made Dockerfiles useful. A Dockerfile describes a container without being tied to a specific host. You can run it anywhere Docker runs. The Envelope schema describes an agent team without being tied to a specific runtime. We run a managed runtime — but the schema is open, and anyone can implement it.

What's in the schema

A quick tour of what v1 covers:

Agents — each agent has a key, a name, a title, a role, a system prompt, and a model configuration. The prompt can reference secrets and variables using {{SECRET_NAME}} interpolation — values are injected at run time, never stored in the file.

Hierarchy — agents declare a reportsToKey to define supervisor/sub-agent relationships. The supervisor routes tasks to sub-agents as tool calls and synthesises the final response.

Access policies — each agent can declare exactly which hosts it's allowed to call. The runtime enforces this at the network level. An agent that tries to call a host not on its allowlist is blocked — not by the prompt, by the infrastructure.

Human gates — pipelines can include review checkpoints between steps. A gate pauses execution and routes records to a review UI. The pipeline continues only after a human approves. Gate types include decision, classification, content generation, and action.

Pipelines — ordered sequences of steps with dependency declarations. Steps can run in parallel or series depending on their dependsOn configuration.

Schedules, inputs, outputs, pricing — for teams that run on a cron, accept structured inputs, produce structured outputs, or charge deployers per run or per token.

The full reference is at schema.openenvelope.org.

SchemaStore

SchemaStore is the open-source registry that powers IDE schema support without extensions. If you've ever opened a package.json, a tsconfig.json, or a GitHub Actions workflow file and seen autocomplete — that's SchemaStore. It ships with VS Code, JetBrains, Neovim, and most other editors by default.

Getting registered there means anyone who creates a .envelope.json file gets autocomplete and validation immediately, in their existing editor, with no setup. It's the lowest-friction way we know to put tooling in developers' hands.

npm

The schema is also published as @openenvelope/schema on npm. If you want to validate .envelope.json files programmatically — in a CI pipeline, a build tool, a runtime implementation — you can import the schema and run it through any JSON Schema validator.

npm install @openenvelope/schema

import schema from "@openenvelope/schema";
import Ajv from "ajv";

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

What's next

We're building the registry and managed runtime at openenvelope.org — a place to publish, discover, and install teams built on the schema. Builders publish teams, deployers install and run them, and the schema is what makes a team portable between builders' intentions and deployers' environments.

If you're building multi-agent systems and have opinions on what the schema is missing, we want to hear them. There's an RFC process for proposing changes — RFC_PROCESS.md in the GitHub repo. The schema is v1 and we expect it to evolve.

The repo is at github.com/openenvelope/schema. The schema is at schema.openenvelope.org. The npm package is @openenvelope/schema.

Envelope is an open schema and managed runtime for AI agent teams. The schema is Apache 2.0. openenvelope.org

Frequently Asked Questions

What is the Envelope schema?

The Envelope schema is an open JSON Schema (Apache 2.0) for defining AI agent teams. It covers agents and their roles, delegation relationships, tool access, human approval gates, scheduling, and secrets injection. A .envelope.json file written to this schema can be run by any compatible runtime.

How do I use it in VS Code?

Open any file named *.envelope.json in VS Code and autocomplete works immediately — field names, descriptions, valid values. No extension, no configuration needed. The schema is registered in SchemaStore, which VS Code ships with by default.

Is it open source?

Yes. The schema is published under Apache 2.0. The npm package is @openenvelope/schema and the canonical reference is at schema.openenvelope.org.

What problem does a shared schema solve?

Without a schema, every AI agent framework uses its own format. A team built in LangChain can't move to CrewAI or AutoGen without being rewritten. A shared schema means the definition travels — across environments, platforms, and runtimes you haven't used yet.