Bắt đầu nhanh

Tệp nguồn liên quan

Trang này được tạo dựa trên các tệp nguồn sau:

• README.md
• examples/quickstart/main.go
• go.mod
• cmd/adkgo/adkgo.go
• examples/a2a/main.go
• examples/mcp/main.go
• examples/web/main.go
• examples/rest/main.go
• examples/telemetry/main.go
• examples/vertexai/agent.go

Giới thiệu về ADK Go

Agent Development Kit (ADK) cho Go là một framework linh hoạt và mô-đun, áp dụng các nguyên tắc phát triển phần mềm vào việc tạo tạo AI agent. Framework được thiết kế để đơn giản hóa việc xây dựng, triển khai và điều phối các workflow của agent, từ các tác vụ đơn giản đến các hệ thống phức tạp (README.md:1-53).

Phiên bản Go của ADK lý tưởng cho các nhà phát triển xây dựng ứng dụng agent cloud-native, tận dụng thế mạnh của Go về đồng thời (concurrency) và hiệu suất. ADK được tối ưu hóa cho Gemini nhưng vẫn model-agnostic, deployment-agnostic và tương thích với các framework khác.

Các tính năng chính

ADK Go cung cấp các tính năng nổi bật sau:

Cài đặt môi trường

Yêu cầu hệ thống

ADK Go yêu cầu Go phiên bản 1.25.0 trở lên (go.mod:1-97). Dự án sử dụng nhiều dependency quan trọng từ Google Cloud và các thư viện open-source:

• google.golang.org/genai - Google GenAI SDK cho tích hợp model
• cloud.google.com/go/aiplatform - Vertex AI integration
• github.com/modelcontextprotocol/go-sdk - MCP protocol support
• github.com/a2aproject/a2a-go - A2A protocol cho giao tiếp giữa các agent

Bước cài đặt

Để thêm ADK Go vào dự án, thực hiện lệnh sau:

bash
1go get google.golang.org/adk

(README.md:40-46)

Lệnh này sẽ tải về package ADK Go và các dependency cần thiết. Sau khi cài đặt hoàn tất, có thể import các package trong code Go:

go
1import (
2    "google.golang.org/adk/agent"
3    "google.golang.org/adk/agent/llmagent"
4    "google.golang.org/adk/model/gemini"
5    "google.golang.org/adk/tool"
6)

Ví dụ Quickstart Tạo Agent đầu tiên

Tổng quan ví dụ

Ví dụ quickstart minh họa cách tạo một agent đơn giản trả lời câu hỏi về thời gian và thời tiết tại một thành phố cụ thể. Agent sử dụng model Gemini 2.5 Flash và tích hợp Google Search tool (examples/quickstart/main.go:1-65).

Cấu trúc code cơ bản

go
1package main
2
3import (
4    "context"
5    "log"
6    "os"
7
8    "google.golang.org/genai"
9
10    "google.golang.org/adk/agent"
11    "google.golang.org/adk/agent/llmagent"
12    "google.golang.org/adk/cmd/launcher"
13    "google.golang.org/adk/cmd/launcher/full"
14    "google.golang.org/adk/model/gemini"
15    "google.golang.org/adk/tool"
16    "google.golang.org/adk/tool/geminitool"
17)
18
19func main() {
20    ctx := context.Background()
21
22    // Tạo model Gemini với API key
23    model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
24        APIKey: os.Getenv("GOOGLE_API_KEY"),
25    })
26    if err != nil {
27        log.Fatalf("Failed to create model: %v", err)
28    }
29
30    // Cấu hình LLM Agent
31    a, err := llmagent.New(llmagent.Config{
32        Name:        "weather_time_agent",
33        Model:       model,
34        Description: "Agent to answer questions about the time and weather in a city.",
35        Instruction: "Your SOLE purpose is to answer questions about the current time and weather in a specific city. You MUST refuse to answer any questions unrelated to time or weather.",
36        Tools: []tool.Tool{
37            geminitool.GoogleSearch{},
38        },
39    })
40    if err != nil {
41        log.Fatalf("Failed to create agent: %v", err)
42    }
43
44    // Cấu hình launcher
45    config := &launcher.Config{
46        AgentLoader: agent.NewSingleLoader(a),
47    }
48
49    l := full.NewLauncher()
50    if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
51        log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
52    }
53}

(examples/quickstart/main.go:34-65)

Các thành phần chính

1. Khởi tạo Model: Sử dụng gemini.NewModel để tạo instance model với tên model và cấu hình client. API key được lấy từ biến môi trường GOOGLE_API_KEY (examples/quickstart/main.go:37-42).

2. Cấu hình Agent: llmagent.New tạo agent với các tham số:

• Name: Tên định danh của agent
• Model: Model LLM sử dụng
• Description: Mô tả chức năng agent
• Instruction: Hướng dẫn hành vi cho agent
• Tools: Danh sách công cụ agent có thể sử dụng

(examples/quickstart/main.go:44-55)

3. Launcher: full.NewLauncher() tạo launcher để chạy agent với nhiều tùy chọn khác nhau (examples/quickstart/main.go:61-64).

Chạy ví dụ

bash
1# Thiết lập API key
2export GOOGLE_API_KEY="your-api-key-here"
3
4# Chạy agent
5go run examples/quickstart/main.go

Các ví dụ nâng cao

Tích hợp A2A Protocol

A2A (Agent-To-Agent) protocol cho phép các agent giao tiếp với nhau thông qua HTTP. Ví dụ examples/a2a/main.go minh họa cách:

1. Tạo một weather agent server sử dụng A2A protocol
2. Kết nối đến agent đó từ một client khác
3. Sử dụng remoteagent.NewA2A để tạo proxy đến remote agent

(examples/a2a/main.go:1-131)

Kiến trúc A2A:

正在加载图表渲染器...

Server A2A được khởi tạo với các thành phần:

• AgentCard: Metadata mô tả khả năng của agent
• adka2a.NewExecutor: Xử lý request từ client
• a2asrv.NewJSONRPCHandler: Handler cho JSON-RPC protocol

(examples/a2a/main.go:80-100)

Sử dụng MCP Tools

MCP (Model Context Protocol) cung cấp cách chuẩn để tích hợp các công cụ bên ngoài. Ví dụ examples/mcp/main.go trình bày hai phương pháp:

1. In-memory MCP Server: Định nghĩa function Go và đăng ký như MCP tool:

go
1func GetWeather(ctx context.Context, req *mcp.CallToolRequest, input Input) (*mcp.CallToolResult, Output, error) {
2    return nil, Output{
3        WeatherSummary: fmt.Sprintf("Today in %q is sunny\n", input.City),
4    }, nil
5}
6
7server := mcp.NewServer(&mcp.Implementation{Name: "weather_server", Version: "v1.0.0"}, nil)
8mcp.AddTool(server, &mcp.Tool{Name: "get_weather", Description: "returns weather in the given city"}, GetWeather)

(examples/mcp/main.go:58-69)

2. Remote MCP Server: Kết nối đến GitHub MCP server với OAuth authentication:

go
1ts := oauth2.StaticTokenSource(
2    &oauth2.Token{AccessToken: os.Getenv("GITHUB_PAT")},
3)
4return &mcp.StreamableClientTransport{
5    Endpoint:   "https://api.githubcopilot.com/mcp/",
6    HTTPClient: oauth2.NewClient(ctx, ts),
7}

(examples/mcp/main.go:78-86)

CLI Tool adkgo

adkgo là CLI tool hỗ trợ deploy và test ứng dụng ADK. Tool này import các module deploy như Cloud Run và cung cấp interface dòng lệnh để quản lý agent lifecycle (cmd/adkgo/adkgo.go:1-25).

go
1import (
2    _ "google.golang.org/adk/cmd/adkgo/internal/deploy/cloudrun"
3    "google.golang.org/adk/cmd/adkgo/internal/root"
4)
5
6func main() {
7    root.Execute()
8}

Xác thực và chạy thử

Thiết lập credentials

ADK Go yêu cầu Google API key để sử dụng Gemini models. Thiết lập biến môi trường:

bash
1export GOOGLE_API_KEY="your-google-api-key"

API key có thể lấy từ Google AI Studio hoặc Google Cloud Console.

Chạy quickstart example

bash
1# Clone repository
2git clone https://github.com/google/adk-go.git
3cd adk-go
4
5# Chạy ví dụ quickstart
6go run examples/quickstart/main.go

Xác minh hoạt động

Khi agent chạy thành công, có thể tương tác thông qua các interface được launcher cung cấp. Launcher hỗ trợ nhiều mode chạy khác nhau tùy thuộc vào arguments truyền vào (examples/quickstart/main.go:62).

Khắc phục sự thường gặp

Lỗi "Failed to create model"

Nguyên nhân: API key không hợp lệ hoặc chưa được thiết lập.

Giải pháp:

1. Kiểm tra biến môi trường GOOGLE_API_KEY đã được set
2. Xác minh API key còn hiệu lực trong Google AI Studio
3. Đảm bảo API key có quyền truy cập Gemini API

Lỗi "Failed to create agent"

Nguyên nhân: Cấu hình agent không hợp lệ hoặc model không khả dụng.

Giải pháp:

1. Kiểm tra tên model đúng: gemini-2.5-flash
2. Xác minh các tools được import đúng cách
3. Kiểm tra network connectivity đến Google APIs

Lỗi dependency khi build

Nguyên nhân: Go version không tương thích hoặc thiếu dependency.

Giải pháp:

1. Nâng cấp Go lên version 1.25.0 trở lên (go.mod:3)
2. Chạy go mod tidy để đồng bộ dependency
3. Xóa cache Go modules: go clean -modcache

Lỗi A2A connection refused

Nguyên nhân: A2A server chưa khởi động hoặc port không khả dụng.

Giải pháp:

1. Kiểm tra A2A server đã start trước client
2. Xác minh port không bị firewall block
3. Kiểm tra URL trong AgentCard đúng với server address

Các bước tiếp theo

Sau khi hoàn thành quickstart, có thể khám phá thêm:

1. Đọc documentation đầy đủ: Truy cập ADK Docs để hiểu sâu hơn về các concept
2. Khám phá examples: Xem thêm các ví dụ trong thư mục examples/ bao gồm web, REST API, telemetry
3. Tìm hiểu về multi-agent systems: Nghiên cứu cách kết hợp nhiều agent để xây dựng hệ thống phức tạp
4. Deploy lên Cloud Run: Sử dụng adkgo CLI để deploy agent lên Google Cloud Run
5. Tích hợp observability: Thêm telemetry và monitoring cho agent sử dụng OpenTelemetry

Các chủ đề nâng cao sẽ được trình bày chi tiết trong các section tiếp theo của documentation.