Build a research agent with CrewAI

Install

pip install crewai crewai-tools httpx

Already have CrewAI wired up? TheCrewAI integration pagehas the connection config on its own — this page assumes you have it and gets on with building.

Step by step

1. 1

   Write the tool

   CrewAI tools subclass BaseTool with a Pydantic args schema. The description is what every agent in the crew reads.

   import os, httpx
   from typing import Type
   from crewai.tools import BaseTool
   from pydantic import BaseModel, Field
   
   
   class SearchInput(BaseModel):
       query: str = Field(description="What to search for")
       min_sources: int = Field(default=2, description="Independent sources required")
   
   
   class UnlobSearch(BaseTool):
       name: str = "web_search"
       description: str = (
           "Search the web on unlob's own index. Returns metadata only — url, "
           "title, snippet and independent_sources. Never returns page bodies."
       )
       args_schema: Type[BaseModel] = SearchInput
   
       def _run(self, query: str, min_sources: int = 2) -> str:
           r = httpx.get("https://api.unlob.com/search",
                         headers={"x-api-key": os.environ["UNLOB_API_KEY"]},
                         params={"q": query,
                                 "min_independent_sources": min_sources,
                                 "limit": 8}, timeout=15)
           r.raise_for_status()
           return "\n".join(
               f"[{h['independent_sources']} sources] {h['title']} — {h['url']}\n  {h['snippet']}"
               for h in r.json()["results"]
           )

2. 2

   Give the crew two roles

   A researcher gathers and a fact-checker challenges. The second agent is the point — it re-queries with a higher corroboration floor rather than trusting the first.

   from crewai import Agent, Task, Crew, Process
   
   search = UnlobSearch()
   
   researcher = Agent(
       role="Research analyst",
       goal="Find what is actually known about {topic}, with sources",
       backstory="You search before you assert, and you keep every URL.",
       tools=[search],
       llm="claude-opus-5",
   )
   
   checker = Agent(
       role="Fact checker",
       goal="Find claims that rest on a single source and flag them",
       backstory=(
           "You are sceptical by default. You re-search each claim with "
           "min_sources=3 and report what fails to corroborate."
       ),
       tools=[search],
       llm="claude-opus-5",
   )

3. 3

   Wire the tasks so the checker sees the findings

   This is the step that makes the crew worth having. Passing the first task in the second task’s context is what hands the researcher’s output to the fact-checker — omit it and the checker verifies nothing while appearing to work.

   from crewai import Task, Crew, Process
   
   gather = Task(
       description="Research {topic}. Return findings, each with its URL.",
       expected_output="A bulleted list of findings, each ending with its source URL.",
       agent=researcher,
   )
   
   verify = Task(
       description=(
           "Take the findings and re-search each with min_sources=3. Mark any "
           "that fail to corroborate as UNVERIFIED and explain why."
       ),
       expected_output="The findings, each marked VERIFIED or UNVERIFIED with a reason.",
       agent=checker,
       context=[gather],   # <- without this the checker never sees the findings
   )
   
   crew = Crew(
       agents=[researcher, checker],
       tasks=[gather, verify],
       process=Process.sequential,
   )
   
   result = crew.kickoff(inputs={"topic": "EU AI Act GPAI rule changes in 2026"})

What happens when it runs

What will go wrong

The failures that cost an afternoon rather than a minute, because they produce something that looks like it is working.

• !

  Pass the first task in the second task's `context`, or the fact-checker never sees the findings and cheerfully verifies nothing.

• !

  `expected_output` is not decoration — CrewAI uses it to decide when a task is done. Vague wording produces agents that ramble past the point.

• !

  Two agents is two sets of model calls. The fact-checker earns its cost here because it re-queries at a higher corroboration floor; a second agent that only rephrases the first is pure overhead.

• !

  Role-play prompting does not add rigour by itself. The scepticism in this crew comes from `min_sources=3` hitting the API, not from the word "sceptical" in the backstory.