Phone Scout

Exit codes

call-one exits:

The parent agent interprets exit codes. Exit 0 with "error": "no_answer" means "nothing went wrong, they just didn't pick up" — proceed with next candidate. Exit 1 means "stop everything, something is broken."

Delegation error survival

When running parallel sub-agent research:

• If a sub-agent's call-one returns exit 0 (with any error code), the sub-agent result is valid — include it in the parent's ranking.
• If a sub-agent crashes (exit 1, or Hermes kills it), that candidate is unreachable. The parent counts it as contacted: false.
• The parent never cancels the entire batch because one child failed. Collect N-1 results, rank them, and present the best.

Quick-start (the agent runs this for you)

PY="python3"
SCOUT="scripts/phone_scout.py"
PY="python3"  # or ./venv/bin/python3 if using venv  # venv with calle-ai installed

# Full pipeline (discover → call → verify → rank)
PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT search \
  --objective "Find me a restaurant in Johannesburg for 8 people tonight after 7pm. It needs vegetarian options and should cost less than R500 per person." \
  --max-calls 3

# Plan only (discovery only, no calls)
PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT search \
  --objective "dentist Manhattan New York teeth cleaning 7-13 September budget 500" \
  --plan-only

# After research, verify + rank in memory (no storage)
PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT verify --results-file /tmp/results.json --constraints '{"max_price":500}'
PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT rank   --results-file /tmp/results.json --constraints '{"max_price":500}'

Architecture

User Request (natural language)
        ↓
Research Planner   → required fields, constraints, max_calls
        ↓
Candidate Discovery → Google Places or OSM Overpass
        ↓
Candidate Selector → rank by likelihood, cap at --max-calls (default: top 3)
        ↓
Phone Research Agents (serial, one at a time)
        │  → CALLE in live mode
        ↓
Structured Extraction → JSON per business
        ↓
Verification Agent → checks each result against constraints
        ↓                detects conflicts, computes confidence
Ranking Agent → scored & ranked recommendation
        ↓
Evidence-backed result

Full JSON includes per-business structured_result, verification (check-by-check), ranking (score + reasons), recommendation (#1 match), and events (full timeline).

Generic by design (works for any vertical)

PhoneScout is not restaurant-specific. It treats a research task as a generic constraints → phone research → verify → rank pipeline:

• Any constraint becomes a check. verify_result() dispatches each key in constraints to a checker. Built-in checkers cover party_size, vegetarian, vegan, halal, max_price_per_person, time_after, min_rating — and any unknown key falls back to a direct field match.
• Required fields derive from constraints. plan_research() maps each constraint to the result field it needs (via CONSTRAINT_FIELD_MAP), so the live CALLE task and result schema are generated per-research, not hardcoded.
• Result schema is auto-generated from the required fields.

Example: a dentist search

python3 phone_scout.py search \
  --objective "Find a dentist in Manhattan New York who can see me this week for under $500 and accepts my insurance" \
  --max-calls 4

The planner would derive fields for max_price_per_person (→ price), accepts_medical_aid, and time_after; the verifier would check each; the ranker would score against whatever constraints were supplied.

Important principles

1. Research-first design. The skill asks "what do I need to know?" not "who do I call?" Phone calls are an execution detail.
2. Call the top 3 only. Discovery may return more candidates via Google Places, but only call the top 3 ranked by relevance (default --max-calls 3).
3. Evidence over summary. Every result carries evidence snippets from the actual call, and verification shows the exact constraint checks.
4. Information gathering only. Calls are read-only research. Do not book, reserve, or commit during a research call.
5. Confidence over speed. A low-confidence result is surfaced as such rather than hidden.

Prerequisites

• Python 3.9+ (stdlib only for phone_scout.py and web_search.py)
• pip install calle-ai into a venv
• CALLE_API_KEY in your environment
• CALLE account with available credits
• GOOGLE_PLACES_API_KEY in your environment (optional — adds phone numbers to discovery; without it, OSM Overpass is used)

Call execution (serial by default)

Default: shared line = 1 concurrent call. CALL-E's shared line allows only ONE active call at a time (author-observed on free-tier accounts; dedicated numbers calls makes N-1 fail with "account concurrency limit of 1". Serialize all calls by default — one call-one at a time.

Serial execution (the default)

Run call-one sequentially for each candidate using terminal(background=true) + process(action='wait'). This gives each call its own timeout, survives long hold times, and doesn't leave stale calls occupying the line if something goes wrong:

PY="python3"  # or ./venv/bin/python3 if using venv
SCOUT="scripts/phone_scout.py"

for candidate in "${candidates[@]}"; do
  PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT call-one \
    --candidate-id "$id" --name "$name" --phone "$phone" \
    --research-questions "availability price booking_requirements" \
    --context "..." --pretty
  sleep 5  # small gap to ensure line is free
done

Agent pattern: use terminal(background=true, notify_on_complete=true) + process(action='wait') for each call. Do NOT use execute_code for sequential calls — if a call hangs and the script hits the 5-minute timeout, the CALLE call stays alive and blocks the shared line.

Concurrency pitfall: execute_code timeouts

execute_code has a 300s timeout. If a call-one invocation inside it creates a CALLE call that hangs (ringing, voicemail, hold queue), the script is killed but the CALLE call keeps running — occupying the shared line. Every subsequent attempt hits the concurrency limit until CALL-E's own timeout releases it (~2 minutes). Never batch sequential call-one calls inside execute_code. Use individual terminal(background=true) calls instead.

Future: parallel delegation (after KYC)

Once KYC is complete and a dedicated number is purchased at https://dashboard.heycall-e.com/account/numbers/buy (unlocks up to 10 concurrent calls), switch to parallel delegation:

Use the host's documented task API, not a Python API from this skill. Give each task one approved candidate, its authorized destination, research questions, and the selected interpreter plus the full path to scripts/phone_scout.py. Ask it to execute the approved call-one command and return masked JSON to the parent. Credentials must be inherited privately, never included in task text. This is an orchestration recipe, not executable host-independent delegation code.

Bounded by min(len(candidates), account_concurrency) at a time.

Full pipeline pattern the agent follows:

PHASE 1 — PLAN (parent, no delegation)
  PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT search --objective "..." --max-calls N --plan-only
  → returns the research plan + candidate list (no calls placed)
  Read candidates[].name, candidates[].phone, research_plan.required_fields

PHASE 2 — SERIAL PHONE CALLS (parent, one at a time)
  For each candidate, run `PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT call-one ...` sequentially:
    terminal(background=true, notify_on_complete=true)
    process(action='wait', timeout=180)
  Collect each result, then proceed to verification.
  Do NOT batch in execute_code — use individual background terminal calls.

PHASE 3 — VERIFY + RANK (parent, after all subagents finish)
  Save the collected results to a JSON file, then re-run verification + ranking
  over them and present the recommendation:

    PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT verify --results-file /tmp/results.json --constraints '{"party_size":8,"vegetarian":true,"max_price_per_person":500}'
    PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT rank   --results-file /tmp/results.json --constraints '{"party_size":8,"vegetarian":true,"max_price_per_person":500}'

  (Or, if the parent ran the one-shot `search` pipeline, just inspect the
   stdin: `PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT verify --results-file /tmp/r.json` / `rank --results-file /tmp/r.json`.\)

Phase 2 serial execution (the agent builds this from the candidate list):

For each candidate in order:
  1. Start background call:
     terminal(background=true, notify_on_complete=true,
       command="PY="python3"  # use venv python if calle-ai installed there
SCOUT="scripts/phone_scout.py"  # adjust to ./scripts/phone_scout.py or full path
$PY $SCOUT call-one
         --candidate-id \"<id>\" --phone \"<phone>\" --name \"<name>\"
         --research-questions availability price booking_requirements
         --context \"...\" --pretty")
  2. Wait for completion:
     process(action='wait', session_id=<id>, timeout=180)
  3. Parse JSON result, add to collected results
  4. Sleep 5s to ensure line is free, then next candidate

Rules:

• One call at a time. Never fire multiple call-one invocations concurrently on the shared line — each subsequent call fails with the concurrency limit error.
• Discovery + selection happen BEFORE calling. Run --plan-only first, then call only the selected candidates.
• Each call is self-contained. Pass the exact research questions and context so each call asks targeted questions.
• Collect all results, then verify + rank. Don't discard partial results.

Related skills

• call-e-booking — book the restaurant/clinic that PhoneScout recommends
• google-workspace — write the recommendation to a Sheet or Doc

Configuration (env vars)

PhoneScout is fully configurable via environment variables — no code changes needed to run in a different city, country, or currency:

Minimal config for a new user in NYC:

export PHONE_SCOUT_CURRENCY="$"
export PHONE_SCOUT_TZ="America/New_York"
export PHONE_SCOUT_DEFAULT_LOCATION="New York City"
export CALLE_API_KEY="..."
# Optional — adds phone numbers to discovery:
export GOOGLE_PLACES_API_KEY="..."

Scripts

• scripts/phone_scout.py — main research orchestrator
  • search — full pipeline (discover → call → verify → rank)
  • call-one — research ONE business (used by sub-agents)
  • verify — re-run constraint verification on an explicit --results-file
  • rank — re-rank an explicit --results-file; no stored-session lookup
• scripts/web_search.py — keyless business discovery (Google Places if an API key is exported, else OSM Overpass). Export GOOGLE_PLACES_API_KEY explicitly; do not assume a host environment file is loaded.