Агенти Google ADK: від одного агента Gemini до розгортання в Cloud Run

Додаток ADK орієнтований на root_agent. Найпростіша версія виглядає так:

from google.adk.agents import Agent

root_agent = Agent(
    name="assistant",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant"
)

Навіть це — це функціональний агент із ім’ям, поведінкою, моделлю та здатністю до виконання дій. Він може спілкуватися, але не може впливати ні на що ззовні себе, поки не отримає інструменти.

Інструменти

Те, що визначає агентський ШІ, — це використання інструментів. Без інструментів модель створює лише текст, а з ними агент може застосовувати справжню логіку. У ADK звичайна функція Python перетворюється на інструмент як тільки її передають у конфігурацію агента. Агент-калькулятор демонструє, як це відбувається:

from google.adk.agents import Agent


def calculator(a: float, b: float, operation: str) -> float:
    if operation == "add":
        return a + b

    if operation == "subtract":
        return a - b

    if operation == "multiply":
        return a * b

    if operation == "divide":
        if b == 0:
            raise Exception("Cannot divide by zero")

        return a / b

    raise Exception("Unsupported operation")


root_agent = Agent(
    name="assistant",
    model="gemini-2.5-flash",
    instruction=(
        "You are a helpful assistant with calculator capabilities. "
        "Use the calculator tool for arithmetic. "
        "Supported operations are add, subtract, multiply, divide."
    ),
    tools=[calculator]
)

Тут модель розуміє запит, але замість того, щоб виконувати арифметичні операції сама, вона передає точні обчислення функції. Штучний інтелект виконує логічні міркування, а інструмент — виконання. Саме такий розподіл є основою серйозних корпоративних рішень.

Реальні системи рідко покладаються лише на один інструмент. Асистент може викликати API, конвертувати дані, здійснювати запити до баз даних, отримувати документи, перевіряти правила та узагальнювати результати. Наведений нижче багатофункціональний агент поєднує в собі арифметику, перетворення одиниць вимірювання та пошук інформації про погоду:

from google.adk.agents import Agent


def calculator(a: float, b: float, operation: str) -> float:
    if operation == "add":
        return a + b

    if operation == "subtract":
        return a - b

    if operation == "multiply":
        return a * b

    if operation == "divide":
        if b == 0:
            raise ValueError("Cannot divide by zero.")

        return a / b

    raise ValueError("Unsupported operation.")


def convert_units(value: float, from_unit: str, to_unit: str) -> float:
    from_unit = from_unit.lower()
    to_unit = to_unit.lower()

    if from_unit == "km" and to_unit == "miles":
        return value * 0.621371

    if from_unit == "miles" and to_unit == "km":
        return value / 0.621371

    if from_unit == "celsius" and to_unit == "fahrenheit":
        return value * 9 / 5 + 32

    if from_unit == "fahrenheit" and to_unit == "celsius":
        return (value - 32) * 5 / 9

    raise ValueError("Unsupported unit conversion.")


def get_weather_mock(city: str) -> dict:
    weather_data = {
        "bucharest": {
            "temperature_celsius": 23,
            "condition": "sunny",
            "wind_speed_kmh": 10,
        },
        "london": {
            "temperature_celsius": 16,
            "condition": "rain",
            "wind_speed_kmh": 18,
        },
    }

    key = city.lower()

    if key not in weather_data:
        return {
            "city": city,
            "error": "Weather data not available."
        }

    return {
        "city": city,
        **weather_data[key],
    }


root_agent = Agent(
    name="multi_tool_agent",
    model="gemini-2.5-flash",
    instruction=(
        "You are a practical assistant. "
        "Use the available tools when the user asks for calculations, "
        "unit conversions, or weather information."
    ),
    tools=[
        calculator,
        convert_units,
        get_weather_mock,
    ],
)

Тепер агент виступає як оркеструвальник. Він на льоту обирає інструменти залежно від запиту, і користувачеві ніколи не доводиться казати, який саме інструмент використати.

Агенти як інструменти інших агентів

ADK дозволяє одному агенту слугувати інструментом для іншого, що сприяє спеціалізації. Замість одного величезного запиту, який намагається охопити все, створюються менші агенти з вузькими функціями. Прикладом цього є планувальник подорожей, складений з кількох агентів:

from google.adk.agents import LlmAgent
from google.adk.tools import google_search
from google.adk.tools import google_maps_grounding
from google.adk.tools.agent_tool import AgentTool


routing_agent = LlmAgent(
    name="routing_agent",
    model="gemini-2.5-pro",
    instruction="""
    You are a routing agent.
    Use google_maps_grounding to estimate routes and travel times.
    """,
    tools=[google_maps_grounding],
)


discovery_agent = LlmAgent(
    name="discovery_agent",
    model="gemini-2.5-pro",
    instruction="""
    You are a travel discovery agent.
    Use Google Search to find interesting places.
    """,
    tools=[google_search]
)


composer_agent = LlmAgent(
    name="composer_agent",
    model="gemini-2.5-pro",
    instruction="""
    Write a friendly travel itinerary based on the collected information.
    """,
    tools=[]
)


root_agent = LlmAgent(
    name="travel_agent",
    model="gemini-2.5-pro",
    instruction="""
    You are a travel assistant.
    Coordinate discovery, routing, and itinerary composition.
    """,
    tools=[
        AgentTool(discovery_agent),
        AgentTool(routing_agent),
        AgentTool(composer_agent)
    ]
)

Кореневий агент функціонує як оркестратор без фіксованої схеми роботи, а кожен підагент є спеціалістом, якого можна викликати в будь-якому порядку. Така система простіша у обслуговуванні, масштабуванні та аналізі, що відповідає напрямку розвитку багатьох корпоративних рішень з штучного інтелекту.

Структуровані потоки

Не кожен процес має бути повністю автономним, адже бізнес-системи часто потребують структури. Типовою схемою є планування, потім виконання та подання звітів. ADK реалізує це за допомогою послідовних агентів, як у цьому ланцюжку планувальника, виконавця та звітувальника:

from google.adk.agents import Agent, SequentialAgent
from google.adk.tools import AgentTool


planner_agent = Agent(
    name="planner_agent",
    model="gemini-2.5-flash",
    instruction="""
    Read the user request and create a short execution plan.
    """
)


executor_agent = Agent(
    name="executor_agent",
    model="gemini-2.5-flash",
    instruction="""
    Execute the plan and delegate specialist work.
    """,
    tools=[]
)


report_agent = Agent(
    name="report_agent",
    model="gemini-2.5-flash",
    instruction="""
    Produce the final report based on execution results.
    """
)


root_agent = SequentialAgent(
    name="planner_executor_report_workflow",
    sub_agents=[
        planner_agent,
        executor_agent,
        report_agent,
    ],
)

Локальна розробка

Локальний цикл ADK працює швидко. Спочатку файл .env визначає проект Google Cloud, місцезнаходження та спосіб використання Vertex AI:

GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=True

Потім один командний запит запускає локальний веб-інтерфейс для інтерактивної проби роботи агентів:

adk web

Такий швидкий цикл ідеально підходить для експериментування.

Розгортання у Cloud Run

Локальні тести мають свої обмеження, а Cloud Run є одним із найпростіших способів для продакшну. Для першого агента вище достатньо короткого Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY . .

RUN pip install --no-cache-dir -r requirements.txt

CMD ["adk", "web", "--host", "0.0.0.0", "--port", "8080"]

Розгорніть з вихідного коду за допомогою gcloud:

gcloud run deploy simple-agent \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE \
  --set-env-vars GOOGLE_CLOUD_PROJECT=PROJECT_ID \
  --set-env-vars GOOGLE_CLOUD_LOCATION=us-central1

Після цього знайдіть URL сервісу:

gcloud run services describe simple-agent \
  --region us-central1 \
  --format='value(status.url)'

Відкриття цього URL відображає інтерфейс ADK безпосередньо з Cloud Run. Результатом є сервіс ШІ, який можна розгорнути, а не просто іграшковий інструмент у форматі нотбука.

Створення API за допомогою FastAPI

Іноді HTTP API підходить краще, ніж інтерфейс браузера, і ADK добре працює з FastAPI. Мінімальний файл main.py, який обгортає агента для роботи з погодою, виглядає так:

import uuid

from fastapi import FastAPI
from pydantic import BaseModel

from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

from agent import root_agent


app = FastAPI()

session_service = InMemorySessionService()

runner = Runner(
    agent=root_agent,
    app_name="weather_agent_service",
    session_service=session_service,
)


class QueryRequest(BaseModel):
    message: str


@app.post("/weather")
async def weather(request: QueryRequest):

    user_id = "api_user"
    session_id = str(uuid.uuid4())

    await session_service.create_session(
        app_name="weather_agent_service",
        user_id=user_id,
        session_id=session_id,
    )

    content = types.Content(
        role="user",
        parts=[
            types.Part(text=request.message)
        ],
    )

    final_answer = ""

    async for event in runner.run_async(
        user_id=user_id,
        session_id=session_id,
        new_message=content,
    ):
        if event.is_final_response():
            final_answer = event.content.parts[0].text

    return {
        "response": final_answer
    }

Для його розгортання потрібен трохи інший Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY . .

RUN pip install --no-cache-dir -r requirements.txt

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

Agent Engine

ADK також може бути розгорнутий у Google’s Agent Engine — керованому середовищі виконання, створеному для роботи корпоративних агентів. Почніть з увімкнення необхідних API:

gcloud services enable \
  aiplatform.googleapis.com \
  storage.googleapis.com

Далі створіть бакет для тестування:

export STAGING_BUCKET="gs://${PROJECT_ID}-agent-staging"

gsutil mb -l us-central1 $STAGING_BUCKET

Потім розгорніть агента:

adk deploy agent_engine \
--project=$PROJECT_ID \
--region=us-central1 \
--staging_bucket=$STAGING_BUCKET \
basic_agent

Це створює ресурс керованого двигуна міркувань у Google Cloud, і процес є простим, враховуючи всі процеси, які відбуваються на нижчих рівнях.

Чому це важливо

Агентні ШІ — це інший підхід до створення програмного забезпечення на основі мовних моделей, а не просто кращі запити. Агенти міркують, використовують інструменти, координують робочі процеси та працюють з зовнішніми системами, замість того щоб формувати ізольовані відповіді.

ADK є хорошим інструментом для навчання, оскільки поступово знайомить із цими ідеями. Ви починаєте з одного агента Gemini, додаєте інструменти, під’єднуєте кілька агентів, а згодом переходите до корпоративних робочих процесів із використанням RAG, інтеграцій MCP, систем оцінки та розгортання на GCP. Ті самі принципи діють від прикладу калькулятора до багатоагентної корпоративної системи: міркування, делегування, оркестрація та виконання. Програмне забезпечення поступово переходить від відповідей на запитання до функціонування всередині реальних додатків.