Crear un agente

Herramientas

Las herramientas permiten que el agente actúe durante la llamada: consultar un pedido, comprobar un horario disponible, abrir un ticket, enviar un enlace por SMS. Una herramienta pertenece a la cuenta y pueden usarla todos los agentes que la referencian.

Cuatro tipos

Tipo	Qué hace	Ajustes clave
`custom`	Envía a tu endpoint HTTPS los argumentos que recopiló el agente y lee la respuesta.	`url`, `parameters` (JSON Schema), `apiTimeout`
`query`	Busca en el contenido de una o varias páginas web para responder a una pregunta.	`urls`
`sendSms`	Envía un SMS durante la llamada, a un número fijo o a quien llama.	`body`, `to`
`sendEmail`	Envía un email durante la llamada, con las notas del agente.	`subject`, `body`, `to`, `notesInstructions`

Crear una herramienta personalizada

parameters sigue el formato de function calling: un objeto JSON Schema con los argumentos que el agente debe recopilar antes de usar la herramienta.

Terminal

curl -X POST "https://api.callshift.ai/v1/tools" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom",
    "name": "Check order",
    "description": "Looks up an order by its number and returns its status.",
    "config": {
      "url": "https://example.com/api/orders/lookup?token=YOUR_SECRET",
      "apiTimeout": 10,
      "parameters": {
        "type": "object",
        "properties": {
          "orderNumber": { "type": "string", "description": "The order number, e.g. ORD-1234" }
        },
        "required": ["orderNumber"]
      },
      "messages": { "requestStart": { "content": "Let me look that up." } }
    }
  }'

Durante la llamada, tu endpoint recibe un POST: el nombre de la función, los argumentos que recopiló el agente en args, la llamada hasta ese momento en call y, cuando quien llama es un contacto conocido, el contact.

JSON

{
  "name": "checkOrder",
  "args": {
    "orderNumber": "ORD-1234"
  },
  "call": {
    "id": "8f14e45f-ceea-467a-9575-6d3c0a5f2b1e",
    "type": "inbound",
    "phoneNumber": "+33612345678",
    "startedAt": "2026-10-30T09:12:00.000Z",
    "createdAt": "2026-10-30T09:11:58.000Z",
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "agentName": "Alice",
    "transcript": "Assistant: Hello, this is Alice...\nUser: Where is my order ORD-1234?"
  },
  "contact": {
    "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "phoneNumber": "+33612345678",
    "metadata": {
      "plan": "pro"
    }
  }
}

Responde en pocos segundos, con un JSON corto que el agente pueda leer: hay una persona esperando al teléfono. La petición no lleva firma: pon un token secreto en la URL y compruébalo.

Transferir a un número que elige tu sistema

No devuelvas el número desde una herramienta personalizada: el agente lo leería y podría equivocarse en una cifra. Usa un nodo forwardCall cuyo número busca tu servicio, que recibe la misma petición: consulta Flujo de llamadas.

Vincular una herramienta a un agente

Una herramienta se vincula referenciándola en el prompt de un nodo knowHow, con un elemento <tool-node>. Su texto es la instrucción que lee el agente.

HTML

<tool-node functionname="checkOrder" category="custom" toolslug=""
  toolid="550e8400-e29b-41d4-a716-446655440000">Use checkOrder to look up the caller's order.</tool-node>

functionname es el nombre de la herramienta en camelCase (Check order se convierte en checkOrder).
category es custom o query para esos tipos, y notifications para sendSms y sendEmail.
toolid es el id de la herramienta. Un diagrama con un nodo de herramienta cuyo id y nombre de función no coincidan con los de una misma herramienta se rechaza con un 422.

GET/v1/agents/{agentId} lista en su campo tools, de solo lectura, las herramientas que referencia un agente.

Cambiar el nombre de una herramienta

Los agentes encuentran una herramienta por su nombre de función. Si cambias el nombre de una herramienta, se desvincula de los agentes que la usan hasta que se actualice su <tool-node functionname>.

Lo que dice el agente mientras usa una herramienta

Mensaje	Se dice cuando
`requestStart`	Empieza la llamada a la herramienta. `blocking: true` espera primero a que termine la frase.
`requestComplete`	La herramienta ha respondido
`requestFailed`	La herramienta ha fallado
`requestDelayed`	La herramienta no ha respondido tras `timingMilliseconds` (de 1000 a 30000)

Si omites requestStart o requestDelayed, el agente dice una frase por defecto; si lo envías sin content, no dice nada. Con async: true, el agente sigue hablando sin esperar el resultado.

Actualizar y eliminar

PATCH/v1/tools/{toolId} reemplaza cada campo de primer nivel de config que envías (envía messages o parameters completos para cambiar una sola entrada), y null borra un campo opcional. El tipo no se puede cambiar. DELETE/v1/tools/{toolId} se rechaza con un 409 que lista los agentes que aún referencian la herramienta, salvo que añadas ?force=true.