Xây dựng khả năng tích hợp với tác nhân AI và các kỹ năng của tác nhân Application Integration

1. Giới thiệu

Trong lớp học này, bạn sẽ xây dựng một quy trình tích hợp Application Integration bằng cách mô tả quy trình đó cho một tác nhân AI. Bạn cài đặt ba kỹ năng tác nhân Application Integration công khai từ kho lưu trữ google/skills, sau đó ra lệnh cho Gemini CLI viết, tải lên, xuất bản và chạy một quy trình tích hợp mẫu nhỏ.

Mẫu sample-claims-adjudication nhận một yêu cầu bồi thường bảo hiểm và trả về APPROVE, REVIEW hoặc DENY.

Bạn sẽ thực hiện

  • Thiết lập Application Integration trong một dự án trên Google Cloud.
  • Cài đặt các kỹ năng của tác nhân Application Integration.
  • Yêu cầu Gemini CLI tạo, tải lên, xuất bản và chạy một quy trình tích hợp.
  • Hãy tự kiểm tra quá trình thực thi và yêu cầu tác nhân khắc phục sự cố.
  • Xoá quy trình tích hợp mẫu.

Kiến thức bạn sẽ học được

  • Những kỹ năng application-integration-basics, -authoring và -troubleshooting mang lại cho tác nhân.
  • Cách xem xét tệp JSON của phiên bản tích hợp và các lệnh mà tác nhân chạy trước khi bạn phê duyệt.
  • Cách đọc bản ghi thực thi.

2. Thiết lập dự án

  1. Nếu chưa có Tài khoản Google, bạn phải tạo một Tài khoản Google.
    • Sử dụng tài khoản cá nhân thay vì tài khoản công việc hoặc trường học. Tài khoản công việc và tài khoản trường học có thể có các quy định hạn chế khiến bạn không thể bật các API cần thiết cho bài thực hành này.
  2. Đăng nhập vào Google Cloud Console.
  3. Bật tính năng thanh toán trong Cloud Console.
    • Bạn sẽ mất chưa đến 1 USD tài nguyên trên Cloud để hoàn thành bài thực hành này.
    • Bạn có thể làm theo các bước ở cuối bài thực hành này để xoá tài nguyên nhằm tránh bị tính thêm phí.
    • Người dùng mới đủ điều kiện nhận khoản tín dụng dùng thử miễn phí trị giá 300 USD.
  4. Tạo dự án mới hoặc chọn sử dụng lại dự án hiện có.
    • Nếu bạn thấy lỗi về hạn mức dự án, hãy sử dụng lại một dự án hiện có hoặc xoá một dự án hiện có để tạo dự án mới.

Sử dụng một dự án mới hoặc một dự án hiện có mà bạn có thể thử nghiệm một cách an toàn, chứ không phải dự án phát hành chính thức. Tác nhân tải lên, xuất bản và chạy các hoạt động tích hợp trong đó bằng thông tin đăng nhập của bạn.

3. Mở Trình chỉnh sửa Cloud Shell

  1. Nhấp vào đường liên kết này để chuyển thẳng đến Trình chỉnh sửa Cloud Shell
  2. Nếu bạn được nhắc uỷ quyền vào bất kỳ thời điểm nào trong ngày hôm nay, hãy nhấp vào Uỷ quyền để tiếp tục. Nhấp để uỷ quyền cho Cloud Shell
  3. Nếu cửa sổ dòng lệnh không xuất hiện ở cuối màn hình, hãy mở cửa sổ đó:
    • Nhấp vào Xem
    • Nhấp vào Terminal (Thiết bị đầu cuối)Mở cửa sổ dòng lệnh mới trong Trình chỉnh sửa Cloud Shell
  4. Trong cửa sổ dòng lệnh, hãy thiết lập dự án bằng lệnh sau:
    • Định dạng:
      gcloud config set project [PROJECT_ID]
      
    • Ví dụ:
      gcloud config set project lab-project-id-example
      
    • Nếu bạn không nhớ mã dự án:
      • Bạn có thể liệt kê tất cả mã dự án bằng lệnh:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Đặt mã dự án trong thiết bị đầu cuối của Trình chỉnh sửa Cloud Shell
  5. Bạn sẽ thấy thông báo sau:
    Updated property [core/project].
    
    Nếu bạn thấy WARNING và được hỏi Do you want to continue (Y/n)?, thì có thể bạn đã nhập sai mã dự án. Nhấn vào n, nhấn vào Enter rồi thử chạy lại lệnh gcloud config set project.

4. Thiết lập Application Integration

Application Integration là dịch vụ theo khu vực, vì vậy, bạn cần thiết lập dịch vụ này ở một khu vực. Phòng thí nghiệm này sử dụng us-central1.

  1. Ghi lại mã dự án của bạn; bạn sẽ dán mã này vào câu lệnh sau:
    gcloud config get-value project
    
  2. Bật Application Integration API:
    gcloud services enable integrations.googleapis.com
    
  3. Chuyển đến trang Application Integration (Tích hợp ứng dụng) trong Google Cloud Console rồi chọn dự án của bạn.
  4. Trên trang Tổng quan, hãy chọn khu vực us-central1 rồi nhấp vào Thiết lập nhanh. Khi quá trình thiết lập hoàn tất, bảng điều khiển sẽ hiển thị danh sách Tích hợp. Nếu bạn sử dụng lại một dự án, hãy kiểm tra để đảm bảo bạn có các vai trò được liệt kê trong phần Thiết lập Application Integration trước khi nhấp vào Thiết lập nhanh.

Để tìm hiểu thêm, hãy xem bài viết Thiết lập tính năng Tích hợp ứng dụng.

5. Cài đặt kỹ năng của tác nhân

Các kỹ năng này cung cấp cho nhân viên hỗ trợ kiến thức về Application Integration:

  • application-integration-basics: các khái niệm, bật API, cấp phép một khu vực, vai trò IAM và các giới hạn.
  • application-integration-authoring: viết các phiên bản tích hợp dưới dạng JSON, đồng thời tải lên, xuất bản và chạy các phiên bản đó.
  • application-integration-troubleshooting: chẩn đoán các lần chạy không thành công, bị kẹt hoặc không có thông báo.
  1. Tạo một thư mục cho lớp học lập trình này rồi chuyển đến thư mục đó:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. Cài đặt 3 kỹ năng:
    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
    
    Đối với mỗi kỹ năng, trình cài đặt sẽ hỏi một vài câu hỏi. Gemini CLI có trong lựa chọn mặc định Universal (.agents/skills), vì vậy, hãy nhấn phím Enter để giữ lựa chọn này, chọn Project (Dự án) làm phạm vi cài đặt và xác nhận cài đặt.

Các kỹ năng hiện đã có trong ~/appint-agent-lab/.agents/skills.

6. Bắt đầu sử dụng Gemini CLI

  1. Khởi động Gemini CLI từ thư mục của phòng thí nghiệm:
    gemini
    
    Khi Gemini CLI hỏi bạn có tin tưởng thư mục này không, hãy chọn Trust folder (Tin tưởng thư mục). Gemini CLI chỉ tải các kỹ năng từ một thư mục dự án sau khi bạn tin tưởng thư mục đó, rồi khởi động lại. Nếu không khởi động lại, hãy mở một dòng lệnh mới, chuyển đến ~/appint-agent-lab và chạy lại gemini. Bạn có thể cần nhấn phím Enter để chấp nhận một số chế độ cài đặt mặc định.
  2. Liệt kê các kỹ năng mà Gemini CLI có thể sử dụng:
    /skills
    
    Bạn sẽ thấy 3 kỹ năng application-integration-* trong danh sách.

7. Tạo, xuất bản và chạy quy trình tích hợp

  1. Dán câu lệnh này vào Gemini CLI. Thay thế PROJECT_ID bằng mã dự án mà bạn đã ghi chú trong phần Thiết lập 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. Khi tác nhân sử dụng một kỹ năng lần đầu tiên, Gemini CLI sẽ yêu cầu bạn kích hoạt kỹ năng đó. Cho phép.
  3. Tác nhân ghi một tệp phiên bản tích hợp, chẳng hạn như sample-claims-adjudication.json. Tệp này chứa điều kiện kích hoạt (triggerConfigs), nhiệm vụ (taskConfigs) và biến (integrationParameters). Hãy đọc tệp này và yêu cầu tác nhân giải thích mọi điều bạn không mong đợi. Ví dụ: kiểm tra xem tác nhân có bật Cloud Logging (cloudLoggingDetails.enableCloudLogging) hay không, vì việc này có thể làm tăng chi phí. Để tắt, hãy đặt enableCloudLogging thành false và xoá cloudLoggingSeverity.
  4. Phê duyệt các lệnh. Gemini CLI sẽ hỏi trước khi chạy từng lệnh, kể cả lệnh chỉ đọc. Các kỹ năng này cũng yêu cầu tác nhân cho bạn xem lệnh hoặc yêu cầu chính xác trước khi thay đổi bất cứ điều gì, chẳng hạn như tải lên, xuất bản hoặc chạy quy trình tích hợp. Nếu nhân viên hỗ trợ yêu cầu phê duyệt mà không hiển thị lệnh, hãy yêu cầu nhân viên hỗ trợ hiển thị lệnh. Kiểm tra dự án, khu vực và tên của thành phần tích hợp trước khi phê duyệt, đồng thời từ chối các lệnh đọc hoặc thay đổi thành phần tích hợp không phải của bạn.

Sau khi bạn phê duyệt, tác nhân sẽ tải tệp JSON lên dưới dạng phiên bản mới (versions.upload), xuất bản tệp (versions.publish) và chạy tệp thông qua trình kích hoạt API (integrations.execute). Sau đó, tác nhân sẽ cho bạn biết quyết định, lý do và mã thực thi.

8. Xác minh quá trình thực thi

Tự chạy quy trình tích hợp đã xuất bản và đọc bản ghi thực thi của quy trình đó.

  1. Mở một thẻ dòng lệnh mới trong Cloud Shell, chuyển đến thư mục của phòng thí nghiệm, rồi lưu mã dự án và khu vực vào các biến:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. Chạy quy trình tích hợp với thông báo xác nhận quyền sở hữu trên 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"
    
    Phản hồi chứa executionId và outputParameters, trong đó decision được đặt thành REVIEW.
  3. Đọc bản ghi thực thi. Thay thế EXECUTION_ID bằng executionId từ phản hồi:
    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"
    
    Trong phản hồi, executionDetails.state là SUCCEEDED và executionDetails.executionSnapshots cho biết trạng thái của từng nhiệm vụ.

Bạn cũng có thể xem lần chạy này trong nhật ký thực thi trong Google Cloud Console.

9. Khắc phục sự cố

Phản hồi thành công không phải lúc nào cũng có nghĩa là mọi tác vụ đều thực hiện đúng như bạn mong đợi. Yêu cầu nhân viên hỗ trợ kiểm tra quá trình thực thi. Trong Gemini CLI, hãy nhập câu lệnh này, thay thế EXECUTION_ID:

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

Tác nhân đọc bản ghi thực thi bằng executions.list, được lọc theo mã thực thi và tóm tắt trạng thái của lần chạy cũng như của từng nhiệm vụ.

Nếu có vấn đề xảy ra trong phòng thí nghiệm này, hãy kiểm tra các nguyên nhân phổ biến sau:

  • /skills không liệt kê các kỹ năng về Application Integration. Bắt đầu Gemini CLI từ ~/appint-agent-lab và tin tưởng thư mục này.
  • Cuộc gọi không thành công và có lỗi PERMISSION_DENIED. Kiểm tra để đảm bảo bạn đang sử dụng đúng dự án và có vai trò Người chỉnh sửa Application Integration (roles/integrations.integrationEditor) trong dự án đó.
  • Không chạy được quá trình tích hợp do lỗi No integrations found for the requested trigger_id. Kiểm tra để đảm bảo dự án và khu vực trong yêu cầu khớp với nơi xuất bản quy trình tích hợp, triggerId là api_trigger/adjudicate_claim và một phiên bản của quy trình tích hợp đã được xuất bản. Bạn cũng sẽ gặp lỗi tương tự nếu đã tải một phiên bản lên nhưng chưa xuất bản.

10. Dọn dẹp

  1. Trong Gemini CLI, hãy yêu cầu tác nhân xoá công cụ tích hợp mẫu:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    Sau khi bạn phê duyệt, nhân viên hỗ trợ sẽ huỷ xuất bản phiên bản đã xuất bản (versions.unpublish) và xoá từng phiên bản (versions.delete). Khi không còn phiên bản nào, thành phần tích hợp sẽ không còn xuất hiện trong danh sách thành phần tích hợp của bạn.Nếu chỉ tạo một dự án cho phòng thí nghiệm này, bạn có thể xoá dự án thay vì xoá thành phần tích hợp. Chạy lệnh này trong thẻ dòng lệnh mà bạn đã mở trong phần Xác minh quá trình thực thi:
    gcloud projects delete $(gcloud config get-value project)
    
  2. Nhập /quit rồi nhấn Enter để thoát khỏi Gemini CLI.
  3. Xoá thư mục phòng thí nghiệm:
    cd ~ && rm -rf ~/appint-agent-lab
    

11. Xin chúc mừng

Bạn đã tạo, xuất bản, chạy và kiểm tra một quy trình tích hợp bằng cách ra lệnh cho một tác nhân AI có các kỹ năng của tác nhân Application Integration.

Bước tiếp theo