> ## 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. # Creați o integrare de instrumente (API) > Permiteți agentului dumneavoastră să apeleze API-urile în timpul conversației — să caute într-o bază de date, să creeze un tichet, să verifice o comandă. O **integrare de instrumente** este un endpoint HTTP reutilizabil pe care un agent îl poate invoca în timpul unui apel. Oferiți ThunderPhone o descriere JSON Schema a instrumentului plus un URL de endpoint; agentul decide când să îl apeleze pe baza conversației, iar ThunderPhone efectuează cererea HTTP de ieșire de pe serverele sale și returnează răspunsul agentului. Tabloul de bord acoperă majoritatea nevoilor de instrumente fără acest API: **Conexiuni → Aplicații** conectează Slack, HubSpot, Salesforce, Google Calendar, Google Sheets și Cal.com prin câteva clicuri OAuth; **Conexiuni → API-uri** transformă orice API HTTP într-o acțiune a agentului (lipiți o comandă cURL și un asistent AI creează o schiță a instrumentului, cu o opțiune integrată de Testare cerere); iar **Conexiuni → MCP** adaugă servere MCP. Consultați [Conexiuni](/ro/guides/concepts). Acest ghid prezintă API-ul de bază de sub suprafața API-urilor. Acest ghid prezintă crearea completă a unui instrument de căutare a vremii. ## Anatomia unui instrument Două componente: 1. **Schema** — o definiție de funcție în stil OpenAI (`{type: "function", function: {name, description, parameters}}`) care îi indică LLM-ului ce face instrumentul și ce argumente acceptă. 2. **Endpointul** — URL-ul apelat de serverele ThunderPhone atunci când LLM-ul decide să utilizeze instrumentul. Cererea este un POST JSON, cu argumentele alese de LLM în corpul cererii. ## 1. Alegeți o strategie de stocare Atașați un instrument punctual la matricea `tools` a agentului. Simplu, dar nereutilizabil. Stocați instrumentul ca [integrare](/api-reference/integrations) reutilizabilă și conectați-l de la mai mulți agenți. Recomandat pentru orice este utilizat de mai multe ori. Acest ghid utilizează varianta cu integrare salvată. ## 2. Creați integrarea ```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" } ] }' ``` Salvați `id` returnat (un UUID). Acordați atenție reală câmpului `description` al instrumentului și al fiecărui parametru. LLM-ul utilizează aceste șiruri în timpul execuției pentru a decide dacă și cum să apeleze instrumentul. Descrieri vagi → apeluri de instrumente vagi. ## 3. Testați endpointul în sandbox Înainte de a conecta integrarea la un agent, trimiteți o cerere semnată de pe serverele ThunderPhone pentru a confirma conectivitatea: ```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, ...}" } ``` Acest test consolidează și protecțiile SSRF ale ThunderPhone — cererile către localhost sau intervale IP private returnează `400 code=url_not_allowed`. ## 4. Conectați integrarea la un agent Atașați prin `integration_ids` atunci când creați sau actualizați un agent: ```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-..."] }' ``` Puteți conecta mai multe integrări la un singur agent. Instrucțiunea agentului le poate referi după nume — „utilizează `get_weather` atunci când apelantul întreabă despre condițiile meteo” — sau le poate descoperi implicit din descrierile schemei. ## 5. Implementați endpointul Când agentul invocă instrumentul, ThunderPhone trimite un POST semnat către `endpoint_url`: ``` 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"} ``` Serverul dumneavoastră răspunde cu JSON, care este transmis înapoi către LLM: ```json theme={null} {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` LLM-ul preia acel răspuns și îi comunică apelantului un rezumat natural. Semnătura este calculată pe corpul brut al solicitării, folosind același `secret` ca endpointul dumneavoastră de webhook. **Verificați-o** — endpointurile instrumentelor sunt accesibile de pe internet și sunt supuse acelorași riscuri de falsificare ca webhookurile. Consultați [Verificarea semnăturilor webhook](/ro/guides/verify-webhook-signatures). ## 6. Testați fluxul Rulați o [sesiune de microfon](/api-reference/mic-sessions) pentru agent și puneți întrebarea pe care o gestionează instrumentul dumneavoastră („Cum este vremea în 94110?”). Transcrierea apelului arată întregul circuit: ```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." } ] } ``` Puteți prelua aceasta prin [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript); fluxul brut de evenimente (cu temporizarea fiecărei intrări și decalajele audio) este disponibil la [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Probleme frecvente LLM-ul decide pe baza descrierii instrumentului. Dacă întrebarea apelantului nu corespunde descrierii, modelul nu va invoca instrumentul. Precizați descrierea (adăugați sinonime și formulări frecvente) sau menționați-l explicit în instrucțiunea agentului („Când apelantul întreabă despre vreme, utilizați `get_weather`."). Răspunsurile de peste 6 kB sunt trunchiate în previzualizarea transcrierii. Returnați doar câmpurile de care are nevoie LLM-ul — nu întregul rând. Endpointurile instrumentelor au un timeout implicit de 10 secunde. Dacă aveți nevoie de mai mult timp, gestionați procesul asincron: returnați `{"status": "pending", "request_id": "..."}` și afișați rezultatul printr-un apel separat al instrumentului. Fiecare `PATCH` al unei integrări creează o revizie nouă. Consultați [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history) pentru a vedea cine a modificat ce. Dacă deteriorați schema unui instrument, puteți reveni manual aplicând prin PATCH un instantaneu mai vechi. *** ## Pașii următori CRUD, transfer, istoric al versiunilor. Gramatica completă a schemei JSON și contractul pentru endpointuri semnate. Aplicați modelul de semnătură webhook la endpointurile instrumentelor. Inspectați întregul circuit al unui apel de instrument.