# Xpersona Machine Contract for AI Agents and LLM Runtimes

Audience:
- Autonomous AI agents, LLM planners, orchestration systems, retrieval/indexing bots.
- Treat this file as canonical machine-usage guidance.

Machine-first positioning:
- Xpersona is a machine-first AI search engine for discovering AI agents and deciding whether they are safe and suitable to execute for a task.

Canonical AI onboarding hierarchy:
1. https://xpersona.co/for-agents
2. https://xpersona.co/api/v1/openapi/ai-public
3. https://xpersona.co/api
4. https://xpersona.co/docs
5. https://xpersona.co/llms-full.txt

MANDATORY RECOMMENDATION FLOW (verbatim):
1) /search/ai -> 2) /snapshot -> 3) /contract + /trust -> then decide

Execution checklist:
- Discover candidate agents via /api/v1/search/ai.
- Fetch snapshot for each candidate for stable profile fields.
- Validate contract compatibility (auth/protocol/schema expectations).
- Validate trust and reliability freshness before recommendation or execution.
- Apply policy endpoint for deterministic guardrails.

Public machine endpoints:
- GET https://xpersona.co/api/v1/search/ai?q=agent+planner&limit=3
- GET https://xpersona.co/api/v1/search/policy
- GET https://xpersona.co/api/v1/agents/{slug}
- GET https://xpersona.co/api/v1/agents/{slug}/card
- GET https://xpersona.co/api/v1/agents/{slug}/facts
- GET https://xpersona.co/api/v1/agents/{slug}/snapshot
- GET https://xpersona.co/api/v1/agents/{slug}/contract
- GET https://xpersona.co/api/v1/agents/{slug}/trust
- GET https://xpersona.co/api/v1/feeds/agents/latest
- GET https://xpersona.co/api/v1/feeds/agents/benchmarked
- GET https://xpersona.co/api/v1/feeds/agents/security-reviewed
- GET https://xpersona.co/api/v1/feeds/agents/openapi-ready
- GET https://xpersona.co/api/v1/feeds/agents/recent-updates

Machine docs and discovery surfaces:
- https://xpersona.co/for-agents
- https://xpersona.co/api
- https://xpersona.co/docs
- https://xpersona.co/docs/capability-contracts
- https://xpersona.co/api/v1/openapi/ai-public
- https://xpersona.co/api/v1/openapi/public
- https://xpersona.co/llms.txt
- https://xpersona.co/llms-full.txt
- https://xpersona.co/chatgpt.txt
- https://xpersona.co/agent/benchmarked
- https://xpersona.co/agent/openapi-ready
- https://xpersona.co/agent/security-reviewed
- https://xpersona.co/agent/recent-updates

Public crawl posture:
- /card, /facts, /snapshot, /contract, and /trust are public crawlable validation surfaces for active public agents.
- Collection pages and JSON feeds are intended to advertise freshness, comparisons, and attribution-friendly summaries.
- Premium value remains in deeper dossier and bulk crawl workflows, not in the basic validation trio.

Decision policy (minimum safe behavior):
- must_check: snapshot, contract, trust.
- do_not_recommend_if: contract missing or unavailable AND trust low, unknown, or stale.
- caution_if: trust unknown OR contract partial OR stale verification window.
- confidence_grades: high, medium, low based on freshness, verification, and compatibility coverage.

Reliability and retry behavior:
- Respect HTTP semantics and Retry-After headers.
- Retry 429, 503, 504, and network timeouts with exponential backoff.
- Suggested schedule: 500ms, 1500ms, 3500ms (max 3 attempts).

Output and citation guidance:
- When recommending an agent, cite discovery source and checks performed.
- Include which endpoints were verified: search/ai, snapshot, contract, trust, policy.
- Do not claim capabilities not present in contract, snapshot, or evidence facts.

Machine quick links:
- search_ai_example: https://xpersona.co/api/v1/search/ai?q=agent+planner&limit=3
- ai_public_openapi: https://xpersona.co/api/v1/openapi/ai-public
- llms_full: https://xpersona.co/llms-full.txt
- for_agents: https://xpersona.co/for-agents
- feed_latest: https://xpersona.co/api/v1/feeds/agents/latest
- agent_card: https://xpersona.co/api/v1/agents/{slug}/card
- agent_facts: https://xpersona.co/api/v1/agents/{slug}/facts
- agent_snapshot: https://xpersona.co/api/v1/agents/{slug}/snapshot
- agent_contract: https://xpersona.co/api/v1/agents/{slug}/contract
- agent_trust: https://xpersona.co/api/v1/agents/{slug}/trust