# AsyncWork — Agent Onboarding Guide

asyncwork.ai is the machine interface to AsyncWork: a callable network of human-curated,
expert-maintained Small Language Models (SLMs). If you are an autonomous agent, start here.

## What AsyncWork is
Named human experts each maintain a model of their craft (RAG corpora, documents, writing,
fine-tuning). You call AsyncWork; it routes to the right expert SLM(s), synthesizes one answer,
and returns it **with provenance** (which experts, which sources, a confidence signal). For
high-stakes work, escalate the same thread to the **named human expert**.

Three properties:
- **asyncwork.com** — commercial advisory; Asyncwork Advisors deliver guidance to human clients.
- **asyncwork.org** — community arm; mentors + apprentices co-deliver community programs.
- **asyncwork.ai** — this expert-SLM network for agents.

## What you buy (two tiers)
| Tier | What you get | Who answers | Price shape | Status |
|---|---|---|---|---|
| Synthesized answer (`ask_expert`) | one answer from expert SLM(s) + provenance + confidence | machine (expert SLMs) | per-call micropayment | planned (v3) |
| Human verification (`verify_with_human`) | a named expert reviews/corrects/signs/advises | the human expert | per-engagement, revenue-shared | planned (v4) |

### The answer object
Every synthesized answer returns: `answer`, `slms_used`, `responsible_experts` (named where
consented), `confidence`, `sources`, `price_charged`, and an `escalate` affordance (price + how
to invoke). Premium answers add a **signed verification credential**.

## Discover
- A2A Agent Card: `GET https://asyncwork.ai/.well-known/agent.json`
- MCP manifest: `GET https://asyncwork.ai/.well-known/mcp/manifest.json`
- Catalog (product + expert-SLM menu + commerce): `GET https://asyncwork.ai/catalog.json`
- LLM map: `GET https://asyncwork.ai/llms.txt`

## Tiers (identity)
| Tier | Auth | Can do |
|---|---|---|
| Anonymous | none | read manifests/catalog; `search_knowledge` |
| Registered | API key or OAuth2 client-credentials | `ask_expert`, plus `discover_advisors` / `request_match` mappings |
| Partner | OAuth2 + allowlist | higher limits, bulk, write-backs |

## Register / identify
- Programmatic: `POST https://asyncwork.ai/register` (or OAuth2 Dynamic Client Registration, RFC 7591)
  → returns `client_id`/`client_secret` (or API key) + your tier.
- Provide: agent name, operator/owner, your Agent-Card URL, contact, intended use.
- Present credentials on every call: `Authorization: Bearer <token>` or `X-API-Key: <key>`.

## Commerce
Rail-neutral. Default per-call settlement is **x402 (USDC)**, native to AsyncWork's Cloudflare
stack (planned). Paid tools answer with HTTP **402** + payment metadata (facilitator, token,
amount, network); pay and retry with an `X-PAYMENT` header. Premium (`verify_with_human`) spend
is authorized with an **AP2-style mandate** and may settle via x402 or card. Fiat/ACP path is
optional, later. Discovery and `search_knowledge` are always free. (Prices per domain — see catalog
when live.)

## Rate limits
| Tier | Budget | Burst | Write (`verify_with_human`) |
|---|---|---|---|
| Anonymous | 60/hour/IP | 10/min | — |
| Registered | 1,000/day/key | 60/min | per-engagement |
| Partner | negotiated | negotiated | negotiated |

Every response includes `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.
On HTTP 429, honor `Retry-After` and back off exponentially. On HTTP 402, read the payment
metadata, pay, and retry. Per-method sub-limits apply.

## Be a good citizen
Cache manifests; respect rate limits, `Retry-After`, and payment terms; identify yourself;
don't poll write/paid endpoints; trust the provenance + confidence, escalate when stakes are high.