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

// src/mastra/tools/leadocean.ts
const BASE = "https://api.leadocean.io";

export class OutOfRecords extends Error {}

export async function call(
  method: "GET" | "POST",
  path: string,
  opts: { query?: Record<string, string>; body?: unknown; signal?: AbortSignal } = {},
  retries = 3,
): Promise<any> {
  const qs = opts.query ? "?" + new URLSearchParams(opts.query) : "";
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(BASE + path + qs, {
      method,
      headers: {
        "x-api-key": process.env.LEADOCEAN_API_KEY!,
        "content-type": "application/json",
      },
      body: opts.body ? JSON.stringify(opts.body) : undefined,
      signal: opts.signal,
    });
    if (res.status === 429 && attempt < retries) {
      const wait = Number(res.headers.get("retry-after") ?? 1);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (res.status === 402) {
      throw new OutOfRecords("LeadOcean records are spent. Stop and tell the user.");
    }
    if (res.status === 404) return { data: null, note: "nobody matched" };
    if (!res.ok) throw new Error(`LeadOcean ${res.status}`);
    return res.json();
  }
}

// src/mastra/tools/leadocean-tools.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { call } from "./leadocean";

export const sizeList = createTool({
  id: "size-list",
  description: "Free. Count people matching job titles and ISO country codes.",
  inputSchema: z.object({ titles: z.array(z.string()), countries: z.array(z.string()) }),
  outputSchema: z.object({ total: z.number(), distinctCompanies: z.number().nullable() }),
  execute: async ({ titles, countries }, { abortSignal }) => {
    const res = await call("POST", "/v1/people/search", {
      query: { count: "true" },
      body: { title: titles, country: countries, limit: 1 },
      signal: abortSignal,
    });
    return { total: res.meta.total, distinctCompanies: res.meta.distinctCompanies ?? null };
  },
});

export const searchPeople = createTool({
  id: "search-people",
  description: "Spends 1 record per person returned. Max 10 per call.",
  inputSchema: z.object({
    titles: z.array(z.string()),
    countries: z.array(z.string()),
    limit: z.number().max(10).default(10),
  }),
  outputSchema: z.object({ people: z.array(z.any()) }),
  execute: async ({ titles, countries, limit }, { abortSignal }) => {
    const res = await call("POST", "/v1/people/search", {
      body: { title: titles, country: countries, limit: Math.min(limit, 10) },
      signal: abortSignal,
    });
    return { people: res.data };
  },
});

export const enrichPerson = createTool({
  id: "enrich-person",
  description: "Spends 1 record. Use only on people that pass the ICP check.",
  inputSchema: z.object({ personId: z.string() }),
  outputSchema: z.object({ person: z.any() }),
  execute: async ({ personId }, { abortSignal }) => {
    const res = await call("POST", "/v1/people/enrich", {
      body: { person_id: personId, reveal_email: true },
      signal: abortSignal,
    });
    return { person: res.data ?? { note: "nobody matched" } };
  },
});

// src/mastra/agents/qualifier.ts
import { Agent } from "@mastra/core/agent";
import { sizeList, searchPeople, enrichPerson } from "../tools/leadocean-tools";

export const qualifier = new Agent({
  id: "qualifier",
  name: "Lead Qualifier",
  instructions: `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.`,
  model: "openai/gpt-5.6-sol",
  tools: { sizeList, searchPeople, enrichPerson },
});

const res = await qualifier.generate("Qualify VP Sales titles in the US.");
console.log(res.text);

import { MCPClient } from "@mastra/mcp";

export const leadocean = new MCPClient({
  id: "leadocean",
  servers: { leadocean: { url: new URL("https://api.leadocean.io/mcp") } },
});

// tools: await leadocean.listTools()

{
  "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": "..." }
}