Envelope
‹ Docs

Export your spec

When your team design is ready, export it as a structured JSON file. This file is the deliverable — it's what you hand to your IT team, commit to Git, or paste into your MCP host.

How to export

In the builder, click Export in the top bar of the spec panel. The file downloads as <team-name>.envelope.json.

The export includes:

  • Team name and description
  • All agent definitions — names, roles, prompts, capabilities, and reporting lines
  • Required credentials list (requiredSecrets) — names only, no values
  • Required config variables (requiredVariables)

It does not include:

  • Any credentials or API keys you've stored in your workspace vault
  • Run history or chat messages
  • Draft or unsaved changes

What to do with the file

Hand it to IT or engineering. The file contains everything they need to implement or deploy the team. Point them to Deploying from a spec for implementation options.

Commit it to Git. The file is safe to version-control — it contains no secrets. See Storing specs in Git.

Run it via MCP. Paste https://mcp.openenvelope.org/api/mcp into Claude or ChatGPT to run the team directly from your AI tool — no engineering handoff needed. See MCP host setup.

File format

The export uses the open Envelope schema (Apache 2.0). Any tool that validates against https://schema.openenvelope.org/team/v1.json can read it.

{
  "_generatedBy": "Envelope · openenvelope.org",
  "name": "Support Triage",
  "description": "Routes inbound support tickets to the right queue and drafts initial responses.",
  "agents": [
    {
      "key": "triage-manager",
      "name": "Support Manager",
      "title": "Head of Support Triage",
      "role": "Receives inbound tickets, classifies by priority, and delegates to the right sub-agent.",
      "model": "anthropic:claude-sonnet-4-5",
      "prompt": "You are the Support Manager at {{companyName}}. Receive inbound Zendesk tickets, classify by priority (P1–P3), and delegate to L1 Agent for standard issues or directly resolve P1 escalations.",
      "capabilities": ["zendesk"],
      "accessPolicy": {
        "defaultAction": "deny",
        "rules": [
          { "host": "api.zendesk.com", "action": "allow" }
        ]
      }
    },
    {
      "key": "l1-agent",
      "name": "L1 Agent",
      "title": "First Line Support",
      "role": "Handles P2 and P3 tickets. Drafts responses and resolves within session.",
      "model": "anthropic:claude-haiku-4-5",
      "prompt": "You are an L1 support agent at {{companyName}}. Handle P2 and P3 tickets assigned by the Support Manager. Draft responses in Zendesk and resolve within the session. Escalate to the Support Manager if the issue is outside your authority.",
      "reportsToKey": "triage-manager",
      "capabilities": ["zendesk", "slack"],
      "accessPolicy": {
        "defaultAction": "deny",
        "rules": [
          { "host": "api.zendesk.com", "action": "allow" },
          { "host": "hooks.slack.com", "action": "allow" }
        ]
      }
    }
  ],
  "gates": [
    {
      "name": "review-customer-response",
      "type": "content_generation",
      "afterStep": "l1-agent",
      "triggersStep": "send-response",
      "fields": ["subject", "body"],
      "trigger": "all_resolved",
      "onReject": "rerun"
    }
  ],
  "requiredSecrets": ["ZENDESK_API_KEY", "SLACK_BOT_TOKEN"],
  "requiredVariables": ["companyName", "SUPPORT_QUEUE_EMAIL"]
}

Key fields in context:

FieldWhat it means
modelWhich AI model this agent runs on — can differ per agent
promptThe agent's system instructions — defines its behaviour and knowledge
reportsToKeySupervision hierarchy — which agent this one escalates to
accessPolicyWhich external hosts this agent can call at runtime
gatesHuman review checkpoints — pause the run until a person approves
requiredSecretsCredential names the team needs (never the actual values)

→ Full schema reference

Frequently asked questions

Can I edit the exported file manually? Yes — the .envelope.json file is plain JSON. Engineers often make small tweaks directly, especially when wiring credentials or adjusting prompts for a specific runtime. Validate the edited file against the schema before using it.

Is the format locked to Envelope? No. The Envelope schema is open (Apache 2.0) and published at schema.openenvelope.org. Any runtime that supports the standard can read and execute a agent spec without going through Envelope at all.

Does the exported file contain credentials or secrets? No. The file lists which credentials the agents require — by name — but never includes actual values. API keys and tokens stay in your Envelope vault and are injected at runtime by whichever platform runs the team.

What if my IT team doesn't know what to do with the file? Point them to Deploying from a spec — it's written for engineers and covers every implementation path including MCP, the REST API, and self-hosted runtimes.

‹ Back to docsGuides ›