How to Build a Lead Qualification Agent (LlamaIndex and LeadOcean)

import os, time, httpx

BASE = "https://api.leadocean.io"
HEADERS = {"x-api-key": os.environ["LEADOCEAN_API_KEY"]}

class OutOfRecords(Exception):
    pass

def call(method, path, params=None, json=None, retries=3):
    for attempt in range(retries + 1):
        r = httpx.request(method, BASE + path, headers=HEADERS,
                          params=params, json=json, timeout=30)
        if r.status_code == 429 and attempt < retries:
            time.sleep(float(r.headers.get("Retry-After", 1)))
            continue
        if r.status_code == 402:
            raise OutOfRecords("LeadOcean records are spent. Stop and tell the user.")
        if r.status_code == 404:
            return {"success": False, "data": None, "note": "nobody matched"}
        r.raise_for_status()
        return r.json()

def size_list(titles: list[str], countries: list[str]) -> dict:
    """Free. Count people matching job titles and ISO country codes."""
    res = call("POST", "/v1/people/search",
               params={"count": "true"},
               json={"title": titles, "country": countries, "limit": 1})
    return {"total": res["meta"]["total"],
            "distinctCompanies": res["meta"].get("distinctCompanies")}

def search_people(titles: list[str], countries: list[str], limit: int = 10) -> list:
    """Spends 1 record per person returned. Max 10 per call."""
    res = call("POST", "/v1/people/search",
               json={"title": titles, "country": countries,
                     "limit": min(limit, 10)})
    return res["data"]

def enrich_person(person_id: str) -> dict:
    """Spends 1 record. Use only on people that pass the ICP check."""
    res = call("POST", "/v1/people/enrich",
               json={"person_id": person_id, "reveal_email": True})
    return res["data"] or {"note": "nobody matched"}

import asyncio
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

SYSTEM = """You qualify leads for an outbound team.
ICP: VP or Director of Sales, B2B software, 50 to 500 employees.
1. Call size_list first. If total is above 100,000, narrow the titles.
2. Call search_people once with limit 10.
3. Score each person 1 to 5 against the ICP using title and company.
4. Call enrich_person only for scores of 4 or 5, at most 3 people.
5. If a tool reports records are spent, stop and say so.
Return a table: name, title, company, score, reason, email status."""

agent = FunctionAgent(
    tools=[size_list, search_people, enrich_person],
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt=SYSTEM,
)

async def main():
    out = await agent.run("Qualify VP Sales titles in the US.")
    print(str(out))

if __name__ == "__main__":
    asyncio.run(main())

SPENT = {"records": 0}
BUDGET = 13

def guarded(fn, cost_of):
    def wrapper(*args, **kwargs):
        if SPENT["records"] >= BUDGET:
            return {"note": "run budget reached, stop calling tools"}
        out = fn(*args, **kwargs)
        SPENT["records"] += cost_of(out)
        return out
    wrapper.__name__, wrapper.__doc__ = fn.__name__, fn.__doc__
    return wrapper

search_people = guarded(search_people, lambda out: len(out))
enrich_person = guarded(enrich_person, lambda out: 1)

from llama_index.tools.mcp import BasicMCPClient, aget_tools_from_mcp_url

client = BasicMCPClient.with_oauth(
    "https://api.leadocean.io/mcp",
    client_name="Lead qualifier",
    redirect_uris=["http://localhost:3000/callback"],
    redirect_handler=lambda url: print(f"Sign in here: {url}"),
    callback_handler=lambda: (input("Paste the code: "), None),
)
tools = await aget_tools_from_mcp_url(
    "https://api.leadocean.io/mcp",
    client=client,
    allowed_tools=["leadocean_count_leads", "leadocean_search_leads",
                   "leadocean_get_lead"],
)
agent = FunctionAgent(tools=tools, llm=OpenAI(model="gpt-4o-mini"),
                      system_prompt=SYSTEM)

{
  "total": 129494,
  "totalIsExact": true,
  "totalAll": 350517,
  "distinctCompanies": 58121,
  "distinctCompaniesIsExact": false,
  "credits": 0
}

{
  "success": true,
  "data": [
    {
      "profile_data": { "...": "name, title, company" },
      "contact_data": { "has_email": true, "has_phone": false },
      "meta": { "source_ids": { "person_id": "1234567890" } }
    }
  ],
  "meta": { "count": 10, "limit": 10, "credits": 10, "nextCursor": "..." }
}