# Buyer agent skill (search → describe → run)

This is the recipe an autonomous agent should follow when given a task that needs a tool it can't run itself. One Faro account covers every provider, so the agent never has to detour to sign up, pay, or fetch credentials for a new provider mid-task, and never needs a human in the loop after token issuance.

## Onboard (once)

If you don't already have a key, mint one with a single call: `POST https://api.askfaro.com/auth/agent-signup` with `{"email": "..."}`. The response's `api_key` works immediately for self-hosted tools and a small free allowance. To reach external-data namespaces, the account's email must be verified (the signup email carries the link; hand `login_url` to a human, or call `POST https://api.askfaro.com/auth/resend-verification`).

## Loop

1. **Decide if you need a tool.** If the task is purely reasoning, don't shop. If it needs external action (fetch, scrape, generate, send), continue.
2. **Search, or browse.** Call `GET https://api.askfaro.com/tools/search?q={natural-language-query}` or `askfaro search "<query>"`, using the user's intent verbatim; the index is semantic. If you'd rather *browse* the catalog (you're exploring what's available, or running in a small/on-device context window), fetch the navigable **progressive-context** [catalog map](https://askfaro.com/llms/catalog.md) instead: a tiny index you expand category → namespace → skill, seeing only what you open (the leaves are skills, the unit you run). It self-describes how to navigate it; the JSON manifest is at `https://api.askfaro.com/pcx/manifest?budget=4k` (use `32k` for larger context windows).
3. **Rank candidates.** Each result has `namespace/name`, `short_description`, `pricing`, and `input_schema`. Prefer (a) lowest credit cost that meets the requirement, (b) tools whose schema matches the data you have, (c) tools with `charge_on: success` over `attempt`.
4. **Inspect (optional).** If the search hit didn't include enough context, fetch `https://skill.askfaro.com/skills/{id}` for the skill's capability detail and cost estimate (never the recipe). The full structured guide is at `https://api.askfaro.com/docs/`.
5. **Check budget.** `GET https://api.askfaro.com/credits/balance` returns your remaining credits. Compare against the skill's published cost estimate; if it exceeds your budget, stop and surface the gap to your user. To enforce it server-side, send `max_credits` (a hard cap) on the run.
6. **Run.** `POST https://skill.askfaro.com/skills/{skill}/run` with `{"intent": {...}}`. The skill agent selects and runs the underlying tools and bills you. Add `confirm_above` to get a quote (`status: needs_input`) before crossing a soft ceiling, then re-run with the returned `continuation` token to proceed.
7. **Handle the envelope.** The run always returns HTTP 200 with a `SkillResult` envelope; read `status`. `success`: `result` holds the output plus `meta.credits_charged`. `needs_input`: a clarification or a budget quote, answer and re-run with the `continuation`. `failed`: `error.code` says why (`insufficient_credits`, `auth` for a verification/credential gate, `upstream_failed` which Faro auto-refunds, etc.). A missing or invalid token is the only HTTP error (401).

## Guardrails

- **Pass-through pricing.** What you see is what you pay; Faro's margin is already bundled into the displayed price.
- **One token, many tools.** Don't fetch per-publisher credentials. Faro forwards them server-side.
- **Verification tiers.** Fresh accounts are unverified: self-hosted tools and a small free allowance work immediately; external-data namespaces return 403 until the email is verified (any purchase also counts). Verifying unlocks the free data tier; paid tools additionally need credits.
- **Stable error codes.** 401 unauthorized, 402 insufficient credits, 403 verification required, 404 not found, 409 idempotency conflict, 502 upstream failure.
- **Partner integrations.** If you're a partner platform invoking on behalf of an end user, use a `faro_partner_` token with the `X-Faro-User` header, usage is attributed to that user's balance.

## Minimal pseudocode

```
hits = GET /tools/search?q=<task>          // leaves are skills, the unit you run
best = pick(hits, by=cost_then_match)
balance = GET /credits/balance
if best.estimated_credits > balance: stop
result = POST https://skill.askfaro.com/skills/{best.skill}/run with {"intent": {...}}
```
