How do you build a multi-agent workflow?

A multi-agent workflow is a program in which several AI agents, each set up for one job, work on the same task and pass their results along. An agent here is a language model with its own instructions and, often, its own tools, such as web search. Instead of asking one model to research, write and proofread in a single long prompt, you give each of those jobs to a separate agent and connect them.

The appeal is focus. A model with one job and short instructions is easier to test and easier to fix than a model juggling five jobs at once. The cost is coordination: someone has to decide which agent runs when and what each one receives. That "someone" can be another model or your own code, and the choice matters more than any prompt.

Two ways to connect agents

OpenAI's Agents SDK documentation, a Python library for building agents, describes two styles of orchestration, meaning the logic that decides which agent runs next.

The documentation notes that code-led flows are more predictable, and lists patterns such as chaining agents so one agent's output becomes the next one's input, and looping a worker with an evaluator until the work passes. For a first multi-agent project, start with code. You can see every hand-off, and a bug shows up in one place.

Anthropic's engineering team describes the model-led style in its own Research feature: a lead agent plans the work and starts several subagents that search in parallel, each with its own context window, then report back. It is powerful for broad research, but it also showed early mistakes such as starting 50 subagents for a simple question.

A worked example: research, write, check

The goal: given a short brief, produce a 300-word beginner article whose every fact can be traced to a link. Three agents share the work.

1. Researcher searches the web and returns facts, each with its URL, as structured data.
2. Writer turns those facts, and only those, into a draft.
3. Checker compares the draft with the facts and returns a pass or a list of problems.

Your code runs them in order. If the checker fails the draft, the writer gets the problems and tries again, at most twice. After that, a person reviews it.

from pydantic import BaseModel
from agents import Agent, Runner, WebSearchTool

class Notes(BaseModel):
    facts: list[str]           # one sentence each, ending with its URL
    open_questions: list[str]  # things the researcher could not confirm

class Review(BaseModel):
    passed: bool
    problems: list[str]

researcher = Agent(
    name="Researcher", model="gpt-5.4",
    instructions=("Find 5 to 8 facts that answer the brief. One sentence per fact, "
                  "ending with the URL you found it on. Put anything unconfirmed "
                  "in open_questions instead."),
    tools=[WebSearchTool()], output_type=Notes)

writer = Agent(
    name="Writer", model="gpt-5.4",
    instructions=("Write about 300 words for beginners using ONLY the facts given. "
                  "Explain every technical term. Keep each URL as a link."))

checker = Agent(
    name="Checker", model="gpt-5.4",
    instructions=("Compare the draft with the facts. List every claim that is not "
                  "supported by a fact, every missing link and every unexplained term. "
                  "Set passed to true only if the list is empty."),
    output_type=Review)

def run_pipeline(brief, max_revisions=2):
    notes = Runner.run_sync(researcher, brief).final_output
    facts = "\n".join(notes.facts)
    draft = Runner.run_sync(writer, f"Brief: {brief}\n\nFacts:\n{facts}").final_output
    for attempt in range(max_revisions + 1):
        review = Runner.run_sync(checker, f"Facts:\n{facts}\n\nDraft:\n{draft}").final_output
        if review.passed:
            return draft
        if attempt < max_revisions:
            fixes = "\n".join(review.problems)
            draft = Runner.run_sync(writer, f"Facts:\n{facts}\n\nDraft:\n{draft}\n\n"
                                            f"Fix only these problems:\n{fixes}").final_output
    return "NEEDS HUMAN REVIEW\n\n" + draft

print(run_pipeline("Explain what a heat pump is and how it works in winter."))

Three details make the hand-offs reliable. The researcher and checker use output_type, so they return fixed fields your code can read, not loose prose. The writer receives the facts again on every revision, so it never has to remember them. And max_revisions stops an endless argument between writer and checker.

What multi-agent workflows cost

Every agent call is a separate model request, and each one carries its own instructions and inputs. Anthropic reports that, in its data, agents used roughly four times the tokens of an ordinary chat, and multi-agent systems roughly fifteen times. A token is a small chunk of text, the unit APIs bill by. A three-agent chain with two revisions makes up to six calls per article, so log each call's token count from the first day.

Anthropic also warns that tasks in which every agent needs the same context, or where agents depend heavily on each other, such as most coding work, are a weaker fit. Multi-agent designs shine when work splits into independent parts.

How do you decide which agent does what?

Draw the line wherever a person would hand work to a different colleague. Each agent should own one kind of judgment: finding information, writing, or checking. If you cannot describe an agent's job, its input and its output in two sentences, it is doing too much, or the split is in the wrong place.

Give each agent only the tools its job needs. In the example, only the researcher can search the web; the writer and checker work purely from text they are given. That keeps the writer from slipping in unsourced facts and makes problems easy to trace to one stage.

Anthropic found that each subagent needs four things spelled out: an objective, an output format, guidance on which tools and sources to use, and clear limits on its task. Vague assignments led its agents to repeat each other's searches or leave gaps.

Finally, test each agent alone before you connect them. Feed the checker a draft with a planted error and confirm it fails the draft. When every stage works on its own, the chain usually works too, and when it doesn't, you know which link to open.