Envelope

How agents are structured

Every Envelope team is built from agents. Each agent has a role, a set of instructions, a model, and a defined relationship to the others. Understanding how these pieces fit together is the key to designing teams that behave predictably.

The five components of an agent

Every agent in a team definition has five things that shape how it behaves at runtime.

1. Role — a short machine-readable description of what the agent does. The role drives automatic model selection and is shown in platform UIs. "Classifies inbound support tickets by urgency and category" is a role. "Support" is not specific enough.

2. System prompt — the agent's full instructions. This is what the agent knows: its context, its mandate, the tools it can use, and when to escalate. A well-written prompt is the difference between an agent that behaves predictably and one that improvises. The prompt is stored encrypted and is never shown to deployers.

3. Model — which AI model the agent runs on. Different agents in the same team can use different models. An orchestrating manager that plans and synthesises might use a frontier model; a classifier that routes tickets might use a fast, cheap one. Envelope auto-assigns models based on role keywords but you can override any agent.

4. Tools and access — the external services the agent can reach. Declared as capabilities (for credential mapping) and enforced by an access policy (the allowlist of permitted hosts). An agent with api.zendesk.com in its policy can call Zendesk; it cannot call anything else unless you explicitly allow it.

5. Reporting line — which agent this one escalates to. The reportsToKey field defines the supervision hierarchy. Root agents (no reportsToKey) receive work from outside the team or from the system trigger. Sub-agents receive delegated tasks from their supervisor and escalate decisions they can't make back up the chain.

Hierarchy vs. execution order

Two separate concepts are easy to confuse.

The reporting hierarchy (reportsToKey) describes authority — who delegates to whom, and who receives escalations. It is not a pipeline. A manager agent can invoke its sub-agents in any order, re-invoke them, or skip them entirely depending on what the run requires.

Execution order is determined by the agents themselves as they run. A root agent receives the initial input, reasons about it, and decides what to delegate and in what order. Sub-agents that don't depend on each other can run concurrently — the runtime handles parallelism transparently.

Gates add explicit, schema-declared checkpoints. A gate sits after a named step and requires human action before the next step runs. This is the right place to enforce a hard ordering constraint — "the send step cannot run until a human approves the draft step output" — regardless of what the agents themselves would do.

Input → Root Agent
         ├── delegates to Sub-Agent A (research)
         ├── delegates to Sub-Agent B (research, runs concurrently with A)
         └── receives both results, synthesises, passes to Sub-Agent C
                        ↓
              [Human Gate — review before sending]
                        ↓
              Sub-Agent C (send)

Flat vs. hierarchical teams

Flat teams — all agents at root level, no reportsToKey. The runtime runs them in sequence or in parallel. Best for simple pipelines with independent steps and no escalation logic.

Hierarchical teams — a root agent (manager) coordinates sub-agents. The manager decides delegation order, handles escalations, and can re-route based on intermediate results. Best for complex workflows, multi-step decisions, or any team where an agent might need to ask a peer for help.

Most real-world teams work better with a single root agent acting as coordinator. Multiple root agents can cause ambiguous routing — the runtime has to decide which one receives a given input.

Writing the reporting hierarchy in JSON

{
  "agents": [
    {
      "key": "manager",
      "name": "Research Manager",
      "role": "Coordinates the research team and synthesises final output.",
      "model": "openai:gpt-5.4",
      "prompt": "You are the Research Manager..."
    },
    {
      "key": "web-researcher",
      "name": "Web Researcher",
      "role": "Searches the web and extracts source material.",
      "model": "openai:gpt-5-mini",
      "reportsToKey": "manager",
      "prompt": "You are a web researcher reporting to the Research Manager..."
    },
    {
      "key": "analyst",
      "name": "Analyst",
      "role": "Synthesises research notes into a structured summary.",
      "model": "anthropic:claude-sonnet-4-5",
      "reportsToKey": "manager",
      "prompt": "You are an analyst reporting to the Research Manager..."
    }
  ]
}

manager is the root — no reportsToKey. web-researcher and analyst both report to manager — they can run concurrently within the same delegation step.

Where gates fit

Add a gates array at the team level to declare review checkpoints:

{
  "gates": [
    {
      "name": "review-summary",
      "type": "content_generation",
      "afterStep": "analyst",
      "triggersStep": "deliver",
      "trigger": "all_resolved",
      "onReject": "rerun"
    }
  ]
}

This gate pauses the run after the analyst step and requires a human to approve the output before the deliver step runs. If rejected, the analyst step re-runs with the reviewer's feedback as context.

→ Full human gates guide — trigger types, rejection paths, and reviewing in your workspace

Frequently asked questions

Can two agents run at the same time? Yes. Sub-agents that don't depend on each other's output can run concurrently within a single delegation step. The root agent delegates to both and waits for both results before continuing. Envelope's runtime handles parallelism automatically — you don't need to configure it.

What's the difference between a root agent and a sub-agent? A root agent has no reportsToKey — it receives the initial trigger input and coordinates the team. A sub-agent reports to another agent, receives delegated tasks, and escalates decisions it can't make back to its supervisor. A team can have multiple root agents, but most teams work better with one.

When should I use a gate vs. just an escalation in the prompt? Use a gate when you need a guaranteed hard stop — where it's not acceptable for the pipeline to proceed without human approval, regardless of what the agent decides. Use an escalation in the prompt ("escalate to the manager if X") for soft decision points that the agent can route autonomously. Gates are schema-enforced; prompt escalations depend on the model following instructions.

Does the reporting hierarchy control which model each agent uses? Partially. If an agent's role doesn't match any keyword pattern, its position in the hierarchy determines the default: root agents get a frontier model, leaf agents get an efficient model. An explicit model field in the definition overrides this entirely. See the model routing guide.

Can I change the team structure after publishing? Yes — click Create new version in the editor. This creates a draft you can edit and publish as the next version without affecting existing installs until deployers choose to upgrade. See the versioning guide.

‹ All guidesDocs ›