Envelope

Reading an Envelope Spec

An Envelope team definition is a single JSON file — usually named <team-name>.envelope.json — that describes everything about your AI agents: who the agents are, what they can do, how they relate to each other, and what external tools or secrets they require.

This guide walks through the structure so you can read a spec your PM exported and understand exactly what needs to be built or deployed.

File structure

{
  "_generatedBy": "Envelope · openenvelope.org",
  "name": "Support Triage",
  "description": "Routes inbound support tickets to the right queue and drafts initial responses.",
  "agents": [...],
  "requiredSecrets": ["ZENDESK_API_KEY"],
  "requiredVariables": ["SUPPORT_EMAIL"]
}

| Field | What it means | |-------|--------------| | name | The team's display name | | description | What the team does — written by the PM during design | | agents | The agent definitions — one object per agent | | requiredSecrets | Credentials the team needs at runtime (API keys, tokens) | | requiredVariables | Non-secret configuration values (URLs, email addresses, queue names) |

Agents

Each agent in the agents array represents one AI role in the team.

{
  "key": "triage-agent",
  "name": "Triage Agent",
  "role": "Reads inbound tickets and classifies them by priority and category.",
  "prompt": "You are a support triage specialist...",
  "capabilities": ["zendesk", "slack"],
  "reportsTo": "supervisor-agent"
}

| Field | What it means | |-------|--------------| | key | Stable identifier — use this when calling override APIs or setting credentials | | name | Display name | | role | One-line description of what this agent does | | prompt | Full system prompt for the agent's LLM | | capabilities | Tool categories this agent uses — maps to the credentials it needs | | reportsTo | Key of the supervising agent, if any — defines the reporting hierarchy |

Capabilities and tools

Capabilities like "zendesk", "slack", or "github" in the capabilities array signal which external services this agent connects to. They don't contain credentials — credentials are passed separately at deploy time.

The requiredSecrets array at the top level is the authoritative list of what credentials need to be provided before the team can run.

Reporting lines

If agents have reportsTo fields, the team has a hierarchy. The root agent (no reportsTo) is the entry point — it receives the initial input and coordinates the others.

A flat team (all agents with no reportsTo) runs agents in sequence or in parallel depending on the runtime.

Validating the spec

The spec validates against the public JSON Schema at https://schema.openenvelope.org/team/v1.json.

VS Code / JetBrains: Validation is automatic for *.envelope.json files via SchemaStore — no setup needed.

CLI (npm):

npx @openenvelope/schema validate ./support-triage.envelope.json

CI (GitHub Actions):

- name: Validate Envelope spec
  run: npx @openenvelope/schema validate ./*.envelope.json

Next steps

Once you've read the spec and understand what it needs:

  • MCP — paste the server URL into Claude or ChatGPT to run the team with zero infrastructure. See MCP host setup.
  • REST API — install and run the team via the Envelope API. See Deploying from a spec.
  • Git — check the file into version control alongside your other infrastructure. See Storing specs in Git.
‹ All guidesDocs ›