Skip to main content
POST
Crear agente a partir de una plantilla (fork de agent_version)
Una plantilla es una versión de agente publicada en el catálogo que sirve como punto de partida: al clonarla, el agente nuevo nace con blueprint, stages, triggers e instrucciones ya escritos. El flujo son dos llamadas: descubrir qué plantillas hay y clonar la que sirva.

1 · Descubrir plantillas

GET /v1/catalogs/templates requiere el scope catalogs:read. No hardcodees identificadores de plantilla en tu integración: el catálogo cambia, y el listado es la única fuente al día.
Cada entrada trae el id de la plantilla, su slug, sus tags y el agentVersionId que se clona. La visibility clasifica la plantilla: curada por Leracom (system), compartida públicamente (community) o no publicada al catálogo general (private).
El catálogo de plantillas es global, no está acotado por workspace: el listado devuelve todas las plantillas activas que coincidan con los filtros. No interpretes ?visibility=private como «las plantillas de mi workspace» — es una etiqueta de la plantilla, no una pertenencia. Identifica las tuyas por slug o por tags.
Para acotar el listado:

2 · Clonar la plantilla

Sólo templateId es obligatorio. Si omites templateVersionId se usa la versión publicada más reciente de la plantilla.

Campos del cuerpo

Requiere el scope agents:write. La respuesta trae el agentId y el versionId de la versión inicial.
Crea el agente en inactive mientras lo revisas. Un agente que nace active empieza a atender con la configuración de la plantilla, sin tus políticas aplicadas.

3 · Antes de publicar

  • Conecta las herramientas que el caso de uso pida —agenda, función propia, transferencia— desde la pestaña Herramientas del agente.
  • Ajusta el horario de atención con POST /v1/agents/{agentId}/schedules, y las excepciones puntuales con POST /v1/agents/{agentId}/schedules/exceptions.
  • Revisa saludo, reglas críticas y triggers contra tus políticas internas.
  • Deja constancia del cambio en notes al publicar la versión (PATCH /v1/agents/{agentId}/versions/{versionId}/notes).

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Datos necesarios para clonar una plantilla del catálogo y crear un nuevo agente en el workspace activo. Permite sobrescribir metadatos básicos del agente generado.

templateId
string<uuid>
required

Identificador de la plantilla a clonar.

templateVersionId
string<uuid>

Opcional. Si no se especifica, se usa el agent_version_id configurado como predeterminado en la tabla catalog_templates.

name
string | null

Opcional. Nombre a asignar al nuevo agente.

Maximum string length: 255
description
string | null

Opcional. Descripción operativa del agente.

Maximum string length: 1000
status
enum<string> | null

Opcional. Estado inicial del agente generado.

Available options:
inactive,
training,
active
debounceDelayMs
integer | null

Opcional. Delay antes de procesar eventos (milisegundos).

Required range: x >= 0
brief
string | null

Prompt de personalización para Claude Code headless. Si se proporciona, la respuesta cambia a SSE (text/event-stream) con eventos de progreso.

Maximum string length: 10000
researchUrl
string<uri> | null

URL del sitio web del cliente para que Claude investigue contexto.

voiceId
string<uuid> | null

Voz seleccionada para el agente (UUID del catálogo de voces). Si se proporciona, se aplica al blueprint durante la personalización.

attachments
object[] | null

Los ficheros que el cliente adjuntó en el chat de creación, ya subidos y confirmados en el namespace agent-briefs, junto con lo que dijo de cada uno. Al crear el agente se reclaman, que es lo que impide que el barrido se los lleve a las 72 h. Todo o nada: si un id no existe, no terminó de subirse, se subió a otro namespace o ya lo usa otro agente, la petición responde 422 nombrando cuáles fallaron y no se reclama ninguno. Un id de otro workspace se reporta como inexistente. Repetir el mismo uploadId en la lista responde 400.

Maximum array length: 10

Response

Agente creado a partir de plantilla

agentId
string<uuid>
required
name
string
required
agentType
enum<string>
required
Available options:
chat,
voice
workspaceId
string<uuid>
required
status
enum<string>
required
Available options:
inactive,
training,
active,
archived,
building,
failed
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
totalCalls
integer
required

Total de llamadas realizadas por el agente.

Required range: x >= 0
totalOperationalDays
integer
required

Total de días operativos desde la creación del agente.

Required range: x >= 0
goalAchievedPercentage
number
required

Porcentaje de llamadas donde el objetivo fue alcanzado.

Required range: 0 <= x <= 100
version
object

La versión vigente del agente: la active si la hay y, si no, el borrador más reciente. Es de aquí de donde sale el identificador de versión que piden las rutas de blueprint, instrucciones y publicación — no hay un versionId plano. Se omite cuando el agente todavía no tiene ninguna versión.

description
string | null
avatarUrl
string<uri> | null

URL pública opcional utilizada para representar al agente.

debounceDelayMs
integer | null

Delay opcional antes de enviar respuestas (milisegundos).

Required range: x >= 0
ownerUserId
string<uuid> | null
knowledgeBaseIds
string<uuid>[]

Las bases de conocimiento que este agente consulta durante la conversación. Vacío significa que no consulta ninguna, no que no se sepa. Es la selección del cliente, leída del mismo sitio del que la lee el sync al publicar una versión, así que no puede divergir de lo que se toma como entrada al publicar. Al publicar, el proveedor de voz recibe sólo las que además están listas y son suyas: una base a medio indexar aparece aquí y todavía no viaja.