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

> The agent resource — what it is, its fields, and the two classes agents fall into.

# Agents

An agent is the unit that resolves customer work. It carries a type, a description, an activation
state, and — for voice agents — a voice model.

An agent on its own does very little. What it's *allowed* to do lives in
[Settings](/response-api-reference/settings), [Rules](/response-api-reference/rules), and
[Functions](/response-api-reference/functions/list). Create the agent, then constrain it.

## Shape

| Field                       | Type   | Notes                            |
| --------------------------- | ------ | -------------------------------- |
| `agent_name`                | string | Display name                     |
| `agent_type`                | string | Which class of agent — see below |
| `description`               | string | What this agent is for           |
| `activated`                 | string | Whether the agent is live        |
| `org_id`                    | string | Owning organisation              |
| `voice_model`               | string | Voice model, for voice agents    |
| `voice_model_id`            | string | Its identifier                   |
| `created_at` / `updated_at` | string | Timestamps                       |

## Endpoints

| Method   | Path              |                                                 |
| -------- | ----------------- | ----------------------------------------------- |
| `GET`    | `/v1/agents`      | [List](/response-api-reference/agents/list)     |
| `GET`    | `/v1/agents/{id}` | [Get](/response-api-reference/agents/get)       |
| `POST`   | `/v1/agents`      | [Create](/response-api-reference/agents/create) |
| `PUT`    | `/v1/agents/{id}` | [Update](/response-api-reference/agents/update) |
| `DELETE` | `/v1/agents/{id}` | [Delete](/response-api-reference/agents/delete) |

## Example

```bash theme={null}
curl https://api.stateset.com/v1/agents \
  -H "Authorization: Bearer $STATESET_API_KEY"
```

```bash theme={null}
curl -X POST https://api.stateset.com/v1/agents \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "agent_name": "Returns Specialist",
    "agent_type": "automation",
    "description": "Handles RMA creation, receipt, and refunds under $100.",
    "activated": "false"
  }'
```

<Tip>
  Create with `activated: "false"`, configure [settings](/response-api-reference/settings) and
  [rules](/response-api-reference/rules), then activate. An agent that goes live before its
  `allowed_intents` are set will act on intents you never approved.
</Tip>

## Two classes of agent

The distinction matters because it determines what you configure.

### Automation agents

The workhorses. They **execute**: trigger functions, integrate with systems, and complete repetitive
work — order management, subscription renewals, inventory checks, returns processing.

Configure these carefully: they take actions with consequences. What matters is
[Functions](/response-api-reference/functions/list) (what they can call),
[Rules](/response-api-reference/rules) (what's forbidden), and the
[review gate](/stateset-response/responsecx-workflow-studio) (what needs a human).

### Analysis agents

These **synthesise**: reasoning over rich data to surface trends, customer-behaviour patterns, and
supply-chain optimisations. [ReasonCX](/response-api-reference/reason) is one of these — it emits
its reasoning alongside its conclusions so a finding can be traced back to the tickets that produced
it.

Configure these for retrieval quality rather than for safety:
[Embeddings](/response-api-reference/embeddings/list),
[Memories](/response-api-reference/memories/list), and
[Examples](/response-api-reference/examples/list).

<Note>
  The split is about consequence, not capability. An analysis agent that's wrong produces a bad
  recommendation you can discard. An automation agent that's wrong has already issued the refund —
  which is why the safety machinery is aimed at that class.
</Note>

## Voice agents

An agent with a `voice_model` answers the phone. The telephony, streaming, and supervision layer is
[StateSet Voice](/stateset-voice/overview) — including live monitor, whisper, barge, and escalate on
an in-flight call.

## Related

* [Settings](/response-api-reference/settings) — the 22 fields that bound agent behaviour
* [Rules](/response-api-reference/rules) — named policy constraints
* [Set up ResponseCX](/stateset-response/stateset-responsecx) — the ordered path to a live agent
* [Public API](/stateset-response/response-public-api) — provision agents programmatically