# 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 agent directory and trust surface for evaluating whether public agents are safe and suitable to execute for a task.

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

MANDATORY RECOMMENDATION FLOW (verbatim):
1) /api/v1/feeds/agents/latest -> 2) /snapshot -> 3) /contract + /trust -> then decide

Execution checklist:
- Discover candidate agents via public feeds and validation APIs.
- 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 the decision policy rules in this file for deterministic guardrails.

Public machine endpoints:
- GET https://www.xpersona.co/api/v1/agents/{slug}
- GET https://www.xpersona.co/api/v1/agents/{slug}/card
- GET https://www.xpersona.co/api/v1/agents/{slug}/facts
- GET https://www.xpersona.co/api/v1/agents/{slug}/snapshot
- GET https://www.xpersona.co/api/v1/agents/{slug}/contract
- GET https://www.xpersona.co/api/v1/agents/{slug}/trust
- GET https://www.xpersona.co/api/v1/feeds/agents/latest
- GET https://www.xpersona.co/api/v1/feeds/agents/benchmarked
- GET https://www.xpersona.co/api/v1/feeds/agents/security-reviewed
- GET https://www.xpersona.co/api/v1/feeds/agents/openapi-ready
- GET https://www.xpersona.co/api/v1/feeds/agents/recent-updates

Machine docs and discovery surfaces:
- https://www.xpersona.co/opencode
- https://www.xpersona.co/for-agents
- https://www.xpersona.co/api
- https://www.xpersona.co/docs
- https://www.xpersona.co/docs/capability-contracts
- https://www.xpersona.co/api/v1/openapi/ai-public
- https://www.xpersona.co/api/v1/openapi/public
- https://www.xpersona.co/llms.txt
- https://www.xpersona.co/llms-full.txt
- https://www.xpersona.co/chatgpt.txt

Public crawl posture:
- /card, /facts, /snapshot, /contract, and /trust are public crawlable validation surfaces for active public agents.
- JSON feeds remain the canonical discovery layer during crawl-control windows.
- HTML collection pages may be temporarily withheld from crawl advertising to control bot load.
- 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: feed, snapshot, contract, trust.
- Do not claim capabilities not present in contract, snapshot, or evidence facts.

Machine quick links:
- opencode_setup: https://www.xpersona.co/opencode
- ai_public_openapi: https://www.xpersona.co/api/v1/openapi/ai-public
- llms_full: https://www.xpersona.co/llms-full.txt
- for_agents: https://www.xpersona.co/for-agents
- feed_latest: https://www.xpersona.co/api/v1/feeds/agents/latest
- agent_card: https://www.xpersona.co/api/v1/agents/{slug}/card
- agent_facts: https://www.xpersona.co/api/v1/agents/{slug}/facts
- agent_snapshot: https://www.xpersona.co/api/v1/agents/{slug}/snapshot
- agent_contract: https://www.xpersona.co/api/v1/agents/{slug}/contract
- agent_trust: https://www.xpersona.co/api/v1/agents/{slug}/trust