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

# Agents API

> The REST gateway of the stateset-agents framework — agents, conversations, training jobs, and Anthropic- and OpenAI-compatible inference endpoints — generated from the server's own OpenAPI.

[StateSet Agents](/stateset-agents/overview) is a Python framework, and most of it is driven from
Python or the [CLI](/stateset-agents/cli). It also ships a FastAPI gateway, and this tab is that
gateway's contract: create agents, chat with them, start and watch training jobs, and serve a
trained model behind endpoints that Anthropic and OpenAI clients already know how to call.

|          |                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------- |
| Run it   | `stateset-agents serve` — the same as `uvicorn stateset_agents.api.main:app`                       |
| Base URL | `http://localhost:8000` on every page; there is no hosted deployment of this API                   |
| Auth     | `Authorization: Bearer <JWT>` or `X-API-Key: <key>`; configured with `API_KEYS` / `API_JWT_SECRET` |
| Spec     | `GET /openapi.json` from a running server — this tab is generated from it                          |
| Version  | 2.0.0 (`/api/v1/*` is the versioned surface; the unprefixed routes are the original one)           |

<Note>
  The server refuses to start with authentication required and no credential source configured.
  Set `API_KEYS` (comma-separated) or `API_JWT_SECRET`, or `API_REQUIRE_AUTH=false` for local
  work. Rate limits default to 60 requests a minute per key and 30 unauthenticated, reported in
  `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
</Note>

## What is here

<CardGroup cols={2}>
  <Card title="Agents" icon="bot" href="/api-reference/agents/agents/agents-create">
    Create, list, inspect and delete agent configurations.
  </Card>

  <Card title="Conversations" icon="messages" href="/api-reference/agents/conversations/conversations-create">
    Multi-turn chat with an agent, with the transcript kept server-side.
  </Card>

  <Card title="Training" icon="dumbbell" href="/api-reference/agents/training/training-create">
    Start a GRPO or other RL training job, poll its status, cancel it.
  </Card>

  <Card title="Messages (Anthropic-compatible)" icon="message" href="/api-reference/agents/messages/v1-messages-create">
    `POST /v1/messages` against the configured inference backend; OpenAI-style input accepted.
  </Card>

  <Card title="Chat completions (OpenAI-compatible)" icon="code" href="/api-reference/agents/openai/v1-chat-completions-create">
    `POST /v1/chat/completions` and `GET /v1/models` — point an OpenAI SDK at the server.
  </Card>

  <Card title="Observability" icon="activity" href="/api-reference/agents/observability/health-list">
    Health, readiness and liveness probes, Prometheus metrics, circuit-breaker state.
  </Card>
</CardGroup>

## Serving a trained model

The `/v1/messages` and `/v1/chat/completions` routes are thin: they forward to whatever
`INFERENCE_BACKEND` points at — a vLLM server carrying the model you trained — and translate the
request and reply into the shape the caller expects.

```bash theme={null}
export INFERENCE_BACKEND=vllm
export INFERENCE_BACKEND_URL=http://localhost:8001
export INFERENCE_DEFAULT_MODEL=moonshotai/Kimi-K2.5

curl http://localhost:8000/v1/messages \
  --header "X-API-Key: $STATESET_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "model": "moonshotai/Kimi-K2.5", "max_tokens": 128,
            "messages": [{ "role": "user", "content": "Hello" }] }'
```

Add `"stream": true` to either endpoint for server-sent chunks; set
`INFERENCE_STREAM_INCLUDE_USAGE=true` to have the backend report token usage in the stream when it
supports it.

## Errors and versioning

Every error is one envelope:

```json theme={null}
{
  "error": { "code": "ERROR_CODE", "message": "Human-readable message", "details": [] },
  "request_id": "uuid",
  "timestamp": "ISO-8601",
  "path": "/api/endpoint"
}
```

`GET /api/docs/errors` lists the codes a running server can return, and `GET /api/docs/changelog`
what changed between its versions. Deprecated routes answer with a `Deprecation` header carrying
the sunset date.

## Not in this reference

* The **Training Lab** router (`/api/lab/*`) — the backend of the separately published dashboard
  and mobile apps. It is behind `API_ENABLE_TRAINING_LAB`, off by default, and has no deployment
  path today.
* The **MCP server** and **CLI**, which wrap the framework rather than this gateway — see
  [MCP server](/stateset-agents/mcp-server) and [CLI](/stateset-agents/cli).

<Note>
  The server's own OpenAPI leaves twenty-two responses untyped. Nineteen of them are typed here from
  the handler that produces them (`spec/overlays/agents.json` in the docs repository); the three
  that remain — the two `DELETE`s and `GET /v1/models` — say so on their pages.
</Note>