Sebastian Petrus

Posted on Jun 25 • Originally published at apidog.com

Google ADK (Agent Development Kit) là gì? Hướng dẫn thực tế

Google ADK là framework mã nguồn mở để xây dựng, đánh giá và triển khai các tác nhân AI. Nó cũng là nền tảng được Google dùng cho các tác nhân trong các sản phẩm như Agentspace. Nếu bạn đã từng dùng các stack tác nhân như OpenAI Agents SDK, ADK cung cấp các khái niệm tương tự: agent, tool, handoff, multi-agent workflow, evaluation và deployment. Bài viết này tập trung vào cách dùng ADK trong thực tế, cách các thành phần kết nối với nhau, và cách Apidog giúp bạn kiểm thử các API mà tác nhân gọi đến.

Thử Apidog ngay hôm nay

Google ADK là gì

ADK là viết tắt của Agent Development Kit. Google giới thiệu ADK tại Google Cloud Next vào tháng 4 năm 2025 như một bộ công cụ mã nguồn mở cho toàn bộ vòng đời của tác nhân:

Định nghĩa tác nhân.
Gắn công cụ cho tác nhân.
Kết hợp nhiều tác nhân.
Đánh giá hành vi.
Triển khai vào môi trường production.

ADK bắt đầu chủ yếu với Python. Sau đó Google thêm Java, tiếp theo là hỗ trợ Go và TypeScript. Framework này cũng là framework Google dùng nội bộ cho các tác nhân trong Agentspace và Customer Engagement Suite, nên nó được thiết kế cho các workload production thay vì chỉ là SDK thử nghiệm.

ADK không khóa bạn vào một mô hình duy nhất. Nó được tối ưu hóa cho Gemini và các mô hình trong Vertex AI Model Garden, đồng thời tích hợp với LiteLLM để kết nối với Anthropic, Meta, Mistral và các nhà cung cấp khác.

ADK nằm ở đâu trong hệ sinh thái Gemini và Vertex AI

Khi triển khai agent với Google stack, bạn nên tách thành ba lớp:

Mô hình. Gemini, hoặc mô hình khác thông qua Vertex AI Model Garden hoặc LiteLLM, xử lý suy luận.
Framework. ADK là lớp code để định nghĩa agent, tool và workflow đa tác nhân.
Môi trường chạy. Vertex AI Agent Engine là runtime được quản lý để chạy agent trong production. Bạn cũng có thể triển khai lên Cloud Run hoặc bất kỳ nền tảng container nào.

Một cách triển khai phổ biến:

Viết agent bằng ADK trên máy local.
Kiểm thử agent bằng adk run hoặc adk web.
Đóng gói agent thành service.
Triển khai lên Vertex AI Agent Engine, Cloud Run hoặc runtime container khác.
Theo dõi, đánh giá và cập nhật prompt/tool khi cần.

Các khái niệm cốt lõi trong ADK

ADK xoay quanh một vài thành phần chính: agent, tool, multi-agent workflow, runner, evaluation và deployment.

Agents

Đơn vị cơ bản trong ADK là một tác nhân được hỗ trợ bởi LLM. Trong Python, bạn import từ google.adk.agents.

Lớp chính là LlmAgent. Agent là alias tiện dụng cho lớp này.

Ví dụ agent đơn giản để tra tỷ giá:

from google.adk.agents import Agent

def get_exchange_rate(base: str, target: str) -> dict:
    """Trả về tỷ giá hối đoái giữa hai loại tiền tệ."""
    # Gọi API FX thực tế của bạn ở đây
    return {
        "base": base,
        "target": target,
        "rate": 1.08
    }

currency_agent = Agent(
    name="currency_exchange_agent",
    model="gemini-2.0-flash",
    instruction=(
        "Bạn giúp người dùng chuyển đổi giữa các loại tiền tệ. "
        "Chỉ trả lời dựa trên dữ liệu từ công cụ được cung cấp."
    ),
    tools=[get_exchange_rate],
)

Trong ví dụ này:

name giúp định danh agent.
model chọn mô hình suy luận.
instruction định hình hành vi.
tools là danh sách hàm agent có thể gọi.

Khi user hỏi tỷ giá, agent có thể quyết định gọi get_exchange_rate() thay vì tự bịa dữ liệu.

Tools

Tool là cách agent làm việc ngoài việc sinh văn bản. Trong ADK, một hàm Python thuần túy có thể trở thành tool.

Ví dụ:

def search_order(order_id: str) -> dict:
    """Tra cứu thông tin đơn hàng theo mã đơn hàng."""
    # Gọi API nội bộ /orders/{order_id}
    return {
        "order_id": order_id,
        "status": "shipped",
        "estimated_delivery": "2026-06-28"
    }

Khi viết tool, hãy chú ý ba phần:

Tên hàm rõ ràng: search_order, create_ticket, get_exchange_rate.
Type hints đầy đủ: giúp mô hình hiểu input/output.
Docstring cụ thể: mô tả khi nào nên gọi tool và tool trả về gì.

Ví dụ docstring tốt hơn:

def create_support_ticket(user_id: str, issue: str, priority: str) -> dict:
    """
    Tạo ticket hỗ trợ khách hàng.

    Dùng công cụ này khi người dùng muốn báo lỗi, yêu cầu hỗ trợ,
    hoặc cần nhân viên xử lý thủ công.

    priority phải là một trong: low, medium, high.
    """
    return {
        "ticket_id": "TICKET-123",
        "user_id": user_id,
        "priority": priority,
        "status": "created"
    }

Ngoài tool tự viết, ADK hỗ trợ các công cụ tích hợp như google_search, thực thi mã, và Model Context Protocol (MCP) để kết nối với tool server bên ngoài.

Bạn cũng có thể:

Bọc REST API nội bộ thành tool.
Dùng thư viện bên thứ ba như LangChain hoặc LlamaIndex.
Dùng một agent khác như một tool.

Trong thực tế, phần lớn tool sẽ gọi API. Vì vậy bạn cần kiểm thử kỹ contract của các API này trước khi để agent phụ thuộc vào chúng.

Hệ thống đa tác nhân

Một agent đơn lẻ phù hợp với tác vụ nhỏ. Với workflow phức tạp, ADK cho phép bạn kết hợp nhiều agent chuyên biệt.

Ví dụ:

flight_agent: tìm chuyến bay.
hotel_agent: tìm khách sạn.
trip_planner: điều phối toàn bộ kế hoạch chuyến đi.

ADK cũng cung cấp các workflow agent có tính xác định:

SequentialAgent: chạy các agent con theo thứ tự.
ParallelAgent: chạy nhiều agent cùng lúc.
LoopAgent: lặp đến khi điều kiện được đáp ứng.

Mẫu thiết kế thường dùng:

Agent điều phối nhận yêu cầu từ user.
Agent điều phối xác định nhiệm vụ con.
Tác vụ được chuyển cho các agent chuyên biệt.
Kết quả được tổng hợp và trả về user.

Runners

Trong production, bạn không nên gọi agent trực tiếp như một hàm thông thường. ADK dùng Runner để thực thi agent.

Runner chịu trách nhiệm:

Quản lý session.
Điều khiển event flow.
Cập nhật state.
Gọi mô hình.
Điều phối tool call.
Trả kết quả cuối cùng.

Trong giai đoạn development, bạn có thể dùng CLI:

adk run

Lệnh này khởi chạy phiên terminal tương tác.

Hoặc dùng giao diện web local:

adk web

adk web hữu ích khi bạn muốn xem agent xử lý từng bước, gọi tool nào, và phản hồi ra sao.

Đánh giá và triển khai

ADK có công cụ evaluation để bạn chấm điểm agent dựa trên trajectory và phản hồi mong đợi, thay vì chỉ kiểm tra thủ công kết quả cuối.

Điều này quan trọng vì hành vi agent có thể thay đổi khi bạn thay đổi:

Prompt.
Tool.
Model.
Sub-agent.
Cấu hình runtime.

Về deployment, bạn có hai hướng chính:

Managed runtime: dùng Vertex AI Agent Engine để chạy agent trong môi trường được quản lý.
Portable runtime: đóng gói agent vào container và triển khai lên Cloud Run hoặc nền tảng container khác.

Ví dụ: xây dựng hệ thống đa tác nhân nhỏ

Ví dụ dưới đây mô phỏng một trip planner. Agent chính ủy quyền việc tìm chuyến bay và khách sạn cho hai agent con.

from google.adk.agents import Agent

def search_flights(origin: str, destination: str, date: str) -> dict:
    """Tìm chuyến bay theo điểm đi, điểm đến và ngày bay."""
    # Hàm này nên gọi API chuyến bay thực tế
    return {
        "origin": origin,
        "destination": destination,
        "date": date,
        "options": [
            {
                "airline": "Example Air",
                "price": 320,
                "currency": "USD"
            }
        ]
    }

def search_hotels(destination: str, check_in: str, nights: int) -> dict:
    """Tìm khách sạn theo điểm đến, ngày nhận phòng và số đêm."""
    # Hàm này nên gọi API khách sạn thực tế
    return {
        "destination": destination,
        "check_in": check_in,
        "nights": nights,
        "options": [
            {
                "name": "Example Hotel",
                "price_per_night": 120,
                "currency": "USD"
            }
        ]
    }

flights = Agent(
    name="flight_agent",
    model="gemini-2.0-flash",
    instruction="Tìm các lựa chọn chuyến bay cho tuyến đường và ngày của người dùng.",
    tools=[search_flights],
)

hotels = Agent(
    name="hotel_agent",
    model="gemini-2.0-flash",
    instruction="Tìm các lựa chọn khách sạn gần điểm đến.",
    tools=[search_hotels],
)

trip_planner = Agent(
    name="trip_planner",
    model="gemini-2.0-flash",
    instruction=(
        "Lên kế hoạch chuyến đi. "
        "Ủy quyền việc tìm kiếm chuyến bay và khách sạn cho các tác nhân con."
    ),
    sub_agents=[flights, hotels],
)

Cách kiểm thử nhanh:

adk web

Sau đó gửi yêu cầu như:

Tôi muốn đi từ Hà Nội đến Tokyo vào ngày 2026-08-10 trong 4 đêm. Hãy tìm chuyến bay và khách sạn.

Khi kiểm thử, hãy quan sát:

Agent chính có chuyển đúng việc cho agent con không.
Agent con có gọi đúng tool không.
Tham số tool có đúng định dạng không.
Output có đủ dữ liệu để tổng hợp câu trả lời không.

ADK so với OpenAI Agents SDK

Cả ADK và OpenAI Agents SDK đều là framework agent ưu tiên code, hỗ trợ tool, handoff và tracing. Khác biệt chính nằm ở hệ sinh thái mặc định.

	Google ADK	OpenAI Agents SDK
Mô hình mặc định	Gemini qua Vertex AI	Các mô hình OpenAI
Các mô hình khác	Vertex AI Model Garden, LiteLLM	LiteLLM và các mô hình khác
Ngôn ngữ	Python, Java, Go, TypeScript	Python, JavaScript/TypeScript
Đa tác nhân	Sub-agent, SequentialAgent, ParallelAgent, LoopAgent	Agent làm tool và handoff
Runtime được quản lý	Vertex AI Agent Engine	Tự triển khai
Giao thức tool	MCP, built-in tools, function tools	MCP, function tools

Nếu stack của bạn đã nằm trên Google Cloud, ADK kết hợp với Vertex AI là lựa chọn tự nhiên. Nếu bạn ưu tiên OpenAI, OpenAI Agents SDK sẽ phù hợp hơn. Cả hai đều hỗ trợ MCP, nên một số tool server có thể được chia sẻ giữa hai hệ sinh thái.

Khi nào nên dùng ADK

Dùng ADK khi:

Bạn đang xây dựng trên Google Cloud.
Bạn muốn dùng Gemini cùng Vertex AI Agent Engine.
Bạn cần workflow đa tác nhân với trình tự, song song hoặc vòng lặp rõ ràng.
Bạn muốn evaluation là một phần của framework.
Bạn muốn có đường thoát sang mô hình khác qua LiteLLM hoặc Vertex AI Model Garden.
Bạn cần triển khai agent theo hướng production thay vì prototype đơn giản.

Không nhất thiết phải dùng ADK nếu:

Use case chỉ cần một prompt và một hoặc hai function call.
Bạn đã khóa hoàn toàn vào hệ sinh thái mô hình khác.
Bạn không cần multi-agent workflow.
Chi phí vận hành framework lớn hơn độ phức tạp của bài toán.

Một nguyên tắc thực tế: bắt đầu với agent đơn giản. Chỉ thêm sub-agent, workflow agent và runtime được quản lý khi bài toán thật sự cần.

Apidog phù hợp ở đâu: kiểm thử và mô phỏng API mà agent gọi

ADK điều phối agent. Nó không thay thế việc kiểm thử các API bên ngoài mà tool của bạn gọi.

Trong một agent thực tế, tool có thể gọi:

API thanh toán.
API đặt vé.
Microservice nội bộ.
Endpoint LLM.
API CRM.
Data service của bên thứ ba.

Nếu một API trả về schema sai hoặc thiếu field, agent có thể suy luận dựa trên dữ liệu lỗi. Lỗi kiểu này thường khó debug vì nó xuất hiện như “agent trả lời sai”, trong khi nguyên nhân nằm ở contract API.

Apidog không phải framework agent và không thay thế ADK. Nó nằm ở lớp API mà các tool của agent phụ thuộc vào.

1. Mock API cho tool

Khi đang phát triển agent, bạn có thể chưa muốn gọi API thật vì:

Tốn token.
Bị rate limit.
Dữ liệu production nhạy cảm.
API bên thứ ba chưa ổn định.
Cần mô phỏng case lỗi.

Bạn có thể dựng API mô phỏng trong Apidog, sau đó trỏ tool của ADK vào mock endpoint.

Ví dụ tool gọi endpoint mock:

import requests

def search_flights(origin: str, destination: str, date: str) -> dict:
    """Tìm chuyến bay từ API chuyến bay."""
    response = requests.get(
        "https://mock.example.com/flights",
        params={
            "origin": origin,
            "destination": destination,
            "date": date,
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

Bạn có thể tạo nhiều response mock:

Thành công.
Không có kết quả.
API timeout.
Field bị thiếu.
Giá trị trả về sai kiểu.

Sau đó kiểm tra agent phản ứng thế nào trong từng trường hợp.

2. Xác nhận response schema của API

Tool thường giả định API trả về cấu trúc ổn định. Ví dụ:

{
  "options": [
    {
      "airline": "Example Air",
      "price": 320,
      "currency": "USD"
    }
  ]
}

Nếu API đổi price thành amount, agent hoặc tool có thể lỗi.

Bạn có thể dùng xác nhận API trong Apidog để kiểm tra:

Status code.
Field bắt buộc.
Kiểu dữ liệu.
Giá trị enum.
Thời gian phản hồi.
Schema JSON.

Checklist nên có cho mỗi API mà agent gọi:

Response có đúng status code không?
JSON có đầy đủ field mà tool cần không?
Field số có đúng kiểu number không?
Field ngày tháng có đúng format không?
Error response có cấu trúc nhất quán không?

3. Quản lý môi trường dev, staging, production

Agent thường cần gọi API ở nhiều môi trường:

Local mock.
Dev.
Staging.
Production.

Với Apidog, bạn có thể quản lý biến môi trường như:

Base URL.
API key.
Token.
Header mặc định.
User test ID.

Điều này giúp cùng một test hoặc request chạy được qua nhiều giai đoạn mà không phải sửa code thủ công.

4. Tách lỗi agent khỏi lỗi API

Khi agent trả lời sai, hãy kiểm tra theo thứ tự:

Tool có được gọi không?
Tool có nhận đúng tham số không?
API có trả đúng schema không?
Tool có parse response đúng không?
Agent có tổng hợp kết quả đúng không?

Apidog giúp bạn xử lý bước 3 và một phần bước 4. Khi API contract đã được xác nhận, bạn có thể tập trung debug prompt, tool selection hoặc orchestration trong ADK.

Nếu bạn muốn đi sâu hơn, hãy xem hướng dẫn kiểm thử các lệnh gọi tool của tác nhân AI trước khi chúng lỗi trong production. Bạn cũng có thể tải xuống Apidog và mock một endpoint trong vài phút.

Các câu hỏi thường gặp

Google ADK có miễn phí và mã nguồn mở không?

Có. ADK là mã nguồn mở theo giấy phép Apache trên kho lưu trữ GitHub. Bạn có thể chạy ADK cục bộ mà không mất phí framework. Bạn vẫn phải trả tiền cho mô hình bạn gọi và runtime được quản lý nếu triển khai lên dịch vụ như Vertex AI Agent Engine.

ADK chỉ hoạt động với Gemini không?

Không. ADK được tối ưu hóa cho Gemini và Vertex AI, nhưng không phụ thuộc vào một mô hình duy nhất. Thông qua Vertex AI Model Garden và LiteLLM, bạn có thể dùng Anthropic, Meta, Mistral và các nhà cung cấp khác. Gemini là lựa chọn mặc định mạnh nhất trong Google stack, không phải yêu cầu bắt buộc.

ADK hỗ trợ những ngôn ngữ nào?

Python là ngôn ngữ đầu tiên và hiện vẫn là lựa chọn đầy đủ nhất. Google sau đó thêm Java, tiếp theo là Go và TypeScript. Nếu bạn muốn bắt đầu nhanh và có phạm vi tính năng rộng nhất, hãy chọn Python.

Làm cách nào để kiểm thử API mà agent ADK phụ thuộc vào?

Hãy kiểm thử API tách biệt khỏi agent:

Mock endpoint để agent chạy mà không gọi API thật.
Kiểm tra status code và schema response.
Tạo test case cho cả success và error response.
Chạy lại test khi API, prompt hoặc tool thay đổi.

Apidog hỗ trợ mock và assertion cho các API này. Hướng dẫn kiểm thử ChatGPT API cũng áp dụng được cho các endpoint LLM hoặc tool endpoint mà agent gọi.

Kết luận

Google ADK cung cấp một cách có cấu trúc để xây dựng agent và hệ thống đa tác nhân cho production. Bạn có thể bắt đầu với một Agent, thêm tool bằng các hàm Python, kiểm thử bằng adk web, sau đó mở rộng sang sub-agent, evaluation và runtime được quản lý khi cần.

Khi agent phụ thuộc vào API bên ngoài, đừng chỉ debug ở tầng prompt. Hãy kiểm thử contract của các API mà tool gọi. Mock endpoint, xác nhận response schema và quản lý môi trường là các bước giúp agent ổn định hơn. Đó là lớp mà Apidog xử lý, và cũng là nơi nhiều lỗi agent trong production thường bắt đầu.

DEV Community