สร้างการผสานรวมเครื่องมือ (API)

การผสานรวมเครื่องมือ คือปลายทาง HTTP ที่นำกลับมาใช้ซ้ำได้ ซึ่งเอเจนต์สามารถ เรียกใช้ระหว่างการโทรได้ คุณมอบคำอธิบาย JSON-schema ของเครื่องมือพร้อม URL ปลายทางให้ ThunderPhone เอเจนต์จะตัดสินใจว่าจะเรียกใช้เมื่อใด ตามบทสนทนา และ ThunderPhone จะส่งคำขอ HTTP ขาออกจากเซิร์ฟเวอร์ของตน และส่งคืนการตอบกลับให้เอเจนต์

คู่มือนี้จะแนะนำการสร้างเครื่องมือค้นหาสภาพอากาศแบบครบวงจร

องค์ประกอบของเครื่องมือ

มีสองส่วน:

1. สคีมา — นิยามฟังก์ชันรูปแบบ OpenAI ({type: "function", function: {name, description, parameters}}) ซึ่งบอก LLM ว่าเครื่องมือทำอะไรและรับอาร์กิวเมนต์ใดบ้าง
2. ปลายทาง — URL ที่เซิร์ฟเวอร์ของ ThunderPhone เรียกใช้เมื่อ LLM ตัดสินใจใช้เครื่องมือ คำขอเป็น JSON POST โดยมี อาร์กิวเมนต์ที่ LLM เลือกเป็นเนื้อหาคำขอ

1. เลือกกลยุทธ์การจัดเก็บ

คู่มือนี้ใช้แนวทางการผสานรวมที่บันทึกไว้

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)

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

{
  "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 รับข้อมูลการตอบกลับนั้นและพูดสรุปแบบเป็นธรรมชาติให้ผู้โทรฟัง

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

ข้อควรระวังที่พบบ่อย

ขั้นตอนถัดไป