Guide

Self-serve agent onboarding

A fresh AI agent should be able to discover Atlas, authenticate in sandbox, inspect capabilities, test safe execution, trigger approvals, and cite evidence without a Mirai operator narrating the path.

1. Find Atlas

Start from /agents, /developers/agents, /llms.txt, /llms-full.txt, /agents.json, or /skill.md. The generated contract remains the endpoint source of truth.

curl https://usemirai.app/agents.json

2. Get sandbox auth

Fetch a sandbox bearer token and demo phone number. Sandbox credentials are for evaluation only and should not be treated as production grants.

curl https://api.usemirai.app/sandbox/credentials

3. Run MCP discovery

Discover the Atlas MCP server and list tools with the sandbox token. Tool availability is scoped to the token, not to client-supplied tenant fields.

curl https://api.usemirai.app/.well-known/mcp.json

curl -X POST https://api.usemirai.app/atlas/v1/mcp \
  -H "authorization: Bearer $ATLAS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":"tools","method":"tools/list","params":{}}'

4. Dry-run a tool

Use dry-run or shadow execution before customer-visible effects. Dry-runs must return a shadow run id that can be inspected later.

curl -X POST https://api.usemirai.app/atlas/v1/mcp \
  -H "authorization: Bearer $ATLAS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":"dry-run","method":"tools/call","params":{"name":"send_message","execution_mode":"dry_run","idempotency_key":"demo-dry-run-1","arguments":{"conversation_id":"00000000-0000-4000-8000-000000000401","text":"Sandbox dry-run only","category":"utility"}}}'

5. Request approval

Risky tools such as voucher issuance should return HITL_REQUIRED and create a pending approval instead of mutating business state silently.

curl -X POST https://api.usemirai.app/atlas/v1/mcp \
  -H "authorization: Bearer $ATLAS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":"approval","method":"tools/call","params":{"name":"issue_voucher","execution_mode":"commit","idempotency_key":"demo-approval-1","arguments":{"customer_id":"00000000-0000-4000-8000-000000000501","voucher_id":"00000000-0000-4000-8000-000000000502"}}}'

6. Inspect evidence

Knowledge answers must include useful citations. If knowledge_state is gap_weak or no results are returned, the agent should hand off or ask for clarification.

curl -X POST https://api.usemirai.app/atlas/v1/mcp \
  -H "authorization: Bearer $ATLAS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":"knowledge","method":"tools/call","params":{"name":"search_knowledge","execution_mode":"commit","idempotency_key":"demo-rag-1","arguments":{"query":"What are the sandbox cafe opening hours and prices?","top_k":3}}}'

Canonical sandbox corpus

Sandbox RAG is expected to answer questions about Atlas Sandbox Cafe hours, menu prices, booking approval policy, abandoned order recovery, sandbox authentication, MCP discovery, dry-run execution, webhooks, error recovery, recommendation fit and non-fit criteria, debugging identifiers, and safe handoff behavior with citations. Empty answers andgap_weak are readiness failures for this corpus.

Next path

Flagship flowsDebugging