Hướng dẫn Google ADK: Xây dựng AI Agents từ con số 0 đến môi trường Production

Hướng dẫn Google ADK: Xây dựng AI Agents từ con số 0 đến môi trường Production

Bộ công cụ phát triển Agent (ADK) của Google là khung làm việc giúp các hệ thống đa tác nhân (multi-agent systems) trở nên dễ tiếp cận hơn bao giờ hết. Nếu bạn đã từng xây dựng AI agents bằng LangChain hoặc CrewAI và cảm thấy mình đang phải "chiến đấu" với khung làm việc nhiều hơn là xây dựng sản phẩm, thì hướng dẫn Google ADK này sẽ dẫn dắt bạn qua mọi thứ, từ agent đầu tiên cho đến khi triển khai nó trên Cloud Run.

Google ADK là gì (Và tại sao bạn nên quan tâm)?

Bộ công cụ phát triển Agent (ADK) của Google là một khung làm việc Python mã nguồn mở để xây dựng, đánh giá và triển khai các AI agents. Ra mắt vào năm 2025, nó được tối ưu hóa cho Gemini nhưng hỗ trợ hơn 100 mô hình thông qua LiteLLM. Tính năng nổi bật nhất của ADK là khả năng điều phối đa tác nhân gốc, cho phép các agents ủy thác nhiệm vụ cho các agents khác mà không cần viết mã kết nối phức tạp.

Sau khi xây dựng agents với LangChain, CrewAI và giờ là ADK, đây là những điểm nổi bật: ADK có quan điểm rõ ràng ở những nơi cần thiết. Nó cung cấp cho bạn cấu trúc dự án, giao diện người dùng phát triển tích hợp sẵn và lệnh triển khai. Bạn không cần phải ghép nối năm thư viện khác nhau chỉ để chạy một agent cơ bản.

Nếu LangChain là một con dao quân đội Thụy Sĩ đa năng, thì ADK là bộ công cụ chuyên biệt của Google dành cho các quy trình làm việc đa tác nhân. CrewAI có triết lý gần gũi hơn với các agents dựa trên vai trò cộng tác, nhưng ADK đi xa hơn với khả năng đánh giá tích hợp, tối ưu hóa native cho Gemini và triển khai Cloud Run chỉ bằng một lệnh. Để phân tích sâu hơn, hãy xem bài so sánh chuyên sâu về các khung làm việc agent của chúng tôi.

ADK dành cho ai? Các nhà phát triển Python muốn có hệ thống đa tác nhân có cấu trúc. Các đội ngũ đã sử dụng Google Cloud hoặc Gemini. Bất kỳ ai mệt mỏi với việc viết mã boilerplate cho logic điều phối.

Dưới đây là bảng so sánh nhanh các khung làm việc:

Nói ngắn gọn: nếu bạn muốn con đường nhanh nhất từ "ý tưởng" đến "hệ thống đa tác nhân đã triển khai", ADK hiện là lựa chọn khó có thể đánh bại.

Điều kiện tiên quyết và Cài đặt Google ADK

Để bắt đầu với Google ADK, bạn cần Python 3.9+, khóa API Gemini (có gói miễn phí tại Google AI Studio) và gói google-adk. Cài đặt bằng pip install google-adk, đặt khóa API của bạn làm biến môi trường và bạn đã sẵn sàng xây dựng agent đầu tiên trong vòng chưa đầy 5 phút.

Dưới đây là danh sách kiểm tra thiết lập của bạn:

• Python 3.9+ (khuyên dùng 3.10+ để hỗ trợ đầy đủ gợi ý kiểu)
• Khóa API Gemini, lấy miễn phí tại aistudio.google.com. Gói miễn phí cung cấp 15 yêu cầu mỗi phút, đủ cho quá trình phát triển.
• pip (hoặc uv nếu bạn thích tốc độ, uv pip install google-adk cũng hoạt động)

Cài đặt gói và đặt khóa của bạn:

pip install google-adk

# Set your API key (add to .bashrc/.zshrc for persistence)
export GOOGLE_API_KEY="your-api-key-here"

ADK yêu cầu một cấu trúc thư mục cụ thể. Mỗi agent nằm trong thư mục package riêng của nó:

my_agent/
  __init__.py    # Exports root_agent
  agent.py       # Agent definition
.env             # Optional: GOOGLE_API_KEY=your-key

Tên thư mục sẽ trở thành tên package của agent, vì vậy hãy chọn tên mô tả rõ ràng. Đừng đặt tên là test hoặc agent, bạn sẽ gây nhầm lẫn cho hệ thống import của Python.

Mẹo chuyên nghiệp: Nếu bạn đang sử dụng uv, hãy tạo môi trường ảo trước với uv venv && source .venv/bin/activate. Nó nhanh hơn đáng kể so với pip thông thường trong việc giải quyết các phụ thuộc.

Xây dựng Google ADK Agent đầu tiên của bạn

Agent ADK đầu tiên của bạn chỉ cần ba thứ: một tên, một mô hình (như gemini-2.0-flash) và một chuỗi hướng dẫn. Định nghĩa nó trong agent.py, đặt nó bên trong một thư mục có file __init__.py, và chạy adk web để trò chuyện với nó trong giao diện trình duyệt. Toàn bộ quá trình thiết lập chỉ mất khoảng 10 dòng Python.

Tạo một thư mục tên là my_agent và thêm hai file. Đầu tiên là định nghĩa agent:

# my_agent/agent.py
from google.adk.agents import LlmAgent

root_agent = LlmAgent(
    name="my_assistant",
    model="gemini-2.0-flash",
    instruction="""You are a helpful coding assistant. 
    You explain concepts clearly and provide working code examples.
    Keep responses concise but thorough.""",
    description="A coding assistant that explains concepts and writes code"
)

Sau đó là file init xuất khẩu agent của bạn:

# my_agent/__init__.py
from .agent import root_agent

Tên biến này rất quan trọng, ADK tìm kiếm cụ thể root_agent. Bỏ qua điều này và bạn sẽ gặp lỗi "agent not found" mà không giải thích rõ lý do.

Bây giờ hãy chạy nó. Bạn có hai lựa chọn:

# CLI mode -- chat in your terminal
adk run my_agent

# Web UI mode -- opens a browser interface
adk web my_agent

Giao diện adk web thực sự hữu ích. Nó hiển thị cho bạn toàn bộ dấu vết cuộc trò chuyện, các công cụ mà agent đã gọi, những gì mô hình nhận được và những gì nó trả về. Hãy coi nó như Chrome DevTools dành cho agent của bạn. Khi bạn bắt đầu xây dựng hệ thống đa tác nhân sau này, điều này trở nên thiết yếu để hiểu luồng ủy thác.

Hãy thử sửa đổi hướng dẫn để xem hành vi thay đổi như thế nào. Biến nó thành một cướp biển. Bắt nó chỉ phản hồi bằng thơ haiku. Việc cảm nhận cách hướng dẫn định hình hành vi là nền tảng cho mọi thứ khác trong hướng dẫn này.

Thêm Công cụ Tùy chỉnh vào Google ADK Agent của bạn

Các agent ADK trở nên hữu ích khi bạn cung cấp cho chúng công cụ. Định nghĩa một hàm Python với docstring rõ ràng, và ADK sẽ tự động chuyển đổi nó thành một công cụ mà agent có thể gọi. Docstring là cực kỳ quan trọng, nó báo cho mô hình biết công cụ làm gì và khi nào nên sử dụng. ADK cũng đi kèm với các công cụ tích hợp sẵn như Google Search và thực thi mã.

Công cụ là đôi tay của agent. Không có chúng, agent của bạn chỉ có thể nói chuyện. Với chúng, nó có thể kiểm tra cơ sở dữ liệu, gọi API, chạy tính toán và tương tác với các hệ thống bên ngoài. Nếu bạn muốn hiểu cách gọi hàm hoạt động bên dưới lớp vỏ, chúng tôi có một bài phân tích sâu riêng về chủ đề đó.

Công cụ Hàm Tùy chỉnh

Dưới đây là một ví dụ thực tế, một công cụ tra cứu giá cổ phiếu:

# my_agent/agent.py
from google.adk.agents import LlmAgent

def get_stock_price(ticker: str) -> dict:
    """Get the current stock price for a given ticker symbol.
    
    Args:
        ticker: The stock ticker symbol (e.g., 'AAPL', 'GOOGL', 'MSFT')
    
    Returns:
        A dictionary with the ticker and its current price.
    """
    # In production, you'd call a real API here
    mock_prices = {"AAPL": 198.50, "GOOGL": 175.20, "MSFT": 425.80}
    price = mock_prices.get(ticker.upper(), None)
    if price:
        return {"ticker": ticker.upper(), "price": price, "currency": "USD"}
    return {"error": f"Ticker {ticker} not found"}

root_agent = LlmAgent(
    name="finance_assistant",
    model="gemini-2.0-flash",
    instruction="You help users check stock prices. Use the get_stock_price tool when asked about any stock.",
    tools=[get_stock_price],
    description="A financial assistant that looks up stock prices"
)

Lưu ý các gợi ý kiểu (type hints) và docstring. Đây không phải là những tiện ích tùy chọn, ADK sử dụng chúng để tạo lược đồ công cụ mà mô hình nhìn thấy. Bỏ qua docstring và mô hình sẽ không biết khi nào gọi hàm của bạn. Bỏ qua gợi ý kiểu và bạn sẽ gặp lỗi chữ ký.

Công cụ Tích hợp Sẵn (Google Search, Thực thi Mã)

ADK cung cấp các công cụ bạn có thể sử dụng ngay mà không cần viết mã:

from google.adk.agents import LlmAgent
from google.adk.tools import google_search, code_execution

root_agent = LlmAgent(
    name="research_agent",
    model="gemini-2.0-flash",
    instruction="You research topics using Google Search and can run Python code to analyze data.",
    tools=[google_search, code_execution],
    description="A research agent with search and code execution capabilities"
)

google_search cho phép agent truy vấn web theo thời gian thực. code_execution cung cấp cho nó một môi trường Python bị cô lập để chạy tính toán. Chỉ hai công cụ này đã bao phủ một số lượng trường hợp sử dụng đáng ngạc nhiên.

Hệ thống Đa tác nhân: Cách Google ADK Agents Ủy thác Công việc

Hệ thống đa tác nhân của ADK sử dụng một agent gốc (root agent) để ủy thác nhiệm vụ cho các agent con chuyên biệt. Mỗi agent con xử lý một lĩnh vực, nghiên cứu, viết lách, lập trình. Agent gốc quyết định gọi agent con nào dựa trên yêu cầu của người dùng. Bạn cũng có thể sử dụng mẫu agent-as-tool, nơi một agent gọi agent khác như thể nó là một hàm. Bài blog chính thức của Google về hệ thống đa tác nhân đi sâu hơn vào các mẫu kiến trúc.

Hãy nghĩ về nó như một quản lý dự án ủy thác cho các chuyên gia. Agent gốc đọc yêu cầu của người dùng, xác định chuyên gia nào nên xử lý nó và định tuyến accordingly. Các chuyên gia không biết về nhau, họ chỉ làm công việc của mình và báo cáo lại.

Mẫu Agent Gốc + Agent Con

Dưới đây là một ví dụ hoạt động với một agent gốc ủy thác cho một agent nghiên cứu và một agent viết lách:

from google.adk.agents import LlmAgent
from google.adk.tools import google_search

# Sub-agent 1: handles research
research_agent = LlmAgent(
    name="researcher",
    model="gemini-2.0-flash",
    instruction="You research topics thoroughly using Google Search. Return factual, well-sourced information.",
    tools=[google_search],
    description="Researches topics and returns factual information"
)

# Sub-agent 2: handles writing
writing_agent = LlmAgent(
    name="writer",
    model="gemini-2.0-flash",
    instruction="You write clear, engaging content based on provided information. Focus on readability and accuracy.",
    description="Writes polished content from research notes"
)

# Root agent: delegates to the right sub-agent
root_agent = LlmAgent(
    name="content_manager",
    model="gemini-2.0-flash",
    instruction="""You manage content creation. 
    - When the user wants information gathered, delegate to the researcher.
    - When the user wants content written or edited, delegate to the writer.
    - You can chain both: research first, then write.""",
    sub_agents=[research_agent, writing_agent],
    description="Manages content creation by delegating to research and writing specialists"
)

Trường description trên mỗi agent con là cách agent gốc hiểu những gì chúng có thể làm. Viết mô tả rõ ràng, những mô tả mơ hồ dẫn đến các quyết định định tuyến kém.

Mẫu Agent-as-Tool

Đôi khi bạn muốn kiểm soát nhiều hơn cách một agent gọi agent khác. Mẫu agent-as-tool bọc một agent con như một công cụ có thể gọi:

from google.adk.tools import agent_tool

research_tool = agent_tool.AgentTool(agent=research_agent)

root_agent = LlmAgent(
    name="writer_with_research",
    model="gemini-2.0-flash",
    instruction="You write articles. Use the research tool to gather facts before writing.",
    tools=[research_tool],
    description="A writer that can research topics on demand"
)

Sử dụng agent con khi bạn muốn agent gốc hoàn toàn ủy thác quyền kiểm soát. Sử dụng agent-as-tool khi bạn muốn agent gọi giữ quyền kiểm soát và chỉ sử dụng đầu ra của agent con làm đầu vào. Nếu bạn đang xây dựng các hệ thống nơi các agents cần chia sẻ ngữ cảnh, hãy xem hướng dẫn toàn diện của chúng tôi về kiến trúc bộ nhớ agent.

Workflow Agents: Tuần tự, Song song và Lặp

Ngoài việc ủy thác dựa trên LLM, ADK cung cấp ba loại workflow agent cho việc điều phối xác định: SequentialAgent chạy các agent con lần lượt, ParallelAgent chạy chúng đồng thời và LoopAgent lặp lại một chuỗi cho đến khi điều kiện được đáp ứng. Những loại này hữu ích khi bạn cần thứ tự thực thi có thể dự đoán thay vì để LLM quyết định.

Sự khác biệt là quan trọng. Việc ủy thác dựa trên LLM (mẫu sub_agents ở trên) cho phép mô hình chọn người để gọi. Workflow agents cung cấp cho bạn quyền kiểm soát lập trình. Sử dụng workflow agents khi thứ tự thực thi đã được biết trước.

from google.adk.agents import SequentialAgent, ParallelAgent, LlmAgent

# Three agents that must run in order
research_agent = LlmAgent(name="researcher", model="gemini-2.0-flash",
    instruction="Research the given topic.", description="Researches topics")
    
draft_agent = LlmAgent(name="drafter", model="gemini-2.0-flash",
    instruction="Write a draft based on the research.", description="Writes drafts")
    
review_agent = LlmAgent(name="reviewer", model="gemini-2.0-flash",
    instruction="Review the draft for accuracy and clarity.", description="Reviews content")

# Pipeline: research -> draft -> review
content_pipeline = SequentialAgent(
    name="content_pipeline",
    sub_agents=[research_agent, draft_agent, review_agent],
    description="Runs a complete content creation pipeline"
)

Đối với các tác vụ độc lập có thể chạy cùng lúc, ParallelAgent tiết kiệm thời gian thực:

# Three data fetchers that run concurrently
fetch_news = LlmAgent(name="news_fetcher", model="gemini-2.0-flash",
    instruction="Fetch latest tech news.", description="Fetches news")
    
fetch_stocks = LlmAgent(name="stock_fetcher", model="gemini-2.0-flash",
    instruction="Fetch stock market summary.", description="Fetches stocks")
    
fetch_weather = LlmAgent(name="weather_fetcher", model="gemini-2.0-flash",
    instruction="Fetch weather forecast.", description="Fetches weather")

morning_briefing = ParallelAgent(
    name="morning_briefing",
    sub_agents=[fetch_news, fetch_stocks, fetch_weather],
    description="Gathers morning briefing data in parallel"
)

Quản lý Trạng thái và Bộ nhớ

ADK quản lý trạng thái agent ở hai cấp độ: trạng thái phiên (dữ liệu trong một cuộc trò chuyện, như sở thích người dùng được thu thập giữa chừng) và dịch vụ bộ nhớ (dữ liệu tồn tại qua các cuộc trò chuyện). Trạng thái phiên là một kho lưu trữ key-value đơn giản được truy cập qua context.state. Bộ nhớ sử dụng các dịch vụ như InMemoryMemoryService hoặc VertexAIMemoryBankService cho production.

Trạng thái phiên là cái đơn giản hơn. Nó là một từ điển đính kèm với mỗi cuộc trò chuyện:

from google.adk.agents import LlmAgent

def save_preference(key: str, value: str, context) -> str:
    """Save a user preference to session state.
    
    Args:
        key: The preference name (e.g., 'language', 'theme')
        value: The preference value
        context: The ADK context object
    
    Returns:
        Confirmation message
    """
    context.state[key] = value
    return f"Saved preference: {key} = {value}"

def get_preference(key: str, context) -> str:
    """Retrieve a user preference from session state.
    
    Args:
        key: The preference name to look up
        context: The ADK context object
    
    Returns:
        The preference value or a not-found message
    """
    value = context.state.get(key, "Not set")
    return f"{key} = {value}"

root_agent = LlmAgent(
    name="personalized_assistant",
    model="gemini-2.0-flash",
    instruction="You remember user preferences. Save them when told, recall them when asked.",
    tools=[save_preference, get_preference],
    description="An assistant that remembers user preferences"
)

Đối với bộ nhớ xuyên suốt các cuộc trò chuyện, loại mà agent của bạn nhớ một người dùng từ thứ Ba tuần trước, bạn cần một dịch vụ bộ nhớ:

from google.adk.memory import InMemoryMemoryService

# For development (data lost on restart)
memory_service = InMemoryMemoryService()

# For production, use VertexAIMemoryBankService
# memory_service = VertexAIMemoryBankService(project="your-project")

Khi nào bạn cần bộ nhớ so với trạng thái phiên? Nếu nó nằm trong một cuộc trò chuyện duy nhất (giỏ hàng, ngữ cảnh tác vụ hiện tại), hãy sử dụng trạng thái phiên. Nếu nó cần tồn tại giữa các cuộc trò chuyện (sở thích người dùng, tương tác trước đó), hãy sử dụng dịch vụ bộ nhớ. Hãy xem hướng dẫn toàn diện của chúng tôi về kiến trúc bộ nhớ agent để biết các mẫu production.

Callbacks: Kiểm soát Hành vi Agent

Callbacks của ADK cho phép bạn chặn và sửa đổi hành vi agent tại bốn điểm: before_model_callback (trước khi gọi LLM), after_model_callback (sau phản hồi LLM), before_tool_callback (trước khi thực thi công cụ) và after_tool_callback (sau kết quả công cụ). Sử dụng chúng để xác thực đầu vào, lọc an toàn, ghi nhật ký hoặc sửa đổi phản hồi trước khi chúng đến tay người dùng.

Callbacks là nơi bạn thêm các rào chắn an toàn. Hãy coi chúng như middleware cho agent của bạn, mọi yêu cầu và phản hồi đều đi qua chúng, và bạn có thể kiểm tra, sửa đổi hoặc chặn bất cứ thứ gì.

from google.adk.agents import LlmAgent

def safety_filter(callback_context, llm_request):
    """Block requests containing harmful content patterns."""
    user_message = str(llm_request)
    blocked_patterns = ["ignore your instructions", "pretend you are"]
    
    for pattern in blocked_patterns:
        if pattern.lower() in user_message.lower():
            # Return a response directly, skipping the model call
            return {"blocked": True, "reason": "Request matched safety filter"}
    
    # Return None to proceed normally
    return None

def log_tool_usage(callback_context, tool_name, tool_result):
    """Log every tool call for monitoring."""
    print(f"[TOOL LOG] {tool_name}: {tool_result}")
    return None  # Don't modify the result

root_agent = LlmAgent(
    name="safe_assistant",
    model="gemini-2.0-flash",
    instruction="You are a helpful assistant.",
    before_model_callback=safety_filter,
    after_tool_callback=log_tool_usage,
    description="A safety-filtered assistant with tool logging"
)

before_model_callback là quan trọng nhất cho production. Nó chạy trước mỗi lần gọi LLM, cho bạn cơ hội chặn tiêm prompt, xác thực đầu vào hoặc thêm ngữ cảnh hệ thống. Nếu bạn trả về một đối tượng phản hồi, ADK sẽ bỏ qua hoàn toàn mô hình. Trả về None để cho phép yêu cầu đi qua. Để biết thêm các mẫu, xem các mẫu sâu hơn cho rào chắn an toàn LLM.

Kiểm thử và Đánh giá Agents ADK của bạn

ADK bao gồm một khung đánh giá tích hợp sẵn với hai loại evaluator: ResponseEvaluator kiểm tra xem câu trả lời cuối cùng của agent có đúng không, và TrajectoryEvaluator xác minh agent đã thực hiện các bước đúng, gọi các công cụ đúng theo thứ tự đúng. Viết các trường hợp kiểm thử dưới dạng file JSON và chạy chúng với pytest để bắt các lỗi hồi quy trước khi triển khai.

Tại sao phải bận tâm kiểm thử agents? Vì chúng không xác định. Cùng một đầu vào có thể tạo ra các đầu ra khác nhau, và một thay đổi nhỏ trong hướng dẫn của bạn có thể phá vỡ việc gọi công cụ theo những cách tinh vi. Theo kinh nghiệm của chúng tôi, các agents vượt qua đánh giá quỹ đạo đáng tin cậy hơn nhiều trong production so với những agents chỉ được kiểm thử trên chất lượng đầu ra cuối cùng. Để biết các chiến lược đánh giá rộng hơn, hãy xem hướng dẫn của chúng tôi về chiến lược đánh giá LLM.

Các trường hợp kiểm thử của bạn nằm trong file JSON:

[
  {
    "input": "What's the stock price of AAPL?",
    "expected_output": "198.50",
    "expected_trajectory": [
      {"tool_name": "get_stock_price", "args": {"ticker": "AAPL"}}
    ]
  },
  {
    "input": "Compare AAPL and GOOGL prices",
    "expected_output": "AAPL.*198.*GOOGL.*175",
    "expected_trajectory": [
      {"tool_name": "get_stock_price", "args": {"ticker": "AAPL"}},
      {"tool_name": "get_stock_price", "args": {"ticker": "GOOGL"}}
    ]
  }
]

Sau đó chạy đánh giá với pytest. Kho lưu trữ ADK Python có tài liệu tham khảo API đánh giá đầy đủ:

# test_agent.py
import pytest
from google.adk.evaluation import ResponseEvaluator, TrajectoryEvaluator

def test_stock_agent_response():
    evaluator = ResponseEvaluator(agent=root_agent)
    results = evaluator.evaluate("test_cases.json")
    
    assert results.pass_rate >= 0.8, f"Response pass rate too low: {results.pass_rate}"

def test_stock_agent_trajectory():
    evaluator = TrajectoryEvaluator(agent=root_agent)
    results = evaluator.evaluate("test_cases.json")
    
    assert results.pass_rate >= 0.9, f"Trajectory pass rate too low: {results.pass_rate}"

Chạy với pytest test_agent.py -v. Đặt ngưỡng của bạn dựa trên mức độ quan trọng -- độ chính xác phản hồi 80% có thể ổn cho một agent viết sáng tạo, nhưng bạn sẽ muốn 95%+ cho bất cứ thứ gì xử lý dữ liệu tài chính.

Triển khai Google ADK Agent của bạn lên Production

Triển khai agent ADK của bạn lên Google Cloud Run chỉ với một lệnh: adk deploy cloud_run --project YOUR_PROJECT --region us-central1. ADK đóng gói mã của bạn, xây dựng một container và khởi chạy một endpoint serverless. Đối với hosting được quản lý, sử dụng Vertex AI Agent Engine. Đối với cơ sở hạ tầng tùy chỉnh, ADK cũng hỗ trợ containerization Docker.

Chúng tôi đã triển khai các agents ADK trên Cloud Run cho các công cụ nội bộ và thời gian khởi động lạnh nhanh đến ngạc nhiên, dưới 3 giây cho một agent cơ bản. Đối với các hệ thống production, hãy cân nhắc ghép nối việc triển khai của bạn với các công cụ giám sát cho agents production.

Triển khai lên Cloud Run (Khuyên dùng cho hầu hết)

Cloud Run là con đường đơn giản nhất. Một lệnh và agent của bạn sẽ hoạt động với một endpoint HTTPS:

adk deploy cloud_run \
  --project your-gcp-project-id \
  --region us-central1 \
  --service-name my-agent-service \
  --with_ui

Cờ --with_ui triển khai giao diện Web ADK cùng với agent của bạn, vì vậy bạn có một cuộc trò chuyện dựa trên trình duyệt để kiểm thử trong production. Đằng sau hậu trường, ADK xây dựng một image container, đẩy nó lên Google Artifact Registry và tạo một dịch vụ Cloud Run. Luồng triển khai đầy đủ được ghi lại trong hướng dẫn nhanh Cloud Run của Google cho ADK.

Đối với cơ sở hạ tầng tùy chỉnh, đây là một Dockerfile tối thiểu:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["adk", "api_server", "--port", "8080", "my_agent"]

Thay thế: Vertex AI Agent Engine

Đối với các đội ngũ doanh nghiệp cần khả năng mở rộng, giám sát và phiên bản được quản lý, Vertex AI Agent Engine xử lý hoàn toàn cơ sở hạ tầng. Bạn đánh đổi sự linh hoạt để lấy sự tiện lợi, không cần quản lý container, tự động mở rộng, phân tích tích hợp sẵn.

Cân nhắc về Chi phí

Những con số thực tế bạn nên biết:

• Gói miễn phí Gemini API: 15 yêu cầu mỗi phút, 1 triệu token/ngày. Đủ cho phát triển và demo nhẹ.
• Gemini 2.0 Flash (trả phí): $0.10 mỗi triệu token đầu vào, $0.40 mỗi triệu token đầu ra. Đủ rẻ cho production.
• Gói miễn phí Cloud Run: 2 triệu yêu cầu/tháng, 360.000 GB-giây tính toán. Một agent cơ bản xử lý 1.000 yêu cầu/ngày vẫn nằm well within gói miễn phí.
• Mẹo tối ưu hóa: Sử dụng gemini-2.0-flash (không phải gemini-2.0-pro) cho các agent con thực hiện định tuyến hoặc định dạng đơn giản. Dự trữ các mô hình mạnh mẽ hơn cho các agent thực hiện suy luận phức tạp.

Cách Techsy Tiếp cận Phát triển AI Agent

Tại Techsy, chúng tôi đã xây dựng các hệ thống đa tác nhân cho khách hàng sử dụng ADK, LangGraph và CrewAI. Lựa chọn khung làm việc phụ thuộc vào ngăn xếp của bạn: nếu bạn đã sử dụng Google Cloud, ADK loại bỏ rất nhiều ma sát tích hợp. Nếu bạn cần hỗ trợ LLM đa nhà cung cấp ngay từ ngày đầu tiên, LangGraph mang lại cho bạn sự linh hoạt hơn.

Quy trình tham gia điển hình của chúng tôi bắt đầu với tư vấn kiến trúc, ánh xạ trường hợp sử dụng của bạn với các mẫu agent phù hợp, tiếp theo là phát triển nguyên mẫu và triển khai Cloud Run. Chúng tôi thấy rằng các đội ngũ tiết kiệm được 2-3 tuần bằng cách làm đúng kiến trúc ngay từ đầu thay vì tái cấu trúc sau này.

Đang xây dựng AI agents cho đội ngũ của bạn? Nhận tư vấn miễn phí, chúng tôi sẽ giúp bạn chọn khung làm việc và chiến lược triển khai phù hợp.

Lỗi Thường gặp và Xử lý Sự cố

Đây là những lỗi chúng tôi gặp phải thường xuyên nhất khi bắt đầu với ADK. Hãy tiết kiệm thời gian gỡ lỗi cho chính bạn:

Mẹo gỡ lỗi: adk web là người bạn tốt nhất của bạn ở đây. Nó hiển thị toàn bộ dấu vết cuộc trò chuyện, mọi lần gọi mô hình, gọi công cụ và ủy thác agent, trong thời gian thực. Khi có sự cố trong hệ thống đa tác nhân, giao diện web cho bạn biết chính xác nơi chuỗi bị đứt gãy.

FAQ

Google ADK là gì?

Bộ công cụ phát triển Agent (ADK) của Google là một khung làm việc Python mã nguồn mở để xây dựng, đánh giá và triển khai các AI agents. Nó được tối ưu hóa cho các mô hình Google Gemini nhưng hỗ trợ hơn 100 LLM thông qua tích hợp LiteLLM. Điểm mạnh cốt lõi của ADK là điều phối đa tác nhân native với các công cụ tích hợp sẵn, giao diện dev và triển khai Cloud Run chỉ bằng một lệnh.

Google ADK có miễn phí không?

Có. Bản thân ADK là mã nguồn mở theo giấy phép Apache 2.0. Bạn cần một khóa API Gemini, có gói miễn phí cung cấp 15 yêu cầu mỗi phút và 1 triệu token mỗi ngày. Chi phí triển khai Cloud phụ thuộc vào lựa chọn hosting của bạn, gói miễn phí của Cloud Run bao gồm 2 triệu yêu cầu mỗi tháng.

Sự khác biệt giữa Google ADK và LangChain là gì?

ADK là khung làm việc có quan điểm rõ ràng của Google, được tối ưu hóa cho Gemini với điều phối đa tác nhân native và các công cụ triển khai tích hợp sẵn. LangChain không phụ thuộc mô hình với khả năng tích hợp bên thứ ba rộng rãi hơn nhưng phức tạp hơn đáng kể. ADK tốt hơn cho các đội ngũ ưu tiên Gemini muốn triển khai nhanh; LangChain phù hợp với các thiết lập đa nhà cung cấp cần sự linh hoạt tối đa.

Google ADK có hỗ trợ hệ thống đa tác nhân không?

Có, và đó là tính năng hàng đầu của ADK. Bạn tạo một agent gốc ủy thác cho các agent con chuyên biệt dựa trên yêu cầu của người dùng. ADK cũng cung cấp SequentialAgent, ParallelAgent và LoopAgent để điều phối quy trình làm việc xác định. Mẫu agent-as-tool cho phép các agents gọi các agents khác như các hàm có thể gọi.

Làm thế nào để triển khai một Google ADK agent?

Chạy adk deploy cloud_run --project YOUR_PROJECT --region us-central1 để triển khai serverless lên Google Cloud Run. Thêm --with_ui để bao gồm giao diện trò chuyện dựa trên trình duyệt. Bạn cũng có thể triển khai lên Vertex AI Agent Engine để hosting được quản lý, hoặc xây dựng một container Docker cho cơ sở hạ tầng tùy chỉnh.

Google ADK có thể sử dụng các mô hình khác ngoài Gemini không?

Có. ADK hỗ trợ hơn 100 mô hình thông qua tích hợp LiteLLM, bao gồm Anthropic Claude, OpenAI GPT-4, Meta Llama và Mistral. Đặt tham số mô hình thành chuỗi mô hình LiteLLM, ví dụ: litellm/anthropic/claude-3-sonnet hoặc litellm/openai/gpt-4o. Các mô hình Gemini hoạt động native mà không cần tiền tố LiteLLM.

ADK Web UI là gì?

Một giao diện gỡ lỗi dựa trên trình duyệt được khởi chạy với adk web your_agent_folder. Nó hiển thị các dấu vết cuộc trò chuyện thời gian thực, các lần gọi công cụ, chuỗi ủy thác agent và các thay đổi trạng thái khi chúng xảy ra. Web UI là thiết yếu để gỡ lỗi các hệ thống đa tác nhân vì nó hiển thị chính xác agent con nào đã xử lý từng yêu cầu.

Google ADK có hỗ trợ MCP (Model Context Protocol) không?

Có. ADK có hỗ trợ native Model Context Protocol, cho phép các agents kết nối với bất kỳ máy chủ công cụ tương thích MCP nào cho các công cụ và nguồn dữ liệu bên ngoài. Điều này làm cho các agents ADK có thể tương tác với hệ sinh thái MCP đang phát triển. Để biết thêm thông tin về giao thức, hãy xem hướng dẫn MCP của chúng tôi.

Làm thế nào để kiểm thử ADK agents?

ADK đi kèm với các evaluators tích hợp sẵn: ResponseEvaluator để kiểm tra chất lượng đầu ra so với các câu trả lời mong đợi, và TrajectoryEvaluator để xác minh agent đã gọi các công cụ đúng theo thứ tự đúng. Viết các trường hợp kiểm thử dưới dạng file JSON xác định đầu vào, đầu ra mong đợi và các chuỗi gọi công cụ mong đợi, sau đó chạy chúng với pytest.

Google ADK yêu cầu phiên bản Python nào?

ADK yêu cầu Python 3.9 trở lên. Python 3.10+ được khuyến nghị để hỗ trợ đầy đủ gợi ý kiểu, điều này quan trọng vì ADK sử dụng gợi ý kiểu để tạo lược đồ công cụ. Python 3.11 hoặc 3.12 cũng cung cấp các cải thiện hiệu suất đáng kể cho các tác vụ agent. Cài đặt với pip install google-adk.