Agents

Define agent identity, voice, background, and behaviors with immutable versioning in the Platform API.

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 stay untouched.

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.

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

Create an agent

Create an agent

post

Create a new agent in a workspace. Requires Agent.create permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

application/json

namestring · min: 1 · max: 256Required

descriptionstring · max: 2000OptionalDefault: ""

Responses

201

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

namestringRequired

descriptionstringRequired

latest_versionintegerOptionalDefault: 0

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

409

Name already taken.

422

Invalid request body.

post/v1/{workspace_id}/agents

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/agents HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "name": "text",
  "description": ""
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "latest_version": 0,
  "created_at": "2026-07-10T23:09:54.539Z",
  "updated_at": "2026-07-10T23:09:54.539Z"
}

List agents

Paginated and searchable.

List agents

get

List agents in a workspace with pagination. Requires Agent.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

searchstring · min: 1 · max: 200 · nullableOptional

sort_bystring · nullableOptional

limitinteger · max: 100OptionalDefault: 10

continuation_tokenintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokeninteger · nullableOptional

totalinteger · nullableOptional

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get/v1/{workspace_id}/agents

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/agents HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "latest_version": 0,
      "created_at": "2026-07-10T23:09:54.539Z",
      "updated_at": "2026-07-10T23:09:54.539Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1,
  "total": 1
}

Get an agent

Get an agent

get

Retrieve an agent by ID. Requires Agent.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

agent_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

namestringRequired

descriptionstringRequired

latest_versionintegerOptionalDefault: 0

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get/v1/{workspace_id}/agents/{agent_id}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/agents/{agent_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "latest_version": 0,
  "created_at": "2026-07-10T23:09:54.539Z",
  "updated_at": "2026-07-10T23:09:54.539Z"
}

Update agent name/description

Update an agent

put

Update an agent's name or description. Requires Agent.update permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

agent_idstring · uuidRequired

Body

application/json

namestring · min: 1 · max: 256 · nullableOptional

descriptionstring · max: 2000 · nullableOptional

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

namestringRequired

descriptionstringRequired

latest_versionintegerOptionalDefault: 0

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

409

Name already taken.

422

Invalid request body.

put/v1/{workspace_id}/agents/{agent_id}

HTTPcURLJavaScriptPython

PUT /v1/{workspace_id}/agents/{agent_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "name": "text",
  "description": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "latest_version": 0,
  "created_at": "2026-07-10T23:09:54.539Z",
  "updated_at": "2026-07-10T23:09:54.539Z"
}

Delete an agent

Delete an agent

delete

Delete an agent. Agent versions are retained. Requires Agent.delete permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

agent_idstring · uuidRequired

Responses

204

Successful Response

No content

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

delete/v1/{workspace_id}/agents/{agent_id}

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/agents/{agent_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Create a new version

Create an agent version

post

Create a new version of an agent. Version number is auto-incremented. Requires Agent.create permission for the first version and Agent.update permission afterward.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

agent_idstring · uuidRequired

Body

application/json

namestring · min: 1 · max: 256Required

initialsstring · max: 10OptionalDefault: ""

backgroundstring · max: 10000OptionalDefault: ""

behaviorsstring[] · max: 200Optional

communication_patternsstring[] · max: 200Optional

Responses

201

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

agent_idstring · uuidRequired

versionintegerRequired

namestringRequired

initialsstringRequired

backgroundstringRequired

behaviorsstring[]Required

communication_patternsstring[]Required

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

409

Name already taken.

422

Invalid request body.

post/v1/{workspace_id}/agents/{agent_id}/versions

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/agents/{agent_id}/versions HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 626

{
  "name": "text",
  "initials": "",
  "identity": {
    "name": "text",
    "role": "text",
    "developed_by": "text",
    "default_spoken_language": "text",
    "relationship_to_developer": {
      "ownership": "text",
      "type": "text",
      "conversation_visibility": "text",
      "thought_visibility": "text"
    }
  },
  "voice_config": {
    "voice_id": "text",
    "stability": 0,
    "similarity_boost": 0,
    "style": 0,
    "tts_provider": "cartesia",
    "tts_config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "language_providers": {
      "ANY_ADDITIONAL_PROPERTY": {
        "provider": "cartesia",
        "config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    },
    "session_provider": "amigo"
  },
  "background": "",
  "behaviors": [
    "text"
  ],
  "communication_patterns": [
    "text"
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "name": "text",
  "initials": "text",
  "identity": {
    "name": "text",
    "role": "text",
    "developed_by": "text",
    "default_spoken_language": "text",
    "relationship_to_developer": {
      "ownership": "text",
      "type": "text",
      "conversation_visibility": "text",
      "thought_visibility": "text"
    }
  },
  "voice_config": {
    "voice_id": "text",
    "stability": 0,
    "similarity_boost": 0,
    "style": 0,
    "tts_provider": "cartesia",
    "tts_config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "language_providers": {
      "ANY_ADDITIONAL_PROPERTY": {
        "provider": "cartesia",
        "config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    },
    "session_provider": "amigo"
  },
  "background": "text",
  "behaviors": [
    "text"
  ],
  "communication_patterns": [
    "text"
  ],
  "created_at": "2026-07-10T23:09:54.539Z",
  "updated_at": "2026-07-10T23:09:54.539Z"
}

List versions

Paginated.

List agent versions

get

List versions of an agent with pagination. Requires Agent.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

agent_idstring · uuidRequired

Query parameters

sort_bystring · nullableOptional

limitinteger · max: 100OptionalDefault: 10

continuation_tokenintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokeninteger · nullableOptional

totalinteger · nullableOptional

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get/v1/{workspace_id}/agents/{agent_id}/versions

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/agents/{agent_id}/versions HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "agent_id": "123e4567-e89b-12d3-a456-426614174000",
      "version": 1,
      "name": "text",
      "initials": "text",
      "identity": {
        "name": "text",
        "role": "text",
        "developed_by": "text",
        "default_spoken_language": "text",
        "relationship_to_developer": {
          "ownership": "text",
          "type": "text",
          "conversation_visibility": "text",
          "thought_visibility": "text"
        }
      },
      "voice_config": {
        "voice_id": "text",
        "stability": 0,
        "similarity_boost": 0,
        "style": 0,
        "tts_provider": "cartesia",
        "tts_config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "language_providers": {
          "ANY_ADDITIONAL_PROPERTY": {
            "provider": "cartesia",
            "config": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          }
        },
        "session_provider": "amigo"
      },
      "background": "text",
      "behaviors": [
        "text"
      ],
      "communication_patterns": [
        "text"
      ],
      "created_at": "2026-07-10T23:09:54.539Z",
      "updated_at": "2026-07-10T23:09:54.539Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1,
  "total": 1
}

Get a specific version

Use the version number or latest to retrieve the most recent version.

Get an agent version

get

Retrieve a specific agent version by number, or 'latest'. Requires Agent.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

agent_idstring · uuidRequired

versionany ofRequired

integerOptional

or

stringOptional

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

agent_idstring · uuidRequired

versionintegerRequired

namestringRequired

initialsstringRequired

backgroundstringRequired

behaviorsstring[]Required

communication_patternsstring[]Required

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get/v1/{workspace_id}/agents/{agent_id}/versions/{version}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/agents/{agent_id}/versions/{version} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "name": "text",
  "initials": "text",
  "identity": {
    "name": "text",
    "role": "text",
    "developed_by": "text",
    "default_spoken_language": "text",
    "relationship_to_developer": {
      "ownership": "text",
      "type": "text",
      "conversation_visibility": "text",
      "thought_visibility": "text"
    }
  },
  "voice_config": {
    "voice_id": "text",
    "stability": 0,
    "similarity_boost": 0,
    "style": 0,
    "tts_provider": "cartesia",
    "tts_config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "language_providers": {
      "ANY_ADDITIONAL_PROPERTY": {
        "provider": "cartesia",
        "config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    },
    "session_provider": "amigo"
  },
  "background": "text",
  "behaviors": [
    "text"
  ],
  "communication_patterns": [
    "text"
  ],
  "created_at": "2026-07-10T23:09:54.539Z",
  "updated_at": "2026-07-10T23:09:54.539Z"
}

Agent Fields

Field	Type	Description
id	string	Unique identifier
name	string	Agent name (max 256 chars, unique per workspace)
description	string	Agent description (max 2,000 chars)
latest_version	integer	Most recent version number (0 if the agent has no versions yet)

Version Fields

Field	Type	Max Length	Description
version	integer	-	Auto-incremented version number
name	string	256 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 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 keeps 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