Developer cookbook

Crea una integración de herramientas (API)

Permite que tu agente llame a tus API durante la conversación: busca en una base de datos, crea un ticket o consulta un pedido.

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.

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:

1. 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.
2. 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#

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).

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

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

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#

Próximos pasos#