# Agents

Agents define the AI persona: identity, voice, background knowledge, behavioral guidelines, and communication style. Each agent supports immutable versioning. Creating a new version auto-increments the version number, and existing versions are never modified.

{% hint style="info" %}
**Classic API vs Platform API**: The Classic API also has agent endpoints. The Platform API agents are workspace-scoped and support richer configuration. Use the Platform API for agent setup; the Classic API resolves agents at conversation runtime.
{% endhint %}

## Key Concepts

* **Agent**: A named container with a description. Holds multiple versions.
* **Agent Version**: An immutable snapshot of the agent's full configuration, including identity, voice, background, behaviors, and communication patterns.
* **Identity**: The agent's persona name, role, developer attribution, default language, and relationship-to-developer settings (ownership, conversation/thought visibility).
* **Voice Config**: Links the agent to a specific voice for text-to-speech.

## Endpoints

| Method   | Path                                                | Description                          |
| -------- | --------------------------------------------------- | ------------------------------------ |
| `POST`   | `/v1/{workspace_id}/agents`                         | Create an agent                      |
| `GET`    | `/v1/{workspace_id}/agents`                         | List agents (paginated, searchable)  |
| `GET`    | `/v1/{workspace_id}/agents/{id}`                    | Get an agent                         |
| `PUT`    | `/v1/{workspace_id}/agents/{id}`                    | Update agent name/description        |
| `DELETE` | `/v1/{workspace_id}/agents/{id}`                    | Delete an agent                      |
| `POST`   | `/v1/{workspace_id}/agents/{id}/versions`           | Create a new version                 |
| `GET`    | `/v1/{workspace_id}/agents/{id}/versions`           | List versions (paginated)            |
| `GET`    | `/v1/{workspace_id}/agents/{id}/versions/{version}` | Get a specific version (or `latest`) |

## Agent Fields

| Field            | Type            | Description                                      |
| ---------------- | --------------- | ------------------------------------------------ |
| `id`             | string          | Unique identifier                                |
| `name`           | string          | Agent name (max 200 chars, unique per workspace) |
| `description`    | string          | Agent description (max 2,000 chars)              |
| `latest_version` | integer or null | Most recent version number                       |

## Version Fields

| Field                    | Type           | Max Length       | Description                                                      |
| ------------------------ | -------------- | ---------------- | ---------------------------------------------------------------- |
| `version`                | integer        | -                | Auto-incremented version number                                  |
| `name`                   | string         | 200 chars        | Version name                                                     |
| `initials`               | string         | 10 chars         | Short display identifier                                         |
| `identity`               | object         | -                | Persona name, role, language, developer attribution              |
| `voice_config`           | object or null | -                | Text-to-speech voice selection                                   |
| `background`             | string         | 10,000 chars     | Domain knowledge, behavioral guidelines, contextual instructions |
| `behaviors`              | array          | 2,000 chars each | Behavioral rules and directives                                  |
| `communication_patterns` | array          | 2,000 chars each | Communication style guidelines                                   |

## Versioning Workflow

1. Create an agent (name + description)
2. Create version 1 with full identity, background, and behaviors
3. Iterate by creating new versions. Each gets an auto-incremented number.
4. Pin specific versions in [Services](https://docs.amigo.ai/developer-guide/platform-api/platform-api/services) via version sets

Use `latest` as the version parameter to retrieve the most recent version without knowing its number.

Deleting an agent removes its metadata but retains all versions for audit. Services continue to function with their pinned versions.

## Filtering and Pagination

The list endpoint supports:

* `search`: text search across agent names
* `sort_by`: `name`, `created_at`, or `updated_at`
* Cursor-based pagination with `limit` and `continuation_token`

## API Reference

* [Agents](https://docs.amigo.ai/api-reference/readme/platform/agents)