Gói Tân thủ dành cho tác nhân có ADK cho Go

1. Giới thiệu

Mặc dù Python vẫn là ngôn ngữ phổ biến để huấn luyện mô hình và nghiên cứu, nhưng các yêu cầu về việc phân phát và điều phối các tác nhân AI phù hợp chặt chẽ với những điểm mạnh của Go: độ trễ thấp, tính đồng thời cao và tính an toàn về kiểu.

Việc chuyển đổi từ một nguyên mẫu sang một tác nhân sản xuất sẽ gây ra những thách thức về kỹ thuật mà Go có thể xử lý một cách đặc biệt hiệu quả. Tính năng nhập tĩnh của Go giúp loại bỏ lỗi thời gian chạy khi phân tích cú pháp đầu ra có cấu trúc của LLM. Các goroutine có dung lượng nhẹ, chỉ bắt đầu với vài kilobyte bộ nhớ ngăn xếp so với vài megabyte cho các luồng hệ điều hành, cho phép các tác nhân xử lý hàng nghìn lượt thực thi công cụ đồng thời mà không cần quản lý luồng quá mức.

Bộ công cụ phát triển tác nhân (ADK) của Google giúp thu hẹp khoảng cách giữa những lợi thế về cấu trúc này và AI tạo sinh. Trong hướng dẫn này, bạn sẽ tạo khung cho một dự án mới và triển khai dự án đó dưới dạng một vi dịch vụ bảo mật trên Google Cloud.

Những gì bạn sẽ làm:

• Tạo giàn giáo cho một dự án tác nhân sẵn sàng sản xuất bằng Gói khởi động tác nhân
• Sử dụng giao diện người dùng web của Agent Development Kit (Bộ công cụ phát triển tác nhân) cục bộ để gỡ lỗi và kiểm thử tác nhân
• Phát triển và tìm hiểu logic của tác nhân ADK dựa trên Go
• Chạy kiểm thử đơn vị và kiểm thử toàn diện (E2E)
• Triển khai tác nhân một cách an toàn lên Cloud Run

Những gì bạn cần:

• Một trình duyệt web như Chrome
• Một dự án trên Google Cloud đã bật tính năng thanh toán

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

Tạo một dự án trên Google Cloud

Nếu bạn chưa có tài khoản:

1. Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
2. Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên đám mây của bạn.

Khởi động Cloud Shell

Cloud Shell là một môi trường dòng lệnh chạy trong Google Cloud và được tải sẵn các công cụ cần thiết. Đây sẽ là môi trường phát triển chính của bạn cho phòng thí nghiệm này.

1. Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Cloud của Google.
2. Sau khi kết nối với Cloud Shell, hãy chạy lệnh này để xác minh quá trình xác thực của bạn trong Cloud Shell:

gcloud auth list

3. Chạy lệnh sau để xác nhận rằng dự án của bạn đã được định cấu hình để sử dụng với gcloud:

gcloud config get project

4. Xác nhận dự án đúng như mong đợi, sau đó chạy lệnh bên dưới để đặt mã dự án:

export PROJECT_ID=$(gcloud config get project)

3. Bắt đầu với Gói tân thủ dành cho tác nhân

Tin vui là bạn không cần phải bắt đầu từ con số không. Agent Starter Pack là một công cụ CLI giúp tạo cấu trúc thư mục sẵn sàng cho hoạt động sản xuất, bao gồm cả quy trình CI/CD, cấu hình cơ sở hạ tầng và mã nguyên mẫu.

Để bắt đầu, bạn chỉ cần chạy lệnh tạo bản dựng bằng uvx:

uvx agent-starter-pack create

CLI sẽ hướng dẫn bạn thực hiện một quy trình thiết lập tương tác. Đối với dự án này, hãy chọn các lựa chọn sau:

• Tên dự án: my-first-go-agent
• Mẫu: Lựa chọn 6 (Go ADK, Go agent có A2A)
• CI/CD: Lựa chọn 3 (GitHub Actions)
• Khu vực: us-central1

Công cụ này tự động xác thực bằng Google Cloud, bật các API Vertex AI cần thiết và định cấu hình môi trường cục bộ của bạn.

Sau khi thấy thông báo Thành công! màu xanh lục, bạn đã sẵn sàng tiếp tục.

4. Trực quan hoá Tác nhân tại địa phương

Một trong những tính năng thuận tiện nhất của ADK là khả năng gỡ lỗi trực quan cho nhân viên hỗ trợ trước khi triển khai. Bằng cách chạy các lệnh bên dưới, bạn sẽ khởi chạy một máy chủ phát triển cục bộ có giao diện người dùng tích hợp. Có, nó có một cửa sổ trò chuyện, nhưng nó còn làm được nhiều việc hơn thế bằng cách theo dõi các sự kiện, lệnh gọi công cụ, v.v.

Chuyển sang thư mục dự án của bạn và bắt đầu sân chơi:

cd my-first-go-agent
make install
make playground

Sau khi sân chơi chạy, hãy mở bản xem trước trên web trong Cloud Shell để tương tác với tác nhân bạn vừa tạo.

Tác nhân được định cấu hình theo mẫu ReAct (Lý luận và hành động) – một khung hình đã trở thành nền tảng trong AI tác nhân. Vòng lặp liên tục của "Suy nghĩ", "Hành động" và "Quan sát" trong mẫu ReAct giúp nâng cao khả năng giải quyết vấn đề và mức độ diễn giải, đồng thời giúp quá trình đưa ra quyết định của tác nhân trở nên minh bạch.

Ví dụ: nếu bạn hỏi về thời tiết, thì tác nhân sẽ nhận ra ý định, gọi công cụ get_weather và trả về dữ liệu có cấu trúc.

5. Tìm hiểu về mã

Giờ đây, khi đã thấy tác nhân hoạt động, hãy xem mã Go giúp tác nhân này hoạt động. Logic này nằm trong agent/agent.go. Tệp này xử lý các định nghĩa về công cụ, cấu hình mô hình và quá trình khởi tạo.

ADK sử dụng các cấu trúc Go tiêu chuẩn để xác định cách Mô hình ngôn ngữ lớn (LLM) tương tác với mã của bạn. Để xác định các tham số đầu vào cho công cụ thời tiết, chúng ta xác định một cấu trúc bằng các thẻ json và jsonschema:

type GetWeatherArgs struct {
    City string `json:"city" jsonschema:"City name to get weather for"`
}

GetWeatherResult xác định cấu trúc của dữ liệu được trả về cho tác nhân sau khi công cụ thực thi:

// GetWeatherResult defines the output for the get_weather tool.
type GetWeatherResult struct {
	Weather string `json:"weather"`
}

GetWeather là một hàm Go tiêu chuẩn chấp nhận tool.Context và cấu trúc đối số, thực hiện logic nghiệp vụ và trả về cấu trúc kết quả:

// GetWeather returns mock weather data for a city.
func GetWeather(_ tool.Context, args GetWeatherArgs) (GetWeatherResult, error) {
	return GetWeatherResult{
		Weather: "It's sunny and 72°F in " + args.City,
	}, nil
}

Hàm NewRootAgent chịu trách nhiệm lắp ráp và trả về phiên bản agent.Agent mà trình chạy ứng dụng yêu cầu. Quá trình này bắt đầu bằng việc khởi chạy cấu hình mô hình, tạo một thực thể mô hình gemini-2.5-flash được hỗ trợ bởi genai.BackendVertexAI.

Tiếp theo, nó thu hẹp khoảng cách giữa mã Go và LLM bằng cách bao bọc hàm GetWeather cục bộ vào một functiontool. Bước này đăng ký công cụ bằng tên get_weather và cung cấp nội dung mô tả cần thiết cho ngữ cảnh của mô hình. Cuối cùng, nó tạo tác nhân bằng cách sử dụng llmagent.New, kết hợp mô hình Gemini đã khởi tạo, các chỉ dẫn của hệ thống xác định hành vi của tác nhân và phần công cụ có sẵn thành một đơn vị duy nhất.

// NewRootAgent creates and returns the root agent with all configured tools.
func NewRootAgent(ctx context.Context) (agent.Agent, error) {
	model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
		Backend: genai.BackendVertexAI,
	})

	weatherTool, err := functiontool.New(functiontool.Config{
		Name:        "get_weather",
		Description: "Get the current weather for a city.",
	}, GetWeather)

	rootAgent, err := llmagent.New(llmagent.Config{
		Name:        "my-first-go-agent",
		Model:       model,
		Description: "A helpful AI assistant.",
		Instruction: "You are a helpful AI assistant designed to provide accurate and useful information.",
		Tools:       []tool.Tool{weatherTool},
	})
	// ... (additional logic omitted for brevity)
	return rootAgent, nil
}

6. Thử nghiệm

Dự án này chứa cả kiểm thử đơn vị cho logic nội bộ và kiểm thử toàn diện cho việc tích hợp máy chủ.

Trong agent/agent_test.go, hàm GetWeather được gọi bằng một bộ trường hợp kiểm thử để xác minh rằng chuỗi đầu ra khớp với các giá trị dự kiến.

func TestGetWeather(t *testing.T) {
	// tests struct initialized with "San Francisco" and "New York"

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// Pass nil for tool.Context since GetWeather doesn't use it
			result, err := GetWeather(nil, GetWeatherArgs{City: tt.city})
			if err != nil {
				t.Fatalf("GetWeather() error = %v", err)
			}
			if !strings.Contains(result.Weather, tt.wantCity) {
				t.Errorf("GetWeather() = %v, want city %v in response", result.Weather, tt.wantCity)
			}
		})
	}
}

Các kiểm thử toàn diện xác minh rằng tác nhân hoạt động chính xác khi chạy dưới dạng một máy chủ, cụ thể là kiểm tra để đảm bảo rằng chế độ hỗ trợ giao thức A2A hoặc giao thức từ Tác nhân đến Tác nhân đang hoạt động chính xác. Các kiểm thử E2E sẽ khởi động một phiên bản thực của máy chủ, gửi yêu cầu HTTP đến phiên bản đó và kiểm tra các phản hồi.

Sau đây là một đoạn trích từ e2e/integration/server_e2e_test.go:

func TestA2AMessageSend(t *testing.T) {
    if testing.Short() { t.Skip("Skipping E2E test in short mode") }

    // Start server (local variable to avoid race conditions)
    t.Log("Starting server process")
    serverProcess := startServer(t)
    defer stopServer(t, serverProcess)

    if !waitForServer(t, 90*time.Second) {
	    t.Fatal("Server failed to start")
    }
    t.Log("Server process started")
    // ...
}

Bạn có thể chạy tất cả các kiểm thử cục bộ bằng cách sử dụng makefile:

make test

7. Triển khai

Khi bạn đã sẵn sàng chia sẻ tác nhân của mình với thế giới hoặc kết nối tác nhân đó với hệ sinh thái sản xuất, hãy chạy lệnh triển khai đi kèm:

make deploy

Lệnh này tự động tạo ứng dụng của bạn từ nguồn bằng cách sử dụng Google Cloud Buildpacks, được kích hoạt bằng cờ --source .. Thao tác này triển khai hình ảnh này đến Cloud Run với một số cờ được tối ưu hoá cho hoạt động sản xuất: --memory "4Gi" để cung cấp đủ RAM cho các hoạt động của LLM và --no-cpu-throttling để đảm bảo CPU luôn được phân bổ 24/7, có thể ngăn chặn các lần khởi động nguội và đảm bảo phản hồi nhanh trong các hoạt động tương tác của tác nhân.

Để đảm bảo tác nhân của bạn chạy một cách an toàn, hệ thống được triển khai với cấu hình nghiêm ngặt bằng cách sử dụng --no-allow-unauthenticated để chặn tất cả quyền truy cập công khai theo mặc định, yêu cầu xác thực Quản lý danh tính và quyền truy cập (IAM) cho mọi yêu cầu. Thao tác này cũng chèn các biến môi trường, bao gồm cả GOOGLE_GENAI_USE_VERTEXAI=True.

Vì ứng dụng của bạn được bảo mật, nên bạn cần bật Identity-Aware Proxy (IAP) để truy cập vào ứng dụng một cách an toàn thông qua trình duyệt. Tài liệu về Cloud cung cấp hướng dẫn từng bước trong phần Bật IAP cho Cloud Run.

Sau khi bật IAP và thêm email của bạn làm người dùng chính, bạn có thể chuyển đến URL dịch vụ được cung cấp sau khi triển khai. Khi xem URL cơ sở của Dịch vụ, bạn có thể thấy Thẻ tác nhân đã triển khai. Cấu trúc JSON này đóng vai trò là giao diện tiêu chuẩn của tác nhân, cho phép các tác nhân, trình điều phối hoặc giao diện người dùng khác khám phá và sử dụng một cách linh hoạt.

8. Dọn dẹp

Để tránh phát sinh các khoản phí liên tục cho tài khoản Google Cloud của bạn, hãy xoá các tài nguyên đã tạo trong Codelab này.

Bạn có thể xoá dự án trên Cloud. Thao tác này sẽ dừng tính phí cho tất cả tài nguyên được dùng trong dự án đó:

gcloud projects delete $PROJECT_ID

Bạn cũng có thể muốn xoá thư mục dự án lớp học lập trình khỏi ổ đĩa Cloud Shell:

rm -rf ~/my-first-go-agent

9. Xin chúc mừng!

🎊 Hoàn thành nhiệm vụ! Bạn đã dàn dựng, kiểm thử và triển khai thành công một AI Agent bằng Go thông qua Agent Development Kit.

Những gì bạn đã đạt được:

• Tạo một đường cơ sở có cấu trúc ban đầu bằng Gói khởi động tác nhân
• Xác minh và kiểm thử giao diện người dùng cũng như mã của nhân viên hỗ trợ trên thiết bị
• Đã tìm hiểu kỹ về các giản đồ được nhập và các hàm ánh xạ hành vi của LLM sang các đối tượng Go
• Triển khai dịch vụ Go lên Cloud Run

Tiếp theo là gì?

• Tài liệu về ADK: Hướng dẫn đầy đủ về các mẫu nâng cao, cơ chế điều phối nhiều tác nhân và hệ thống bộ nhớ
• Bộ tài liệu hướng dẫn bắt đầu dành cho tác nhân: Khám phá các mẫu, bao gồm cả hệ thống nhiều tác nhân và cấu trúc phức tạp
• Tài liệu về Cloud Run: Phân tích chuyên sâu về việc tối ưu hoá hiệu suất, các chiến lược mở rộng quy mô và các phương pháp hay nhất về bảo mật
• Go Concurrency Patterns: Việc hiểu rõ goroutine và kênh sẽ giúp bạn xây dựng công cụ tác nhân hiệu quả hơn
• Vertex AI Agent Engine: Đối với cơ sở hạ tầng tác nhân được quản lý có sẵn tính năng điều phối và công cụ