Crea una integración de herramientas (API)

Una integración de herramientas es un endpoint HTTP reutilizable que un agente puede invocar durante una llamada. Le proporcionas a ThunderPhone una descripción mediante esquema JSON de la herramienta junto con una URL de endpoint; el agente decide cuándo llamarla según la conversación, y ThunderPhone realiza la solicitud HTTP saliente desde sus servidores y devuelve la respuesta al agente.

El dashboard cubre la mayoría de las necesidades de herramientas sin esta API: Conexiones → Aplicaciones conecta Slack, HubSpot, Salesforce, Google Calendar, Google Sheets y Cal.com con unos pocos clics de OAuth; Conexiones → APIs convierte cualquier API HTTP en una acción de agente (pega un comando cURL y un asistente de IA crea un borrador de la herramienta, con una Prueba de solicitud integrada); y Conexiones → MCP agrega servidores MCP. Consulta Conexiones. Esta guía trata sobre la API sin procesar detrás de la interfaz de APIs.

Esta guía te acompaña en la creación integral de una herramienta de consulta del clima.

Anatomía de una herramienta

Dos partes:

El esquema — una definición de función al estilo de OpenAI ({type: "function", function: {name, description, parameters}}) que le indica al LLM qué hace la herramienta y qué argumentos acepta.
El endpoint — la URL a la que llaman los servidores de ThunderPhone cuando el LLM decide usar la herramienta. La solicitud es un POST JSON con los argumentos elegidos por el LLM como cuerpo.

1. Elige una estrategia de almacenamiento

En línea en el agente

Adjunta una herramienta de uso único al arreglo tools del agente. Es simple, pero no reutilizable.

Integración guardada

Almacena la herramienta como una integración reutilizable y vincúlala desde varios agentes. Se recomienda para cualquier herramienta que se use más de una vez.

Esta guía usa el enfoque de integración guardada.

2. Crea la integración

curl -X POST https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Weather API",
    "spec": {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return the current weather for a zip code.",
        "parameters": {
          "type": "object",
          "properties": {
            "zip": { "type": "string", "description": "5-digit US ZIP code" }
          },
          "required": ["zip"]
        }
      }
    },
    "endpoint_url":    "https://api.example.com/weather",
    "endpoint_method": "GET",
    "headers": [
      { "key": "X-Api-Key", "value": "your-provider-key" }
    ]
  }'

Guarda el id devuelto (un UUID).

Dedica un esfuerzo real a la description de la herramienta y de cada parámetro. El LLM usa estas cadenas en tiempo de ejecución para decidir si debe llamar a la herramienta y cómo hacerlo. Descripciones vagas → llamadas a herramientas vagas.

3. Prueba el endpoint en el entorno de pruebas

Antes de vincular la integración a un agente, envía una solicitud firmada desde los servidores de ThunderPhone para confirmar la conectividad:

curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://api.example.com/weather?zip=94110",
    "method": "GET",
    "headers": { "X-Api-Key": "your-provider-key" }
  }'

Response

{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}

Esta prueba también refuerza las protecciones SSRF de ThunderPhone: las solicitudes a localhost o a rangos de IP privados devuelven 400 code=url_not_allowed.

4. Vincula la integración a un agente

Asóciala mediante integration_ids cuando crees o actualices un agente:

curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_ids": ["f9b5a1a4-..."]
  }'

Puedes vincular varias integraciones a un agente. El prompt del agente puede hacer referencia a ellas por nombre — “usa get_weather cuando quien llama pregunte sobre las condiciones meteorológicas” — o puede descubrirlas de forma implícita a partir de las descripciones del esquema.

5. Implementa el endpoint

Cuando el agente invoca la herramienta, ThunderPhone envía un POST firmado a tu endpoint_url:

POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

Tu servidor responde con JSON que se devuelve al LLM:

{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}

El LLM procesa esa respuesta y le comunica a quien llama un resumen natural.

La firma se calcula sobre el cuerpo sin procesar de la solicitud usando el mismo secret que tu endpoint de webhook. Verifícala — los endpoints de herramientas están expuestos a internet y sujetos a los mismos riesgos de suplantación que los webhooks. Consulta Verificar firmas de webhooks.

6. Prueba el ciclo

Inicia una sesión de micrófono con el agente y haz la pregunta que gestiona tu herramienta (“¿Cuál es el clima en 94110?”). La transcripción de la llamada muestra el ciclo completo:

{
  "call_id": 987654321,
  "transcripts": [
    { "role": "user",
      "content": "What's the weather in 94110?" },
    { "role": "tool_call",
      "content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" },
    { "role": "tool_response",
      "content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" },
    { "role": "agent",
      "content": "It's 64 degrees and partly cloudy." }
  ]
}

Puedes obtenerla mediante GET /v1/calls/{call_id}/transcript; el flujo de eventos sin procesar (con tiempos por entrada y desplazamientos de audio) está en GET /v1/calls/{call_id}/history.

Problemas comunes

El agente nunca llama a la herramienta

El LLM decide según la descripción de la herramienta. Si la pregunta de quien llama no coincide con la descripción, el modelo no invocará la herramienta. Ajusta la descripción (agrega sinónimos y formulaciones comunes) o menciónala explícitamente en el prompt del agente (“Cuando quien llama pregunte sobre el clima, usa get_weather.”).

La herramienta devuelve demasiados datos

Las respuestas de más de 6 kB se truncan en la vista previa de la transcripción. Devuelve solo los campos que necesita el LLM, no todo tu registro.

Tiempos de espera

Los endpoints de herramientas tienen un tiempo de espera predeterminado de 10 segundos. Si necesitas más tiempo, manéjalo de forma asíncrona: devuelve {"status": "pending", "request_id": "..."} y muestra el resultado mediante una llamada a una herramienta independiente.

Control de versiones

Cada PATCH de integración crea una nueva revisión. Consulta GET /v1/integrations/{id}/versions para ver quién cambió qué. Si rompes el esquema de una herramienta, puedes revertirlo manualmente aplicando PATCH a una instantánea anterior.

Próximos pasos

Referencia de integraciones

CRUD, transferencia, historial de versiones.

Especificación de herramientas de función

Gramática completa del esquema JSON y el contrato de endpoint firmado.

Verificar firmas

Aplica el patrón de firma de webhook a los endpoints de herramientas.

API de transcripciones e historial

Inspecciona el recorrido completo de ida y vuelta de una llamada a una herramienta.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Crea una integración de herramientas (API)

Anatomía de una herramienta

1. Elige una estrategia de almacenamiento

En línea en el agente

Integración guardada

2. Crea la integración

3. Prueba el endpoint en el entorno de pruebas

4. Vincula la integración a un agente

5. Implementa el endpoint

6. Prueba el ciclo

Problemas comunes

Próximos pasos

Referencia de integraciones

Especificación de herramientas de función

Verificar firmas

API de transcripciones e historial

​Anatomía de una herramienta

​1. Elige una estrategia de almacenamiento

En línea en el agente

Integración guardada

​2. Crea la integración

​3. Prueba el endpoint en el entorno de pruebas

​4. Vincula la integración a un agente

​5. Implementa el endpoint

​6. Prueba el ciclo

​Problemas comunes

​Próximos pasos

Referencia de integraciones

Especificación de herramientas de función

Verificar firmas

API de transcripciones e historial

Anatomía de una herramienta

1. Elige una estrategia de almacenamiento

2. Crea la integración

3. Prueba el endpoint en el entorno de pruebas

4. Vincula la integración a un agente

5. Implementa el endpoint

6. Prueba el ciclo

Problemas comunes

Próximos pasos