Ricky logorickyDocs

Crear un agente

POST
/agents

Crea un agente de IA con sus instrucciones, modelo, voz y capacidades. No responde ninguna conversación hasta que lo asignes a una o lo pongas como agente predeterminado de un canal en Ricky.

Permiso: agents:write.

Autorización

bearerAuth
headerAuthorizationBearer <clave>

Una clave de API de la organización, rky_live_…, creada en Configuración → API. Envíala solo desde un servidor.

Parámetros de cabecera

Idempotency-Key?string

Opcional. Un valor que eliges, único por escritura lógica, de 8 a 200 caracteres: un UUID o un ID de tu sistema, como order-10482-ready. Reintentar con la misma clave y el mismo cuerpo repite la primera respuesta en lugar de repetir la escritura.

Longitud8 <= length <= 200

Cuerpo de la solicitud

application/json
  1. body

Solo name es obligatorio; no conecta el agente a ningún canal.

name*string

Nombre que ve el equipo.

Longitud1 <= length <= 120
description?|

Para qué sirve el agente.

instructions?|

Cómo responde el agente a los clientes.

model?string

Un id de modelo de GET /agent-options. Sin él, el modelo predeterminado.

Longitudlength <= 200
voice?string

Una voz de GET /agent-options. Sin ella, la voz predeterminada.

Longitudlength <= 100
capabilities?array<>

El conjunto completo de nombres de capacidades. Reemplaza las actuales.

Elementositems <= 200
handoff_user_ids?array<>

El conjunto completo de miembros que reciben las conversaciones que el agente pasa a una persona. Obligatorio con ricky.handoff.request.

Elementositems <= 100

Cuerpo de la respuesta

Éxito.

application/json
  1. response
data*

Un agente de IA que responde conversaciones junto al equipo.

curl -X POST 'https://getricky.ai/api/v1/agents' \  -H 'Idempotency-Key: order-10482-ready' \  -H 'Content-Type: application/json' \  -d '{  "name": "Asistente de ventas",  "instructions": "Saluda por el nombre y confirma el pedido antes de dar la fecha de entrega.",  "capabilities": [    "ricky.handoff.request"  ],  "handoff_user_ids": [    "2d4f6a8c-1b3d-4e5f-8a7b-9c0d1e2f3a4b"  ]}'
{  "data": {    "id": "7e8f9a0b-1c2d-4e3f-a4b5-c6d7e8f9a0b1",    "name": "Asistente de ventas",    "description": "Atiende consultas de pedidos y horarios.",    "instructions": "Saluda por el nombre y confirma el pedido antes de dar la fecha de entrega.",    "model": "deepseek/deepseek-v4.1-flash",    "voice": "diana",    "capabilities": [      "ricky.handoff.request"    ],    "handoff_user_ids": [      "2d4f6a8c-1b3d-4e5f-8a7b-9c0d1e2f3a4b"    ],    "created_at": "2026-10-14T15:30:00.000Z",    "updated_at": "2026-10-14T15:30:00.000Z",    "archived_at": "2026-10-14T15:30:00.000Z"  }}