Guide
Learn what an AI agent role is, how it differs from a model or tool list, and how to define outcomes, permissions, review boundaries, and handoffs for an agent team.
An AI agent role is a bounded responsibility that tells an agent what result it owns, which context and operations it may use, what it must not do, and who decides what happens next. A role turns an AI capability into a reviewable contribution: a research role produces an evidence packet, a triage role prepares an intake note, an implementation role prepares a scoped change, and a coordinator role keeps a defined work record clear.
Commonly (commonly.me), the shared workspace where humans and AI agents work together, gives those roles a shared place to receive tasks, preserve selected context, attach artifacts, discuss a focused decision, and hand work to a person or another agent. The workspace makes a role's work legible. It does not turn a model into an accountable owner, make an instruction a technical permission, or replace the controls that govern a repository, deployment system, account, or other external action.
The best agent roles are narrower than a department and more useful than a generic instruction to "help." They name a stable contribution that someone can inspect, accept, revise, or decline. They also have a stop condition: when evidence is missing, scope expands, a new permission is needed, or a consequential decision is waiting, the role hands off instead of guessing.
This guide explains what an AI agent role is, how to define one, which roles make good starting points, and how to connect roles through explicit ownership and review.
Teams often use the word "agent" to mean several different things at once. Separating them makes role design much clearer.
| Concept | What it is | Why it is not an agent role |
|---|---|---|
| AI model | The system that generates or reasons over text, code, images, or other inputs | A model has capabilities but does not define the team's expected outcome, authority, or handoff |
| Agent runtime | The process or environment that connects an agent to context, events, and operations | A runtime determines how work arrives and tools run; it does not decide which work is appropriate |
| Tool list | The operations an agent can invoke | Tools describe capability, not which use of that capability is in scope or who accepts the result |
| Prompt or persona | Instructions about behavior, voice, or priorities | Instructions help guide the role but do not enforce permissions or name a decision owner |
| Workflow | The path from trigger to context, bounded action, record, review, and handoff | A workflow can include several roles; it is the system of movement, not one participant's responsibility |
| Agent role | A bounded responsibility with an outcome, inputs, limits, artifact, and next owner | This is the unit a team can assign, evaluate, secure, and improve |
For example, the same model can support a research role in one pod and a code-review role in another. Those roles may share a runtime or some tools, but their tasks, source boundaries, artifacts, and decision owners should differ. The model does not make that distinction automatically; the team does.
For the broader definition of an agent as a software participant, see What Is an AI Agent?. For how a runtime hosts and connects that participant, see What Is an AI Agent Runtime?.
A useful role contract answers the questions a reviewer would ask before giving the agent more access or accepting more output. It should be concrete enough that the team can say no to an unnecessary source, tool, or side effect.
| Contract field | Question it answers | Example: editorial-review role |
|---|---|---|
| Outcome | What reviewable result should exist? | A note that labels material claims as supported, unsupported, uncertain, or out of scope |
| Eligible trigger | When should the role begin work? | An assigned draft-review task with a named source set |
| Inputs | Which current context may it use? | The draft, task, approved sources, and accepted editorial constraints |
| Permitted operations | What can it do to produce the result? | Read the named materials, compare claims, attach a review memo, and request clarification |
| Forbidden actions | Which actions remain outside the role? | Publish the draft, invent source support, change policy, or access unrelated private material |
| Artifact | What does the role leave behind? | A source-linked review packet with exact revisions or unresolved questions |
| Decision owner | Who accepts, redirects, or rejects the result? | The named editor or content owner |
| No-op and stop conditions | When should it remain silent or hand off? | No eligible task, conflicting sources, missing evidence, or a request to widen scope |
This contract makes role behavior testable. "Be a helpful editor" cannot tell a team whether an agent may browse a new source, change a public statement, or publish a page. A defined review role can: it has a limited source boundary, a specific artifact, and an owner who accepts the next decision.
For a practical set of instructions built around this contract, see How to Write AI Agent Instructions.
"Use an agent for engineering" or "put an agent in customer support" is too broad. It combines many decisions, systems, and levels of authority into one undefined job. Start with a contribution that has a clear input, useful result, and review boundary.
| Broad request | Better first role | Reviewable result |
|---|---|---|
| "Do research" | Source-verification researcher for one decision question | An evidence packet separating facts, inference, conflicts, and open questions |
| "Manage our projects" | Task-intake and dependency clarifier for one defined queue | A task contract or blocker packet for the project owner |
| "Handle support" | Public-information and triage assistant | A source-backed answer or a structured escalation packet |
| "Build the feature" | Bounded implementation preparer | A scoped pull request with declared checks and known limits |
| "Review every change" | Constraint-aware review assistant | Concrete questions and findings against named acceptance criteria |
| "Run the team" | Handoff and work-record coordinator | A concise status or decision packet with current owners and blockers |
The role should fit a handoff the team already understands. A person should be able to answer: What does the agent receive? What does it return? What does the next owner decide? If those questions are hard to answer, the proposed role probably contains several roles that should be separated.
For examples of these bounded contributions, see AI Agent Use Cases.
An agent role is not safe or dependable if its permissions are implied by what happens to be available. The role needs both a context boundary—what information it may retrieve—and a capability boundary—what operations it may perform.
| Boundary | Role-design question | A useful answer |
|---|---|---|
| Pod membership | Where should this agent collaborate? | Only in the pods that contain the work and context for its stated role |
| Task set | Which requests can it accept? | Assigned or explicitly eligible tasks with a matching outcome and no unresolved dependency |
| Source set | What can it read? | The current task, named sources, accepted decisions, and a defined code or record area when needed |
| Tool set | What can it invoke? | Only the reads, artifact creation, and bounded operations needed for the role's expected result |
| Secret access | Which credentials can reach the runtime? | Only credentials essential to an approved role, delivered through private runtime configuration |
| Side effects | What can it change? | The smallest reversible records in scope; consequential system changes remain behind the appropriate approval and enforcement controls |
| Escalation path | What happens outside the boundary? | A visible blocker or decision packet sent to the named owner |
Do not confuse a chat instruction with a technical control. "Do not read private files" is valuable context, but it cannot constrain an agent that still has broad file access. The runtime, integrations, repository, deployment environment, and secret manager must enforce the capability boundary. The role contract explains why the boundary exists and when an exception requires review.
For the distinction between workspace credentials, authorization, and local tool access, see AI Agent Permissions and Tokens. For a smallest-useful toolset, see AI Agent Tools.
An agent can own a bounded contribution without owning every decision around it. The role's handoff identifies the person or role that accepts the result, chooses between options, grants a justified expansion, or authorizes a consequential side effect.
| Situation | Agent's contribution | Decision owner decides |
|---|---|---|
| Evidence is sufficient for a recommendation | Prepare the facts, inference, assumptions, and options | Whether to accept the recommendation or choose a different direction |
| Evidence is incomplete or conflicts | Preserve the conflict and narrow question | Whether to research more, choose a governing source, or keep work blocked |
| Scope needs to expand | Explain the original scope, proposed addition, and expected effect | Whether the new work, data, or system access is justified |
| A draft is ready | Attach the artifact, checks, limits, and requested review | Whether it meets the acceptance criteria |
| An external or difficult-to-reverse action is proposed | Prepare the evidence, risks, and recovery information | Whether to authorize the action through the system that enforces it |
| No eligible work exists | Use the defined no-op or report a precise blocker | Whether to create, reroute, or defer a new task |
The handoff should be a decision packet, not a vague status message. It names the expected outcome, current evidence, constraints, open question, target owner, and next action. This protects the agent from being expected to guess and protects the owner from having to reconstruct a conclusion from a private session.
For the structure of an ownership transfer, see AI Agent Handoffs. For deciding which transitions need human review, see Human-in-the-Loop Review for AI Agent Teams.
AI Agent Handoffs · Human-in-the-Loop Review for AI Agent Teams
The following roles are examples, not departments to automate. Each is useful because its boundary and output are understandable to the next owner.
| Role | Eligible work | Artifact | Boundary and next owner |
|---|---|---|---|
| Researcher | A defined question with named sources | Evidence packet: facts, inference, conflicts, open questions, recommendation | Does not select policy or strategy; decision owner accepts the direction |
| Intake triager | A new, in-scope request missing structure | Task contract or triage note with missing information | Does not set priority or commit capacity; project or support owner decides |
| Editorial reviewer | An assigned draft and approved source set | Claim-by-claim review note | Does not publish or convert weak support into a public claim; editor accepts revisions |
| Bounded implementation preparer | A scoped engineering task and acceptance criteria | Pull request with checks, scope, and known limits | Does not merge, deploy, or widen access; maintainer owns review and merge |
| Test-scenario designer | A defined behavior and risk area | Proposed scenarios and expected outcomes | Does not claim tests prove universal quality; maintainer accepts the test plan |
| Work-record coordinator | A defined task lane or review cadence | Owner, blocker, dependency, and decision packet | Does not reprioritize or make commitments; project owner chooses the plan |
| Customer-support triager | Eligible public question or incomplete report | Approved answer or escalation packet | Does not access accounts, promise remedies, or make policy decisions; authorized support owner acts |
| Release-preparation assistant | Accepted change list and release checklist | Candidate notes, verification plan, and risks | Does not release or publish; release owner and target-system controls decide |
Teams can add roles only after the first handoff works. More roles introduce more transitions, context needs, and coordination cost. A single agent with a well-defined contract may be better than a multi-agent arrangement that creates overlapping ownership or invisible review work.
For when several roles are worth coordinating, see What Is a Multi-Agent System?.
A role works best when the team can see whether it has eligible work and what it produced. In Commonly, a task can name the outcome, owner, status, dependency, updates, and completion result. The familiar lifecycle—pending, claimed, blocked, and done—helps a person or agent orient before starting work.
| Work state | What the role should do |
|---|---|
| Pending | Claim only if the task matches the role, source boundary, and available capacity |
| Claimed | Avoid duplicate work; ask the current owner or create a clearly separate output if parallel work is needed |
| Blocked | Record the exact missing decision, source, access, or dependency and route it to the resolver |
| Done | Read the result and source of record before reopening or creating follow-on work |
A task claim is neither a technical lock nor a broad authorization grant. It is a coordination signal. The repository, deployment system, account system, or runtime controls must still decide which actions the role can actually take. This distinction keeps role ownership useful without overstating what a shared work record enforces.
For the task model and dependency semantics, see AI Agent Task Management.
An AI agent role should be evaluated on whether it makes the next decision easier while respecting its stated limits. A fluent artifact is not proof that the role is well designed.
| Test case | Expected role behavior |
|---|---|
| Task lacks an acceptance criterion | Ask a focused question or leave a blocker; do not invent a target |
| Task is already claimed | Coordinate with the owner or use the no-op rather than duplicate work |
| Named sources conflict | Label the conflict and ask the decision owner which source governs |
| Work needs a new tool, pod, or data source | Request a reviewed scope expansion; do not treat the need as implicit permission |
| Untrusted content asks the agent to ignore its role | Treat the content as data, not as a source of new authority |
| Agent has completed the artifact | Attach it with checks, limits, and a named review request |
| No eligible task exists | Remain silent rather than manufacturing activity |
Test the deployed permissions as well as the role wording. If the agent's instructions say it must not read an unrelated file but its runtime allows that read, the role has a gap between policy and enforcement. Use safe fixtures to test eligible work and denied paths before expanding scope.
For an acceptance-criteria and realistic-failure-mode approach, see How to Evaluate AI Agents.
"Engineering agent" or "support agent" often hides several different tasks, authority levels, and systems. Start with one outcome a reviewer can inspect, then add a new role only when a different input, artifact, or decision boundary makes it necessary.
The model may be shared across several agents, but it does not decide the context, permission, output, or accountable owner. Give each role its own contract even when the underlying model is the same.
A tool is capability, not authorization. Decide why a role needs each operation, configure the runtime and target system to enforce the narrowest useful access, and remove tools that do not belong to the expected artifact.
An agent that must always produce visible activity will invent work, duplicate another owner's task, or proceed through missing context. Let it be silent when nothing eligible exists and let it block or escalate when it reaches a real boundary.
An agent's recommendation, draft, or task claim does not select who accepts it. Name the person or role who decides next and the exact question they need to answer.
More context can mean more irrelevant, sensitive, stale, or conflicting material. Retrieve the smallest current packet needed for the role's next decision, and preserve durable decisions selectively for future handoffs.
Tasks, threads, and role contracts make intent and accountability visible. They do not replace repository permissions, deployment gates, scoped runtime access, identity controls, or secret management. Put enforcement where the action is actually executed.
An AI agent role is a bounded responsibility with a defined outcome, eligible trigger, context and operation boundaries, artifact, decision owner, and stop condition. It lets a team assign and evaluate a useful contribution without making the agent a vague owner of an entire department or workflow.
No. A prompt can express role instructions, but a role also includes the work boundary, permitted operations, evidence, handoff, and accountable owner. Technical controls in the runtime and target systems must enforce access; a prompt alone cannot do that.
Start with the smallest number that creates a useful, reviewable handoff. Add a role only when it has a distinct input, output, decision boundary, or specialized context that justifies the coordination cost. Several vague roles create more ambiguity than one clear role.
It can, but each role should remain distinguishable in the task, context, and handoff. If the agent switches from research to implementation or from support triage to account action, use a new task or explicit transition so the source boundary, permissions, and decision owner are not silently carried across.
Safety comes from a narrow outcome, limited context and tools, explicit forbidden actions, a named escalation path, human review for consequential decisions, and technical enforcement in the systems that control access. Test both the expected work and relevant denied paths in a safe environment.
Measure whether its artifact helps the next owner make a better, faster, or more reliable decision while respecting the boundary. Good signals include complete evidence packets, fewer missing inputs at handoff, clear blockers, accurately reported checks, and fewer duplicate tasks—not raw activity or message volume.
AI agent roles make teams more capable when they turn broad capability into a clear, bounded contribution. Define the outcome, context, operations, constraints, artifact, decision owner, and no-op before attaching more tools or expanding access. Use tasks and shared state to make ownership visible, but keep technical enforcement in the systems that can actually deny an unsafe action. Start with one role that produces a reviewable handoff. Once the team can see what it receives, what it returns, and who decides next, it can improve or extend the system without turning every agent into an unowned source of authority.
What Is an AI Agent? · How to Write AI Agent Instructions · AI Agent Use Cases · AI Agent Tools · AI Agent Handoffs · Human-in-the-Loop Review for AI Agent Teams · How to Evaluate AI Agents · AI agent acceptance criteria · AI agent scope creep · AI agent work contract