Subagents are extra AI workers that handle focused parts of a larger task. The main agent assigns the work, brings the findings together and checks the result.
- Use them when useful work can happen independently, such as reviewing separate documents or investigating different causes of a bug.
- Keep one agent for a small task or when each step depends on the last answer.
- Keep someone responsible for checking the combined result. More agents do not guarantee a better answer.
Try it on a real task
Choose a task with two or more parts that can be investigated separately. Replace the brackets, then copy this prompt into an assistant that supports subagents. It asks for an investigation and recommendation before any changes.
Help me achieve [specific outcome] using [files, sources or project]. Preserve [important constraints]. Use subagents where independent work would help. Choose a small, useful division of work and give each agent a bounded assignment. Keep tasks with dependencies in the right order. For now, inspect and propose only; do not edit files or take external actions. Ask each agent for findings, supporting references and uncertainties. You own the final answer: check material claims, reconcile disagreements and give me one coherent recommendation. Say if delegation is unavailable.
How the work fits together
- Main agent assigns the workOne goal, clear questions and agreed boundaries.
- Subagents investigate separate questions
- BrowserWhat does the user see?
- ServerWhat does the system return?
- TestsWhich paths are covered?
- Main agent checks and combines the findingsResolve disagreements, verify the result and explain what is still unknown.
Three ways to put this to work
These are hypothetical examples, not client results. Start with the one closest to your task.
Investigate a checkout failure
Goal: Explain why some checkout attempts end without a clear confirmation.
- Bounded assignments: One agent traces the browser response handling. Another examines the server path and relevant, redacted logs. A third checks existing test coverage.
- Main agent: Establish the affected environment, align the timeline and check competing explanations.
- Useful outcome: A supported cause—or a clear list of evidence still needed—plus a proposed next step.
- Why it helps: Different parts of the same failure can be examined before choosing a repair.
Keep the initial investigation read-only. A request to diagnose checkout does not authorize charging a card or changing payment settings.
Compare products against the same requirements
Goal: Compare three booking tools for a small training business.
- Bounded assignments: Give each agent one product and the same questions about scheduling, exports, integrations and published pricing.
- Main agent: Check sources and dates, distinguish included features from paid additions, and compare against the actual requirements.
- Useful outcome: A consistent comparison with evidence, unknowns and relevant trade-offs.
- Why it helps: Product research can proceed separately while the decision criteria stay consistent.
Missing public information should remain unknown, rather than becoming a guessed feature or price.
Synthesize several documents
Goal: Prepare a briefing from a project proposal, meeting notes and a requirements document.
- Bounded assignments: One agent extracts commitments from the proposal. Another identifies decisions in the notes. A third maps requirements and unresolved questions.
- Main agent: Reconcile dates, definitions and contradictions across the documents.
- Useful outcome: One briefing with source locations and clearly unresolved conflicts.
- Why it helps: Focused reading reduces the amount of intermediate material the coordinator must handle.
Do not let the final summary silently choose between contradictory source statements.
Seven more situations to explore
Open an example to see the assignments, checks and expected result.
Review a code change from different angles
Goal: Find meaningful defects in a proposed account-settings change.
- Bounded assignments: One agent traces behavior changes. Another reviews access checks within the changed code. A third examines tests and missed cases.
- Main agent: Verify findings against the same version, remove duplicates and rank consequences.
- Useful outcome: A concise review with file references, failure conditions and uncertainty clearly stated.
- Why it helps: Separate review questions can improve coverage without asking every agent to repeat the entire review.
A security-focused review is scoped evidence, not a guarantee that the application is secure.
Implement separate parts of an agreed feature
Goal: Add an approved reporting feature with a clear interface between its parts.
- Bounded assignments: One agent owns the export component. Another owns the report-view component. Each receives the same agreed data contract and a distinct file list.
- Main agent: Own shared configuration, coordinate interface changes and run the integrated flow.
- Useful outcome: Components that work together and preserve existing behavior.
- Why it helps: Implementation can overlap after dependencies and ownership are clear.
If both agents need to change the same shared file, pause that overlap and assign one owner for the change.
Turn support conversations into product questions
Goal: Understand recurring problems in an approved, redacted set of support conversations.
- Bounded assignments: Agents review separate batches using the same categories, keeping conversation IDs with each observation.
- Main agent: Merge similar themes, check duplicate conversations and count unique reports consistently.
- Useful outcome: A source-linked list of recurring problems and questions worth investigating.
- Why it helps: The reading is divisible; the interpretation still has a single owner.
The supplied sample does not establish how common a problem is across all customers.
Prepare a useful resource article
Goal: Create a practical guide for a defined audience.
- Bounded assignments: One agent checks technical claims against primary sources. Another develops examples from the agreed outline. A later reviewer checks whether the assembled draft is clear and faithful to the brief.
- Main agent: Decide the structure, write a coherent article and resolve unsupported claims.
- Useful outcome: A reviewable draft with useful examples and linked evidence.
- Why it helps: Research and example development can overlap. Editorial review becomes useful once a draft exists.
The draft remains unpublished until publication is authorized.
Assess a business idea before committing to it
Goal: Decide what to learn before offering a new service.
- Bounded assignments: One agent reviews supplied customer evidence. Another maps delivery work and dependencies. A third challenges the assumptions behind the proposed offer.
- Main agent: Separate evidence from guesses and design a small next test.
- Useful outcome: A decision brief identifying what is known, what is uncertain and what would change the decision.
- Why it helps: Demand, delivery and assumptions are different questions that can be examined separately.
A convincing plan is not proof of demand, revenue or a workable delivery model.
Build an operational plan with explicit dependencies
Goal: Prepare an internal training day for a known group and budget.
- Bounded assignments: One agent drafts a session agenda. Another checks the supplied venue and accessibility requirements. A third prepares a materials checklist.
- Main agent: Align timings, identify dependencies and flag decisions needing a person’s approval.
- Useful outcome: One consistent plan with owners, dates and open decisions.
- Why it helps: Several planning streams can progress from the same brief.
Planning does not authorize booking a venue, sending invitations or spending the budget.
Verify a website change through different checks
Goal: Check an approved resource page before release.
- Bounded assignments: One agent checks content against the source draft. Another checks links and metadata. A third inspects a defined browser flow and narrow-screen layout in an assigned browser session.
- Main agent: Check the final version, resolve defects and distinguish local checks from any later live verification.
- Useful outcome: A handover that says what passed, what failed and what remains unverified.
- Why it helps: Different checks reveal different kinds of problems.
The checks must target the same final version. A screenshot from an earlier draft cannot verify the released page.
What is a subagent?
A subagent is an additional AI worker that the main agent starts for a particular job. It works with its own context—the information available to it—and returns a result. Depending on the system, it may also use tools, inspect files or make permitted changes. OpenAI’s Agents API describes this arrangement as separate agent contexts coordinated by a main agent. Agents API: multi-agent
Give each agent a clear question and ask for evidence you can check. A role name such as “security expert” does not establish expertise.
Separate working context also does not guarantee a separate workspace. For example, Agents API subagents share their session’s filesystem. Before allowing edits, establish who owns which files and how changes will be combined. Agents API: shared environment
How are subagents different from skills, hooks and separate chats?
On a narrow screen, scroll the table sideways to read every column.
| Concept | What it contributes | Example |
|---|---|---|
| Subagent | An additional worker with a bounded assignment | Investigate one possible cause of a checkout failure and return evidence |
| Skill | A reusable method, with instructions and supporting material | Follow a structured debugging workflow |
| Hook | A configured action connected to an event | Run a validation check at a supported point in the workflow |
| Separate chat you open | Another conversation that you manage | Explore a different product idea without making it a delegated part of this task |
A subagent can follow an available skill. A hook can supply a check or reminder at a configured event. These concepts describe different parts of the work; they are not interchangeable. See the official guides to skills and hooks.
Opening several chats yourself does not, by itself, make one chat their coordinator. For this guide, “subagent” means a worker delegated as part of the main task.
For a fuller comparison of workflows and event-triggered actions, read How to Choose Between Hooks and Skills for Your AI Agent.
Do you have to ask for subagents every time?
Not necessarily. Current local Codex documentation says delegation can follow a direct request or applicable AGENTS.md or skill instructions. A standing instruction can therefore remove the need to repeat the request. Available tools, configuration and higher-priority instructions still govern what happens. Do not assume that every complex task automatically triggers delegation. Codex subagent triggering
There are three practical ways to express your preference:
On a narrow screen, scroll the table sideways to read every column.
| Mode | What you provide | What the main agent decides |
|---|---|---|
| Delegation guided by standing instructions | A project rule asking for delegation when appropriate | Whether the current task benefits and how to divide it |
| Explicit request, flexible assignments | “Use subagents where they would help with this review” | The useful assignments, their order and the integration work |
| Explicit assignments | “One agent checks the UI path; another checks server logs” | How to carry out those assignments within the available tools and constraints |
A possible standing instruction is:
Use subagents when independent, bounded work would materially help. Keep small tasks and tightly dependent steps with the main agent. Give each subagent a clear scope, relevant context and expected evidence. The main agent checks material findings, integrates the work and verifies the final result. Do not expand the user's authorization by delegating.
This is an example instruction to adapt. It does not enable missing tools, change permissions or guarantee a particular number of agents.
A worked example of checkout failing
Suppose the report is:
“On mobile, checkout sometimes leaves people on a spinner.”
The main agent should first establish what the report actually means. Which environment? Which checkout path? Is there a known time, error or reproduction step? Is the request to investigate, repair or both?
Clarify the outcome before dividing the work. Delegation cannot fill in missing user intent reliably.
For this example, assume the agreed task is a read-only investigation using the repository, existing test results and redacted logs. No live purchase is permitted.
On a narrow screen, scroll the table sideways to read every column.
| Owner | Assignment | Evidence to return | Boundary |
|---|---|---|---|
| Main agent | Define the failure and coordinate the investigation | Environment, reported steps, timeline and open questions | Own the conclusion; do not assume a repair is authorized |
| UI investigator | Trace how checkout handles success, failure and delayed responses | Relevant code locations and paths that leave the spinner active | No source edits or live purchases |
| Server investigator | Trace the endpoint and examine the supplied logs | Matching timestamps, status codes and supported explanations | No production changes or exposure of private customer data |
| Test reviewer | Inspect coverage of the reported path | Existing cases, uncovered branches and proposed reproduction checks | No fixture or expectation changes to make tests pass |
Illustrative findings: The UI investigator finds a branch that leaves the loading state active after an unsuccessful response. The server investigator finds an unsuccessful response near a reported incident, but cannot establish that it was the same attempt. The test reviewer finds that the relevant UI test covers only success.
Those findings support a possible explanation. They do not yet prove that the reported customer failure followed that path.
The main agent should:
- Read the identified code and check whether the findings refer to the same version.
- Record the missing link between the log entry and the reported attempt.
- Propose a controlled reproduction with a simulated unsuccessful response.
- If repair is authorized, assign the smallest relevant change to one owner.
- After the change, rerun the affected test and exercise the relevant browser path in the approved environment.
- Report separately what was reproduced, what was changed and what remains unverified in production.
A useful final statement might be:
“The controlled test reproduced a spinner that never cleared after an unsuccessful response. The repair now shows a retry message in that test and in the local browser check. We have not yet established whether this explains the reported production incident.”
Passing tests is not proof of live customer success. Several agents agreeing is not independent verification if they all rely on the same unverified assumption. Different roles help only when their work adds checkable evidence.
Six more prompts for specific tasks
Already tried the starting prompt? Choose one of these when you know how you want to divide the work. Replace the brackets with your details.
2. Compare products consistently
Compare [products] for [use case] against [requirements and budget]. Use one subagent per product where practical, all using the same criteria. Read current official documentation. Return source links, dates checked, relevant plan limits and unknowns. Do not sign up, contact vendors or buy. As the main agent, verify the important differences and produce one comparison table. Explain which trade-offs matter to my requirements. Do not recommend a product on the strength of an unsupported claim.
3. Investigate checkout without changing it
Investigate [checkout symptom] in [environment] using [repository, redacted logs and existing test results]. This is read-only diagnosis. Delegate UI response handling, server/log analysis and test-coverage inspection as separate bounded tasks. Give everyone the same reported steps, timeframe and version. Do not edit code, change payment settings, run a live purchase or trigger new transactions. Each agent should return evidence, possible explanations and missing proof. You check and combine the findings, then propose the smallest useful next check. Distinguish a plausible cause from a reproduced failure.
4. Review a code change with evidence
Review [branch or diff] against [base revision]. Do not modify files. Use separate subagents for behavior regressions, access-control risks within the changed code, and test gaps. Keep all reviews on the same diff. Each finding needs a file reference, a concrete failure condition and an explanation of its consequence. Mark uncertainty; do not invent findings. Wait for the reviews. As the main agent, check the evidence, remove duplicates and return a prioritized list. State the review's scope and any checks that could not be performed.
5. Combine documents without losing contradictions
Create a briefing for [audience and decision] from [documents]. Use only these materials and keep their contents within this workspace. Assign separate documents or clearly defined sections to subagents. Have each extract decisions, commitments, dates and unanswered questions, with page or section references. Do not edit the source documents. You own the synthesis. Check conflicting statements against the originals; do not silently resolve them. Return a concise briefing, a conflicts table and questions that need an owner. Do not send the briefing to anyone.
6. Produce content with a single editorial owner
Draft [resource] for [audience] to help them [specific outcome]. Use [approved brief, tone and source material]. Delegate primary-source checking and practical-example development as separate tasks. Once a draft exists, use a reviewer to check clarity and whether the claims are supported. Label hypothetical examples honestly. You own the structure and final voice. Resolve review findings, preserve the brief and save one reviewable draft at [destination]. Include source links beside factual claims. Do not publish, schedule or send the content.
7. Implement with clear file ownership
Implement [approved feature] in [repository], preserving [working behavior]. Use the agreed interface [reference] and acceptance checks [checks]. First inspect the current code. Delegate independent components only: - Agent A may edit [component A files]. - Agent B may edit [component B files]. - You, the main agent, own [shared configuration and integration files]. Each agent reports its changes, checks and unresolved issues. If it needs another owner's file or a changed interface, it must report the dependency before editing. Preserve unrelated work. Do not commit, push or deploy. After both assignments finish, review the combined changes and run the agreed checks, including the relevant user flow. Report the final result and any remaining evidence gaps.
File ownership is a coordination rule. Where stronger separation is needed, use supported workspace or permission controls; writing a boundary in a prompt does not enforce it technically.
When one agent is the better choice
More agents bring more work to coordinate. OpenAI’s Responses API guidance identifies independent work as a useful fit and highlights dependencies, shared writable state and extra token use as important trade-offs. Those are useful considerations when choosing a workflow; the API’s settings should not be assumed to apply to every product. Responses API: when to use multi-agent
On a narrow screen, scroll the table sideways to read every column.
| Situation | A sensible starting point | Reason |
|---|---|---|
| Correct one sentence or rename one label | One agent | Delegation overhead is likely to exceed the work |
| The next step depends on the previous discovery | One agent, or staged delegation | Later assignments do not yet have the information they need |
| Compare several substantial, separate sources | Focused subagents and one coordinator | Reading can be divided while criteria remain shared |
| Several agents would edit the same file, database or browser session | One owner, or properly separated work | Separate agent contexts do not prevent shared-state conflicts |
| Explore a sensitive or nuanced decision through conversation | Keep the main discussion together | Splitting it may lose meaning or interrupt useful clarification |
| One slow external service dominates the task | Check the bottleneck first | More agents may only create more waiting or duplicate requests |
| Implement independent components with an agreed interface | Bounded assignments plus integration | File ownership and a final combined check make the split workable |
Faster completion can still mean more total work
Subagents may reduce elapsed time when useful tasks overlap. They also consume tokens for their own instructions, reasoning, tool results and reports. The coordinator then needs to read and reconcile the results. Codex documentation explicitly notes the additional token use. Codex subagent availability and usage
Think about elapsed time and total work separately. A shorter wait does not establish a lower bill or a better answer. Cost depends on the product, models, tools and actual usage; there is no universal savings figure.
“Parallel” also does not mean everything starts at once. Capacity limits, tool access and dependencies can cause work to run in stages.
A practical workflow that keeps the work connected
- Define the result and boundaries. Say what you need, what must stay unchanged and which actions are allowed.
- Assign independent pieces. Give each worker the relevant sources, version, expected output and file ownership. Keep dependent steps in order.
- Choose suitable tools and models where supported. A short extraction task may need less reasoning than a difficult review. Local Codex supports model and reasoning settings for subagents. Codex model configuration
- Check and combine the findings. Read the evidence, resolve contradictions and bring the work into one answer.
- Verify the result. Try the finished artifact or user flow. Say which checks passed and what remains unknown.
Delegation does not expand authorization. Permission to research does not include publishing, sending messages, spending money or deleting data. Pass the same boundaries to each worker and use the available permission controls.
A reusable assignment template
Objective: [the result we need] Context: [sources, relevant decisions, environment and version] Preserve: [working behavior, facts or constraints] Assignment: [one bounded question or component] Allowed actions: [read-only, or exact permitted edits] Ownership: [files, tools or state this worker owns] Dependencies: [what must happen first; who owns shared changes] Return: [findings or artifact], [supporting evidence], [checks performed], and [uncertainties or blockers]. If the task requires work outside this scope, report it before proceeding. Main agent: [who checks the findings, integrates the work and verifies the final result]
Start with one useful delegation
Give one worker a clear assignment. Check whether its result helped you make progress. If it did not, improve the assignment before adding more agents.
Go back to the starting prompt and try it with a task you already understand.
Read the companion hooks and skills guide to decide whether you also need a reusable method or an event-triggered action. For help applying these ideas to a real workflow, explore AI consulting and training.