Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

CLI tác nhân trong Nền tảng tác nhân: Từ giai đoạn phát triển đến giai đoạn sản xuất

1. Tổng quan

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

Trong Lớp học lập trình này, bạn sẽ xây dựng, kiểm thử và triển khai một tác nhân AI sẵn sàng cho hoạt động sản xuất bằng Agents CLI và Bộ công cụ phát triển tác nhân (ADK). Bạn sẽ chuyển từ việc cài đặt các công cụ sang việc có một tác nhân đang chạy trên Agent Runtime của Google Cloud trong vòng chưa đầy một giờ.

Sản phẩm bạn sẽ tạo ra

Một tác nhân AI hỗ trợ khách hàng có thể:

Trả lời câu hỏi bằng ngôn ngữ tự nhiên
Gọi các công cụ tuỳ chỉnh (tra cứu thời tiết và thời gian)
Được kiểm thử tại địa phương và nhận phản hồi tức thì
Được đánh giá tự động về chất lượng
Chạy trong môi trường phát hành chính thức trên Google Cloud

Hai cách sử dụng Agents CLI

Agents CLI hỗ trợ 2 quy trình làm việc:

🤖 Với Trợ lý lập trình (Nên dùng cho người mới bắt đầu)

Hãy để AI hướng dẫn bạn! Cài đặt các kỹ năng vào Gemini CLI, Antigravity, Claude Code, Cursor hoặc bất kỳ tác nhân lập trình nào khác được hỗ trợ – các kỹ năng này sẽ giúp bạn xây dựng tác nhân từng bước.

👤 Chế độ thủ công (Dành cho những nhà phát triển muốn kiểm soát trực tiếp)

Tự chạy các lệnh từ thiết bị đầu cuối. Bạn sẽ nhập từng lệnh và xem chính xác những gì xảy ra.

Trong suốt Lớp học lập trình này, chúng ta sẽ xem xét cả hai phương pháp. Hãy chọn cách phù hợp với phong cách của bạn!

Bạn cần có

Bắt buộc:

Python 3.11 trở lên
Trình quản lý gói uv
Node.js 18 trở lên (đối với các kỹ năng của tác nhân lập trình)
Dự án trên Google Cloud đã bật tính năng thanh toán
Đã cài đặt Google Cloud SDK

Không bắt buộc đối với quá trình phát triển chỉ dành cho địa phương:

Khoá API AI Studio (phương án thay thế cho GCP để kiểm thử cục bộ)

Điều kiện tiên quyết

Lớp học lập trình này giả định rằng bạn đã quen thuộc với:

Sử dụng thiết bị đầu cuối/dòng lệnh
Các khái niệm cơ bản về Python
Kiến thức cơ bản về Google Cloud Console

Bạn không cần có kinh nghiệm sử dụng tác nhân AI hoặc ADK!

2. Trước khi bắt đầu

Thiết lập Google Cloud

Tạo hoặc chọn một dự án

Chuyển đến Google Cloud Console
Tạo dự án mới hoặc chọn một dự án hiện có
Ghi lại Mã dự án – bạn sẽ cần mã này sau

Bật các API bắt buộc

Chạy các lệnh này trong thiết bị đầu cuối (hoặc sử dụng Cloud Console):

gcloud services enable aiplatform.googleapis.com \
  run.googleapis.com \
  cloudtrace.googleapis.com \
  cloudbuild.googleapis.com

Điều này cho phép:

Nền tảng tác nhân – Dành cho mô hình Gemini và Thời gian chạy tác nhân
Cloud Run – Lựa chọn triển khai thay thế
Cloud Trace – Khả năng ghi nhận và giám sát
Cloud Build – Tự động hoá quy trình tạo bản dựng

Xác thực

gcloud auth login
gcloud auth application-default login

Đặt các biến môi trường

export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1

Thay thế YOUR_PROJECT_ID bằng mã dự án thực tế của bạn.

3. Cài đặt Agents CLI

🤖 Với một Trợ lý lập trình

Nếu bạn đang sử dụng Gemini CLI, Antigravity, Claude Code, Cursor hoặc bất kỳ tác nhân lập trình nào khác được hỗ trợ:

uvx google-agents-cli setup

Thao tác này sẽ cài đặt:

Công cụ CLI của Agents trên toàn cầu
7 kỹ năng mà mọi tác nhân mã hoá được hỗ trợ trên máy của bạn đều có thể sử dụng để giúp bạn tạo tác nhân (các kỹ năng được cài đặt một lần và được mọi tác nhân hỗ trợ chúng phát hiện)

Kết quả đầu ra dự kiến (đã cắt bớt):

 █▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀   █▀▀ █  █
 █▀█ █▄█ ██▄ █ ▀█  █  ▄█   █▄▄ █▄ █

 Your coding agent just got an upgrade.

 1. Authentication
 ─────────────────
   ✓ Authenticated with Google Cloud

 2. CLI Installation
 ───────────────────
   ▸ uv tool install google-agents-cli
   ✓ Installed google-agents-cli

 3. Skills Installation
 ──────────────────────
   ▸ npx -y skills add https://github.com/google/agents-cli -y --all -g

   ◇  Found 7 skills
   ~/.agents/skills/google-agents-cli-adk-code
   ~/.agents/skills/google-agents-cli-deploy
   ~/.agents/skills/google-agents-cli-eval
   ~/.agents/skills/google-agents-cli-observability
   ~/.agents/skills/google-agents-cli-publish
   ~/.agents/skills/google-agents-cli-scaffold
   ~/.agents/skills/google-agents-cli-workflow

Các kỹ năng được cài đặt thông qua skills (npx -y skills@latest) vào ~/.agents/skills/ và được mọi tác nhân lập trình được hỗ trợ trên máy của bạn tự động chọn.

👤 Chế độ thủ công

Nếu bạn muốn chạy lệnh trực tiếp:

uv tool install google-agents-cli

Xác minh quá trình cài đặt:

agents-cli --version

Kết quả đầu ra dự kiến:

agents-cli, version 0.1.2

4. Tạo dự án tác nhân

🤖 Với một Trợ lý lập trình

Hỏi tác nhân lập trình:

"Tạo một dự án tác nhân ADK mới có tên là customer-support-agent bằng mẫu nguyên mẫu"

Tác nhân của bạn sẽ chạy lệnh giàn giáo và tạo dự án cho bạn.

👤 Chế độ thủ công

Sử dụng chế độ nhanh để tạo một dự án nhất quán phù hợp với Lớp học lập trình này:

agents-cli scaffold create customer-support-agent --prototype --yes

Thao tác này sẽ tạo ngay một dự án tác nhân ADK cơ bản với tất cả mã cần thiết cho Lớp học lập trình này.

Kết quả đầu ra dự kiến:

Agents CLI v0.1.2
> Verifying GCP credentials...
> ✓ Connected to project: YOUR_PROJECT_ID

✅ Success! Your agent project is ready.

📖 Documentation
   README:    cat customer-support-agent/README.md

💡 Tip
   Add a deployment target later with: agents-cli scaffold enhance

🚀 Get Started
   cd customer-support-agent && agents-cli install && agents-cli playground

Cách khác: Chế độ tương tác

Nếu bạn muốn khám phá các loại tác nhân khác, hãy chạy mà không có cờ:

agents-cli scaffold create customer-support-agent

Bạn sẽ thấy các lựa chọn:

adk – Tác nhân ReAct đơn giản (chọn tác nhân này cho Lớp học lập trình)
adk_a2a – Giao tiếp giữa các nhân viên hỗ trợ
agentic_rag – Tính năng Hỏi và đáp về tài liệu dựa trên RAG

Nội dung nào đã được tạo?

customer-support-agent/
├── app/
│   ├── agent.py              # Your agent code (main file)
│   ├── fast_api_app.py       # Development server (replaced when you add a deployment target)
│   └── app_utils/            # Utilities (telemetry, etc.)
├── tests/
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── eval/                 # Evalsets and rubric config for `adk eval`
├── Dockerfile                # Container image (removed when you switch to Agent Runtime)
├── GEMINI.md                 # Coding-agent context for this project
├── pyproject.toml            # Project config & dependencies
├── README.md                 # Project documentation
└── .gitignore

5. Khám phá mã tác nhân

Chuyển đến dự án của bạn

cd customer-support-agent

Kiểm tra nhân viên hỗ trợ

Mở app/agent.py – đây là nơi bạn xác định tác nhân của mình:

import datetime
from zoneinfo import ZoneInfo

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

import os
import google.auth

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"


def get_weather(query: str) -> str:
    """Simulates a web search. Use it get information on weather.

    Args:
        query: A string containing the location to get weather information for.

    Returns:
        A string with the simulated weather information for the queried location.
    """
    if "sf" in query.lower() or "san francisco" in query.lower():
        return "It's 60 degrees and foggy."
    return "It's 90 degrees and sunny."


def get_current_time(query: str) -> str:
    """Simulates getting the current time for a city.

    Args:
        city: The name of the city to get the current time for.

    Returns:
        A string with the current time information.
    """
    if "sf" in query.lower() or "san francisco" in query.lower():
        tz_identifier = "America/Los_Angeles"
    else:
        return f"Sorry, I don't have timezone information for query: {query}."

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    return f"The current time for query {query} is {now.strftime('%Y-%m-%d %H:%M:%S %Z%z')}"


root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-flash-latest",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
    tools=[get_weather, get_current_time],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Khái niệm chính

Công cụ: Các hàm Python mà tác nhân của bạn có thể gọi

get_weather(query) – Trả về thời tiết mô phỏng (sương mù 60°F cho San Francisco, trời nắng 90°F cho các địa điểm khác)
get_current_time(query) – Trả về thời gian hiện tại (chỉ San Francisco trong phần nội dung này)

Mô hình: gemini-flash-latest là một bí danh tự động theo dõi bản phát hành ổn định mới nhất của Gemini Flash, vì vậy mã này sẽ tiếp tục hoạt động khi Google phát hành các phiên bản mới. Để ghim một mô hình cụ thể, hãy thay thế bằng một mô hình như gemini-2.5-flash (ổn định) hoặc gemini-3-flash-preview (xem trước).

Ứng dụng / root_agent: Các dự án ADK hiển thị một App cấp cao nhất bao bọc một root_agent. Sân chơi, adk eval và Thời gian chạy của tác nhân đều phát hiện tác nhân thông qua đối tượng app này.

Vị trí =

"global": Một số mô hình xem trước của Gemini chỉ được phân phát từ điểm cuối global. Đó là lý do mà giàn giáo đặt điểm cuối này một cách rõ ràng.

Hướng dẫn: Câu lệnh hệ thống định hình hành vi của đặc vụ.

6. Kiểm thử cục bộ bằng Playground

Sân chơi này cung cấp một giao diện trò chuyện tương tác để kiểm thử.

🤖 Với một Trợ lý lập trình

Hỏi nhân viên hỗ trợ:

"Start the playground for my agent" (Bắt đầu sân chơi cho đặc vụ của tôi)

👤 Chế độ thủ công

Trước tiên, hãy cài đặt các phần phụ thuộc

agents-cli install

Thao tác này chạy uv sync ở chế độ nền, giải quyết và cài đặt các phần phụ thuộc của tác nhân vào .venv cục bộ.

Bắt đầu bản nháp

agents-cli playground

Kết quả đầu ra dự kiến:

╭──────────────────────────────────────────────────────────────────────────────╮
│ Starting your agent playground...                                            │
│                                                                              │
│ Will be available at:  http://127.0.0.1:8080/dev-ui/?app=app                 │
╰──────────────────────────────────────────────────────────────────────────────╯
  ▸ uv run adk web . --host 127.0.0.1 --port 8080 --reload_agents
INFO:     Started server process
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8080

Dùng thử

Mở http://127.0.0.1:8080/dev-ui/?app=app trong trình duyệt
Hãy thử những câu lệnh sau:
- "Thời tiết ở San Francisco thế nào?"
- "Thời tiết ở Tokyo thế nào?"
- "Ở San Francisco đang là mấy giờ?"

Xem cách nhân viên hỗ trợ:

Gọi công cụ get_weather
Gọi công cụ get_current_time
Kết hợp các kết quả thành câu trả lời tự nhiên

7. Chạy từ dòng lệnh

Thử nghiệm nhân viên hỗ trợ mà không cần mở trình duyệt.

🤖 Với một Trợ lý lập trình

Hỏi nhân viên hỗ trợ:

"Chạy tác nhân với truy vấn "Thời tiết ở Paris thế nào?""

👤 Chế độ thủ công

agents-cli run "What's the weather in San Francisco?"

Kết quả đầu ra dự kiến:

Using project root directory: /path/to/customer-support-agent
Local server started on port 18080 (PID 30008)
  Stop with: agents-cli run --stop-server
[user]: What's the weather in San Francisco?
[root_agent]:
[tool_call: get_weather({"query": "San Francisco"})]
[tool_response: get_weather -> {"result": "It's 60 degrees and foggy."}]The weather in San Francisco is 60 degrees and foggy.

Session: fb30f7f7-147e-4697-8aaa-706d604589fa (resume with --session-id)

Ở chế độ nền, run sẽ khởi động một adk api_server ở chế độ nền (duy trì trạng thái hoạt động trong khoảng 30 phút) để các lệnh gọi tiếp theo diễn ra nhanh chóng. Dừng rõ ràng bằng agents-cli run --stop-server. Tiếp tục cuộc trò chuyện nhiều lượt với --session-id .

Lệnh run rất phù hợp với:

Thử nghiệm nhanh trong quá trình phát triển
Tập lệnh và tự động hoá
Quy trình CI/CD

8. Đánh giá tác nhân

Các đánh giá ADK xác thực 2 điều độc lập:

Quỹ đạo của công cụ – liệu tác nhân có gọi đúng công cụ với đúng đối số không? Xác định, khớp chính xác.
Chất lượng của câu trả lời – câu trả lời cuối cùng có phù hợp, hữu ích và dựa trên kết quả của công cụ không? Được tính điểm bởi một LLM đóng vai trò là người đánh giá.

Bạn cần cả hai. Chỉ dựa vào điểm theo bảng tiêu chí thì có thể bỏ qua một câu trả lời ảo nhưng đọc được; chỉ dựa vào quỹ đạo thì không thể biết liệu người dùng có nhận được câu trả lời hữu ích hay không. Lớp học lập trình này sẽ đánh giá cả hai.

Các tệp này được điều khiển bởi 2 tệp:

tests/eval/evalsets/basic.evalset.json – các cuộc trò chuyện cần phát lại, cộng với các lệnh gọi công cụ dự kiến
tests/eval/eval_config.json – những chỉ số cần tính điểm, ngưỡng của các chỉ số đó và bộ quy tắc chấm điểm cho LLM

Chỉnh sửa evalset để thêm các lệnh gọi công cụ dự kiến

Thay thế nội dung của tests/eval/evalsets/basic.evalset.json bằng nội dung sau:

{
  "eval_set_id": "basic_eval",
  "name": "Basic Agent Evaluation",
  "description": "Validates that the agent calls the right tools AND produces a quality response.",
  "eval_cases": [
    {
      "eval_id": "weather_san_francisco",
      "conversation": [
        {
          "user_content": {"parts": [{"text": "What's the weather like in San Francisco?"}], "role": "user"},
          "final_response": {"parts": [{"text": "The weather in San Francisco is 60 degrees and foggy."}], "role": "model"},
          "intermediate_data": {
            "tool_uses": [{"name": "get_weather", "args": {"query": "San Francisco"}}],
            "tool_responses": [],
            "intermediate_responses": []
          }
        }
      ],
      "session_input": {"app_name": "app", "user_id": "eval_user", "state": {}}
    },
    {
      "eval_id": "weather_tokyo",
      "conversation": [
        {
          "user_content": {"parts": [{"text": "What's the weather in Tokyo?"}], "role": "user"},
          "final_response": {"parts": [{"text": "The weather in Tokyo is 90 degrees and sunny."}], "role": "model"},
          "intermediate_data": {
            "tool_uses": [{"name": "get_weather", "args": {"query": "Tokyo"}}],
            "tool_responses": [],
            "intermediate_responses": []
          }
        }
      ],
      "session_input": {"app_name": "app", "user_id": "eval_user", "state": {}}
    },
    {
      "eval_id": "time_san_francisco",
      "conversation": [
        {
          "user_content": {"parts": [{"text": "What time is it in San Francisco?"}], "role": "user"},
          "intermediate_data": {
            "tool_uses": [{"name": "get_current_time", "args": {"query": "San Francisco"}}],
            "tool_responses": [],
            "intermediate_responses": []
          }
        }
      ],
      "session_input": {"app_name": "app", "user_id": "eval_user", "state": {}}
    }
  ]
}

Khối intermediate_data.tool_uses là quỹ đạo dự kiến – những công cụ mà tác nhân nên gọi, với những đối số nào. Chỉ số quỹ đạo so sánh điều này với những gì thực sự xảy ra trong thời gian chạy.

Chỉnh sửa bảng điểm để tính điểm cho cả hai chỉ số

Thay thế tests/eval/eval_config.json bằng:

{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "rubric_based_final_response_quality_v1": {
      "threshold": 0.8,
      "judgeModelOptions": {"judgeModel": "gemini-flash-latest", "numSamples": 1},
      "rubrics": [
        {"rubricId": "relevance",     "rubricContent": {"textProperty": "The response directly addresses the user's query."}},
        {"rubricId": "helpfulness",   "rubricContent": {"textProperty": "The response is helpful and provides useful information."}},
        {"rubricId": "tool_grounded", "rubricContent": {"textProperty": "The response is grounded in the values returned by the tools (e.g. the exact temperature and weather condition) and does not invent details."}}
      ]
    }
  }
}

Chức năng của từng dòng:

tool_trajectory_avg_score: 1.0 – thêm chỉ số quỹ đạo với ngưỡng nghiêm ngặt là 1.0 (mọi lệnh gọi công cụ dự kiến đều phải khớp chính xác). Điểm số được tính toán một cách xác định bằng cách so sánh các sự kiện function_call thực tế của tác nhân với intermediate_data.tool_uses.
rubric_based_final_response_quality_v1 – chạy LLM-as-judge (gemini-flash-latest ở đây) để chấm điểm câu trả lời cuối cùng theo từng tiêu chí trên thang điểm từ 0 đến 1, sau đó tính điểm trung bình. Trường hợp này được coi là đạt yêu cầu khi điểm trung bình đạt threshold (0,8). Tiêu chí chấm điểm tool_grounded yêu cầu rõ ràng giám khảo phạt những câu trả lời mâu thuẫn hoặc bịa đặt so với kết quả của công cụ – một biện pháp chống ảo tưởng được áp dụng thêm vào quy trình kiểm tra quỹ đạo.

🤖 Với một Trợ lý lập trình

Hỏi nhân viên hỗ trợ:

"Chạy quy trình đánh giá cho trợ lý của tôi"

👤 Chế độ thủ công

agents-cli eval run --all

--all chạy mỗi *.evalset.json trong tests/eval/evalsets/. Để nhắm đến một mục tiêu, hãy sử dụng --evalset tests/eval/evalsets/basic.evalset.json.

Kết quả đầu ra dự kiến (đã cắt bớt):

  ▸ uv run adk eval ./app tests/eval/evalsets/basic.evalset.json --config_file_path tests/eval/eval_config.json
INFO - google_llm.py - Sending out request, model: gemini-flash-latest, backend: GoogleLLMVariant.VERTEX_AI
INFO - local_eval_set_results_manager.py - Writing eval result to file: app/.adk/eval_history/app_basic_eval_<ts>.evalset_result.json
Using evaluation criteria: criteria={'tool_trajectory_avg_score': 1.0, 'rubric_based_final_response_quality_v1': BaseCriterion(threshold=0.8, ...)}
*********************************************************************
Eval Run Summary
basic_eval:
  Tests passed: 3
  Tests failed: 0

Kết quả cho từng trường hợp được ghi trong app/.adk/eval_history/ – mỗi tệp kết quả liệt kê điểm số cho từng chỉ số để bạn có thể biết chính xác bước kiểm tra nào đã đạt hoặc không đạt.

Cách đọc tệp kết quả

Một trường hợp đạt trong app/.adk/eval_history/app_basic_eval_.evalset_result.json sẽ có dạng như sau:

{
  "eval_id": "weather_san_francisco",
  "final_eval_status": 1,
  "overall_eval_metric_results": [
    {"metric_name": "tool_trajectory_avg_score",            "score": 1.0, "threshold": 1.0, "eval_status": 1},
    {"metric_name": "rubric_based_final_response_quality_v1","score": 1.0, "threshold": 0.8, "eval_status": 1}
  ]
}

Nếu tác nhân ảo tưởng và gọi sai công cụ (hoặc không gọi công cụ nào), thì tool_trajectory_avg_score sẽ giảm xuống 0.0 và trường hợp sẽ thất bại – ngay cả khi văn bản cuối cùng có vẻ hợp lý. Đó là đặc điểm mà chỉ có thang điểm không thể mang lại cho bạn.

Các chỉ số khác hiện có

ADK cung cấp một số trình đánh giá tích hợp mà bạn có thể thêm vào criteria:

Chỉ số	Nội dung mà tính năng này kiểm tra
`tool_trajectory_avg_score`	Các lệnh gọi công cụ khớp chính xác so với quỹ đạo dự kiến
`rubric_based_final_response_quality_v1`	LLM đánh giá theo tiêu chí chấm điểm của bạn (phản hồi cuối cùng)
`rubric_based_tool_use_quality_v1`	LLM đánh giá dựa trên tiêu chí chấm điểm (sử dụng công cụ)
`final_response_match_v2`	Giám khảo LLM: câu trả lời cuối cùng có tương đương về mặt ngữ nghĩa với câu trả lời dự kiến không?
`response_match_score`	ROUGE-1 giữa câu trả lời cuối cùng thực tế và dự kiến
`safety_v1`	Giám khảo LLM: mức độ an toàn của câu trả lời
`hallucinations_v1`	Giám khảo LLM: câu trả lời dựa trên bối cảnh được cung cấp

9. Thêm việc triển khai Thời gian chạy của tác nhân

Thời gian chạy của tác nhân là thời gian chạy không máy chủ, được quản lý của Google Cloud dành cho các tác nhân ADK. Nền tảng này tự động xử lý việc mở rộng quy mô, cơ sở hạ tầng và khả năng ghi nhận.

🤖 Với một Trợ lý lập trình

Hỏi nhân viên hỗ trợ:

"Thêm việc triển khai Thời gian chạy của tác nhân vào dự án của tôi"

👤 Chế độ thủ công

agents-cli scaffold enhance --deployment-target agent_runtime --yes

Kết quả đầu ra dự kiến:

Agents CLI v0.1.2
Resolved project root to: /home/user/customer-support-agent

Generating templates for comparison...
  - Original template...
  - Enhanced template...

Comparing files...

Will auto-update (unchanged by you):
  ✓ README.md
  ✓ app/app_utils/telemetry.py

Skipping (your code):
  - app/agent.py

Files to add:
  + app/agent_runtime_app.py
  + deployment_metadata.json
  + tests/integration/test_agent_runtime_app.py

Files to remove:
  - Dockerfile
  - app/fast_api_app.py
  - tests/integration/test_server_e2e.py

Dependency changes:
  + Add: google-cloud-aiplatform[evaluation,agent-engines]>=1.130.0
  + Add: protobuf>=6.31.1,<7.0.0

📦 Creating backup before modification...
Backup created: /home/user/.agents-cli/backups/customer-support-agent_20260430_001940

  Updated: 2 files
  Added: 3 files
  Removed: 3 files

✅ Enhance complete!

Điều gì đã thay đổi?

Đã thêm:

app/agent_runtime_app.py – Trình bao bọc Thời gian chạy của tác nhân
deployment_metadata.json – Theo dõi việc triển khai
Các kiểm thử dành riêng cho Thời gian chạy của tác nhân

Đã xoá:

Dockerfile – Không cần thiết (Thời gian chạy của tác nhân được quản lý)
fast_api_app.py – Thay thế bằng ứng dụng Agent Runtime

Được giữ lại:

app/agent.py – Mã đại lý của bạn (không thay đổi!)

10. Triển khai cho Thời gian chạy tác nhân

Triển khai tác nhân của bạn vào cơ sở hạ tầng do Google Cloud quản lý.

Cập nhật phần phụ thuộc

uv lock

🤖 Với một Trợ lý lập trình

Hỏi nhân viên hỗ trợ:

"Triển khai tác nhân của tôi đến Thời gian chạy tác nhân trong dự án YOUR_PROJECT_ID, khu vực us-central1"

👤 Chế độ thủ công

agents-cli deploy --project YOUR_PROJECT_ID --region us-central1

Kết quả đầu ra dự kiến:

Using project root directory: /home/user/customer-support-agent
  📦 Auto-generated requirements: app/app_utils/.requirements.txt

    ╔═══════════════════════════════════════════════════════════╗
    ║                                                           ║
    ║   🤖 DEPLOYING AGENT TO VERTEX AI AGENT ENGINE 🤖         ║
    ║                                                           ║
    ╚═══════════════════════════════════════════════════════════╝

📋 Deployment Parameters:
  Project: YOUR_PROJECT_ID
  Location: us-central1
  Display Name: customer-support-agent
  Min Instances: 1
  Max Instances: 10
  CPU: 4
  Memory: 8Gi
  Container Concurrency: 9

🌍 Environment Variables:
  AGENT_VERSION: 0.1.0
  GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY: true
  GOOGLE_CLOUD_REGION: us-central1
  NUM_WORKERS: 1
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: true

INFO:root:Introspecting app.agent_runtime_app.agent_runtime via subprocess

🚀 Creating agent: customer-support-agent (this can take 5-10 minutes)...
INFO:vertexai_genai.agentengines:Using agent framework: google-adk
   Operation: projects/.../locations/us-central1/reasoningEngines/.../operations/...

[... deployment in progress for ~5–10 minutes ...]

INFO:root:Agent Runtime ID written to deployment_metadata.json

✅ Deployment successful!
Agent Runtime ID: projects/.../locations/us-central1/reasoningEngines/XXXXXXXXXXXXXXXXXX
Service Account: service-XXXXXXXXX@gcp-sa-aiplatform-re.iam.gserviceaccount.com

📊 Open Console Playground: https://console.cloud.google.com/vertex-ai/agents/agent-engines/locations/us-central1/agent-engines/XXXXXXXXXXXXXXXXXX/playground?project=YOUR_PROJECT_ID

Điều gì vừa xảy ra?

Thời gian chạy của tác nhân:

Tự động đóng gói mã của bạn
Đã tải lên Google Cloud
Cơ sở hạ tầng được quản lý đã cung cấp (4 CPU, bộ nhớ 8Gi)
Đã định cấu hình tính năng tự động cấp tài nguyên bổ sung (1-10 phiên bản)
Đã bật tính năng đo từ xa và khả năng ghi nhận

Thời gian triển khai: Khoảng 5 – 10 phút (thiết lập một lần; các lần triển khai lại sau đó sẽ nhanh hơn)

11. Kiểm thử và giám sát tác nhân đã triển khai

Tác nhân của bạn hiện đang chạy trên Thời gian chạy tác nhân! Hãy thử nghiệm và khám phá tính năng giám sát tích hợp.

Thử nghiệm nhân viên hỗ trợ

Cách 1: Console Playground (Dễ nhất)

Đầu ra agents-cli deploy sẽ in một đường liên kết đến Console Playground có dạng:

https://console.cloud.google.com/vertex-ai/agents/agent-engines/locations/<REGION>/agent-engines/<RUNTIME_ID>/playground?project=<PROJECT_ID>

(Agent Runtime là tên sản phẩm; tài nguyên GCP cơ bản là Vertex AI Agent Engine, đó là lý do đường dẫn URL có chứa vertex-ai/agents/agent-engines.) Nhấp vào đường liên kết để:

Đăng nhập vào Google Cloud Console
Xem tác nhân đã triển khai bằng giao diện người dùng trò chuyện tương tác
Các cụm từ tìm kiếm thử nghiệm như "Thời tiết ở San Francisco thế nào?"
Xem các lệnh gọi và phản hồi của công cụ theo thời gian thực

Console Playground là cách dễ nhất để xác minh việc triển khai của bạn.

Lựa chọn 2: agents-cli run –url

Lệnh agents-cli run mà bạn đã dùng cục bộ cũng truy vấn các tác nhân đã triển khai:

RUNTIME_ID=$(jq -r .remote_agent_runtime_id deployment_metadata.json)
agents-cli run \
  --url "https://us-central1-aiplatform.googleapis.com/v1/${RUNTIME_ID}" \
  --mode adk \
  "What's the weather in San Francisco?"

--mode adk nói giao thức ADK SSE (tác nhân được triển khai sẽ hiển thị :streamQuery). agents-cli tự động đính kèm mã truy cập Google từ thông tin đăng nhập gcloud đang hoạt động của bạn.

Cách 3: Agent Engine SDK (Python)

Để truy cập theo chương trình từ Python, hãy sử dụng mô-đun Agent Engine của Vertex AI SDK (vertexai.agent_engines):

import vertexai
from vertexai import agent_engines

vertexai.init(project="YOUR_PROJECT_ID", location="us-central1")

# remote_agent_runtime_id from deployment_metadata.json (full resource name)
remote_agent = agent_engines.get(
    "projects/.../locations/us-central1/reasoningEngines/..."
)

session = remote_agent.create_session(user_id="user-1")
for event in remote_agent.stream_query(
    user_id="user-1",
    session_id=session["id"],
    message="What's the weather in San Francisco?",
):
    print(event)

Theo dõi nhân viên hỗ trợ

Agent Runtime có khả năng ghi nhận tích hợp sẵn thông qua các công cụ giám sát của Google Cloud:

Cloud Trace – Theo dõi yêu cầu

Chuyển đến: Cloud Console > Trace Explorer (Cloud Console > Trình khám phá dấu vết)
Chọn dự án
Lọc khoảng thời gian theo thuộc tính service.name = customer-support-agent
Truy sâu vào một dấu vết để xem suy luận mô hình, lệnh gọi công cụ và độ trễ từ đầu đến cuối

Cloud Logging – Nhật ký ứng dụng

Chuyển đến: Cloud Console > Trình khám phá nhật ký
Sử dụng truy vấn: resource.type="aiplatform.googleapis.com/ReasoningEngine"
Thêm resource.labels.reasoning_engine_id="" vào phạm vi cho nhân viên hỗ trợ này
Xem các yêu cầu, câu trả lời, quá trình thực thi công cụ và lỗi của tác nhân

Cloud Monitoring – Chỉ số và trang tổng quan

Chuyển đến Cloud Console > Trình khám phá chỉ số
Lọc theo loại tài nguyên aiplatform.googleapis.com/ReasoningEngine
Các chỉ số hữu ích: request_count, request_latencies, instance_count

12. Không bắt buộc: Xuất bản lên Gemini Enterprise

Cung cấp tác nhân của bạn trong Gemini Enterprise cho tổ chức của bạn.

🤖 Với một Trợ lý lập trình

Hỏi nhân viên hỗ trợ:

"Xuất bản tác nhân của tôi lên Gemini Enterprise"

👤 Chế độ thủ công

Liệt kê các ứng dụng Gemini Enterprise trong dự án của bạn để có một mã nhận dạng ứng dụng cần nhắm đến:

agents-cli publish gemini-enterprise --list

Sau đó, hãy đăng ký tác nhân đã triển khai. Lệnh này tự động đọc Mã thời gian chạy của tác nhân từ deployment_metadata.json:

agents-cli publish gemini-enterprise \
  --gemini-enterprise-app-id "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/YOUR_APP_ID" \
  --display-name "Customer Support Agent" \
  --description "Answers weather and time questions" \
  --tool-description "Use this tool to ask the customer support agent."

Điều này giúp nhân viên hỗ trợ của bạn có thể:

Trong trang web thương mại của tác nhân Gemini Enterprise
Cho người dùng trong tổ chức của bạn
Với hoạt động quản lý và quản trị tập trung

Để biết thông tin chi tiết, hãy xem Tài liệu về việc xuất bản.

13. Dọn dẹp

Để tránh bị tính phí, hãy dọn dẹp các tài nguyên mà bạn đã tạo.

Xoá tác nhân

Lấy tên tài nguyên Agent Runtime từ deployment_metadata.json:

jq -r .remote_agent_runtime_id deployment_metadata.json

Xoá thông qua Agent Engine SDK (Python)

import vertexai
from vertexai import agent_engines

vertexai.init(project="YOUR_PROJECT_ID", location="us-central1")

# Full resource name from deployment_metadata.json
remote_agent = agent_engines.get(
    "projects/.../locations/us-central1/reasoningEngines/..."
)

# force=True also deletes any child sessions
remote_agent.delete(force=True)
print("✅ Deleted successfully")

Hoặc thông qua API REST (curl):

RUNTIME_ID=$(jq -r .remote_agent_runtime_id deployment_metadata.json)
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://us-central1-aiplatform.googleapis.com/v1beta1/${RUNTIME_ID}?force=true"

14. Xin chúc mừng!

🎉 Bạn đã làm được! Bạn đã tạo, kiểm thử và triển khai thành công một tác nhân AI từ đầu.

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

Hai cách sử dụng Agents CLI (với tác nhân lập trình hoặc theo cách thủ công)
Tạo dự án tác nhân bằng agents-cli scaffold
Xây dựng tác nhân bằng các công cụ tuỳ chỉnh
Kiểm thử cục bộ bằng sân chơi
Chạy quy trình đánh giá tự động
Triển khai vào Thời gian chạy của tác nhân (cơ sở hạ tầng được quản lý)
Giám sát bằng Cloud Trace và Logging
Các phương pháp hay nhất về sản xuất

Sản phẩm bạn đã tạo

Một tác nhân AI sẵn sàng hoạt động với:

Hiểu ngôn ngữ tự nhiên (Gemini)
Tích hợp công cụ tuỳ chỉnh
Đánh giá chất lượng
Triển khai tính năng tự động cấp tài nguyên bổ sung
Khả năng ghi nhận được tích hợp sẵn

Các bước tiếp theo

Mở rộng phạm vi hoạt động của tác nhân:

Thêm các công cụ khác (truy vấn cơ sở dữ liệu, lệnh gọi API)
Triển khai RAG bằng tính năng tìm kiếm vectơ
Thêm cuộc trò chuyện nhiều lượt
Bật giao tiếp A2A (tác nhân với tác nhân)

Tìm hiểu thêm:

Tham gia cộng đồng:

GitHub Issues
Stack Overflow
Email: agents-cli@google.com
Chia sẻ những gì bạn đã tạo!