Руководство по аутричу и генерации лидов

Полный конвейер

Исследовательский прогон — это один и тот же цикл на каждом уровне: план, разветвление, сбор в рамках бюджетов, проверка и передача более чистого сигнала дальше. Вот что происходит на самом деле, инструмент за инструментом.

A research run is the same loop at every level: plan, fan out, collect under budgets, verify, then hand cleaner signal to the next stage. Here is what actually happens, tool by tool.

Начните с цели на обычном языке

Никаких схем и настройки CRM заранее. Опишите, чего хотите, своими словами.

fathom run "Find VP Engineering at Series B startups in SF, verify their emails, and save the leads"

The coordinator turns that into sub-tasks with per-task contact quotas. Each sub-task becomes a Researcher (or an OS process with use_multiprocess = true), runs until its budget is spent, then hands its findings forward.

Почему проверка важна

Every bounce costs sender reputation and budget. That is why email goes through five gates before it is saved. verify_email returns a confidence score in [0,1] and a verdict — you decide the cutoff that matches your risk appetite.

Оценка уверенности

• База 0.5 — синтаксис, disposable и ролевые проверки корректируют её.
• +0.4, если домен разрешается через MX/A.
• SMTP принял → ≥ 0.95; отклонён → ≤ 0.2; без SMTP → максимум 0.9.
• −0.3, если адрес похож на disposable. Итоговое значение ограничено [0,1].

Введите лидов в свой процесс

Всё автоматически попадает в contacts.db (дедуп + слияние). Дальше есть три пути.

Everything lands in contacts.db automatically (dedup + merge). From there you have three paths.

Контроль человека там, где это важно

Побочные эффекты ждут явного «да». save_contacts и git_push по умолчанию за воротами одобрения — подтвердите в TUI или через POST /api/v1/sessions/:id/approve в API.

Side effects wait for an explicit yes. save_contacts and git_push are gated behind an approval flow by default — approve in the TUI, or via POST /api/v1/sessions/:id/approve on the API.

OSINT Tools Deep Dive

The outreach pipeline is powered by five complementary data-gathering tools. Each one targets a different surface — business directories, social networks, news coverage, or individual corporate sites — and the coordinator orchestrates them in parallel to maximize coverage while staying within per-run budgets.

result = await agent.call_tool("find_leads", {
  industry: "B2B SaaS",
  location: "San Francisco Bay Area",
  roles: ["VP Engineering", "CTO"],
  limit: 25,
  enrich: true
})

{
"company": "Acme Analytics",
"website": "https://acme-analytics.com",
"industry": "B2B SaaS",
"location": "San Francisco, CA",
"employees": "80-120",
"funding_stage": "Series B",
"contacts": [
  {
    "name": "Jordan Lee",
    "title": "VP Engineering",
    "email": "[email protected]",
    "email_confidence": 0.97,
    "linkedin": "https://linkedin.com/in/jordanlee",
    "source_url": "https://acme-analytics.com/team"
  }
],
"confidence": 0.92,
"sources": [
  "https://2gis.com/san-francisco/firm/acme-analytics",
  "https://acme-analytics.com/team",
  "https://linkedin.com/company/acme-analytics"
]
}

{
"name": "NovaTech Solutions",
"category": "Software Development",
"address": "45 Market St, Suite 200, San Francisco, CA 94105",
"phone": "+14155550123",
"website": "https://novatech.io",
"email": "[email protected]",
"rating": 4.6,
"reviews_count": 38,
"source": "google_maps"
}

{
"profile_url": "https://twitter.com/jordanlee_eng",
"name": "Jordan Lee",
"bio": "VP Engineering @AcmeAnalytics · Building data pipelines at scale",
"followers_count": 4200,
"location": "San Francisco, CA",
"platform": "twitter"
}

{
"title": "Acme Analytics Raises $40M Series B Led by Sequoia",
"url": "https://techcrunch.com/2025/03/15/acme-series-b",
"source": "TechCrunch",
"date": "2025-03-15",
"snippet": "Acme Analytics, the San Francisco-based B2B data platform, has closed a $40M Series B round...",
"mentioned_persons": ["Jordan Lee", "Maria Chen"],
"mentioned_companies": ["Acme Analytics", "Sequoia Capital"]
}

{
"company_name": "Acme Analytics",
"description": "Real-time data pipelines for modern B2B teams",
"industry": "B2B SaaS / Data Infrastructure",
"size": "80-120 employees",
"hq": "45 Market St, Suite 200, San Francisco, CA 94105",
"emails": ["[email protected]", "[email protected]"],
"phones": ["+14155550100"],
"social": {
  "twitter": "https://twitter.com/acmeanalytics",
  "linkedin": "https://linkedin.com/company/acme-analytics",
  "github": "https://github.com/acme-analytics"
},
"team": [
  { "name": "Jordan Lee", "title": "VP Engineering" },
  { "name": "Maria Chen", "title": "CEO" },
  { "name": "Alex Rivera", "title": "CTO" }
],
"technologies": ["React", "Go", "Kubernetes", "PostgreSQL"]
}

Verification Tools Deep Dive

Raw data is noisy. Verification tools clean, normalize, and score every contact record before it enters your pipeline. Here is exactly what each tool does and how to interpret its output.

score = 0.5                                    # base
if mx_resolved:     score += 0.4               # domain is real
if disposable:      score -= 0.3               # throwaway domain
if role_based:      score -= 0.15              # department mailbox
if smtp_accepted:   score = max(score, 0.95)   # server confirmed
if smtp_rejected:   score = min(score, 0.2)    # server denied
if no_smtp_check:   score = min(score, 0.9)    # can't fully confirm
score = clamp(score, 0.0, 1.0)
if pattern_matched: score = min(score + 0.15, 0.95)  # suggest_emails bonus

{
"email": "[email protected]",
"verdict": "valid",
"confidence": 0.97,
"stages": {
  "syntax": "pass",
  "mx": "pass",
  "disposable": "clean",
  "role_based": false,
  "smtp": "accepted (250 OK)"
},
"mx_records": ["alt1.gmail-smtp-in.l.google.com", "gmail-smtp-in.l.google.com"]
}

{
"email": "[email protected]",
"verdict": "disposable",
"confidence": 0.05,
"stages": {
  "syntax": "pass",
  "mx": "pass",
  "disposable": "flagged (mailinator)",
  "role_based": false,
  "smtp": "skipped"
}
}

{
"email": "[email protected]",
"verdict": "role_based",
"confidence": 0.78,
"stages": {
  "syntax": "pass",
  "mx": "pass",
  "disposable": "clean",
  "role_based": "flagged (info@)",
  "smtp": "accepted (250 OK)"
}
}

{
"input": "8 (495) 123-45-67",
"e164": "+74951234567",
"country": "RU",
"line_type": "fixed_line",
"valid": true,
"carrier": null
}

{
"url": "https://twitter.com/jordanlee_eng",
"platform": "twitter",
"valid": true,
"metadata": {
  "name": "Jordan Lee",
  "handle": "@jordanlee_eng",
  "bio": "VP Engineering @AcmeAnalytics",
  "followers": 4200,
  "following": 890,
  "verified": false,
  "joined": "2019-04-22",
  "location": "San Francisco, CA"
}
}

Enrichment Tools Deep Dive

Once you have a verified contact, enrichment fills in the context that makes outreach personal and relevant. These two tools turn bare email addresses into full profiles.

{
"domain": "acme-analytics.com",
"company_name": "Acme Analytics",
"industry": "B2B SaaS — Data Infrastructure",
"employee_range": "80-120",
"estimated_revenue": "$10M-$25M",
"founded": 2019,
"hq": "San Francisco, CA, USA",
"description": "Real-time data pipeline platform for B2B analytics teams.",
"technologies": ["React", "Go", "Kubernetes", "PostgreSQL", "Snowflake"],
"funding": {
  "latest_round": "Series B",
  "amount": "$40M",
  "date": "2025-03-15",
  "investors": ["Sequoia Capital", "Y Combinator"]
}
}

{
"name": "Jordan Lee",
"title": "VP Engineering",
"company": "Acme Analytics",
"location": "San Francisco, CA",
"bio": "Engineering leader with 12 years in data infrastructure. Previously at Stripe and Google.",
"linkedin": "https://linkedin.com/in/jordanlee",
"twitter": "https://twitter.com/jordanlee_eng",
"github": "https://github.com/jordanlee",
"emails": ["[email protected]"],
"phones": ["+14155550199"],
"recent_mentions": [
  {
    "title": "Acme Analytics Raises $40M Series B",
    "source": "TechCrunch",
    "date": "2025-03-15"
  }
]
}

Contact Management Workflow

Every contact discovered by the pipeline flows through a unified management layer backed by SQLite. The system handles deduplication, merge, export, and CRM sync — so you never lose data or create duplicates.

How contacts.db works

All contacts are stored in contacts.db, a SQLite database in your project’s data directory. The schema is designed for fast dedup and flexible metadata.

CREATE TABLE contacts (
  id          TEXT PRIMARY KEY,   -- UUID v4
  name        TEXT,
  email       TEXT,
  phone       TEXT,
  title       TEXT,
  company     TEXT,
  linkedin    TEXT,
  twitter     TEXT,
  github      TEXT,
  website     TEXT,
  location    TEXT,
  bio         TEXT,
  confidence  REAL DEFAULT 0.0,
  source_url  TEXT,
  crm_id      TEXT,               -- set after CRM push
  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE UNIQUE INDEX idx_dedup
  ON contacts(email, phone, linkedin);

Dedup logic

• Primary key: email + phone + LinkedIn composite. If any two of the three match, the record is merged.
• Merge strategy: non-empty fields from the newer record overwrite older empty fields; confidence takes the higher value.
• Name normalization: diacritics stripped, whitespace collapsed, case-insensitive comparison.

extract_contacts

Extracts emails, phone numbers, and social profile URLs from free text, raw HTML, or a live URL. Handles obfuscated patterns like bob [at] acme [dot] com and JavaScript-rendered content.

result = await agent.call_tool("extract_contacts", {
  url: "https://acme-analytics.com/team"
})

result = await agent.call_tool("extract_contacts", {
  text: "Reach Jordan at [email protected] or +1 (415) 555-0199"
})

save_contacts

Saves extracted contacts to contacts.db with automatic dedup and merge. When CRM integration is configured, an optional push happens after save.

# Save with auto-push to CRM
await agent.call_tool("save_contacts", { push_crm: true })

# Save without CRM push (default)
await agent.call_tool("save_contacts", {})

CLI commands

CRM integration

[crm]
provider = "amocrm"          # amocrm | bitrix24 | hubspot
domain = "mycompany.amocrm.com"
api_key = "..."

# Or for HubSpot:
# provider = "hubspot"
# domain = "api.hubapi.com"
# api_key = "pat-xxx-..."

Approval Flow Deep Dive

Not every tool should run without human review. The approval flow gates side-effect-causing operations — so the agent can plan freely, but it needs your explicit OK before it writes to your CRM, saves contacts, or pushes code.

Gated tools (by default)

How to customize

Add or remove gated tools in config.toml under the [agent] section:

[agent]
# Default: save_contacts and git_push require approval
approval_tools = ["save_contacts", "git_push"]

# Add more tools to the gate:
approval_tools = ["save_contacts", "git_push", "send_email", "crm_push"]

# Remove all gates (use with caution):
approval_tools = []

TUI approval workflow

• The agent pauses and displays a summary of the pending action in the terminal UI.
• You see: tool name, parameters, expected outcome, and any warnings.
• Press y to approve, n to reject, or e to edit the parameters before approving.
• Editing opens the parameter JSON in your $EDITOR for inline modification.

API approval workflow

When running headless or integrated into CI/CD, approve via the REST API:

# Approve a pending action
curl -X POST http://localhost:8080/api/v1/sessions/sess_abc123/approve \\
-H "Content-Type: application/json" \\
-d '{"action_id": "act_789", "approved": true}'

# Reject a pending action
curl -X POST http://localhost:8080/api/v1/sessions/sess_abc123/approve \\
-H "Content-Type: application/json" \\
-d '{"action_id": "act_789", "approved": false}'

Timeout and fallback behavior

If no approval arrives within the configured window, the agent uses the fallback strategy:

[agent]
# What to do when approval times out:
# "deny"  — skip the action, continue the pipeline
# "allow" — auto-approve (for fully automated runs)
# "pause" — pause the session, resume later
approval_fallback = "deny"

# Timeout in seconds (default: 300 = 5 minutes)
approval_timeout_seconds = 300

Watch Mode & Monitoring

Watch mode transforms a one-shot outreach task into a recurring monitor. Re-run the same query on a schedule, diff the results, and get notified only when new contacts appear.

The –repeat flag

Add –repeat N to re-run every N seconds. The agent runs the full pipeline on each cycle — but only saves contacts that are new or changed since the last run.

# Re-run every 24 hours (86400 seconds)
fathom run "Find new VP Engineering hires at Series B startups in SF" \\
--repeat 86400

How diff detection works

• Each run snapshots the contact database state (hash of email + phone + LinkedIn).
• Before saving, new records are compared against the previous snapshot.
• Only genuinely new or updated contacts trigger notifications.
• Removed contacts (present in snapshot, absent in new run) are logged but not deleted.

Notification channels

Example: daily lead monitoring setup

# Full monitoring setup
export NOTIFY_WEBHOOK_URL="https://hooks.slack.com/services/T00/B00/xxx"
export TELEGRAM_BOT_TOKEN="123456:ABC-..."
export TELEGRAM_CHAT_ID="-1001234567890"

fathom run \\
"Find newly funded startups in Berlin, extract CTO contacts, verify emails" \\
--repeat 86400

Webhook payload example

{
"event": "watch_diff",
"run_id": "run_20250615_001",
"timestamp": "2025-06-15T08:00:00Z",
"new_contacts": 7,
"updated_contacts": 2,
"total_contacts": 156,
"contacts": [
  {
    "name": "New CTO at StartupX",
    "email": "[email protected]",
    "title": "CTO",
    "company": "StartupX",
    "confidence": 0.94
  }
],
"query": "newly funded startups in Berlin"
}

Real-World Workflow Examples

These end-to-end examples show how the pipeline works in practice — from a plain-language goal to verified, enriched leads ready for outreach.

Example 1: Build a targeted engineering leadership list

fathom run \\
"Find VP Engineering at B2B SaaS companies in the Bay Area. \\
 Verify their emails and LinkedIn profiles. \\
 Save enriched contacts with confidence >= 0.85."

{
"session_id": "sess_abc123",
"query": "VP Engineering at B2B SaaS companies in the Bay Area",
"total_companies_found": 87,
"total_contacts_extracted": 134,
"verified_contacts": 92,
"filtered_contacts": 41,
"contacts": [
  {
    "name": "Jordan Lee",
    "title": "VP Engineering",
    "company": "Acme Analytics",
    "email": "[email protected]",
    "email_confidence": 0.97,
    "linkedin": "https://linkedin.com/in/jordanlee",
    "linkedin_verified": true,
    "twitter": "https://twitter.com/jordanlee_eng",
    "location": "San Francisco, CA",
    "bio": "Engineering leader with 12 years in data infrastructure.",
    "company_size": "80-120 employees",
    "company_funding": "Series B ($40M)"
  }
]
}

Example 2: Monitor competitor hiring

fathom run \\
"Monitor career pages and job boards for senior engineering roles \\
 at CompetitorA, CompetitorB, CompetitorC. \\
 Alert on new VP/Director/Staff-level postings." \\
--repeat 43200

{
"event": "watch_diff",
"new_postings": [
  {
    "company": "CompetitorA",
    "title": "Director of Platform Engineering",
    "location": "San Francisco, CA",
    "url": "https://competitora.com/careers/director-platform",
    "posted_date": "2025-06-14",
    "detected_at": "2025-06-15T08:00:00Z"
  }
],
"monitoring_since": "2025-06-01T00:00:00Z",
"total_runs": 30
}

Example 3: Enrich an existing CSV of contacts

# Step 1: Import the CSV
fathom contacts list --limit 50

# Step 2: Enrich each contact
fathom run \\
"For each contact in the database that is missing an email, \\
 find their professional email and LinkedIn profile. \\
 Verify emails before saving." \\
--source-db contacts.db

# Step 3: Export enriched results
fathom contacts export --format csv -o ./enriched_contacts

name,email,email_confidence,title,company,linkedin,twitter,location,bio,source
Jordan Lee,[email protected],0.97,VP Engineering,Acme Analytics,https://linkedin.com/in/jordanlee,https://twitter.com/jordanlee_eng,"San Francisco, CA","Engineering leader with 12 years...",suggest_emails+verify
Maria Chen,[email protected],0.91,CTO,StartupX,https://linkedin.com/in/mariachen,,Berlin,"Former Google, building developer tools...",search_social+verify