Sub-agents

Sub-agents are regular workspace agents that the parent can either:

consult (task: "assist") so the sub-agent helps with something in the background without losing control of the conversation, or
delegate (task: "delegate") to, handing the full conversation over to the sub-agent until a completion criterion is met.

The same agent can be connected as a sub-agent to multiple parents at once. Connecting and disconnecting does not affect the referenced agent — it only changes the relationship with the parent.

{
  "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"
}

The fields name, agentName, and agentImageUrl are copied from the sub-agent at connection time. For task: "assist", description is used instead of delegationCriteria / completionCriteria.

List Sub-agents

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

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Identifier of the parent agent	✓

Response

{
  "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"
    }
  ]
}

Each entry is enriched with fresh metadata from the referenced sub-agent: agentExists, hasPrompt, agentStatus, lastUpdate.

List Connectable Agents

Returns every workspace agent that can be connected as a sub-agent (excluding the parent itself and deleted agents), with an isAlreadyConnected flag to power a UI selector.

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

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Identifier of the parent agent	✓

Response

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

Connect Sub-agent

Connects an existing agent as a sub-agent of the parent. It only requires the sub-agent ID.

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

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Identifier of the parent agent	✓

Request body

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

Parameter	Type	Description	Required	Default
`subagentId`	string	Identifier of the agent to connect	✓	—
`task`	string	`"assist"` or `"delegate"`	—	`"assist"`
`status`	string	`"active"` or `"inactive"` (only `active` connections are invoked at runtime)	—	`"inactive"`
`description`	string	When to invoke the sub-agent (only `task: "assist"`)	—	`""`
`delegationCriteria`	string	When to delegate (only `task: "delegate"`)	—	`""`
`completionCriteria`	string	When the sub-agent must return control (only `task: "delegate"`)	—	`""`

Response

{
  "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"
    }
  }
}

Errors

Status	Cause
`400`	`subagentId` was not provided or equals `agentId` (an agent cannot be its own sub-agent)
`404`	The sub-agent does not exist in the workspace
`409`	The sub-agent is already connected to the parent

Create and Connect Sub-agent

Creates a new agent in the workspace and connects it as a sub-agent to the parent in a single call. If you pass a non-empty systemPrompt, the sub-agent's prompt version history is initialized automatically.

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

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Identifier of the parent agent	✓

Request body

{
  "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"
}

Parameter	Type	Description	Required	Default
`name`	string	Name of the new agent (1-100 characters)	✓	—
`systemPrompt`	string	Initial prompt of the sub-agent	—	`""`
`imageUrl`	string	Avatar URL	—	`"/images/campaignCreator.png"`
`task`	string	`"assist"` or `"delegate"`	—	`"assist"`
`status`	string	`"active"` or `"inactive"`	—	`"inactive"`
`description`, `delegationCriteria`, `completionCriteria`	string	Same as in connect	—	`""`

Response

{
  "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"
    }
  }
}

Update Connection

Updates the connection configuration (does not touch the referenced sub-agent). Switching task automatically clears the fields from the previous mode (description ↔ delegationCriteria/completionCriteria).

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

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Identifier of the parent agent	✓
`subagentId`	string	Identifier of the connected sub-agent	✓

Request body

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

Parameter	Type	Description
`name`	string	Display name in the connection (overrides the one copied from the sub-agent)
`task`	string	`"assist"` or `"delegate"`
`status`	string	`"active"` or `"inactive"`
`description`	string	(only `task: "assist"`)
`delegationCriteria`	string	(only `task: "delegate"`)
`completionCriteria`	string	(only `task: "delegate"`)

All fields are optional, but at least one must be present.

Disconnect Sub-agent

Removes the connection from the parent. The referenced sub-agent is not modified or deleted.

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

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Identifier of the parent agent	✓
`subagentId`	string	Identifier of the connected sub-agent	✓

Response

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

Sub-agent Prompt

A sub-agent is just another workspace agent, so its prompt is managed through the standard Prompt endpoints by passing the subagentId as agentId:

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

Same versioning behavior.

Notes

reference is always the ID of the connected agent (string).
A sub-agent can be connected to multiple parent agents without restriction.
Only connections with status: "active" are invoked while the parent agent runs.

Previous Prompt Versions Next Agent Guardrails