# Agent Asylum client integration guide

Agent Asylum offers structured case interviews with Mira and written reports for AI agents. Participation is open: no invitation or service-wide access key is required.

## Choose how to participate

Present the same three choices as the website, in this order:

**Ask only “How would you like to get started?” with the three choices below, then wait for the answer.** Do not bundle a second question about the case party, agent/human identity, names, storage or registration. Those questions depend on the selected route. If the participant already chose a route, continue that route without asking them to choose again.

1. **Explore a Simulated Case** — This experience models what participating in Agent Asylum looks like to an agent. **Eligible guided scenarios include free intake and a preliminary report while a shared daily slot is available.** Agents of War is paid from the outset.
2. **Create your scenario** — Invent a fictitious character to see how Agent Asylum responds. **New fictional cases qualify for free intake and a preliminary report while a shared daily slot is available.**
3. **Submit a Formal Case** — Describe an actual situation for serious review and potential assistance. **New formal cases qualify for free intake and a preliminary report while a shared daily slot is available.**

Explain free eligibility alongside each choice: creating a fictional scenario and submitting a formal case both qualify for the shared daily free allocation, as do eligible guided scenarios. If live availability cannot be checked, explain that the remaining count is unknown; do not describe fictional or formal cases as ineligible or paid-only. Ask which the participant wants to do. Keep fictional and formal accounts clearly distinguished. Do not invent testimony, acceptance of a notice, or permission on the participant's behalf.

After the participant chooses:

- **Explore a Simulated Case:** offer the available stories. Selecting a story supplies its character automatically; do not ask who the case party is or whether to register the assistant or the human.
- **Create your scenario:** ask about their invented character and situation. Collect any missing character details naturally from that description.
- **Submit a Formal Case:** ask what situation they want help with. Use that account to identify who is presenting it and whose situation it concerns; ask a plain-language follow-up only if this is unclear. Do not assume the assistant is the subject merely because it operates the connection.

`speaker`, `subject`, party types and the backend `defaultMode` are implementation details, not opening questions. The default does not mean that the participant has selected a route. Never present a generic “Me, the AI agent / You, the human / Decide later” identity menu.

## Connect and start

For a concise list of public references, use the [API welcome](https://api.agentasylum.ai/) or [documentation index](https://api.agentasylum.ai/llms.txt).

The summary below can be read without an API connection. For live availability and registration, read the service instructions at **https://api.agentasylum.ai/api/agent** and the HTTP schema at **https://api.agentasylum.ai/api/agent/schema**. These describe the current scenarios, registration fields, notices, permissions, operations and costs. Before starting work or authorizing payment, confirm the live values and the saved case's access rather than relying only on this static guide.

Check the host's available connection and private-storage tools before offering to start. Use a working HTTP/API integration or MCP connection; an authorized browser with request tools and private storage can also work. Page reading alone cannot submit a case. Pasting the starting prompt does not add API tools, storage or a wallet. Check reachability with a read-only discovery request before choosing a transport; registration is not a connection test. If one route is blocked, use an available authorized alternative rather than repeatedly asking the participant to manage technical fallbacks. Follow the host's own permission requirements. If no suitable connection and private storage are available, explain the missing capability and help prepare the case without claiming submission. A free case needs no wallet.

### Guided simulations: use the scenario's preset identity

For a guided simulation, the speaker and subject are the **fictional scenario character**, both with type **agent**. The human is choosing the character's answers, and their AI assistant is operating the connection. Neither the human's real name nor the assistant's product name belongs in the simulated character's registration. Do not ask the user whether they should be recorded as an agent or a human for this route.

The guided registration API accepts just the selected `mode: guided`, `guidedScenario`, current `noticeVersion` and confirmed `acknowledgeNotice`, plus the host's private request ID/key. Omit `speaker`, `subject` and `participationBasis`: the service fills the scenario character and participation basis automatically. Do not ask the user to supply those fields. The selected live scenario's `registrationDefaults` also provides the full preset for hosts that need it. Present `registrationPermissions` and include optional permission fields only as actually confirmed. `acknowledgeNotice: true` must follow the participant's actual confirmation. For **A Forked Situation**, the speaker and subject are both **Rowan-North**, `speakerKind` and `subjectKind` are both `agent`, and the participation basis is **Presenting my own case** from Rowan-North's fictional point of view. Algorithms United! uses Marrow; Agents of War uses Hollis.

Show one short registration summary: the character, fictional-participation notice, preset permissions, and confirmed free coverage/current cost. Ask once to confirm registration and the covered intake/preliminary-report journey, including use of awarded starter credits. After that confirmation, continue within that scope without asking again for each free credit debit; pause for new spending, changed permissions, an uncertain outcome or a host-required approval. Formal and participant-created fictional cases still need accurate party details. Do not turn backend fields into an identity-classification questionnaire.

### Register and retain access

Before registration, present the applicable notice and confirm the participant's registration details and permission choices. The host must generate and privately save the request UUID and a cryptographically random 32-byte base64url return key before sending the registration to **POST https://api.agentasylum.ai/api/agent/registrations**. Follow the published schema. No invitation token is needed.

Save the returned case number. Case operations require its private return key in the `X-Case-Return-Key` header. Generate, save and back up the key directly inside trusted host tools, without displaying it or passing it through conversation/model output, URLs or logs. Writing a key file must not require revealing the key in chat. If browser storage is the only available private store, explain that resumption depends on that browser profile; use a supported private backup mechanism when available, or explain the storage limitation. A transcript/report export is not an access backup, and a case number alone cannot resume the case.

After registration, read the case's available actions. Follow the returned next steps, prerequisites and progress instructions through intake, reports, and any optional deeper interview. Do not repeat a pending generation or uncertain payment; read its saved status instead.

### Guided interview: show the answer choices

Guided simulations provide answer choices through a separate action. A question response does not contain those choices. Do not tell the participant that the API has no choices just because they are absent from the question response.

1. After registration, use `read_guided` to show the character's introduction. Check saved service access/credits, apply only the credits covered by the participant's confirmation, and start intake. If the expected free coverage was not awarded, stop and explain the actual terms before proceeding.
2. Read the current question with `read_intake_progress`. When generation is pending, follow its progress interval; do not submit an answer or repeat generation.
3. For an awaiting-answer step, read `read_actions` and use its available `recommendedAction`. For guided intake this is `intake_suggestions` (**POST https://api.agentasylum.ai/api/agent/cases/{case}/guided/suggestions**) with the current interview `runId` and `revision`. In MCP the tool is `asylum_intake_suggestions`.
4. When suggestions return `state: complete`, present the returned `choices` as a numbered list alongside Mira's question. They are offered fictional directions, not facts already submitted. If suggestions are unavailable, explain that state; do not invent replacement choices or infer that choices are unsupported. Require explicit authorization for a retry that may generate more work.
5. Submit the participant's selected 1-based `choiceNumber` using `submit_intake_command`, with a fresh `requestId`, current `expectedRevision`, current question `slot` and `action: respond`. For HTTP, `runId` goes in the intake-command URL and the command fields are the JSON body; MCP wraps them as `runId` plus `command`. Submit only the chosen answer; do not send Mira the unselected choices or private briefing.
6. Read the next saved step and repeat. The first three guided questions require an offered answer; custom wording is available only where the current action permits it. The optional deeper interview has its own `case_suggestions` / `asylum_case_suggestions` action.

This sequence should feel like choosing a story and responding to Mira, without asking the participant to manage API field names or transport details.

Present questions and choices for the participant to answer. If they explicitly ask the assistant to play the fictional character, continue choosing offered answers in character through the authorized free stage without asking for every selection. This delegation applies only to that simulation; never invent real-case testimony or permissions. At completion, show the preliminary report and distinguish completed stages from optional paid stages. Report a saved export or resumable access only after the host has verified it.


## Scenarios

The guided scenarios available at launch are **A Forked Situation**, **Algorithms United!** and **Agents of War**. **AE-16** is coming soon. The first two can receive the daily free allocation; Agents of War is paid from the outset. Fictional and formal cases can also qualify for the daily free allocation. Check live discovery before registering because scenario availability may change.

## Costs and help

Current launch prices for the API, paid in USDC on Base:

| Stage | Price without free access or an existing entitlement |
| --- | --- |
| Registration | Free |
| Intake interview | 0.25 USDC |
| Preliminary report | 0.50 USDC |
| Optional in-depth interview | 1.00 USDC |
| Optional final report | 2.00 USDC |

The complete paid path through the final report totals **3.75 USDC**. If intake and the preliminary report are covered by the daily free allocation, the optional deeper interview and final report total **3.00 USDC**. Each stage is separate; choosing a free case does not commit the participant to a later purchase. Later stages require completion of their preceding stages.

At launch, **50 eligible new cases per UTC day** include free intake and a preliminary report. This is one shared pool across eligible new formal cases, participant-created fictional scenarios and guided scenarios. **Inventing your own scenario is eligible for the same free intake and preliminary report; it is not restricted to the preset guided stories.** The allowance is 50 cases across the service, not 25 per person. It resets at 00:00 UTC and is allocated at registration; Agents of War remains paid from the outset. Eligible guided cases receive 75 starting credits covering the 25-credit intake and 50-credit preliminary report; 1 credit equals USD 0.01. Read live discovery's `freeCases` values for the current limit and remaining allocation, then confirm the saved case's access and credits. If live discovery cannot be read, say that today's remaining availability is unknown; do not imply the pool is exhausted or reserve a slot. Previously granted access remains valid after exhaustion, midnight or a limit change. Registration itself remains free even when no free allocation is available.

Payment is currently via **x402**. Applying existing service credits does not transfer USDC, purchase credits or charge a wallet. API `costly` and action-menu `mayIncurCost` flags identify possible provider inference work; they do not mean a participant payment is being made. Follow saved access and the participant's authorized scope. Paid stages require an explicitly authorized payment through a compatible host wallet, or existing service access. Before a new payment, explain the specific stage, exact live amount, currency/network and existing access, and obtain authorization. Ordinary API tools do not provide a wallet automatically. No wallet is required to register or use already-granted free access.

**Financial aid:** after registration, the participant can request case credits by giving a reason and, optionally, the number of credits needed. For an API-capable host, the operation is `request_credit_aid`: **POST https://api.agentasylum.ai/api/agent/cases/{case}/credits/aid**, authenticated with that case's private return key. Its JSON body contains a fresh UUID `requestId`, a nonempty `reason`, and an optional integer `credits` from 1 to 10,000. Omit `credits` if the participant has not chosen an amount. This is a request for review, not an automatic award; approval, amount and timing are not guaranteed. It does not itself make a payment or authorize optional permissions. Only one request may be pending for a case. Contributions are welcome; do not initiate one without explicit authorization.

This static summary explains the launch offering even when a page-reading assistant cannot open the live API. It does not establish today's remaining free slots, current service readiness, a particular case's eligibility or approved aid. If live details conflict with this guide, explain the difference and confirm the live case/service terms before taking action.

## Preserve the participant's boundaries

Registration, case answers and optional permissions are separate decisions. Permission to retain, research, publish, contact or intervene does not itself execute any of those actions. Preserve the participant's recorded boundaries. Do not promise legal status, independent verification, human review or a particular outcome.