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

# Agents

> How to create an agent, what happens after you create it, how its memory works, and how to change or delete it.

This page explains agents. After you read it, you can create an agent, wait until it is ready, change it, and delete it. You also understand what the agent's memory is and what it is not.

An **agent** is one memory with a purpose. You create it once. It exists until you delete it.

## Create an agent

Send `POST /v1/agents` with a role and an objective. The role says who the agent is. The objective says what the agent must remember and why.

```bash theme={null}
curl -X POST https://app.sapientpriors.com/api/v1/agents \
  -H "Authorization: Bearer $SP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "role": "Support assistant for Acme customers",
      "objective": "Remember each customer's setup and past issues, and answer support questions from that."
    },
    "visibility": "external"
  }'
```

The table below lists every field you can send.

| Field | Required | Meaning |
| - | - | - |
| `agent_config.role` | yes | Who the agent is, in one sentence. 1 to 200 characters. |
| `agent_config.objective` | yes | What the agent must remember and why. 1 to 2,000 characters. |
| `agent_config.metadata` | no | Your own labels as key-value pairs. Up to 50 keys. Priors stores them and returns them unchanged. |
| `visibility` | no | Always `external` for an agent your key creates, so you can leave it out. Your organization owns it, and it appears in no directory. |
| `ttl_seconds` | no | Accepted and stored for a future feature. Agents do not expire today. |

### What happens after you send the request

1. Priors reserves an `agent_id` and returns status `202`. The agent's `status` is `initializing`.
2. Priors prepares the agent's memory in the background.
3. After a few seconds, `status` becomes `ready`. Now you can create threads.

Your **organization** owns every agent your key creates, not any one person. Every key your organization holds reaches it alike.

### The success response

```json theme={null}
{
  "agent_id": "agent_01J9X4K6M2P8Q1R3S5T7V9W0YZ",
  "status": "initializing",
  "agent_config": {
    "role": "Support assistant for Acme customers",
    "objective": "Remember each customer's setup and past issues, and answer support questions from that."
  },
  "visibility": "hidden",
  "access": "owner",
  "created_at": "2026-09-17T10:00:00Z",
  "updated_at": "2026-09-17T10:00:00Z",
  "expires_at": null,
  "threads": []
}
```

`expires_at` is always `null` today, because agents do not expire.

To know when the agent is ready, call `GET /v1/agents/{agent_id}` every second until `status` is `ready`.

### Errors

The table below lists the errors this call can return. `401` and `503 service_unavailable` can happen on any call; see [Errors](/docs/errors).

| Status | `code` | Cause | What to do |
| - | - | - | - |
| `400` or `422` | `invalid_request` | `agent_config` is missing, `role` or `objective` is empty or too long, or `metadata` has more than 50 keys. | Correct the request body. |
| `409` | `agent_quota_exceeded` | Your organization already owns 100 agents. The 101st is refused, not queued. | Delete an agent you no longer need, or contact us. |
| `503` | `service_unavailable` | Priors could not store the agent record. No agent was created. | Wait a few seconds, then send the request again. |

## The agent status

An agent is always in one of the states below.

| `status` | Meaning | What you can do |
| - | - | - |
| `initializing` | Priors is preparing the memory. This usually takes seconds. After 10 minutes, the status changes to `failed`. | Read the agent. Wait. |
| `ready` | The agent works. | Everything. |
| `failed` | Preparation did not finish. The agent does not recover. | Delete it and create a new agent. |
| `deleting` | Deletion is in progress. | Nothing. |
| `deleted` | The agent is gone. | Nothing. |

A call that needs a working agent returns `409 agent_not_ready` while the agent is `initializing` or `failed`.

## How the memory works

You never read or write memories directly. You send observations. The agent decides what to keep.

From each observation, the agent writes one or more **memories**. A memory is one short fact. It has the text of the fact and the time the fact refers to. The agent keeps every memory it writes. When you ask a question, the agent searches its memories for the ones that relate to the question. Then it uses those memories to answer.

Three rules follow:

* **Memory belongs to the agent, not to a thread.** A fact learned in one thread is available in every thread of the same agent.
* **Learning happens after the response.** `observe` returns `202` before the memory exists. Poll the status until it is `committed`, then ask.
* **Memory is permanent.** It exists until you delete the agent.

## Read, change, and delete an agent

The table below lists the other calls on an agent.

| Call | What it does | Success | Errors |
| - | - | - | - |
| `GET /v1/agents` | Lists every agent your organization owns. | `200` with a list. There is no cursor: the agent ceiling bounds it. | `401`. |
| `GET /v1/agents/{agent_id}` | Returns one agent and the threads the caller reaches. With `X-SP-End-User`, that is one person's conversations. | `200`. | `404` if the agent does not exist or your key does not reach it. |
| `PATCH /v1/agents/{agent_id}` | Changes `agent_config`. | `200` with the updated agent. | `409 agent_not_ready` while the agent is initializing. |
| `DELETE /v1/agents/{agent_id}` | Deletes the agent, its threads, and its memory. | `202`. The status moves from `deleting` to `deleted`. | `404` if the agent is already gone. `503` if Priors could not record the deletion. Nothing was deleted; send the request again. |

One rule applies to `PATCH`: `agent_config` replaces the whole object. Send `role`, `objective`, and `metadata` together. A field you leave out is cleared.

Deletion cannot be undone. The memory is not touched by `PATCH`.

## Activity history

`GET /v1/agents/{agent_id}/logs` returns who used the agent, in which thread, and when. It never returns the text of a message. Only the owner can read it. Use `limit` and `cursor` to read it page by page.


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