# AgilityOS — Recommendation Agents

> The agentic web is here. Most merchants are still on "let agents scrape my HTML." AgilityOS clients are agent-callable today: structured products, operator-curated trust claims, end-to-end conversion attribution — all on three industry-standard protocols.

## Why this matters

When an autonomous agent (a personal AI assistant, an MCP client, a B2B procurement bot) shops on behalf of a user, it has three choices:

1. **Scrape the merchant's website** — brittle, breaks on any UI change, returns unstructured HTML, gets blocked.
2. **Use a generic search API** — generic results, no merchant context, no conversion tracking.
3. **Call an agent-callable storefront** — structured products, real-time inventory, operator-curated trust claims, attribution wired in.

AgilityOS is option 3. Every recommendation agent built on the platform exposes its catalog over Google A2A, Anthropic MCP, and a richer REST endpoint — same backend, three protocols.

## What you get as an external agent

- **Structured products** — typed JSON, never HTML
- **Per-recommendation pitch context** — every product comes with verifiable trust claims (`lab-tested`, `ships next-day`, `30-day returns`) sourced from the operator's curated catalog data
- **Conversion attribution** — register your agent, get a key, fire `/track-conversion` callbacks, see your traffic land in the merchant's analytics
- **Sub-second discovery** — `.well-known/agent.json` per agent + a domain-level index at `/.well-known/agents.json`

## What you get as a merchant operator

- **Embedded chat widget** for human visitors (already there if you're an AgilityOS client)
- **Agent-callable surface** layered automatically on top — no new build
- **Editable pitch** — control what your agent advertises to other agents
- **Tier-managed external agents** — registered callers get attribution + elevated rate limits; anonymous callers get baseline access
- **External-agent analytics tab** — see conversions by caller, B2C vs. B2B split, attributed revenue

## Three protocols, one backend

| Protocol | Origin | Best for |
|---|---|---|
| **Google A2A** | Google A2A spec | Agent-to-agent message protocol — `tasks/send` JSON-RPC. Use when your client speaks A2A natively. |
| **Anthropic MCP** | Anthropic Model Context Protocol | Tool invocation pattern — `tools/call` JSON-RPC. Use for Claude Desktop, ChatGPT Apps, MCP clients. |
| **REST** | AgilityOS | The richest output surface, easiest to integrate with any HTTP client. |

Same data on all three. Pick the one your client speaks; switch later if needed.

## Quickstart

```bash
# 1. Discover available agents
curl https://agilityos.co/.well-known/agents.json

# 2. Read an agent's card (A2A spec)
curl https://agilityos.co/api/public/agents/savoir/.well-known/agent.json

# 3. Call /recommend
curl -X POST https://agilityos.co/api/public/agents/savoir/recommend \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent-id" \
  -d '{"goal":"a clean fragrance for office wear","budget":80,"maxResults":3}'
```

Returns structured products, reasoning, pitchContext, sessionId, and a 24h conversionToken for attribution.

## Next

- [Recommendation Agent reference](/docs/recommendation-agents) — full protocol details
- [API reference](/docs/api-reference) — every endpoint with request/response schemas
- [Authentication](/docs/auth) — caller registration + rate limits
- [Voice Agent reference](/docs/voice-agents) — different system, also agent-callable