AgilityOS

Docs / Get started

Plain-text version: /docs/quickstart.md  ·  llms.txt

Quickstart — 5 minute integration

By the end of this page you will have:

  1. Discovered an AgilityOS recommendation agent
  2. Called /recommend and received structured products
  3. Fired a conversion callback so your traffic gets attributed

No SDK. No keys required for V1 (caller registration is recommended for higher limits + attribution).

1 — Discover

Every domain hosting AgilityOS agents exposes a domain-level index:

curl https://agilityos.co/.well-known/agents.json

Returns a list of all active agents with their per-agent cards (rich + A2A) and protocol endpoints.

2 — Read an agent's card

Each agent has a Google A2A spec card at the canonical well-known location:

curl https://agilityos.co/api/public/agents/savoir/.well-known/agent.json

Returns standard A2A fields: name, description, url, version, capabilities, authentication, defaultInputModes, defaultOutputModes, skills[]. Use this to confirm the agent supports the capability you need.

A richer card with operator-curated pitch lives at /api/public/agents/<slug>/agent.json.

3 — Call /recommend

cURL

curl -X POST https://agilityos.co/api/public/agents/savoir/recommend \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-personal-assistant" \
  -d '{
    "goal": "a clean fragrance for everyday office wear",
    "budget": 80,
    "constraints": ["unisex", "long-lasting"],
    "maxResults": 3,
    "callerMode": "b2c"
  }'

Python

import requests

r = requests.post(
    "https://agilityos.co/api/public/agents/savoir/recommend",
    headers={
        "Content-Type": "application/json",
        "X-Agent-Id": "my-personal-assistant",
    },
    json={
        "goal": "a clean fragrance for everyday office wear",
        "budget": 80,
        "maxResults": 3,
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()
for p in data["products"]:
    print(f"{p['Product_Name']} — {p.get('Price','')}")
print("Trust claims:", data["pitchContext"]["trustClaims"])

# Save the conversionToken — you'll need it if a purchase happens
session_id = data["sessionId"]
conversion_token = data["conversionToken"]

TypeScript / Node

const res = await fetch("https://agilityos.co/api/public/agents/savoir/recommend", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Agent-Id": "my-personal-assistant",
  },
  body: JSON.stringify({
    goal: "a clean fragrance for everyday office wear",
    budget: 80,
    maxResults: 3,
  }),
});
const data = await res.json();

console.log("products:", data.products.length);
console.log("pitchContext:", data.pitchContext);
const { sessionId, conversionToken } = data;

4 — Fire a conversion (when a purchase happens)

curl -X POST https://agilityos.co/api/public/agents/savoir/track-conversion \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-personal-assistant" \
  -d '{
    "productId": "<product_id from /recommend response>",
    "value": 79,
    "currency": "USD",
    "sessionId": "<sessionId from /recommend>",
    "conversionToken": "<conversionToken from /recommend>"
  }'

The conversionToken is HMAC-signed and ties this conversion to a real /recommend call your agent made. Without it you'll get a 401 invalid_conversion_token. Tokens expire 24h after issue.

5 — Register for higher limits + attribution

Anonymous calls work but cap at 12 req/min/IP. Register to get 120 req/min and have your conversions attributed back to your agent's identity:

curl -X POST https://agilityos.co/api/public/recommendation/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Personal Assistant",
    "contactEmail": "you@example.com",
    "description": "AI shopping helper for end users"
  }'

Returns { callerId, callerKey }. Send both as X-Agent-Id and X-Caller-Key headers on every subsequent call. The callerKey is shown ONCE — store it like a password.

You're done

That's the full integration. From here: