/// agent mode

Agent Mode API

Agent Mode runs reusable read-only workflows with source-grounded extraction, optional local browser profiles, schedules, and exports. API callers pass their own user id; Wide Area Intelligence scopes that id under your gateway key owner, so two customers using the same id do not share browser state or run history.

Create a run

Use a built-in or custom workflow. If you pass browserProfile, the run may return needs_login until that external user has completed the login handoff for that profile.

agent run

curl https://wideareaai.com/api/agent/runs \
  -H "Authorization: Bearer wai_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "customer-or-user-123",
    "workflow": "opportunity-research",
    "workflowInputs": {
      "target": "Vista Equity Partners",
      "target_profile": "CIO/CTO executive roles"
    },
    "browserProfile": "linkedin"
  }'

clone workflow

curl https://wideareaai.com/api/agent/workflows \
  -H "Authorization: Bearer wai_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cloneFrom": "opportunity-research",
    "slug": "my-opportunity-scout",
    "name": "My opportunity scout"
  }'

Persistent browser profiles

Browser cookies and sessions stay on the user's node by default. The cloud database stores only profile metadata: owner, external user subject, profile name, status, allowed domains, and an opaque storage reference.

node setup

# On the node that should hold logged-in browser sessions:
export WAI_BROWSER_AUTOMATION=1

# Optional:
export WAI_BROWSER_PROFILE_DIR="$HOME/.wideareaai/browser-profiles"
export WAI_CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
export WAI_BROWSER_HEADLESS=0

wai restart

# Open the user's local browser profile at a login page.
curl https://wideareaai.com/api/agent/runs/{runId} \
  -X PATCH \
  -H "Authorization: Bearer wai_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"action":"start_login","loginUrl":"https://www.linkedin.com/login"}'

# After the user signs in locally, mark the profile ready.
curl https://wideareaai.com/api/agent/runs/{runId} \
  -X PATCH \
  -H "Authorization: Bearer wai_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"action":"login_complete","allowedDomains":["linkedin.com"]}'

Schedules and exports

Schedules store workflow inputs and create Agent Mode runs through the same tenant/profile path as direct API runs. The internal due-schedule runner is protected by CRON_SECRET. Exports are available as markdown reports, full JSON, or structured entity CSV.

schedule

curl https://wideareaai.com/api/agent/schedules \
  -H "Authorization: Bearer wai_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "company-hiring-manager-research",
    "workflowInputs": {
      "company": "Acme Software",
      "target_profile": "VP Engineering candidate"
    },
    "externalUserId": "customer-or-user-123",
    "cadence": "weekly",
    "browserProfile": "linkedin"
  }'

export

# markdown report
curl "https://wideareaai.com/api/agent/runs/{runId}/export?format=markdown" \
  -H "Authorization: Bearer wai_sk_..."

# full run JSON
curl "https://wideareaai.com/api/agent/runs/{runId}/export?format=json" \
  -H "Authorization: Bearer wai_sk_..."

# structured entity CSV
curl "https://wideareaai.com/api/agent/runs/{runId}/export?format=csv" \
  -H "Authorization: Bearer wai_sk_..."

run history

curl "https://wideareaai.com/api/agent/runs?externalUserId=customer-or-user-123&workflow=company-hiring-manager-research&browserProfile=linkedin" \
  -H "Authorization: Bearer wai_sk_..."

Local verification

smoke tests

# Local development smoke tests:
AGENT_API_KEY="$(cat /tmp/wai-agent-api-key.txt)" npm run agent:api:test
npm run agent:browser:test
WAI_BROWSER_RPC_REAL_TEST=1 npm run agent:browser:test