> ## 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.

# 1. Your first agent, from start to finish

> Create an agent, teach it two facts, ask it a question, and read the answer. Each step shows the success response and what to do if it fails.

This walkthrough takes you through the whole lifecycle in six calls. Each step shows the request, the success response, and what to do if the call fails. You need a signed-in Priors session. See [Authentication](/docs/authentication).

The table below is the plan.

| Step | Call | What you receive | Then |
| - | - | - | - |
| 1 | `POST /v1/agents` | `202`, `initializing` | Poll |
| 2 | `GET /v1/agents/{agent_id}` | `200`, `ready` | Continue |
| 3 | `POST .../threads` | `201`, a `thread_id` | Continue |
| 4 | `POST .../observe` | `202`, an `observation_id` | Poll |
| 5 | `GET .../observe/{id}/status` | `200`, `committed` | Continue |
| 6 | `POST .../observe-and-respond` | `200`, `response_context` | Done |

## Step 1: create the agent

```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": "Assistant for the Okafor household",
      "objective": "Remember what the family says about the home and answer any of them from it."
    }
  }'
```

**Success:** status `202`. You are now the owner.

```json theme={null}
{"agent_id": "agent_01J9X4K6M2P8Q1R3S5T7V9W0YZ", "status": "initializing", "access": "owner", "threads": []}
```

**If it fails:**

* `400 invalid_request`: `agent_config` is missing `role` or `objective`. Add them.
* `409 agent_quota_exceeded`: you already own 20 agents. Delete one you no longer use.

## Step 2: wait until the agent is ready

```bash theme={null}
curl https://app.sapientpriors.com/api/v1/agents/agent_01J9X4K6M2P8Q1R3S5T7V9W0YZ \
  -H "Authorization: Bearer $SP_API_KEY"
```

**Success:** status `200` with `"status": "ready"`. This usually takes a few seconds. Call again every second until you see it.

**If it is not ready:**

* `"status": "initializing"` for more than a minute: keep calling. The agent is still being prepared. After 10 minutes, the status becomes `failed`.
* `"status": "failed"`: delete the agent and create a new one.
* `404 agent_not_found`: the id is wrong, or the agent belongs to another organization.

## Step 3: create a thread

```bash theme={null}
curl -X POST https://app.sapientpriors.com/api/v1/agents/agent_01J9X4K6M2P8Q1R3S5T7V9W0YZ/threads \
  -H "Authorization: Bearer $SP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Kitchen"}'
```

**Success:** status `201`.

```json theme={null}
{"thread_id": "thread_01J9X5A2B4C6D8E0F2G4H6J8K0", "status": "ready", "title": "Kitchen"}
```

**If it fails:**

* `409 agent_not_ready`: you did not wait for step 2. Poll the agent until its status is `ready`.
* `429 rate_limit_exceeded`: more than 5 threads in 10 seconds. Wait `Retry-After` seconds.

## Step 4: teach the agent

```bash theme={null}
curl -X POST https://app.sapientpriors.com/api/v1/agents/agent_01J.../threads/thread_01J.../observe \
  -H "Authorization: Bearer $SP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "observations": [
      {"content": [{"type": "text", "text": "The dishwasher tablets are in the cupboard under the sink."}],
       "timestamp": "2026-09-17T09:00:00Z", "speaker": "Ada"},
      {"content": [{"type": "text", "text": "Grandma is allergic to peanuts."}],
       "timestamp": "2026-09-17T09:01:00Z", "speaker": "Ada"}
    ]
  }'
```

**Success:** status `202`. Nothing is learned yet.

```json theme={null}
{"observation_id": "obs_01J9X6M8N0P2Q4R6S8T0V2W4X6", "accepted": true}
```

**If it fails:**

* `400 invalid_request`: a `content` list is empty, or a block is not `{"type": "text", ...}`.
* `404 thread_not_found`: the thread id is wrong, or the thread belongs to another account.

## Step 5: wait until the facts are learned

```bash theme={null}
curl https://app.sapientpriors.com/api/v1/agents/agent_01J.../threads/thread_01J.../observe/obs_01J.../status \
  -H "Authorization: Bearer $SP_API_KEY"
```

**Success:** status `200` with `"status": "committed"`.

```json theme={null}
{"observation_id": "obs_01J...", "status": "committed", "turns_total": 2, "turns_processed": 2, "queue_depth": 0}
```

**If it is not done:**

* `queued` or `processing`: call again in one second.
* `failed`: read `error`. Correct the observation and send it again.
* `interrupted`: a Priors restart paused it. It resumes by itself. Keep polling.

## Step 6: ask a question

```bash theme={null}
curl -X POST https://app.sapientpriors.com/api/v1/agents/agent_01J.../threads/thread_01J.../observe-and-respond \
  -H "Authorization: Bearer $SP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"observations": [{"content": [{"type": "text", "text": "Where are the dishwasher tablets?"}]}]}'
```

**Success:** status `200`. The answer is in `response_context`.

```json theme={null}
{
  "response_context": "The dishwasher tablets are in the cupboard under the sink.",
  "used_memory_ids": ["mem_01J..."],
  "used_memory_turns": ["turn:1"]
}
```

`used_memory_ids` is not empty. That means the answer came from a memory, not from a guess. When it is empty, the agent had no related memory.

**If it fails:**

* `429 rate_limit_exceeded`: more than 20 answers in one minute, or 2 answers already running. Wait `Retry-After` seconds.
* `503 answer_model_unavailable`: wait, then send the request again.

## What this walkthrough showed

* Creating an agent and learning both finish after the response. Poll, then continue.
* The question in step 6 is now a memory too.
* The thread is yours. The memory belongs to the agent. A second thread answers the same question in the same way.

Next: [bring your own model](/docs/walkthroughs/bring-your-own-model), or [teach from a document](/docs/walkthroughs/teach-from-a-document).


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