Crear Client Tool

POST /client-tools Crea una tool en el catálogo reutilizable del cliente. Esta es la forma recomendada de agregar una tool que debe estar disponible en varios agentes — asígnala después con Asignar Tool a Workflow. Para una tool puntual que debe vivir solo en un agente, usa Crear Workflow Tool en su lugar.

Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	snake_case, coincidiendo con `^[a-z][a-z0-9_]*$`. Inmutable después de creada
`description`	string	Sí	Qué hace la tool y cuándo debería llamarla el agente. No vacío, máximo 1024 caracteres
`url`	string	Sí	Endpoint que llama la tool. No vacío
`method`	string	No	`GET`, `POST`, `PUT`, `PATCH`, o `DELETE`. Por defecto `POST`
`parameters`	object	No	Objeto estilo JSON-schema que describe los argumentos de llamada de la tool. Por defecto `{ "type": "object", "properties": {} }`
`headers`	object	No	Headers estáticos enviados en cada llamada, ej. `{ "Authorization": "Bearer ..." }`. Por defecto `{}`
`query_parameters`	object	No	Query params estáticos enviados en cada llamada. Por defecto `{}`
`timeout_ms`	integer	No	Limitado entre 1,000 y 120,000. Por defecto `10000`
`speak_during_execution`	boolean	No	Hace que el agente de voz hable mientras la llamada está en curso. Por defecto `true`
`speak_after_execution`	boolean	No	Hace que el agente de voz hable una vez que la llamada retorna. Por defecto `true`
`response_variables`	object	No	Mapa de campos de la respuesta capturados como variables de la llamada. Por defecto `{}`
`execution_message_type`	string	No	Ej. `"prompt"`
`execution_message_description`	string	No	Qué dice el agente durante/después de la ejecución
`llm_response_fields`	string[]	No	Lista de campos de la respuesta que el agente puede ver
`is_active`	boolean	No	Por defecto `true`
`sort_order`	integer	No	Por defecto `0`

Respuestas

`201` — Tool creada

{
  "success": true,
  "tool": {
    "id": "7c1b2c3d-0000-4000-8000-000000000002",
    "client_id": "3f9a1111-0000-4000-8000-000000000099",
    "name": "check_subscription",
    "description": "Checks whether the lead has an active subscription",
    "url": "https://api.acme.com/subscriptions/status",
    "method": "GET",
    "timeout_ms": 10000,
    "parameters": { "type": "object", "properties": {} },
    "headers": {},
    "query_parameters": {},
    "speak_during_execution": true,
    "speak_after_execution": true,
    "response_variables": {},
    "is_active": true,
    "sort_order": 0,
    "execution_message_type": null,
    "execution_message_description": null,
    "llm_response_fields": null,
    "created_at": "2026-07-15T12:00:00.000Z",
    "updated_at": "2026-07-15T12:00:00.000Z"
  }
}

Ver Listar Client Tools para la referencia completa de campos de ClientTool.

`400` — Error de validación

{
  "error": "Invalid input",
  "message": "name must be snake_case (^[a-z][a-z0-9_]*$)"
}

También se devuelve como "description is required", "description must be a non-empty string", "description must be at most 1024 characters", "url is required", "url must be a non-empty string", "method must be one of: GET, POST, PUT, PATCH, DELETE", o "timeout_ms must be a number".

`401` — Error de autenticación

Ver Autenticación.

`409` — Conflicto

{
  "error": "Conflict",
  "message": "A tool named \"check_subscription\" already exists in your catalog"
}

`500` — Error interno del servidor

Última modificación el 15 de julio de 2026

Listar Client Tools

Actualizar Client Tool

​Cuerpo de la Solicitud

​Respuestas

​201 — Tool creada

​400 — Error de validación

​401 — Error de autenticación

​409 — Conflicto

​500 — Error interno del servidor