도구 통합(API) 구축

도구 통합은 에이전트가 통화 중에 호출할 수 있는 재사용 가능한 HTTP 엔드포인트입니다. 도구의 JSON 스키마 설명과 엔드포인트 URL을 ThunderPhone에 제공하면, 에이전트는 대화 내용을 바탕으로 호출 시점을 결정하고 ThunderPhone은 자체 서버에서 외부 HTTP 요청을 수행한 뒤 응답을 에이전트에 반환합니다.

이 API 없이도 대시보드에서 대부분의 도구 요구 사항을 처리할 수 있습니다. 연결 → 앱에서는 몇 번의 OAuth 클릭으로 Slack, HubSpot, Salesforce, Google Calendar, Google Sheets 및 Cal.com을 연결할 수 있습니다. 연결 → API에서는 모든 HTTP API를 에이전트 작업으로 전환할 수 있습니다(cURL 명령을 붙여넣으면 AI 마법사가 내장된 요청 테스트와 함께 도구 초안을 생성합니다). 연결 → MCP에서는 MCP 서버를 추가할 수 있습니다. 연결을 참조하세요. 이 가이드는 API 화면 아래에 있는 원시 API를 다룹니다.

이 가이드에서는 날씨 조회 도구를 처음부터 끝까지 구축합니다.

도구의 구성 요소

두 가지 구성 요소가 있습니다.

스키마 — 도구의 기능과 인수로 받는 값을 LLM에 알려 주는 OpenAI 스타일 함수 정의 ({type: "function", function: {name, description, parameters}})입니다.
엔드포인트 — LLM이 도구 사용을 결정했을 때 ThunderPhone 서버가 호출하는 URL입니다. 요청은 LLM이 선택한 인수를 본문으로 포함하는 JSON POST 요청입니다.

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

이 테스트는 ThunderPhone의 SSRF 보호 기능도 강화합니다. 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이 endpoint_url로 서명된 POST 요청을 전송합니다.

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

서버는 LLM에 다시 전달되는 JSON으로 응답합니다.

{"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를 사용합니다.”).

도구가 너무 많은 데이터를 반환함

6kB를 초과하는 응답은 기록 미리보기에서 잘립니다. 전체 행이 아니라 LLM에 필요한 필드만 반환합니다.

시간 초과

도구 엔드포인트의 기본 시간 초과는 10초입니다. 더 긴 시간이 필요하면 비동기적으로 처리합니다. {"status": "pending", "request_id": "..."}를 반환하고 별도의 도구 호출을 통해 결과를 표시합니다.

버전 관리

모든 통합 PATCH는 새 리비전을 생성합니다. GET /v1/integrations/{id}/versions를 검사하여 누가 무엇을 변경했는지 확인합니다. 도구의 스키마를 손상한 경우 이전 스냅샷을 다시 PATCH하여 수동으로 롤백할 수 있습니다.

다음 단계

통합 레퍼런스

CRUD, 전환, 버전 기록.

Function Tools 사양

전체 JSON 스키마 문법 및 서명된 엔드포인트 계약.

서명 검증

도구 엔드포인트에 웹훅 서명 패턴을 적용합니다.

트랜스크립트 + 기록 API

도구 호출의 전체 왕복 과정을 검사합니다.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

도구 통합(API) 구축

도구의 구성 요소

1. 저장 전략 선택

에이전트에 인라인으로 추가

저장된 통합

2. 통합 생성

3. 샌드박스에서 엔드포인트 테스트

4. 통합을 에이전트에 연결

5. 엔드포인트 구현

6. 루프 테스트

일반적인 주의 사항

다음 단계

통합 레퍼런스

Function Tools 사양

서명 검증

트랜스크립트 + 기록 API

​도구의 구성 요소

​1. 저장 전략 선택

에이전트에 인라인으로 추가

저장된 통합

​2. 통합 생성

​3. 샌드박스에서 엔드포인트 테스트

​4. 통합을 에이전트에 연결

​5. 엔드포인트 구현

​6. 루프 테스트

​일반적인 주의 사항

​다음 단계

통합 레퍼런스

Function Tools 사양

서명 검증

트랜스크립트 + 기록 API

도구의 구성 요소

1. 저장 전략 선택

2. 통합 생성

3. 샌드박스에서 엔드포인트 테스트

4. 통합을 에이전트에 연결

5. 엔드포인트 구현

6. 루프 테스트

일반적인 주의 사항

다음 단계