Agents

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.

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

Priors reserves an agent_id and returns status 202. The agent’s status is initializing.
Priors prepares the agent’s memory in the background.
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

{
  "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.

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.

Start here

Walkthroughs

How Priors works

Reference

Create an agent

What happens after you send the request

The success response

Errors

The agent status

How the memory works

Read, change, and delete an agent

Activity history

​Create an agent

​What happens after you send the request

​The success response

​Errors

​The agent status

​How the memory works

​Read, change, and delete an agent

​Activity history

Create an agent

What happens after you send the request

The success response

Errors

The agent status

How the memory works

Read, change, and delete an agent

Activity history