Build a research agent with OpenAI Agents SDK

Install

pip install openai-agents httpx

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

Step by step

1. 1

   Declare tools with @function_tool

   The decorator reads your type hints and docstring to build the schema, so an accurate signature is the whole job. Pydantic types work as parameters if you want stricter validation.

   import os, httpx
   from agents import function_tool
   
   API = "https://api.unlob.com"
   HEADERS = {"x-api-key": os.environ["UNLOB_API_KEY"]}
   
   
   @function_tool
   def web_search(query: str, min_sources: int = 2) -> list[dict]:
       """Search the web. Returns metadata only — never page bodies.
   
       Args:
           query: What to search for.
           min_sources: Require this many independent sources. Use 3 for facts.
       """
       r = httpx.get(f"{API}/search", headers=HEADERS, params={
           "q": query, "min_independent_sources": min_sources,
           "fields[]": ["url", "title", "snippet", "independent_sources"],
           "limit": 8,
       }, timeout=15)
       r.raise_for_status()
       return r.json()["results"]

2. 2

   Define the agent and run it

   Runner.run drives the loop. Everything it does is captured in a trace you can open afterwards, which is the feature that makes this SDK pleasant to debug.

   from agents import Agent, Runner
   
   agent = Agent(
       name="Researcher",
       instructions=(
           "Search before you answer. Prefer claims carried by several "
           "independent sources, and say so when a claim rests on one. Cite URLs."
       ),
       tools=[web_search, assemble_context],
   )
   
   result = await Runner.run(agent, "What changed in the EU AI Act in 2026?")
   print(result.final_output)

3. 3

   Make failures survivable

   A tool that raises ends the run. Catching the error inside the tool and returning it as a string gives the model something to work with — it can retry with a different query, or tell the user what went wrong, instead of the whole agent dying on a transient 503.

   @function_tool
   def web_search(query: str, min_sources: int = 2) -> list[dict] | str:
       """Search the web. Returns metadata only — never page bodies.
   
       Args:
           query: What to search for.
           min_sources: Require this many independent sources. Use 3 for facts.
       """
       try:
           r = httpx.get(f"{API}/search", headers=HEADERS, params={
               "q": query, "min_independent_sources": min_sources,
               "fields[]": ["url", "title", "snippet", "independent_sources"],
               "limit": 8,
           }, timeout=15)
           r.raise_for_status()
       except httpx.HTTPStatusError as e:
           if e.response.status_code == 429:
               return "Rate limited. Wait a moment, then try a narrower query."
           return f"Search failed with {e.response.status_code}."
       except httpx.RequestError as e:
           return f"Search unreachable: {e!r}"
   
       results = r.json()["results"]
       if not results:
           # An empty result is information, not an error. Say so, or the model
           # will assume the tool is broken and keep calling it.
           return f"No results for {query!r} at min_sources={min_sources}. Try lowering it."
       return results

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.

• !

  The docstring Args block becomes the parameter descriptions in the tool schema. Skip it and the model gets untyped, undescribed arguments and guesses — most often by passing a whole sentence as `min_sources`.

• !

  Runner.run is async. Calling it from a synchronous script without asyncio.run gives you an un-awaited coroutine and an agent that appears to do nothing.

• !

  Tracing is on by default and uploads run data to OpenAI. Disable it explicitly if your queries are sensitive.

• !

  A tool that raises will end the run. Catch httpx errors inside the tool and return a short error string instead, so the model can retry or explain rather than crashing the agent.