Most articles about AI agents explain the concept and stop. Setup Files work differently: each one publishes a setup we actually ran, with the real files, the real run, and the ways it fails. No theory without a transcript. This one covers agent teams: when one AI session dispatches others to work in parallel.
The situation
This week we needed to update two data-driven tools on this site in one afternoon. Our AI Subscription Plan Finder needed current prices for six providers we did not yet track, and our LLM Ranking Tool was missing Kimi K3, which had shipped the day before. Both jobs require web research against official sources, and both produce structured data.
One AI session doing all of that serially would spend an hour researching before touching a file, and every page it read would crowd its working memory. The right shape is a team: the main session keeps building while two specialist agents research in parallel and return structured results. This is the single biggest maximization unlock in both Claude Code and Codex: stop thinking of the AI as one worker and start thinking of it as a lead with staff.
The files
In Claude Code, a reusable agent is one Markdown file. Drop this in .claude/agents/ in your repo and the lead session can dispatch it by name:
---
name: fact-checker
description: Verifies claims against primary sources on the live web.
Use for anything involving current prices, product names, or release
dates. Returns structured JSON with a source URL per claim.
tools: WebSearch, WebFetch, Read
---
You verify facts. Today's date is provided by the system; your training
data may be stale, so NEVER answer from memory. Every claim you return
must come from a page you fetched during this run.
Rules:
- Prefer official sources (vendor pricing pages, docs, changelogs).
- If the official page cannot be fetched, use two independent secondary
sources and mark the entry "source_quality": "secondary".
- If something cannot be verified, say "unverified". Never guess.
- Your final message must be ONLY the JSON object requested, no prose.The agent file is only half of the setup. The other half is the dispatch prompt, and this is where most agent teams quietly fail. A vague dispatch ("research AI subscription prices") produces an essay. A contract produces data. Here is the shape of the actual brief we sent, trimmed for length:
Today is 2026-07-17. Do not answer from memory: verify every fact
with fetches against official pages, today.
CONTEXT: our dataset already covers [list of what we have].
TASK: research current US pricing for these missing providers:
1. Ollama (paid cloud tier; verify the current plan name)
2. Mistral Le Chat (all tiers)
3. ... [seven more, each named specifically]
For EACH plan return: provider, plan_name, monthly, annual_monthly,
min_seats, source_url (a page you actually fetched), verified date,
included (short capability strings), caution (one honest limitation).
If a provider has NO such plan, record that in "findings" rather
than inventing one.
Your final message must be ONLY:
{"plans": [...], "findings": [...], "fetch_log": [...]}Read the two files again and notice what they establish: fresh-data discipline, a source-quality ladder, permission to say "unverified", an exhaustive task list instead of a vibe, and a machine-readable output contract. That is the whole trick.
The run
Here is the shape of the actual session, annotated. Two agents launch in the background; the lead keeps working; results integrate when they land.
> Update both tools. Verify plans and models against official
sources before touching the data files.
# Lead session dispatches two agents in one message so they
# run concurrently, each with its own contract:
Agent 1: "Research AI subscription plans" [background]
Agent 2: "Research new LLM releases" [background]
# While they research, the lead keeps building: it verified a
# homepage fix in the browser and prepped the JSON schemas.
# Roughly six minutes later:
[notification] Agent 2 finished → kimi: {"official_model_name":
"Kimi K3", "release_date": "2026-07-16", "pricing": {"input": 3.00,
"output": 15.00}, "context_window_tokens": 1048576, ...}
[notification] Agent 1 finished → {"plans": [27 entries with
source URLs], "findings": ["DeepSeek: still NO paid consumer
tier...", "Ollama rename confirmed: Turbo is now Pro/Max..."]}
# Integration is now mechanical: validate the JSON, merge it,
# lint, reload the page, and confirm zero console errors.
> php -l ai-subscription-plan-finder.php
No syntax errors detectedThe result: both tools went from stale to verified-current in one afternoon, and the research never polluted the lead session's working memory. The agents returned data, not opinions, because the contract demanded data.
Same idea in Codex. OpenAI's Codex has both halves of this setup too. Reusable staff are subagents defined as TOML files in .codex/agents/, with the same required trio our Markdown file carries: a name, a description that says when to use it, and standing instructions. Parallel work runs through Codex cloud tasks, each in its own isolated environment, handed off from the CLI, ChatGPT, or straight from a GitHub pull request. Repo-level instructions live in AGENTS.md, the sibling convention to CLAUDE.md, and nest per directory in larger repos. The maximization rule is identical in both tools: parallelize only independent work, give each task a definition of done, and never let two agents edit the same files at once.
Where it breaks
- Agents answering from memory. An AI's training data is months old. Without the "verify with fetches, never from memory" rule, you get confident 2025 prices in a 2026 dataset. This is the number one failure and the reason our agent file leads with it.
- No output contract. Ask for research, get an essay. Ask for a JSON schema, get data you can validate. If you cannot machine-check the deliverable, you will hand-check it, which erases the time you saved.
- Unbounded scope. "Research everything about X" runs forever and returns mush. Our brief named nine providers. Agents excel at exhaustive lists and drown in open oceans.
- Trusting one source. Note the source-quality ladder: official page first, two agreeing secondaries as a labeled fallback. Our subscription agent hit exactly this: one vendor's site blocks automated fetches, and the entry ships with a caution saying so.
- Parallel agents, shared files. Two agents writing to one file is a race condition with extra steps. Research agents should return data and let the lead integrate. If agents must edit code in parallel, isolate each in its own git worktree.
Steal this
The dispatch checklist
Before launching any agent, your brief should contain all five. Ours do, and the two files above show where each lives:
- Date + freshness rule: "Today is [date]. Verify by fetching; never answer from memory."
- Context: what you already have, so the agent researches the gap, not the world.
- Exhaustive task list: named items, not themes.
- Output contract: exact JSON shape, with "final message is ONLY the JSON."
- Honesty valves: "unverified" is an allowed answer; negative findings go in a findings list.
Copy the fact-checker.md file above into .claude/agents/ in any repo and adapt the dispatch template to your domain: supplier price checks, competitor monitoring, inventory data verification. The pattern does not care that our example was AI pricing. If you want this wired into your actual business workflows, that is what we build.