Team engineering for AI agents
Each agent is a text file of plain instructions. A team is a folder. One more file, the chair, says who speaks when. TeamRunner runs the team, keeps every word, decision and cost, and lets you change one line and run it again.
Mac, Windows and Linux. OpenAI, Anthropic, Gemini, OpenRouter, or free local models through Ollama. No code.
Five text files → a running team example: multi_agent_debate
Two debaters argue a topic for three rounds, then a judge decides. The whole flow is two lines of chair.md. Rehearse it for free, watch a real run we recorded on Claude Opus 5.5, then add a fact checker: one new file and a few new lines in chair.md, and the flow redraws.
# Three rounds, each side speaking in turn, # then the judge decides. rounds(*3) -> judge rounds = for -> against
Recorded run
Now it’s an experiment. Does fact-checking change who wins, or only make the debate longer and costlier? In our six recorded runs on the motion “Splitting AI work into clear roles makes it safer and easier to audit and improve than one prompt doing it all”, for won two of three plain debates but only one of three checked ones; the replay shows one of each. The fact checker never failed a speech, and the checked debates cost about twice as much. Three runs each is too few to call it. Would your model agree? Run each version a few times and compare: that is tutorial step 8, on a real question.
Why a team, and not one big prompt?
A single agent with every instruction, every tool and every document piles it all into one prompt. Splitting the work across agents lets you give each one a narrow job, the right model, only the tools it needs, and a place in a flow you can read. Each reason below comes with the organizational idea it borrows and the research behind it.
01
A job description, not “other duties as assigned”
Each agent’s file holds one objective in plain words. A fact checker that only checks facts can’t drift into arguing, and its instructions are short enough to read, test and fix on their own.
Anthropic’s research agent splits work across subagents with “clearly divided responsibilities”: How we built our multi-agent research system, 2025.
02
A briefing, not the whole archive
Models get less reliable as their input grows, even on simple tasks, and miss what sits in the middle of a long prompt. In a team each agent carries only its own instructions, and a tool’s answer goes only to whoever asked: a 20,000-character web page the fact checker reads never lands in the debaters’ prompts.
Context Rot, Chroma, 2025, 18 models; Lost in the Middle, Liu et al., 2023.
03
You don’t staff every desk with a senior partner
The team names one model in team.yaml, and any agent can name its own with a model: line. Put the judge on a strong model and the drafters on a cheap or free local one, or mix providers in one team.
Sending only the hard calls to the strong model cut cost by over 2× with little loss in quality: RouteLLM, Ong et al., 2024.
04
A budget line for each department
Every turn records its tokens and cost, by agent. Every loop must carry a count, so a run always ends. A toolkeeper caps calls per turn. A missing key stops the run before anything is spent, and a rehearsal costs nothing at all.
Teams of agents can burn through tokens fast, and token use alone explained 80% of the variance in Anthropic’s results, so measure it: Anthropic, 2025.
05
The tool crib, not a power drill on every desk
Agents never hold tools. A toolkeeper does, with a plain access list: who may use it, how often, with what limits. The sandbox runs Python with no internet. TeamRunner enforces the terms, not the agent’s good behaviour.
Least privilege for agents is the standard fix for “excessive agency”: OWASP Top 10 for LLM Applications, LLM06, 2025.
06
The meeting rules, written down
Who acts next is a script in chair.md, drawn as a diagram. Decisions are typed answers, like pass or fail, and there are no hidden if-statements. To change how the team works, you change a line.
Most failures of multi-agent systems trace to how the system is designed, specs and hand-offs, not only to the model: Why Do Multi-Agent LLM Systems Fail?, Cemri et al., NeurIPS 2025.
07
Separation of duties: the writer isn’t the editor
The agent that makes a claim isn’t the one that checks it. A fact checker can send a speech back; a judge hears both sides and the checker’s verdicts before ruling.
Models that debate and check each other got more factual and reasoned better: Improving Factuality and Reasoning through Multiagent Debate, Du et al., 2023.
08
Need to know
A fact can live in one member’s own file, so only that member knows it until they choose to share it. That is how the hiring committee below works. Sealing whole conversations from some members is coming next.
The classic hidden-profile study of groups: Stasser & Titus, 1985.
09
Minutes for every meeting
Each run keeps its own folder on your disk: every prompt and reply, every decision about who acts next, every tool call, the model that answered, tokens, time and cost. Compare two runs side by side. No agent can read or change the record.
You can only fix a hand-off you can see. Plain files, no dashboard to log in to.
10
Pilot it, then make it policy
A team isn’t automatically better than one agent; studies find the gains are often small. So treat the structure as a hypothesis: change one line, rehearse for free, run both versions a few times, and compare.
Gains over single agents “often remain minimal” on popular benchmarks: Cemri et al., 2025. That is the case for testing.
Tutorial
Each step starts from a working example and adds one idea. Follow it in your browser or in a terminal. Every step can be rehearsed for free before you spend anything; a real run costs a fraction of a cent.
round_robin and run it with no model.Rather not write files at all? Describe the team in a sentence and a model writes them for you: teamrunner new launch --describe "a PM pitches, an engineer and a designer push back twice, the CEO decides". It checks its own work and draws the flow.
The big example · hiring_committee
In 1985 Stasser and Titus showed that human groups mostly discuss what they all already know, and so miss the facts that would change their decision. It is one of the most replicated findings about how groups decide. With TeamRunner you can ask whether a committee of AI agents falls into the same trap, and what gets it out. It ships as an example, so you can run it today.
The committee is hiring a Director of Operations for a food bank. Everyone has read the same packet, which makes Avery look best. Each member also holds two facts the others don’t, written into that member’s own file.
Alone, each member would still choose Avery. With all six facts on the table, Blake is the clear choice.
chen.md reference calls
Avery Former manager would not say whether they would rehire.
Blake “The best operations person I have worked with.”
diaz.md finance office
Avery Part of one under-budget year came from a one-time grant.
Blake Cost per meal delivered fell 18% in two years.
okafor.md human resources
Avery Team turnover 28%, against 18% across the sector.
Blake Regular volunteers grew from 250 to 400.
A well-known fix from the research is to have everyone report what they know before anyone gives an opinion. In TeamRunner the way a meeting runs lives in one file, chair.md. Both versions are already written there. Put a # in front of one and take it off the other. Nothing else changes.
# is a note for people, and is not run.Every turn records whom each member would hire right now, so you can see when minds change and whose facts changed them. Models are random, so run each version more than once; teamrunner runs lists every run with the committee’s decision.
Running each version 25 times and getting one table is coming soon. Tutorial step 8 does it by hand today.
teamrunner new open --from hiring_committee
teamrunner new share_first --from hiring_committee
# swap the line in share_first/chair.md, then:
teamrunner run open
teamrunner run share_first
teamrunner runs open
teamrunner runs share_first
All six examples
Copy one by name and it is yours to change: teamrunner new my_team --from fact_checked
round_robinThe simplest team: three members and no chair, one turn each in name order, and a typed verdict.
multi_agent_debateThe debate at the top of this page: a chair, with a repeated block of rounds.
fact_checkedThe debate with a fact checker that reads the web, and a Python sandbox to check the sums.
hiring_committeeThe committee above: facts only one member knows, kept in that member’s own file.
orchestrators_liteFive engineers review code against planted bugs, sharing one model profile.
reference_checkChecks every reference in a paper: that it exists, that its details are right, and that it says what the citing sentence claims.
What’s coming
Nothing on this list is in TeamRunner yet, and none of it is in the tutorial. What you build today keeps working as these arrive.
One file names the versions to compare and how many runs of each. TeamRunner runs them all, seeded, and gives you one CSV for R, Stata or pandas.
Seal reviewers from each other, or pass work along a chain where each person hears only the one before. One line each, in a whiteboard file.
An AI that runs the meeting and decides who speaks next, in place of a fixed script, so script vs. judgment can itself be compared.
A folder inside a folder: a subcommittee that deliberates on its own and reports back, so the org chart is the directory tree.
base: ../hiring_committee
factors:
meeting:
- {label: open, patch: {}}
- label: share_first
patch:
chair: file:variants/share_first.md
replications: 25 # 25 runs of each version, 50 in all
seed: 42
This opens an email to hello@teamrunner.ai from your own mail app; we write back when there is news. Or watch the repository on GitHub for new releases.
Reference
During the preview, the full documentation is the README on GitHub. This site will take over more of it.
teamrunner --help, or --help after any commandGlossary
chair.md: the meeting’s script, saying who speaks when. With no chair, members take one turn each, in name order.--- lines at the top of an agent’s file..md. An agent is one.name: value per line. team.yaml is one.