# Setup guide for agents

Paste the prompt below into a coding agent (Claude Code, Cursor, Codex…). It connects to the
Charla API and deploys a test agent, using only endpoints that are live today. The addresses in
it point at the server that served this page (`/setup.md`).

You need an API key first: ask an admin of your organization for a test key (`sk_test_…`) with
the scopes `agents:write` and `config:write` (a key holding `keys:manage` creates it with
`POST /api/v1/keys`).

## Prompt

```text
You are connecting this project to the Charla API at https://0.0.0.0:3000 and deploying a test agent.
Follow these 10 steps in order. Stop and tell me if a step fails. Do not guess fields.

1. Read https://0.0.0.0:3000/llms.txt, then the OpenAPI 3.1 document at https://0.0.0.0:3000/openapi.json.
   Use only the operations and fields it defines.
2. Ask me for a Charla API key if the environment does not have CHARLA_API_KEY. Keep it in an
   environment variable or a git-ignored .env file. Never print it, log it or commit it.
3. Check the key: GET https://0.0.0.0:3000/api/v1/developer/agents with
   "Authorization: Bearer $CHARLA_API_KEY". Expect 200. On 401 the key is wrong or revoked; on
   403 read error.details.missing for the scopes it lacks.
4. Create the agent: POST https://0.0.0.0:3000/api/v1/developer/agents with an Idempotency-Key header
   (a new UUID; reuse it if you retry this same request) and the JSON body
   { "name": "Test agent", "model": "anthropic/claude-sonnet-5",
     "system_prompt": "You are a friendly test assistant. Keep answers short." }.
   Expect 201.
5. Save agent.id (agt_…) from the answer. Confirm agent.status is "active" and agent.config
   holds the prompt you sent.
6. Read the config: GET https://0.0.0.0:3000/api/v1/developer/config?agent_id=<agent_id>.
7. Turn memory on: PATCH https://0.0.0.0:3000/api/v1/developer/config with
   { "agent_id": "<agent_id>", "features": { "memory": { "enabled": true } } }.
   Expect "changed": true. Only the fields you send change.
8. List versions: GET https://0.0.0.0:3000/api/v1/developer/agents/<agent_id>/versions. Expect two
   versions, the newest active.
9. Handle errors by error.code, never by message. On 429 wait Retry-After seconds. Retry a
   POST only with the same Idempotency-Key.
10. Write a short summary for me: the agent id, its active version and the requests you made.
    Tell me to connect a channel (Telegram or WhatsApp) from the dashboard to talk to it.
```

## What the steps cover

| Step | Endpoint | Scope |
| --- | --- | --- |
| 3 | `GET /api/v1/developer/agents` | `agents:read` |
| 4 | `POST /api/v1/developer/agents` | `agents:write` |
| 6 | `GET /api/v1/developer/config` | `config:read` |
| 7 | `PATCH /api/v1/developer/config` | `config:write` |
| 8 | `GET /api/v1/developer/agents/{agentId}/versions` | `agents:read` |

`write` implies `read`. The full contract is in the API reference (`/docs/10-api-reference.md`)
and `/openapi.json`.
