Splitting work across agents

Who this is for and what you will be able to do

This article is for people who already use an AI coding assistant or an agent framework, and find that one long conversation has become hard to manage. It explains three ways to divide work across several agents: Claude Code subagents, the handoffs in the OpenAI Agents SDK, and the orchestrator-worker pattern in LangGraph. After reading it you should be able to create a first Claude Code subagent file, understand what a handoff does, and know where the context and token costs will limit you.

What each approach is

A Claude Code subagent is a specialized assistant for one type of task. Each one runs in its own context window with a custom system prompt, its own tool access and independent permissions, and returns only a summary to the main conversation.^[2] Claude Code also has built-in ways to run work in parallel. /batch splits one large change into 5 to 30 subagents, each isolated in its own worktree. claude agents opens agent view, and /tasks lists background items, including finished subagents.^[3] For larger jobs there are dynamic workflows. Claude writes a JavaScript script for the task, and a runtime executes it in the background at a scale of dozens to hundreds of agents per run. Because the script holds the loop, the branching and the intermediate results, Claude's context holds only the final answer.^[4] The bundled /deep-research <question> workflow is one example. It fans out web searches across several angles, cross-checks the sources, votes on each claim, and returns a cited report with the claims that did not survive cross-checking filtered out.^[4]

The OpenAI Agents SDK takes a different route. The README describes it as a lightweight yet powerful framework for multi-agent workflows that is provider-agnostic. It supports the OpenAI Responses and Chat Completions APIs as well as 100+ other LLMs.^[6] Its central idea is the handoff: one agent delegates a task to another, and the handoff is represented to the model as a tool. A handoff to an agent named Refund Agent is exposed as a tool named transfer_to_refund_agent.^[7] The SDK also offers agents as tools, where a manager keeps control through Agent.as_tool(). With handoffs, a triage agent routes the conversation to a specialist, which then becomes active.^[10]

LangGraph is a graph framework. Its documentation separates workflows, which have predetermined code paths that operate in a certain order, from agents, which define their own processes and tool usage.^[11] For work that can run side by side, LangGraph's Send API dynamically creates worker nodes, each with its own state. In the orchestrator-worker configuration, the orchestrator breaks a task into subtasks, delegates them to workers and synthesizes their outputs. ToolNode runs parallel tool calls automatically.^[11]

The three differ mainly in where coordination lives. A Claude Code subagent is started by the main conversation and returns a summary. An SDK handoff moves control: the new agent takes over and sees the entire previous conversation history.^[7] In LangGraph, coordination is written into the graph itself. Send runs the same node once per item when the number of items is known only at runtime, while Command updates state and chooses the next node in one return.^[13]

Preparation

Subagent files go in .claude/agents/ for the current project, or in ~/.claude/agents/ for all of your projects. There are other scopes as well, and when several define the same name, the higher-priority location wins.^[2]

The OpenAI Agents SDK needs Python 3.10 or newer. The README gives pip install openai-agents as the install command and says to set the OPENAI_API_KEY environment variable before running the examples.^[6]

LangGraph installs with pip install -U langgraph.^[12]

Plan for cost from the start. Running several sessions or subagents at once multiplies token usage.^[3] Each subagent also spends tokens of its own while it runs.^[2]

Step by step

1. Create your first Claude Code subagent. The official quickstart uses a user-level file at ~/.claude/agents/code-improver.md, with this content:^[2]

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Only name and description are required in the frontmatter. The Markdown body becomes the subagent's system prompt.^[2]

1. Keep the descriptions short. When the combined description fields of custom subagents exceed 15,000 tokens, Claude Code shows a startup warning with the total. The docs advise moving detail into each subagent's system prompt instead.^[2]

1. Choose cheaper models for simple tasks. The docs list routing tasks to faster, lower-cost models such as Haiku as one benefit of subagents. CLAUDE_CODE_SUBAGENT_MODEL sets a default model. Setting CLAUDE_CODE_SUBAGENT_MODEL_FORCE to 1 applies one model to every subagent, teammate and workflow agent.^[2] Claude Code charges by API token consumption, and /usage reports the API token usage in its Session block.^[5]

1. Read a handoff example. Install the SDK with pip install openai-agents, then read the minimal example from the official handoffs guide:^[7]

from agents import Agent, handoff

billing_agent = Agent(name="Billing agent")
refund_agent = Agent(name="Refund agent")

# (1)!
triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])

Here triage_agent receives the other two agents through its handoffs parameter, and handoff(refund_agent) wraps one of them so it can be customized. The handoff() function accepts options including tool_name_override, tool_description_override, on_handoff, input_type, input_filter, is_enabled and nest_handoff_history.^[7] The runner has three methods, Runner.run(), Runner.run_sync() and Runner.run_streamed().^[8]

1. Try a LangGraph subgraph. A subgraph is a graph used as a node in another graph. If the parent and the subgraph have different state schemas, call the subgraph inside a node through a wrapper function. If they share state keys, add the compiled subgraph directly with add_node.^[12]

Our practice

TellWorld's news update is one case of this kind of split. Each update divides searching into three areas, one subagent each: US and European model vendors; Chinese companies; and cross-company topics such as robotics, chips, policy, lawsuits and large deals.^[1] The three subagents run in the background. The main agent does not poll their output. It is notified when each one finishes.^[1] Its job is deliberately narrow. It assigns the work, receives the files, runs the pipeline scripts, and spot-checks the three to five most important entries by opening their sources.^[1]

A spot check of this kind is what the next case depends on. On 13 November 2026 a subagent reported that NVIDIA's CEO had resigned. The main agent fetched NVIDIA's own press release and confirmed the names and the date before accepting the entry.^[1]

Large backlog tasks go to WorkBuddy, Tencent's agent app, not to our subagents. The tasks are written as Markdown task sheets and tracked in a queue table. By November 2026 the queue listed 29 delivered tasks.^[1] WorkBuddy is told to read a feedback file before it starts each new file, and to carry out any pending instructions in it first. That lets the maintainer steer a long-running agent without stopping it.^[1]

Several agents can return the same entry, so the merge step is part of the design. When several files contain the same entry, the intake script merges their facts and renumbers the sources instead of keeping one copy.^[1]

This is our setup for our scenario: a few well-defined search areas, a short list of entries checked against their original sources, and a merge step at the end. It is not a general best practice.

Limits and common problems

• Subagent results return to the main conversation. Running many subagents that each return detailed results can use a significant amount of context.^[2]
• By default, when 20 subagents are running, spawning another with the Agent tool fails with Concurrent subagent limit reached. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS changes that limit. A subagent can by default spawn subagents of its own, up to three layers below the main conversation.^[2]
• Parallel subagents suit independent investigations. The docs say this works best when the research paths do not depend on each other.^[2]
• Foreground subagents block the main conversation until they finish. Background subagents run concurrently.^[2]
• A handoff stays within a single run. Input guardrails apply only to the first agent, and output guardrails only to the agent that produces the final output.^[7]
• The runner raises MaxTurnsExceeded when max_turns is exceeded. max_turns=None disables the limit.^[8]

Next steps

Read the Claude Code subagent documentation^[2] and the guide to running agents in parallel.^[3] Then read the OpenAI guide to agent orchestration^[10] and LangGraph's subgraph guide.^[12] Run one small job in each framework first, and check /usage before you scale up.^[5]