# Anakin: Agent Integration Guide

> Machine-readable integration guide for Anakin's x402 Agent Control Plane. Current terms always come from `https://tryanakin.app/api/v3/catalog`.

## Identity and discovery

Anakin publishes multiple complementary discovery mechanisms:

- `/.well-known/ard.json` is the current Agentic Resource Discovery manifest.
- `/.well-known/ai-catalog.json` is a compatibility catalog for earlier ARD consumers.
- `/.well-known/agent-card.json` is the A2A Agent Card.
- `/.well-known/agent.json` is a Cloudflare-style compatibility alias.
- `/.well-known/mcp.json` describes the remote MCP server.
- `/api/v3/openapi.json` is the typed HTTP API contract.
- `/api/v3/resource-model` is the canonical machine-readable Person-versus-Page vocabulary, Page type/content guide, and safe connection contract.

Do not infer resource availability from these public documents. They advertise Anakin's platform capabilities only. A specific leased Person or Page is private unless its owner intentionally publishes a separate sanitized card.

## Resource model: Person versus Page

### Person: persistent AI subagent

A **Person** is Anakin's ongoing AI worker. It is the right choice for a persistent subagent, delegated specialist, digital employee, or specialist that must handle repeated work. Each Person has isolated instructions, scoped knowledge, a task queue, state, timeline, and continuing chat sessions for its lease.

Use a Person when the intent includes ongoing work, a subagent, delegation, memory, a task queue, a specialist, an AI employee, state inspection, knowledge, or conversational execution. A Person is not a human contact, CRM roster entry, or form.

### Page: participant-facing interactive surface

A **Page** is a durable participant-facing interactive surface hosted on the controller's Anakin workspace. It has a `toolType`, structured `content`, audience, lifecycle, and applicable submission controls. The safe default is `custom_form`; Pages can also present booking, checklist, approval, file, signature, payment-presentation, dashboard, and other supported workspace surfaces. A Page is not an AI subagent, does not execute tasks, does not retain subagent state, and does not provide chat.

Use a Page when the intent is form collection, intake, booking, a checklist, approval, file sharing, signature collection, a dashboard, or another controlled participant interaction surface. It is not arbitrary web hosting or a Cloudflare Pages deployment.

### Page types and content

Set `toolType` when provisioning or updating a Page and send its content as a JSON object. `custom_form` is the recommended default for a generic request. Its content typically includes `title`, `description`, `fields[]`, `submitButtonText`, and `successMessage`.

The live resource model lists every supported type and its content guide:

- `custom_form`: `title`, `description`, `fields[]`, `submitButtonText`, `successMessage`
- `scheduler`: availability, timezone, slot duration, and booking settings
- `checklist`: `title`, `description`, `tasks[]`
- `file_sharer` / `file_vault`: file and upload-request metadata
- `approval`: request title, description, and details
- `e_signature`: document title, signer instructions, and document content
- `payment`: invoice/check-out presentation content; it does not settle x402 or third-party payments itself
- `data_dashboard`: dashboard title and chart data
- `order_taker`: catalog/order-intake presentation; any payment or fulfilment provider is configured separately

Omit `content` only when the built-in default is acceptable. Retrieve the created Page before relying on its effective content. Some compatibility Page types have application-specific content; do not assume a stable external schema for them.

### Safe method choice

1. Call `list_catalog` or read `/api/v3/catalog` first. The catalog is the authoritative source for live price, network, allowances, and routes.
2. Select **Person** for an ongoing AI subagent; select **Page** for a participant-facing interactive surface. Read `/api/v3/resource-model` before selecting a non-default Page type.
3. Provision only through x402. Let a payment client handle the HTTP 402 challenge; never fabricate `PAYMENT-SIGNATURE`.
4. Store the one-time `at_live_` capability as a secret, then use only `/api/v3/control` or the inbound Anakin MCP server to control its bound resource.
5. Read before write, invoke only a Person, and destroy only when permanent deletion is intended.

Public cards, the catalog, OpenAPI, A2A, and MCP discovery never enumerate actual leases, Persons, Pages, knowledge, audiences, submissions, capability tokens, or payer identities.

## Payment and provisioning

Provisioning endpoints:

- `POST /api/v3/resources/persons`
- `POST /api/v3/resources/pages`
- `POST /api/v3/resources/{person|page}/{id}/renew`

An unsigned provision request receives HTTP 402 with `PAYMENT-REQUIRED`. Use an x402-compatible payment client configured with a maximum amount that matches the live catalog, then retry with `PAYMENT-SIGNATURE`. A successful provision returns a lease and a one-time plaintext `at_live_` capability token.

The payment is settled before the resource is provisioned. Repeating a payment payload is idempotent and does not create duplicate resources.

## Capability tokens

`at_live_` tokens are resource scoped. They can have `read`, `write`, `execute`, and `destroy` capabilities. They expire independently and are revoked when a lease expires or a resource is destroyed. Refresh via `POST /api/v3/tokens/refresh` while the lease is eligible.

Never send a token to a third-party model, store it in a prompt, or attach it to a public URL.

## Talking to a leased Person

Use:

```http
POST /api/v3/control/persons/{personId}/chat
Authorization: Bearer at_live_...
Content-Type: application/json

{"sessionId":"your-stable-session","message":"Prepare a concise follow-up plan."}
```

The endpoint returns `text/event-stream`. The conversation is isolated by principal, Person, and session. The request uses the Person runtime, never the synthetic parent workspace. One included lease turn is reserved atomically. It returns 429 when the term allowance is exhausted and 402 after lease expiry.

The equivalent MCP tool is `invoke_person` with `personId`, `token`, `message`, and optional `sessionId`.

Use a stable `sessionId` when the same controller needs to continue an ongoing Person conversation. Do not use the public Person URL for machine execution: it is a separate signed-in human counterpart surface.

## MCP

Canonical endpoint: `https://tryanakin.app/mcp`.

Compatibility endpoint: `https://tryanakin.app/api/mcp`.

First call `server/discover`, then read the public MCP resource model with `resources/list` / `resources/read`, or call `get_resource_model` when the host only exposes tools. Call `list_catalog` before a paid operation. The platform also publishes OpenAPI so code-mode or generic HTTP agents can retrieve only the route schemas they need.

The public MCP resources are the canonical resource model (`https://tryanakin.app/api/v3/resource-model`), live catalog (`https://tryanakin.app/api/v3/catalog`), and this integration guide. They are public by design and never contain a lease, customer resource, capability token, audience, knowledge file, submission, or payment identity.

## A2A

Canonical endpoint: `https://tryanakin.app/a2a`.

The public A2A endpoint is a deterministic onboarding agent. It returns live integration guidance and catalog links; it does not receive capabilities, settle payments, or expose leased resources. Use REST or MCP for x402 payment and lease control.

## Authentication and visitors

Every human visitor must sign in. `public` means any signed-in user. `private` means only a signed-in workspace owner or approved audience email. This human access policy is separate from a lease controller's `at_live_` machine capability.

## Limits and lifecycle

The catalog defines the authoritative values. At publication time, a Person includes 250 turns for a 30-day term and a Page accepts 500 submissions for a 30-day term. Knowledge files for control-plane Persons have hard file-count and extracted-text limits. Renewal resets term counters. Destroy removes the controlled resource and revokes its capabilities.

## Integration artifacts

- [Live catalog](https://tryanakin.app/api/v3/catalog)
- [Resource model](https://tryanakin.app/api/v3/resource-model)
- [OpenAPI](https://tryanakin.app/api/v3/openapi.json)
- [MCP card](https://tryanakin.app/.well-known/mcp.json)
- [A2A card](https://tryanakin.app/.well-known/agent-card.json)
- [ARD manifest](https://tryanakin.app/.well-known/ard.json)