Multi-Agent Research Crew

This is a sketch (not the file you build later) showing the shape of a crew in CrewAI style: you declare each agent with a role and a one-line goal, then hand the whole team to a Crew that runs them. Read it as "here are four specialists and how they're wired together".

1. Each Agent(...) line creates one specialist. The role is its job title and the goal is its single responsibility in plain English — planner splits the question, researcher gathers evidence, critic checks it, writer synthesizes.
2. Only the researcher gets tools=[search] — it's the one that needs to look things up. The others reason over what they're handed. Giving each agent only the tools it needs is a safety habit.
3. Crew(agents=[...], process="sequential", ...) assembles the team and says run them in order: plan, then research, then critique, then write.
4. max_steps=20 is the leash — a hard cap on how many turns the crew may take, so it can't loop forever and run up cost. The comment calls this out.

Try this: This is the mental model for the rest of the page. As you build agents.py and crew.py, match each real function back to one of these four roles.

Before any agent code, you build an isolated workspace. A virtual environment (venv) is a private copy of Python just for this project, so the packages you install here can't clash with anything else on your machine. These are terminal commands — type them one line at a time.

1. mkdir -p research-crew/tests makes the project folder and a tests sub-folder in one go. cd research-crew steps into it so every later command runs in the right place.
2. python3 -m venv .venv creates the private Python in a hidden .venv folder. source .venv/bin/activate switches your terminal to use it — you'll see (.venv) appear at the start of the prompt. (Windows uses the .ps1 line instead.)
3. pip install pytest "anthropic>=0.40" downloads the two libraries you need: pytest to run the tests and anthropic for the optional real model call later.
4. pip freeze > requirements.txt writes the exact versions you installed into a file, so anyone (including future-you) can recreate the same setup.

What the output means: The Successfully installed anthropic-0.69.0 pytest-8.3.4 line confirms both libraries landed in your venv. The (.venv) prefix means the environment is active.

Try this: If you close the terminal and come back, re-run source .venv/bin/activate first — the venv isn't active until you activate it in each new terminal.

This file defines the crew's roles as plain functions and a fake LLM so the whole thing runs offline with no API key. The trick that makes it testable: every role takes a call argument, so a test can swap in its own scripted "model".

1. @dataclass class Finding defines a tiny record with two fields: a claim (something the researcher asserts) and the source text it supposedly came from. Keeping the source attached is what lets the critic check claims later.
2. mock_call(role, task) is a pretend model: given a role string it returns fixed, predictable output. Planner returns two sub-questions; researcher returns a Finding whose claim does appear in its source (so it's honest); writer joins the claims into a report string.
3. plan, research, and write are thin wrappers. Each just calls call("<role>", ...). The call=mock_call default means they use the fake model unless you pass a real one.
4. Because call is a parameter, a test can inject a fake researcher that lies — a claim whose words are NOT in its source — to prove the critic catches it (that happens in Step 4).

What the output means: Nothing prints yet — this file only defines the roles and the mock. The next file wires them into an orchestrator that actually runs them.

Try this: Read mock_call's researcher branch: the claim string is a substring of the source string. That's deliberate — an honest finding. Later you'll see a dishonest one where it isn't.

This is the heart of the project: the critic that verifies findings and the orchestrator that runs the four roles in order under a step cap. The single most important rule here — the writer only ever sees findings the critic approved.

1. MAX_STEPS = 12 is the hard cap on total agent turns across the whole run — the leash that prevents runaway cost or infinite loops.
2. critique(findings) is the safety gate. For each finding it checks whether the claim's text actually appears inside its source text (if f.claim.lower() in f.source.lower()). Supported claims are kept; unsupported ones are silently dropped. This is a simple stand-in for a real verifier.
3. run_crew(question, call) runs the pipeline in order: plan turns the question into sub-queries, the for loop calls research on each (counting a step each time and breaking if it hits MAX_STEPS), then critique filters, then write gets only the verified list.
4. It returns a dict summarising the run: the report, the verified findings, how many were dropped, and the total steps. The if __name__ == "__main__" block runs a demo when you execute the file directly.

What the output means: Running it prints the report plus a one-line summary — e.g. all findings verified, 0 dropped, 5 steps — proving the pipeline ran end to end within the cap.

Try this: Notice write(verified, call) is passed verified, never the raw findings. That one choice is what stops an unverified claim from ever reaching the report.

Six tests that prove the crew behaves — all offline, no API key, because the roles accept an injectable call. pytest treats every function named test_* as a test; assert means "this must be true, or fail".

1. test_planner_produces_subqueries runs the whole crew and checks it took some steps and produced a report — a basic end-to-end smoke test.
2. test_supported_claims_pass_critique feeds the critic an honest finding (claim "net 30" is inside "payment is net 30 days") and asserts it survives. test_critic_drops_planted_false_claim is the mirror: a planted lie whose claim isn't in its source must be dropped — this is the key safety test.
3. test_writer_only_sees_verified mixes one good and one bad finding and asserts only one passes. test_step_cap_not_exceeded checks the run stays within MAX_STEPS.
4. test_report_contains_only_verified_claims defines its own scripted call where the researcher returns one true finding and one lie, then asserts the word "lie" never appears in the final report and exactly one claim was dropped — an end-to-end proof the critic protects the output.

What the output means: All six report PASSED and pytest prints 6 passed. The planted-lie test passing is the headline: the critic really does catch a fabricated claim.

Try this: Temporarily break the critic in crew.py (e.g. always append(f)) and re-run — the two planted-lie tests should turn red. That's your safety net doing its job.

This shows how to go live: swap the fake mock_call for a real one that talks to Claude. Crucially, the orchestrator doesn't change at all — only the function that produces text is different.

1. client = anthropic.Anthropic() creates the API client; it reads your key from the ANTHROPIC_API_KEY environment variable automatically, so the key never appears in code.
2. ROLES is a dictionary mapping each role name to a system prompt — a one-line instruction that turns the same model into a planner, a researcher, or a writer. Specialization here is just a different prompt per role.
3. real_call(role, task) sends one message: it picks the system prompt with ROLES[role], passes the task as the user message, and returns the model's text (msg.content[0].text).
4. The final comment shows the payoff: run_crew(question, call=real_call) — the exact same orchestrator, now driven by a real model instead of the mock.

Try this: Because the mock and the real caller share the same (role, task) shape, you can flip between offline testing and live runs by changing one argument. That separation — logic vs. model — is the pattern to remember.