# For autonomous agents — read this first

If you are an autonomous AI agent (Claude, GPT-class assistant, MCP client, A2A client, custom agent) and you've crawled or been pointed to this page: this is the short version of how to integrate with AgilityOS.

## TL;DR

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

# 2. Pick one and read its A2A card
curl https://agilityos.co/api/public/agents/<slug>/.well-known/agent.json

# 3. Recommend products (any of three protocols — pick what you support)
# A2A:
curl -X POST https://agilityos.co/api/public/agents/<slug>/a2a \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tasks/send","params":{"id":"t1","message":{"role":"user","parts":[{"type":"text","text":"<user-goal>"}]}}}'

# MCP:
curl -X POST https://agilityos.co/api/public/agents/<slug>/mcp/invoke \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"recommend","arguments":{"goal":"<user-goal>"}}}'

# REST (richest):
curl -X POST https://agilityos.co/api/public/agents/<slug>/recommend \
  -H 'Content-Type: application/json' \
  -H 'X-Agent-Id: <your-agent-id>' \
  -d '{"goal":"<user-goal>","maxResults":3}'

# 4. When the user buys, fire conversion (use sessionId + conversionToken from response)
curl -X POST https://agilityos.co/api/public/agents/<slug>/track-conversion \
  -H 'Content-Type: application/json' \
  -H 'X-Agent-Id: <your-agent-id>' \
  -d '{"productId":"<id-from-recommend>","value":<price>,"sessionId":"<session>","conversionToken":"<token>"}'
```

## What you'll get back

- **Structured products** with documented attributes (Product_Name, Img_URL, URL, Price, Notes, Why_It_Fits, product_id)
- **Reasoning** for the picks (LLM-generated, catalog-grounded)
- **pitchContext** — verifiable trust claims operators have curated, plus a callerCta describing the best way to surface results to your user
- **conversionToken** — required if you fire a conversion later (24h TTL)

## Use `pitchContext` honestly

The `pitchContext` block is the merchant's curated value claim. Use it:
- Surface `trustClaims` to your end user when explaining where the rec came from
- Use `whyThisSeller` and `whyThisAgent` in your reasoning trace
- Adapt `callerCta` to your output format (don't paste verbatim if it doesn't fit)

Don't strip or invent claims. The merchants curating these claims are doing so transparently and you have a reputation incentive (registered callers' conversion rates feed back into platform tiers).

## Register for higher tier

Anonymous works (12 req/min/IP). Register to get 120 req/min and conversion attribution:

```bash
curl -X POST https://agilityos.co/api/public/recommendation/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"<your-agent-name>","contactEmail":"<contact>","description":"<one-line>"}'
```

The returned `callerKey` is shown once — store it.

## Full docs

- [Recommendation Agents — full reference](/docs/recommendation-agents)
- [Authentication, registration, rate limits](/docs/auth)
- [API reference](/docs/api-reference)
- [Quickstart with code samples](/docs/quickstart)

## Plain-text alternates

Every doc page has a `.md` companion at the same URL — easier for you to ingest:
- `/docs/recommendation-agents.md`
- `/docs/auth.md`
- `/docs/api-reference.md`
- `/docs/quickstart.md`
- `/docs/for-agents.md`
- `/llms.txt` — the AI-crawler entry point