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

Большие языковые модели изменили способ использования программного обеспечения людьми, но следующий шаг связан не столько с улучшением функций чатов, сколько с системами, способными к логическим рассуждениям, вызову инструментов, совместной работе и самостоятельному выполнению целых рабочих процессов. Именно это и является сферой деятельности агентных ИИ. В то время как классическое приложение отправляет один запрос и ждет одного ответа, агент сам решает, что делать дальше: он может вызвать API, получить информацию, передать подзадачу специалисту или вернуть структурированный результат.

Инструментарий разработки агентов от Google (Agent Development Kit, ADK) представляет собой практическую платформу для изучения этой темы. Он позволяет создавать агентов на основе моделей Gemini, использовать функции Python в качестве инструментов, координировать действия нескольких агентов и развертывать их в Google Cloud. В следующих разделах рассматривается процесс от создания одного агента до его развертывания в облаке.

От запросов к агентам

Традиционные приложения на основе больших языковых моделей работают по принципу ввода запроса и получения ответа. Вы задаёте вопрос, модель отвечает, и на этом всё заканчивается. В агентной архитектуре модель находится внутри более крупной системы выполнения. Она может иметь цели, выбирать инструменты, взаимодействовать с API и сотрудничать с другими агентами. Суть в том, что агент — это не просто запрос: это программный компонент, управляемый языковой моделью.

Приложение 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 также может быть развернут в Agent Engine от Google — управляемой среде выполнения, созданной для работы корпоративных агентов. Начните с включения необходимых 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. Те же принципы применимы как к примеру калькулятора, так и к многоагентным корпоративным решениям: рассуждения, делегирование задач, оркестрация и выполнение. Программное обеспечение переходит от ответов на вопросы к выполнению функций внутри реальных приложений.