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,-authoringvà-troubleshootingmang 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
- 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.
- Đăng nhập vào Google Cloud Console.
- 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.
- 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
- Nhấp vào đường liên kết này để chuyển thẳng đến Trình chỉnh sửa Cloud Shell
- 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.

- 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)

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

- Bạn có thể liệt kê tất cả mã dự án bằng lệnh:
- Định dạng:
- Bạn sẽ thấy thông báo sau:
Nếu bạn thấyUpdated property [core/project].
WARNINGvà được hỏiDo you want to continue (Y/n)?, thì có thể bạn đã nhập sai mã dự án. Nhấn vàon, nhấn vàoEnterrồi thử chạy lại lệnhgcloud 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.
- 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 - Bật Application Integration API:
gcloud services enable integrations.googleapis.com - 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.
- Trên trang Tổng quan, hãy chọn khu vực
us-central1rồ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.
- 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 - Cài đặt 3 kỹ năng:
Đố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ímnpx 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-troubleshootingEnterđể 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
- Khởi động Gemini CLI từ thư mục của phòng thí nghiệm:
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 đếngemini~/appint-agent-labvà chạy lạigemini. Bạn có thể cần nhấn phímEnterđể chấp nhận một số chế độ cài đặt mặc định. - Liệt kê các kỹ năng mà Gemini CLI có thể sử dụng:
Bạn sẽ thấy 3 kỹ năng/skillsapplication-integration-*trong danh sách.
7. Tạo, xuất bản và chạy quy trình tích hợp
- Dán câu lệnh này vào Gemini CLI. Thay thế
PROJECT_IDbằ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. - 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.
- 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 đặtenableCloudLoggingthànhfalsevà xoácloudLoggingSeverity. - 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 đó.
- 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 - 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:
Phản hồi chứacurl -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"executionIdvàoutputParameters, trong đódecisionđược đặt thànhREVIEW. - Đọc bản ghi thực thi. Thay thế
EXECUTION_IDbằngexecutionIdtừ phản hồi: Trong 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"executionDetails.statelàSUCCEEDEDvàexecutionDetails.executionSnapshotscho 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:
/skillskhông liệt kê các kỹ năng về Application Integration. Bắt đầu Gemini CLI từ~/appint-agent-labvà 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,triggerIdlàapi_trigger/adjudicate_claimvà 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
- Trong Gemini CLI, hãy yêu cầu tác nhân xoá công cụ tích hợp mẫu:
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 (Unpublish sample-claims-adjudication, then delete every version of it.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) - Nhập
/quitrồi nhấnEnterđể thoát khỏi Gemini CLI. - 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
- Tạo một công cụ tích hợp với tác nhân AI
- Kỹ năng của tác nhân Application Integration
- Đọc về các kỹ năng trên GitHub: kiến thức cơ bản, tác giả và khắc phục sự cố.