OpenAI Agents SDK Enrichment — Function Tools over RichAPI

import os, requests
from dataclasses import dataclass
from agents import Agent, Runner, function_tool

@dataclass
class EmailHit:
 email: str | None
 status: str | None
 found: bool
 note: str

@function_tool
def find_work_email(full_name: str, company_domain: str) -> EmailHit:
 """Find a verified work email for a person at a company.

 Args:
 full_name: The person's full name, e.g. "Jane Okafor".
 company_domain: Bare domain only, e.g. "acme.com". Not a URL.
 """
 r = requests.post(
 "https://api.richapi.ai/api/v1/email_finder",
 headers={"x-api-key": os.environ["RICHAPI_KEY"]},
 json={"full_name": full_name, "company_domain": company_domain},
 ).json()
 if not r.get("success"):
 tried = [a.get("status") for a in r.get("execution_log", [])]
 return EmailHit(None, None, False, f"Waterfall exhausted, sources returned {tried}. Nothing billed.")
 d = r["data"]
 return EmailHit(d["email"], d["status"], True, "5 credits")

agent = Agent(
 name="Account researcher",
 instructions="Research the account. Never invent a contact detail. "
 "If a lookup misses, say so and report what was tried.",
 tools=[find_work_email],
)
result = await Runner.run(agent, "Who runs engineering at acme.com, and what is their email?", max_turns=8)

The decorator reads the type hints and the Google-style docstring and builds a strict JSON schema from them. That is genuinely useful and also the thing people under-use: the Args: block is the only place the model learns that company_domain means acme.com and not https://acme.com/careers.

The note field is deliberate. It carries either the cost or the reason for the miss into the model's context, so the agent's summary can say "no email found, four sources returned no data" instead of quietly omitting the person.

Every run produces a trace with a span per tool call. Open a failed run and you see the arguments the model sent, which is how you find out it has been passing "Jane Okafor, VP Eng" as full_name for three weeks.

Pair that with what we return. A waterfall response includes execution_log showing who ran and what each returned. Put it in the tool's return value and the span shows both halves: what the model asked for, and what actually happened underneath.

We do not publish the source list. It changes, and a per-call record beats a marketing page either way.

Read-only lookups. No sending, no sequencing, no CRM app, no prospecting UI. A runaway agent costs you credits, not a customer relationship.

Siblings, from the integrations index: LangChain for typed chains, CrewAI for role-based crews, ChatGPT to test the prompt before you write any code, and agent-driven account research for the full recipe.

100 free credits, no card. Wire one function tool, run one agent, and read the trace.