How to write a good AI agent role definition

Quick answer

A good agent role definition describes the boundary of responsibility — what the agent owns, where it sits in the hierarchy, what it can and cannot access, and where human review fits. It is not a list of instructions. It is a position in a system, legible enough that anyone deploying the team can evaluate it on its own terms.

Most people building multi-agent AI systems start with prompts. They open a chat interface, describe what they want an agent to do, iterate on the wording until the output looks right, and call it done. This works for single-agent tasks. It breaks down at scale.

When you have multiple agents working together — a coordinator routing work, specialists executing it, a reviewer checking results before they go out — the system's behaviour depends not just on what each agent is told to do, but on how their responsibilities are bounded relative to each other. A prompt tells an agent what to do. A role definition tells the system where one agent ends and another begins.

The distinction matters because failure in multi-agent systems usually isn't a prompt quality problem. It's an overlap problem or a gap problem. Two agents trying to do the same thing. One agent picking up a task that was supposed to go somewhere else. A decision falling into the space between two agents with no clear owner.

Scope, not instructions

A role definition should describe the boundary of responsibility, not a list of instructions. There's a meaningful difference between telling an agent "write email drafts based on the research you receive" and telling it that its role is "content production — converting structured research into draft communications for human review."

The first is a task. The second is a position in a system.

Instructions tell an agent what to do in a given situation. Roles tell the system which situations belong to which agent. The coordinator shouldn't need to decide which specialist handles edge cases — the role definitions should make the routing deterministic.

Reporting structure as first-class design

In a team with more than two agents, hierarchy is not optional. Every agent should have exactly one parent — another agent that receives its output and decides what to do with it. Flat structures where multiple agents all report to nothing create coordination problems the system can't resolve.

This doesn't mean deep hierarchies are better. The most reliable pattern is a single coordinator with two to four specialists. The coordinator receives inputs, dispatches work, and assembles outputs. The specialists have narrow, well-defined functions. The coordinator doesn't try to do specialist work. The specialists don't try to coordinate.

When you draw the graph of your agent design and it looks like a net rather than a tree, that's a signal the role definitions need work. Net structures require every agent to understand the full system. Tree structures let each agent only understand its immediate context.

Capabilities as constraints

Declaring what an agent can do is easy. Declaring what it can't do is the part that matters.

An agent with access to email sending, database writes, and external API calls is an agent that can cause damage if something goes wrong. Restricting outbound access to only the hosts an agent legitimately needs — and explicitly denying everything else — makes the blast radius of a mistake smaller and makes the agent's behaviour more auditable.

An access policy that says defaultAction: "deny" with explicit allow rules for specific hosts is a stronger safety guarantee than the same agent with unrestricted access. The capability list tells you what the agent will try to do. The access policy tells you what the runtime will actually permit.

This is the part of role definition that most prompt-based systems skip entirely, because prompts can't express it. "Only call the Zendesk API" is a request you're making to a language model. defaultAction: "deny", rules: [{ host: "api.zendesk.com", action: "allow" }] is an enforcement constraint.

The human-in-the-loop placement problem

Good role definitions make explicit where human review fits. In most multi-agent pipelines, there's at least one step where the agent's output is high-stakes enough that a human should check it before the system acts on it. Email going out. Payments being initiated. Content being published.

The mistake is treating this as a runtime concern — something to add later, after the agents are working. It should be part of the role structure: this agent produces output that requires review before triggering the next step. The gate between them is part of the design, not an afterthought.

If you can't identify where the human checkpoints are when you're defining the roles, the system probably isn't ready to run unsupervised.

What good role definitions look like in practice

A well-defined role has:

• A title that describes position, not task (Head of Support, not Ticket Handler)
• A role type that signals function within the hierarchy (manager, specialist)
• Capability labels that say what this agent is good at (triage, escalation, outreach)
• An access policy that matches only what the agent needs to do its job
• A clear parent, or a clear indication it's the root of the hierarchy

A poorly-defined role has:

• Instruction-heavy prompt with no structure around it
• Overlapping capabilities with another agent in the same team
• Unrestricted outbound access because the builder didn't think about it
• No clear position in the hierarchy — or multiple agents all reporting to nobody

The test is simple: if you removed this agent from the team, would the gap in responsibility be immediately obvious? If yes, the role is well-defined. If you're not sure what would break, the role boundaries need more work.

Why this changes when multiple people are involved

Single-developer AI teams can get away with informal role definitions because one person holds the full mental model. When a team is published for others to install — when the builder and the deployer are different people — the role definitions have to stand on their own. The deployer reads the team's agent list and needs to understand what each agent does, what it can access, and where it sits in the workflow.

This is the real argument for explicit role definitions: they're not just a design tool for the builder. They're the contract the deployer is agreeing to when they install the team. A team with clear role definitions is a team the deployer can evaluate. A team with vague role definitions is one they have to trust blindly.

Trust is easier when the structure is legible.

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 is an agent role definition?

An agent role definition describes the boundary of an agent's responsibility — its scope, position in the hierarchy, capabilities, and access policy — rather than a list of instructions. It tells the system where one agent's job ends and another's begins.

How is a role definition different from a prompt?

A prompt tells an agent what to do in a given situation. A role definition tells the system which situations belong to which agent in the first place, making routing between agents deterministic instead of ambiguous.

Why does every agent need exactly one parent in a multi-agent team?

Flat structures where multiple agents report to nothing create coordination problems the system can't resolve. A single coordinator with a small number of specialists — a tree, not a net — keeps each agent's context and responsibility legible.

What should a good access policy for an agent look like?

A strong access policy defaults to deny and explicitly allows only the specific hosts or systems an agent legitimately needs. This makes the blast radius of a mistake smaller and the agent's behaviour auditable.

Where should human review fit in a role definition?

Human checkpoints should be part of the role structure from the start — not added later. If a role produces output that's high-stakes enough to need review, that gate belongs in the design, not bolted on after the system is already running.

Why do role definitions matter more when a team is published for others to install?

When the builder and the deployer are different people, the deployer has to evaluate the team based on its role definitions alone. Clear roles make a team's behaviour something a deployer can trust based on structure, not blind faith.