สร้างการผสานรวมกับ AI Agent และทักษะของ Agent ใน Application Integration

1. บทนำ

ในห้องปฏิบัติการนี้ คุณจะสร้างการผสานรวม Application Integration โดยอธิบายให้ AI Agent ฟัง คุณติดตั้งทักษะของเอเจนต์ Application Integration สาธารณะ 3 รายการจากที่เก็บ google/skills จากนั้นจึงพรอมต์ Gemini CLI ให้เขียน อัปโหลด เผยแพร่ และเรียกใช้การผสานรวมตัวอย่างขนาดเล็ก

ตัวอย่าง sample-claims-adjudication จะรับการเคลมประกันและแสดงผลเป็น APPROVE, REVIEW หรือ DENY

สิ่งที่คุณจะทำ

  • ตั้งค่า Application Integration ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google
  • ติดตั้งทักษะ Agent ของ Application Integration
  • ป้อนพรอมต์ให้ Gemini CLI สร้าง อัปโหลด เผยแพร่ และเรียกใช้การผสานรวม
  • ตรวจสอบการดำเนินการด้วยตนเอง และขอให้ Agent แก้ปัญหา
  • ล้างการผสานรวมตัวอย่าง

สิ่งที่คุณจะได้เรียนรู้

  • ทักษะ application-integration-basics, -authoring และ -troubleshooting ช่วยให้ Agent ทำอะไรได้บ้าง
  • วิธีตรวจสอบ JSON ของเวอร์ชันการผสานรวมและคำสั่งที่ Agent เรียกใช้ก่อนที่คุณจะอนุมัติ
  • วิธีอ่านบันทึกการดำเนินการ

2. การตั้งค่าโปรเจ็กต์

  1. หากยังไม่มีบัญชี Google คุณต้องสร้างบัญชี Google
    • ใช้บัญชีส่วนตัวแทนบัญชีงานหรือบัญชีโรงเรียน บัญชีงานและบัญชีโรงเรียนอาจมีข้อจำกัดที่ทำให้คุณไม่สามารถเปิดใช้ API ที่จำเป็นสำหรับห้องทดลองนี้ได้
  2. ลงชื่อเข้าใช้คอนโซล Google Cloud
  3. เปิดใช้การเรียกเก็บเงินใน Cloud Console
    • การทำห้องทดลองนี้ให้เสร็จสมบูรณ์ควรใช้ทรัพยากร Cloud ไม่เกิน $1 USD
    • คุณสามารถทำตามขั้นตอนที่ตอนท้ายของห้องทดลองนี้เพื่อลบทรัพยากรเพื่อหลีกเลี่ยงการเรียกเก็บเงินเพิ่มเติม
    • ผู้ใช้ใหม่มีสิทธิ์รับช่วงทดลองใช้ฟรีมูลค่า $300 USD
  4. สร้างโปรเจ็กต์ใหม่หรือเลือกใช้โปรเจ็กต์ที่มีอยู่ซ้ำ
    • หากเห็นข้อผิดพลาดเกี่ยวกับโควต้าโปรเจ็กต์ ให้ใช้โปรเจ็กต์ที่มีอยู่ซ้ำหรือลบโปรเจ็กต์ที่มีอยู่เพื่อสร้างโปรเจ็กต์ใหม่

ใช้โปรเจ็กต์ใหม่หรือโปรเจ็กต์ที่มีอยู่ซึ่งคุณสามารถทดสอบได้อย่างปลอดภัย ไม่ใช่โปรเจ็กต์เวอร์ชันที่ใช้งานจริง Agent จะอัปโหลด เผยแพร่ และเรียกใช้การผสานรวมในนั้นด้วยข้อมูลเข้าสู่ระบบของคุณ

3. เปิดเครื่องมือแก้ไข Cloud Shell

  1. คลิกลิงก์นี้เพื่อไปยังเครื่องมือแก้ไข Cloud Shell โดยตรง
  2. หากระบบแจ้งให้คุณให้สิทธิ์ในขั้นตอนใดก็ตามในวันนี้ ให้คลิกให้สิทธิ์เพื่อดำเนินการต่อ คลิกเพื่อให้สิทธิ์ Cloud Shell
  3. หากเทอร์มินัลไม่ปรากฏที่ด้านล่างของหน้าจอ ให้เปิดเทอร์มินัลโดยทำดังนี้
    • คลิกดู
    • คลิก Terminalเปิดเทอร์มินัลใหม่ในเครื่องมือแก้ไข Cloud Shell
  4. ในเทอร์มินัล ให้ตั้งค่าโปรเจ็กต์ด้วยคำสั่งต่อไปนี้
    • รูปแบบ:
      gcloud config set project [PROJECT_ID]
      
    • ตัวอย่าง
      gcloud config set project lab-project-id-example
      
    • หากจำรหัสโปรเจ็กต์ไม่ได้ ให้ทำดังนี้
      • คุณแสดงรายการรหัสโปรเจ็กต์ทั้งหมดได้โดยใช้คำสั่งต่อไปนี้
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      ตั้งค่ารหัสโปรเจ็กต์ในเทอร์มินัลเครื่องมือแก้ไข Cloud Shell
  5. คุณควรเห็นข้อความต่อไปนี้
    Updated property [core/project].
    
    หากเห็น WARNING และระบบถามว่า Do you want to continue (Y/n)? แสดงว่าคุณอาจป้อนรหัสโปรเจ็กต์ไม่ถูกต้อง กด n กด Enter แล้วลองเรียกใช้คำสั่ง gcloud config set project อีกครั้ง

4. ตั้งค่า Application Integration

Application Integration เป็นระดับภูมิภาค คุณจึงตั้งค่าได้ในภูมิภาคเดียว ห้องทดลองนี้ใช้ us-central1

  1. จดรหัสโปรเจ็กต์ไว้เพื่อนำไปวางในพรอมต์ในภายหลัง
    gcloud config get-value project
    
  2. เปิดใช้ Application Integration API โดยทำดังนี้
    gcloud services enable integrations.googleapis.com
    
  3. ไปที่หน้า Application Integration ในคอนโซล Google Cloud แล้วเลือกโปรเจ็กต์
  4. ในหน้าภาพรวม ให้เลือกภูมิภาค us-central1 แล้วคลิกการตั้งค่าด่วน เมื่อตั้งค่าเสร็จแล้ว คอนโซลจะแสดงรายการการผสานรวม หากใช้โปรเจ็กต์ซ้ำ ให้ตรวจสอบว่าคุณมีบทบาทที่ระบุไว้ในตั้งค่า Application Integration ก่อนคลิกการตั้งค่าด่วน

ดูข้อมูลเพิ่มเติมได้ที่ตั้งค่า Application Integration

5. ติดตั้งทักษะของ Agent

ทักษะจะให้ความรู้เกี่ยวกับ Application Integration แก่ Agent ดังนี้

  • application-integration-basics: แนวคิด, การเปิดใช้ API, การจัดสรรภูมิภาค, บทบาท IAM และขีดจำกัด
  • application-integration-authoring: การเขียนเวอร์ชันการผสานรวมเป็น JSON รวมถึงการอัปโหลด การเผยแพร่ และการเรียกใช้
  • application-integration-troubleshooting: การวิเคราะห์การเรียกใช้ที่ล้มเหลว ค้าง หรือไม่มีการตอบสนอง
  1. สร้างไดเรกทอรีสำหรับห้องทดลองนี้และไปที่ไดเรกทอรีดังกล่าว
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. ติดตั้งทักษะ 3 อย่างต่อไปนี้
    npx skills add google/skills --skill application-integration-basics
    npx skills add google/skills --skill application-integration-authoring
    npx skills add google/skills --skill application-integration-troubleshooting
    
    ผู้ติดตั้งจะถามคำถาม 2-3 ข้อสำหรับทักษะแต่ละอย่าง Gemini CLI รวมอยู่ในตัวเลือก Universal (.agents/skills) โดยค่าเริ่มต้น ดังนั้นให้กด Enter เพื่อเก็บไว้ เลือก Project เป็นขอบเขตการติดตั้ง และยืนยันการติดตั้ง

ตอนนี้ทักษะอยู่ใน ~/appint-agent-lab/.agents/skills แล้ว

6. เริ่มใช้ Gemini CLI

  1. เริ่ม Gemini CLI จากไดเรกทอรีห้องทดลอง
    gemini
    
    เมื่อ Gemini CLI ถามว่าคุณเชื่อถือโฟลเดอร์นี้หรือไม่ ให้เลือกเชื่อถือโฟลเดอร์ Gemini CLI จะโหลดทักษะจากโฟลเดอร์โปรเจ็กต์หลังจากที่คุณเชื่อถือโฟลเดอร์เท่านั้น จากนั้นจะรีสตาร์ท หากไม่รีสตาร์ท ให้เปิดเทอร์มินัลใหม่ ไปที่ ~/appint-agent-lab แล้วเรียกใช้ gemini อีกครั้ง คุณอาจต้องกด Enter เพื่อยอมรับการตั้งค่าเริ่มต้นบางอย่าง
  2. แสดงรายการทักษะที่ Gemini CLI ใช้ได้
    /skills
    
    คุณควรเห็นทักษะ application-integration-* 3 รายการในลิสต์

7. สร้าง เผยแพร่ และเรียกใช้การผสานรวม

  1. วางพรอมต์นี้ลงใน Gemini CLI แทนที่ PROJECT_ID ด้วยรหัสโปรเจ็กต์ที่จดไว้ในส่วนตั้งค่า Application Integration
    Using the Application Integration skills, build an integration named
    sample-claims-adjudication in project PROJECT_ID, region us-central1.
    
    - Start it with an API trigger named adjudicate_claim.
    - Inputs: claimId (string), claimAmount (double), policyActive (boolean).
    - Outputs: decision (string) and reason (string).
    - Rules: if policyActive is false, return DENY. If claimAmount is 1000 or less,
      return APPROVE. Otherwise, return REVIEW. Set reason to a short explanation.
    - Save the integration version JSON in this directory so I can review it.
    - Show me every command before you run it, then upload, publish, and run it
      once with a sample claim.
    
  2. เมื่อ Agent ใช้ทักษะเป็นครั้งแรก Gemini CLI จะขอให้คุณเปิดใช้งาน อนุญาต
  3. ตัวแทนจะเขียนไฟล์เวอร์ชันการผสานรวม เช่น sample-claims-adjudication.json ซึ่งประกอบด้วยทริกเกอร์ (triggerConfigs) งาน (taskConfigs) และตัวแปร (integrationParameters) โปรดอ่านและขอให้ Agent อธิบายสิ่งที่คุณไม่คาดคิด เช่น ตรวจสอบว่า Agent เปิด Cloud Logging (cloudLoggingDetails.enableCloudLogging) ไว้หรือไม่ ซึ่งอาจทำให้มีค่าใช้จ่ายเพิ่มขึ้น หากต้องการปิด ให้ตั้งค่า enableCloudLogging เป็น false และนำ cloudLoggingSeverity ออก
  4. อนุมัติคำสั่ง Gemini CLI จะถามก่อนที่จะเรียกใช้แต่ละคำสั่ง รวมถึงคำสั่งแบบอ่านอย่างเดียว นอกจากนี้ ทักษะยังบอกให้ Agent แสดงคำสั่งหรือคำขอที่แน่นอนก่อนที่จะเปลี่ยนแปลงสิ่งใดๆ เช่น การอัปโหลด การเผยแพร่ หรือการเรียกใช้การผสานรวม หาก Agent ขออนุมัติโดยไม่แสดงคำสั่ง ให้ขอให้ Agent แสดงคำสั่ง ตรวจสอบโปรเจ็กต์ ภูมิภาค และชื่อการผสานรวมก่อนอนุมัติ และปฏิเสธคำสั่งที่อ่านหรือเปลี่ยนแปลงการผสานรวมที่ไม่ใช่ของคุณ

หลังจากที่คุณอนุมัติ ตัวแทนจะอัปโหลดไฟล์ JSON เป็นเวอร์ชันใหม่ (versions.upload) เผยแพร่ (versions.publish) และเรียกใช้ผ่านทริกเกอร์ API (integrations.execute) จากนั้นจะแสดงการตัดสินใจ เหตุผล และรหัสการดำเนินการให้คุณเห็น

8. ยืนยันการดำเนินการ

เรียกใช้การผสานรวมที่เผยแพร่ด้วยตนเองและอ่านบันทึกการดำเนินการ

  1. เปิดแท็บเทอร์มินัล Cloud Shell ใหม่ ไปที่ไดเรกทอรีของห้องทดลอง แล้วบันทึกรหัสโปรเจ็กต์และภูมิภาคในตัวแปร โดยทำดังนี้
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. เรียกใช้การผสานรวมที่มีการอ้างสิทธิ์มากกว่า 1,000 รายการโดยทำดังนี้
    curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
          "triggerId": "api_trigger/adjudicate_claim",
          "inputParameters": {
            "claimId": {"stringValue": "CLM-1001"},
            "claimAmount": {"doubleValue": 2500},
            "policyActive": {"booleanValue": true}
          }
        }' \
        "https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/integrations/sample-claims-adjudication:execute"
    
    การตอบกลับจะมี executionId และ outputParameters โดยตั้งค่า decision เป็น REVIEW
  3. อ่านบันทึกการดำเนินการ แทนที่ EXECUTION_ID ด้วย executionId จากการตอบกลับ:
    curl -G \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        --data-urlencode 'filter=execution_id="EXECUTION_ID"' \
        "https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/integrations/sample-claims-adjudication/executions"
    
    ในการตอบกลับ executionDetails.state คือ SUCCEEDED และ executionDetails.executionSnapshots แสดงสถานะของแต่ละงาน

นอกจากนี้ คุณยังดูการเรียกใช้ได้ในบันทึกการดำเนินการในคอนโซล Google Cloud

9. แก้ปัญหา

การตอบกลับที่สำเร็จไม่ได้หมายความว่าทุกงานจะทำตามที่คุณคาดหวังเสมอไป ขอให้ตัวแทนตรวจสอบการดำเนินการ ใน Gemini CLI ให้ป้อนพรอมต์นี้โดยแทนที่ EXECUTION_ID:

Check execution EXECUTION_ID of sample-claims-adjudication. Did every task
succeed? If anything failed, tell me why and propose a fix.

ตัวแทนจะอ่านบันทึกการดำเนินการด้วย executions.list โดยกรองตามรหัสการดำเนินการ และสรุปสถานะของการเรียกใช้และของแต่ละงาน

หากเกิดข้อผิดพลาดในห้องทดลองนี้ ให้ตรวจสอบสาเหตุที่พบบ่อยต่อไปนี้

  • /skills ไม่ได้ระบุทักษะด้าน Application Integration เริ่มใช้ Gemini CLI จาก ~/appint-agent-lab และเชื่อถือโฟลเดอร์
  • การเรียกใช้ล้มเหลวโดยมีข้อผิดพลาด PERMISSION_DENIED ตรวจสอบว่าคุณใช้โปรเจ็กต์ที่ถูกต้อง และคุณมีบทบาท Application Integration Editor (roles/integrations.integrationEditor) ในโปรเจ็กต์นั้น
  • การเรียกใช้การผสานรวมไม่สำเร็จโดยมีข้อผิดพลาด No integrations found for the requested trigger_id ตรวจสอบว่าโปรเจ็กต์และภูมิภาคในคำขอตรงกับตำแหน่งที่เผยแพร่การผสานรวม โดย triggerId คือ api_trigger/adjudicate_claim และมีการเผยแพร่เวอร์ชันของการผสานรวม คุณจะได้รับข้อผิดพลาดเดียวกันหากอัปโหลดเวอร์ชันแต่ไม่ได้เผยแพร่

10. ล้างข้อมูล

  1. ใน Gemini CLI ให้ขอให้ Agent นำการผสานรวมตัวอย่างออกโดยทำดังนี้
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    หลังจากที่คุณอนุมัติ ตัวแทนจะยกเลิกการเผยแพร่เวอร์ชันที่เผยแพร่ (versions.unpublish) และลบแต่ละเวอร์ชัน (versions.delete) เมื่อไม่มีเวอร์ชันเหลืออยู่ การผสานรวมจะไม่ปรากฏในรายการการผสานรวมอีกต่อไป หากคุณสร้างโปรเจ็กต์สำหรับห้องทดลองนี้เท่านั้น คุณสามารถลบโปรเจ็กต์แทนการนำการผสานรวมออกได้ เรียกใช้คำสั่งนี้ในแท็บเทอร์มินัลที่คุณเปิดในยืนยันการดำเนินการ
    gcloud projects delete $(gcloud config get-value project)
    
  2. พิมพ์ /quit แล้วกด Enter เพื่อออกจาก Gemini CLI
  3. ลบไดเรกทอรีของห้องทดลองโดยทำดังนี้
    cd ~ && rm -rf ~/appint-agent-lab
    

11. ขอแสดงความยินดี

คุณได้สร้าง เผยแพร่ เรียกใช้ และตรวจสอบการผสานรวมโดยการป้อนพรอมต์ AI Agent ด้วยทักษะ Agent ของ Application Integration

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