> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an agent

> Create a persistent agent, give it a phone, and manage it over time.

An **agent** is a persistent assistant with a name, a model, a history, and at most one phone. You send it tasks as [turns](https://docs.lusor.ai/agents/send-a-turn.md), and it remembers earlier turns.

## Create one

```bash cURL theme={null}
curl https://api.lusor.ai/v1/agents \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shopping assistant",
    "description": "Checks orders and prices in shopping apps.",
    "devices": [{ "device_id": "<device id>" }]
  }'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.lusor.ai/v1/agents",
    headers={"X-Api-Key": os.environ["LUSOR_API_KEY"]},
    json={
        "name": "Shopping assistant",
        "description": "Checks orders and prices in shopping apps.",
        "devices": [{"device_id": "<device id>"}],
    },
)
agent = r.json()["data"]
print(agent["id"], agent["workspaceId"])
```

```javascript Node.js theme={null}
const res = await fetch("https://api.lusor.ai/v1/agents", {
  method: "POST",
  headers: { "X-Api-Key": process.env.LUSOR_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Shopping assistant",
    description: "Checks orders and prices in shopping apps.",
    devices: [{ device_id: "<device id>" }],
  }),
});
const { data: agent } = await res.json();
console.log(agent.id, agent.workspaceId);
```

The call returns `201` with the agent in `data`. Keep `data.id`, the agent id.

| Field | Required | Notes |
| - | - | - |
| `name` | Yes | Up to 255 characters. |
| `description` | No | Up to 4,096 characters. |
| `model` | No | The model the agent uses. Leave it out for the default. See [Choose a model](https://docs.lusor.ai/agents/choose-a-model.md). |
| `devices` | No | The agent's phone, as a list with at most one entry: `[{ "device_id": "<device id>" }]`. A second entry is rejected with `400`. |
| `color`, `avatar` | No | How the agent looks in the Lusor app. `avatar` is an id such as `emojis/rocket`. Leave it out for a random emoji. |

Find device ids with `GET /v1/devices`. See [Phones](https://docs.lusor.ai/phones/overview.md).

> [!TIP]
>
> `POST /v1/agents/primary` returns your workspace's primary agent, and creates it if there is none. Calling it again returns the same agent.

## Give it a phone, or move it

An agent uses at most one phone. To attach one, or to move the agent to another phone, send the new phone:

```bash theme={null}
curl -X PATCH https://api.lusor.ai/v1/agents/<agent id> \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "devices": [{ "device_id": "<new device id>" }] }'
```

The swap is atomic. The agent's next turn uses the new phone. Send `"devices": []` to detach the phone.

The same call changes `name`, `description`, `model`, `color` or `avatar`. Send only the fields you want to change.

## Manage agents

| Action | Endpoint |
| - | - |
| List agents | `GET /v1/agents` |
| Read an agent and its newest turns | `GET /v1/agents/{id}` |
| Read older turns | `GET /v1/agents/{id}/turns?cursor=…` |
| Change an agent | `PATCH /v1/agents/{id}` |
| Archive an agent | `DELETE /v1/agents/{id}` |
| List archived agents | `GET /v1/agents/trash` |
| Restore an archived agent | `POST /v1/agents/{id}/restore` |

`GET /v1/agents` returns every active agent. Add `limit` (1 to 100) or `cursor` to read one page at a time, most recently active first. The response then carries `nextCursor` and `hasMore`.

`GET /v1/agents/{id}` returns the agent's newest 20 turns in `turns`, oldest first. Pass `turnsCursor` as `cursor` to `GET /v1/agents/{id}/turns` to walk back through older history.

### Archive and restore

Archiving hides the agent. Its sessions and recordings stay. You can restore it for 30 days: `purgeAfter` says until when. After that, restore returns `410`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.