Создайте интеграцию инструмента (API)

Интеграция инструмента — это повторно используемая HTTP-конечная точка, которую агент может вызывать во время звонка. Вы предоставляете ThunderPhone описание инструмента в формате JSON-схемы и URL конечной точки; агент решает, когда вызвать его, на основе разговора, а ThunderPhone выполняет исходящий HTTP-запрос со своих серверов и возвращает ответ агенту.

Панель управления покрывает большинство задач с инструментами без этого API: Подключения → Приложения подключает Slack, HubSpot, Salesforce, Google Calendar, Google Sheets и Cal.com несколькими OAuth-кликами; Подключения → API превращает любой HTTP API в действие агента (вставьте команду cURL, и мастер на основе ИИ создаст черновик инструмента со встроенной функцией «Тестовый запрос»); а Подключения → MCP добавляет MCP-серверы. См. Подключения. В этом руководстве описан базовый API, лежащий в основе раздела API.

В этом руководстве пошагово рассматривается создание инструмента для получения погоды.

Структура инструмента

Две части:

Схема — определение функции в стиле OpenAI ({type: "function", function: {name, description, parameters}}), которое сообщает LLM, что делает инструмент и какие аргументы он принимает.
Конечная точка — URL, который серверы ThunderPhone вызывают, когда LLM решает использовать инструмент. Запрос представляет собой JSON POST, а тело содержит аргументы, выбранные LLM.

1. Выберите стратегию хранения

Встроенный в агента

Добавьте разовый инструмент в массив tools агента. Это просто, но не подходит для повторного использования.

Сохранённая интеграция

Сохраните инструмент как повторно используемую интеграцию и привяжите его к нескольким агентам. Рекомендуется для всего, что используется более одного раза.

В этом руководстве используется путь с сохранённой интеграцией.

2. Создайте интеграцию

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

Сохраните возвращённый id (UUID).

Уделите особое внимание description инструмента и каждого параметра. LLM использует эти строки во время выполнения, чтобы решить, следует ли и как вызывать инструмент. Нечёткие описания → нечёткие вызовы инструмента.

3. Протестируйте конечную точку в песочнице

Прежде чем привязывать интеграцию к агенту, отправьте подписанный запрос с серверов ThunderPhone, чтобы подтвердить подключение:

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, ...}"
}

Этот тест также усиливает SSRF-защиту ThunderPhone — запросы к localhost или диапазонам частных IP-адресов возвращают 400 code=url_not_allowed.

4. Привяжите интеграцию к агенту

Добавьте integration_ids при создании или обновлении агента:

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

К одному агенту можно привязать несколько интеграций. В промпте агента на них можно ссылаться по имени — «используй get_weather, когда звонящий спрашивает о погодных условиях» — либо агент может неявно обнаружить их по описаниям схем.

5. Реализуйте эндпоинт

Когда агент вызывает инструмент, ThunderPhone отправляет подписанный POST на ваш 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"}

Ваш сервер отвечает JSON, который передаётся обратно в LLM:

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

LLM обрабатывает этот ответ и сообщает звонящему краткую информацию понятным языком.

Подпись вычисляется по необработанному телу запроса с использованием того же secret, что и для вашего эндпоинта вебхуков. Проверяйте её — эндпоинты инструментов доступны из интернета и подвержены тем же рискам подмены, что и вебхуки. См. Проверка подписей вебхуков.

6. Протестируйте цикл

Запустите сеанс с микрофоном для агента и задайте вопрос, который обрабатывает ваш инструмент («Какая погода в 94110?»). В расшифровке звонка отображается полный цикл:

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

Получить её можно через GET /v1/calls/{call_id}/transcript; поток необработанных событий (со временем для каждой записи и смещениями аудио) доступен по адресу GET /v1/calls/{call_id}/history.

Распространённые проблемы

Агент никогда не вызывает инструмент

LLM принимает решение на основе описания инструмента. Если вопрос звонящего не соответствует описанию, модель не вызовет инструмент. Уточните описание (добавьте распространённые синонимы и формулировки) или явно укажите это в промпте агента («Когда звонящий спрашивает о погоде, используй get_weather.»).

Инструмент возвращает слишком много данных

Ответы размером более 6 кБ обрезаются в предпросмотре расшифровки. Возвращайте только поля, нужные LLM, а не всю запись.

Тайм-ауты

Для эндпоинтов инструментов по умолчанию установлен тайм-аут 10 секунд. Если нужно больше времени, обрабатывайте запрос асинхронно: верните {"status": "pending", "request_id": "..."} и передайте результат через отдельный вызов инструмента.

Версионирование

Каждый PATCH интеграции создаёт новую ревизию. Проверьте GET /v1/integrations/{id}/versions, чтобы узнать, кто и что изменил. Если вы нарушили схему инструмента, можно вручную откатить изменения, передав через PATCH более ранний снимок.

Следующие шаги

Справочник по интеграциям

CRUD, передача, история версий.

Спецификация инструментов-функций

Полная грамматика схемы JSON и контракт подписанного эндпоинта.

Проверка подписей

Применяйте шаблон подписи вебхука к эндпоинтам инструментов.

API расшифровки и истории

Просматривайте полный цикл вызова инструмента.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Создайте интеграцию инструмента (API)

Структура инструмента

1. Выберите стратегию хранения

Встроенный в агента

Сохранённая интеграция

2. Создайте интеграцию

3. Протестируйте конечную точку в песочнице

4. Привяжите интеграцию к агенту

5. Реализуйте эндпоинт

6. Протестируйте цикл

Распространённые проблемы

Следующие шаги

Справочник по интеграциям

Спецификация инструментов-функций

Проверка подписей

API расшифровки и истории

​Структура инструмента

​1. Выберите стратегию хранения

Встроенный в агента

Сохранённая интеграция

​2. Создайте интеграцию

​3. Протестируйте конечную точку в песочнице

​4. Привяжите интеграцию к агенту

​5. Реализуйте эндпоинт

​6. Протестируйте цикл

​Распространённые проблемы

​Следующие шаги

Справочник по интеграциям

Спецификация инструментов-функций

Проверка подписей

API расшифровки и истории

Структура инструмента

1. Выберите стратегию хранения

2. Создайте интеграцию

3. Протестируйте конечную точку в песочнице

4. Привяжите интеграцию к агенту

5. Реализуйте эндпоинт

6. Протестируйте цикл

Распространённые проблемы

Следующие шаги