How to Build a Lead Qualification Agent (With the Vercel AI SDK)

export LEADOCEAN_API_KEY="paste-your-key-here"

const BASE = "https://api.leadocean.io";
const KEY = process.env.LEADOCEAN_API_KEY!;
const RECORD_CAP = 20;            // hard ceiling for one run
let spent = 0;                    // records spent in this process

type Result = { data?: any; error?: string };

async function call(path: string, body: object, query = ""): Promise<Result> {
  for (let attempt = 0; attempt < 2; attempt++) {
    const r = await fetch(`${BASE}${path}${query}`, {
      method: "POST",
      headers: { "x-api-key": KEY, "content-type": "application/json" },
      body: JSON.stringify(body),
    });
    if (r.status === 429 && attempt === 0) {
      const wait = Number(r.headers.get("retry-after") ?? "1");
      await new Promise((res) => setTimeout(res, wait * 1000));
      continue;
    }
    if (r.status === 402) return { error: "Out of records on this plan. Stop and tell the user." };
    if (r.status === 429) return { error: "Rate limited twice. Stop and report what you have." };
    if (r.status === 404) return { error: "Nobody matched. This lookup cost nothing." };
    if (!r.ok) return { error: `HTTP ${r.status}: ${(await r.text()).slice(0, 300)}` };
    return { data: await r.json() };
  }
  return { error: "Unreachable" };
}

import { tool } from "ai";
import { z } from "zod";

const icp = {
  jobLevel: z.array(z.string()).optional(),
  jobFunction: z.array(z.string()).optional(),
  country: z.array(z.string()).optional(),
  industry: z.array(z.string()).optional(),
  employeeRange: z.array(z.string()).optional(),
};

export const countAudience = tool({
  description: "Count mailable people for an ICP. Free. Call this first.",
  inputSchema: z.object(icp),
  execute: async (args) => {
    const { data, error } = await call("/v1/people/search", { ...args, limit: 1 }, "?count=true");
    return error ?? data.meta;
  },
});

export const searchPeople = tool({
  description: "Search people for an ICP. Costs 1 record per person returned. Max 10.",
  inputSchema: z.object({ ...icp, limit: z.number().int().min(1).max(10) }),
  execute: async (args) => {
    if (spent + args.limit > RECORD_CAP) return "Record cap reached. Do not search again.";
    const { data, error } = await call("/v1/people/search", args);
    if (error) return error;
    spent += data.data.length;
    return data;
  },
});

export const enrichPerson = tool({
  description: "Full lookup for one person by person_id. Costs 1 record.",
  inputSchema: z.object({ person_id: z.string() }),
  execute: async ({ person_id }) => {
    if (spent + 1 > RECORD_CAP) return "Record cap reached. Do not enrich again.";
    const { data, error } = await call("/v1/people/enrich", { person_id, reveal_email: true });
    if (error) return error;
    spent += 1;
    return data;
  },
});

export const getSpent = () => spent;

export const INSTRUCTIONS = `You qualify leads for Acme, which sells project management software.

ICP: VP of Sales at US software companies with 51 to 200 staff.

Procedure:
1. Call countAudience with the ICP filters. Report the total.
2. Call searchPeople with the same filters and limit 10.
3. Score each person 0 to 3: +1 title matches "VP Sales" or "VP of Sales",
   +1 contact_data.email_status is verified, +1 the company is a software company.
4. Call enrichPerson for the 3 highest scores only.
5. Return a ranked list: name, title, company, score, one-line reason.

Rules: use only fields that came back in a tool result. If a field is missing,
write "unknown". Never call a tool more than the procedure says.

Filter values are exact strings: jobLevel "VP", jobFunction "Sales & Business Development",
country "US", industry "Software Development", employeeRange "51-200".`;

import { ToolLoopAgent, isStepCount } from "ai";
import { countAudience, searchPeople, enrichPerson, getSpent, INSTRUCTIONS } from "./leadocean";

const agent = new ToolLoopAgent({
  model: "anthropic/claude-sonnet-5.5",
  instructions: INSTRUCTIONS,
  tools: { countAudience, searchPeople, enrichPerson },
  stopWhen: isStepCount(8),
});

const result = await agent.generate({ prompt: "Qualify this week's leads." });
console.log(result.text);
console.log(`LeadOcean records spent: ${getSpent()}`);

import { createMCPClient } from "@ai-sdk/mcp";

const mcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.leadocean.io/mcp",
    authProvider: myOAuthClientProvider, // you implement this, see the AI SDK MCP docs
  },
});
const tools = await mcp.tools();

curl -s https://api.leadocean.io/v1/account -H "x-api-key: $LEADOCEAN_API_KEY" | jq

{
  "total": 1649,
  "totalIsExact": true,
  "distinctCompanies": 1125,
  "totalAll": 4141,
  "credits": 0
}

{
  "success": true,
  "data": [
    {
      "profile_data": { "...": "name, headline, location" },
      "contact_data": { "has_email": true, "email_status": "verified", "email_type": "work",
                        "contact_current_experiences": [ { "...": "current role and company" } ] },
      "meta": { "source_ids": { "person_id": "<digits>" } }
    }
  ],
  "meta": { "count": 10, "limit": 10, "nextCursor": "<opaque cursor>" }
}