> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 도구 통합(API) 구축
> 에이전트가 대화 중에 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 서버를 추가할 수 있습니다.
[연결](/ko/guides/concepts)을 참조하세요. 이 가이드는 API 화면 아래에 있는 원시
API를 다룹니다.
이 가이드에서는 날씨 조회 도구를 처음부터 끝까지 구축합니다.
## 도구의 구성 요소
두 가지 구성 요소가 있습니다.
1. **스키마** — 도구의 기능과 인수로 받는 값을 LLM에 알려 주는 OpenAI 스타일 함수 정의
(`{type: "function", function: {name, description, parameters}}`)입니다.
2. **엔드포인트** — LLM이 도구 사용을 결정했을 때 ThunderPhone 서버가 호출하는 URL입니다.
요청은 LLM이 선택한 인수를 본문으로 포함하는 JSON POST 요청입니다.
## 1. 저장 전략 선택
일회성 도구를 에이전트의 `tools` 배열에 연결합니다. 간단하지만
재사용할 수 없습니다.
도구를 재사용 가능한 [통합](/api-reference/integrations)으로
저장하고 여러 에이전트에서 연결합니다. 두 번 이상 사용하는 모든 항목에
권장됩니다.
이 가이드에서는 저장된 통합 경로를 사용합니다.
## 2. 통합 생성
```bash theme={null}
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 서버에서 서명된 요청을 보내 연결을 확인합니다.
```bash theme={null}
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" }
}'
```
```json Response theme={null}
{
"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`를 통해 연결합니다.
```bash theme={null}
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:
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json
{"zip": "94110"}
```
서버는 LLM에 다시 전달되는 JSON으로 응답합니다.
```json theme={null}
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}
```
LLM은 해당 응답을 처리하고 발신자에게 사람이 이해하기 쉬운 요약을 말합니다.
서명은 웹훅 엔드포인트와 동일한 `secret`을 사용하여 원시 요청 본문을 기반으로 계산됩니다. **반드시 검증합니다**. 도구 엔드포인트는 인터넷에 노출되며 웹훅과 동일한 스푸핑 위험에 노출됩니다. 자세한 내용은 [웹훅 서명 검증](/ko/guides/verify-webhook-signatures)을 참조합니다.
## 6. 루프 테스트
에이전트를 대상으로 [마이크 세션](/api-reference/mic-sessions)을 실행하고 도구가 처리하는 질문을 합니다("94110의 날씨는 어떤가요?"). 통화 기록에는 전체 왕복 과정이 표시됩니다.
```json theme={null}
{
"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`](/api-reference/calls#get-transcript)에서 가져올 수 있으며, 항목별 타이밍과 오디오 오프셋을 포함한 원시 이벤트 스트림은 [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history)에서 확인할 수 있습니다.
## 일반적인 주의 사항
LLM은 도구 설명을 기준으로 결정합니다. 발신자의 질문이 설명과 일치하지 않으면 모델은 도구를 호출하지 않습니다. 설명을 더 구체적으로 작성하거나(일반적인 동의어와 표현 추가) 에이전트 프롬프트에 명시적으로 언급합니다("발신자가 날씨를 물어보면 `get_weather`를 사용합니다.").
6kB를 초과하는 응답은 기록 미리보기에서 잘립니다. 전체 행이 아니라 LLM에 필요한 필드만 반환합니다.
도구 엔드포인트의 기본 시간 초과는 10초입니다. 더 긴 시간이 필요하면 비동기적으로 처리합니다. `{"status": "pending", "request_id": "..."}`를 반환하고 별도의 도구 호출을 통해 결과를 표시합니다.
모든 통합 `PATCH`는 새 리비전을 생성합니다. [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history)를 검사하여 누가 무엇을 변경했는지 확인합니다. 도구의 스키마를 손상한 경우 이전 스냅샷을 다시 PATCH하여 수동으로 롤백할 수 있습니다.
***
## 다음 단계
CRUD, 전환, 버전 기록.
전체 JSON 스키마 문법 및 서명된 엔드포인트 계약.
도구 엔드포인트에 웹훅 서명 패턴을 적용합니다.
도구 호출의 전체 왕복 과정을 검사합니다.