Sub-agentes

Los sub-agentes son agentes regulares del workspace que el padre puede:

consultar (task: "assist") para que le ayude con algo en segundo plano sin perder el control de la conversación, o
delegar (task: "delegate") entregando la conversación completa al sub-agente hasta que cumpla un criterio de completado.

Un mismo agente puede estar conectado como sub-agente de varios padres simultáneamente. Conectar y desconectar no afecta al agente referenciado — solamente cambia la relación con el padre.

{
  "reference": "RuzoaswTBBrhutHyKYZn",
  "name": "Especialista en devoluciones",
  "agentName": "Especialista en devoluciones",
  "agentImageUrl": "/images/campaignCreator.png",
  "status": "inactive",
  "task": "delegate",
  "delegationCriteria": "Cuando el cliente pide devolver un producto",
  "completionCriteria": "Cuando se confirma o se rechaza la devolución"
}

Los campos name, agentName y agentImageUrl se copian del sub-agente al momento de conectarlo. Para task: "assist" se usa description en lugar de delegationCriteria / completionCriteria.

Listar Sub-agentes

GET https://api.platica.mx/v1/agents/{agentId}/subagents

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente padre	✓

Respuesta

{
  "subagents": [
    {
      "reference": "RuzoaswTBBrhutHyKYZn",
      "name": "Especialista en devoluciones",
      "agentName": "Especialista en devoluciones",
      "agentImageUrl": "/images/campaignCreator.png",
      "status": "inactive",
      "task": "assist",
      "description": "Especialista en QA",
      "agentExists": true,
      "hasPrompt": true,
      "agentStatus": "inactive",
      "lastUpdate": "2026-05-28T06:48:17.023Z"
    }
  ]
}

Cada entrada se complementa con metadatos frescos del sub-agente referenciado: agentExists, hasPrompt, agentStatus, lastUpdate.

Listar Agentes Conectables

Devuelve todos los agentes del workspace que se pueden conectar como sub-agentes (excluido el padre y los eliminados), con un flag isAlreadyConnected para construir un selector en la UI.

GET https://api.platica.mx/v1/agents/{agentId}/subagents/available

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente padre	✓

Respuesta

{
  "agents": [
    {
      "id": "QZPHpckDPC58JIVLQA3Z",
      "name": "DataBot",
      "imageUrl": "/images/campaignCreator.png",
      "status": "inactive",
      "hasPrompt": true,
      "lastUpdate": "2026-05-28T05:07:16.203Z",
      "isAlreadyConnected": false
    }
  ]
}

Conectar Sub-agente

Conecta un agente existente como sub-agente del padre. Sólo requiere el ID del sub-agente.

POST https://api.platica.mx/v1/agents/{agentId}/subagents

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente padre	✓

Cuerpo de la solicitud

{
  "subagentId": "RuzoaswTBBrhutHyKYZn",
  "task": "assist",
  "status": "inactive",
  "description": "Especialista en ventas premium"
}

Parámetro	Tipo	Descripción	Requerido	Default
`subagentId`	string	Identificador del agente a conectar	✓	—
`task`	string	`"assist"` o `"delegate"`	—	`"assist"`
`status`	string	`"active"` o `"inactive"` (sólo las conexiones `active` se invocan en tiempo de ejecución)	—	`"inactive"`
`description`	string	Cuándo invocar al sub-agente (sólo `task: "assist"`)	—	`""`
`delegationCriteria`	string	Cuándo delegar (sólo `task: "delegate"`)	—	`""`
`completionCriteria`	string	Cuándo el sub-agente debe devolver el control (sólo `task: "delegate"`)	—	`""`

Respuesta

{
  "status": "success",
  "message": "Sub-agent connected successfully",
  "data": {
    "connection": {
      "reference": "RuzoaswTBBrhutHyKYZn",
      "name": "Especialista en QA",
      "agentName": "Especialista en QA",
      "agentImageUrl": "/images/campaignCreator.png",
      "status": "inactive",
      "task": "assist",
      "description": "Especialista en ventas premium"
    }
  }
}

Errores

Status	Causa
`400`	`subagentId` no se proporcionó o es igual al `agentId` (un agente no puede ser su propio sub-agente)
`404`	El sub-agente no existe en el workspace
`409`	El sub-agente ya está conectado al padre

Crear y Conectar Sub-agente

Crea un agente nuevo en el workspace y lo conecta como sub-agente al padre en una sola llamada. Si pasas un systemPrompt no vacío, se inicializa el historial de versiones del prompt del sub-agente automáticamente.

POST https://api.platica.mx/v1/agents/{agentId}/subagents/create

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente padre	✓

Cuerpo de la solicitud

{
  "name": "Especialista en devoluciones",
  "systemPrompt": "Eres un experto en políticas de devolución...",
  "task": "delegate",
  "status": "active",
  "delegationCriteria": "Cuando el cliente pide devolver un producto",
  "completionCriteria": "Cuando se confirma o se rechaza la devolución"
}

Parámetro	Tipo	Descripción	Requerido	Default
`name`	string	Nombre del nuevo agente (1-100 caracteres)	✓	—
`systemPrompt`	string	Prompt inicial del sub-agente	—	`""`
`imageUrl`	string	URL del avatar	—	`"/images/campaignCreator.png"`
`task`	string	`"assist"` o `"delegate"`	—	`"assist"`
`status`	string	`"active"` o `"inactive"`	—	`"inactive"`
`description`, `delegationCriteria`, `completionCriteria`	string	Igual que en conectar	—	`""`

Respuesta

{
  "status": "success",
  "message": "Sub-agent created and connected successfully",
  "data": {
    "subagentId": "RuzoaswTBBrhutHyKYZn",
    "connection": {
      "reference": "RuzoaswTBBrhutHyKYZn",
      "name": "Especialista en devoluciones",
      "agentName": "Especialista en devoluciones",
      "agentImageUrl": "/images/campaignCreator.png",
      "status": "active",
      "task": "delegate",
      "delegationCriteria": "Cuando el cliente pide devolver un producto",
      "completionCriteria": "Cuando se confirma o se rechaza la devolución"
    }
  }
}

Actualizar Conexión

Modifica la configuración de la conexión (no toca al sub-agente referenciado). Al cambiar task se limpian automáticamente los campos del modo anterior (description ↔ delegationCriteria/completionCriteria).

PATCH https://api.platica.mx/v1/agents/{agentId}/subagents/{subagentId}

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente padre	✓
`subagentId`	string	Identificador del sub-agente conectado	✓

Cuerpo de la solicitud

{
  "task": "delegate",
  "delegationCriteria": "Cuando aparece la palabra refund",
  "completionCriteria": "Cuando se procesa el reembolso",
  "status": "active"
}

Parámetro	Tipo	Descripción
`name`	string	Nombre mostrado en la conexión (sobreescribe el copiado del sub-agente)
`task`	string	`"assist"` o `"delegate"`
`status`	string	`"active"` o `"inactive"`
`description`	string	(sólo `task: "assist"`)
`delegationCriteria`	string	(sólo `task: "delegate"`)
`completionCriteria`	string	(sólo `task: "delegate"`)

Todos los campos son opcionales, pero al menos uno debe estar presente.

Desconectar Sub-agente

Retira la conexión del padre. El sub-agente referenciado no se modifica ni se elimina.

DELETE https://api.platica.mx/v1/agents/{agentId}/subagents/{subagentId}

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente padre	✓
`subagentId`	string	Identificador del sub-agente conectado	✓

Respuesta

{
  "status": "success",
  "message": "Sub-agent disconnected successfully"
}

Prompt del Sub-agente

Un sub-agente es un agente normal del workspace, así que para gestionar su prompt se usan los endpoints estándar de Prompt pasando el subagentId como agentId:

GET /v1/agents/{subagentId}/prompt
POST /v1/agents/{subagentId}/prompt
PATCH /v1/agents/{subagentId}/prompt

Mismo comportamiento de versionado.

Notas

reference siempre es el ID del agente al que se conecta (string).
Un sub-agente puede estar conectado a varios agentes padre sin restricción.
Sólo las conexiones con status: "active" se invocan durante la ejecución del agente padre.

Anterior Versiones del Prompt Siguiente Guardrails del Agente