Sub-agent design: the five components every agent needs

Quick answer

Every sub-agent in a multi-agent system needs five things: a role that defines its responsibility and scope, skills that contain the instructions and rules it runs on, a model assignment that matches its capability needs to cost, tools that define what external systems it can access, and handoffs that specify how it connects to the agents around it. Get all five right on paper before any code runs.

Role

The role is the most important and most frequently underdone component. It does two things: it tells the agent what it is responsible for, and it tells the system where this agent ends and the next one begins.

A weak role definition is a job title: "You are a research agent." A strong role definition specifies responsibility, scope, and boundary:

You are a Research Specialist. Your job is to find and summarise publicly available information about a given company — founding date, headcount, funding history, recent news, and key product lines. You do not score or qualify the company; that is the Scorer's responsibility. You do not reach out to the company; that is the Outreach Specialist's responsibility. Your output is a structured research brief that the Scorer will use.

The boundary language is not optional. Without it, agents in the same system will overlap — both will attempt tasks that belong to the other, or neither will because each assumes the other has it covered. The stitching problem starts here.

A role definition should answer four questions:

1. What is this agent responsible for? One clear sentence.
2. What does it explicitly not do? Name the adjacent responsibilities it hands off.
3. Who does it report to? The coordinator or orchestrator above it.
4. What does a good output from this agent look like? A brief description of the deliverable it produces.

For a deeper treatment of role definition — including what makes a role strong versus vague — see what makes a good agent role definition.

Skills

If the role tells the agent what it is, skills tell it how to do it. This is the operational layer: the instructions, rules, SOPs, constraints, and heuristics the agent runs on when it works.

Skills are often written as a system prompt, but thinking of them as a prompt is the wrong frame. A prompt is usually written to get a good output on the first try. Skills are written to produce consistent output across many runs, under varying inputs, without supervision. The difference in approach is significant.

Strong skills documentation covers:

• Process steps — the sequence of actions the agent takes for its core task
• Decision rules — when to do X vs. Y, and what information drives that choice
• Quality criteria — what a good output looks like, and what disqualifies a result
• Edge cases — known situations that deviate from the standard path, and how to handle them
• Constraints — things the agent must never do, regardless of what it's asked

The level of specificity matters. An agent with underspecified skills will improvise in ways that make the system unpredictable. An agent with overspecified skills will fail on cases the spec didn't anticipate. The right level is: specific enough that the agent's behaviour on standard cases is predictable, flexible enough that novel inputs don't cause it to stall.

One practical rule: write skills as if you were handing off to a new employee on their first day, not briefing an expert colleague. The expert knows what you meant. The new employee does what you said.

Model

The model component specifies which LLM the agent uses. This is a design decision, not a default.

The instinct for most teams early on is to route everything to the best available model — usually the most capable frontier model. This is expensive, slow, and unnecessary. Most of the work in a multi-agent system does not require frontier-level reasoning. Much of it can be done faster and cheaper by a smaller model without any loss in output quality.

The right frame is to match model to task type:

In a five-agent content workflow, running the coordinator on a frontier model while the classifier and formatter use a smaller model can halve the per-run cost without changing the quality of the output a human sees. The savings compound at volume.

For a full treatment of how to approach model selection across an entire multi-agent team, see model routing in multi-agent workflows.

Tools

Tools define what external systems an agent can access — APIs, databases, email providers, CRMs, file systems, search. The tool component has two parts: what tools the agent has, and what the scope of each tool is.

Both matter. An agent that has access to the right tool but with the wrong scope is either underpowered (it can't do what you need) or over-privileged (it can do things you never intended). Tool boundaries are access policy.

A few rules that hold across most multi-agent designs:

Give each agent only what it needs for its role. An agent that sends emails does not need database write access. An agent that reads from a CRM does not need to write back unless its role explicitly includes updating records. Minimal tool access reduces the blast radius of errors and makes the system easier to audit.

Name what each tool can do inside the agent's context. The same API surface looks different to different agents. A CRM access tool for a Researcher means read-only lookup. The same CRM tool for an Outreach Specialist means read company data, write contact notes, and create tasks. Be explicit about the scope — don't rely on API permission settings alone to enforce it.

Treat third-party credentials as a shared resource that requires explicit policy. When an agent uses a tool that requires credentials — an API key, an OAuth token, a service account — that credential carries the permissions of the credential holder, not just the role of the agent using it. Design the access policy first, then wire the credential. For a deeper look at how credentials create trust boundaries across an agent system, credentials and trust in multi-agent systems covers this in detail.

Envelope's credential vault handles this separation: tools are granted to agents at the role level, and the vault manages the actual credential underneath without exposing it to the agent directly.

Handoffs

Handoffs specify how the agent connects to the rest of the system. There are two types, and they are different:

Reporting lines are hierarchical relationships. An agent reports to its coordinator or manager agent. The reporting line determines who orchestrates the agent, who receives its output, and who handles escalation when the agent can't complete its task. Reporting lines are represented as reportsTo in the Envelope schema. For more on what the coordinator role actually needs to do, do AI agents need managers? goes into the design of the oversight layer.

Pipeline dependencies are sequencing relationships. An agent has a pipeline dependency when it must wait for another agent to complete before it can start — because it needs that agent's output as input. Pipeline dependencies are represented as dependsOn. They say: don't start this agent until the named step is done and its output is available.

The distinction matters because they compose differently. An agent can report to a coordinator while having a pipeline dependency on a peer agent that also reports to the same coordinator. The coordinator manages the team; the pipeline manages the sequence.

When should you use dependsOn vs. letting agents run concurrently?

Use dependsOn when:

• Agent B needs Agent A's output as its primary input
• Running Agent B before Agent A would produce no useful result
• The ordering is structural, not just preferential

Let agents run concurrently when:

• Each agent has what it needs to start immediately
• The outputs are independent (they'll be combined later, not sequenced)
• Parallelism saves meaningful time and the coordinator can handle concurrent results

For most single-pipeline workflows, the sequencing is obvious. For more complex systems with branching paths and concurrent sub-teams, see parallel vs. sequential agents.

Putting it together: a worked example

A lead research agent on an outbound sales team, specified across all five components:

Role:

Lead Researcher. Responsible for researching inbound leads and producing a structured brief covering company size, industry, recent news, funding status, and primary pain signals. Does not score or qualify leads — that is the Scorer's responsibility. Reports to the Sales Coordinator.

Skills:

Search for the company's website and LinkedIn page first. Extract headcount from LinkedIn and funding history from Crunchbase if available. Identify any news in the last 90 days using a web search. Surface one to three pain signals based on recent news, job postings, or product announcements. Output must include: company name, headcount, funding stage, last funding date (if available), pain signals (1–3 bullet points), and source URLs. If you cannot find reliable data for a field, mark it as "not found" — do not estimate.

Model:

Claude Sonnet — research synthesis and summarisation do not require frontier reasoning; mid-tier is sufficient and meaningfully faster.

Tools:

Web search (read-only), LinkedIn lookup (read-only), Crunchbase lookup (read-only). No CRM write access — the Researcher produces a brief, not a CRM record. CRM write is the Outreach Specialist's responsibility.

Handoffs:

Reports to: Sales Coordinator. dependsOn: none (runs first in the pipeline after the Coordinator routes the lead). Downstream: Scorer receives the research brief as input.

Five components. One agent. Specified before any code runs.

This is the output that the design step produces. Once each agent in the team is specified this way, the full system is readable, auditable, and implementable without ambiguity in the handoff to engineering.

Where Envelope fits

Envelope is the tool where this design step happens. You describe what your workflow needs to do; Envelope structures each sub-agent with role, skills, model assignment, tool access, and handoffs defined — and exports the result as a .envelope.json file conforming to the open schema.

The design is the hard part. The code that executes it follows from the spec.

Design your AI agents in Envelope

Envelope turns a plain-language description of your workflow into a complete AI agent system — agents with named roles, model assignments, tool access, handoffs, and human review gates. Free to start, no code required.

Start designing →

Frequently asked questions

What are the five components of a sub-agent design?

Role (what the agent is responsible for and where it ends), skills (the instructions and rules it operates on), model (which LLM handles its task), tools (what external systems it can access and at what scope), and handoffs (how it connects to the agents around it via reporting lines and pipeline dependencies). All five need to be specified before building.

What is the difference between an agent's role and its skills?

The role defines what the agent is responsible for — its job, its boundary, and what it hands off. Skills define how it does that job — the process steps, decision rules, quality criteria, and constraints it follows. Role is identity and scope; skills are operating procedure. Both belong in the spec before a single line of code runs.

How do I choose which model to use for each agent?

Match model to task type. Coordinators and agents handling ambiguous reasoning benefit from frontier models (Claude Opus, GPT-4o). Drafters and researchers do well on mid-tier models (Claude Sonnet). Classifiers and formatters can often use smaller, faster models with no quality loss. Running every agent on the best model is the most expensive option, not the best one — see model routing for a full breakdown.

What is the difference between reporting lines and pipeline dependencies?

Reporting lines (reportsTo) are hierarchical — they define who orchestrates the agent and receives its output. Pipeline dependencies (dependsOn) are sequencing — they define which step must complete before this agent can start. An agent can have both: it reports to a coordinator and has a dependency on a peer agent's output. The two structures compose independently.

How specific should an agent's tool access be?

As specific as its role requires, and no more. Give each agent only the tools its role needs, and specify the scope of each tool explicitly — read-only vs. write, which records, which actions. Tool access is access policy. Over-permissioned agents expand the blast radius of errors and make the system harder to audit. Under-permissioned agents can't do their job.

Why does the boundary language in a role definition matter?

Because agents in the same system will overlap or gap without it. If a Researcher and a Scorer both have a role that doesn't explicitly exclude the other's responsibility, one of two things happens: both attempt the task (overlap, conflicting outputs) or neither does (gap, silent failure). The boundary language — "you do not score leads; that is the Scorer's responsibility" — is what prevents both outcomes.

Can I add tools to an agent later, after the system is built?

Yes, but each addition requires reviewing the agent's role and skills to check that the new tool access doesn't create conflicts with adjacent agents. Tool access is not just a technical setting — it's a statement about what the agent can do in the real world. Adding write access to a CRM for an agent that was designed as read-only changes its blast radius. Review the role and skills alongside any tool change.

How does Envelope export this design?

Envelope exports a .envelope.json file conforming to the open Envelope schema. The file encodes each sub-agent's role, prompt (skills), model configuration, tool access, reporting lines, and pipeline dependencies in a structured, version-controllable format that any conforming runtime can execute. The schema is open (Apache 2.0) and registered in SchemaStore. See the schema docs for the full specification.