Агенты Google ADK: адаптаванне ад аднаго агента Gemini да запуску ў Cloud Run

Масштабныя мовныя мадэлі змянілі спосаб прыемкі програмнага забезпечэння людзьмі, але наступны крок стосуецца не столькі розумнейшых чатоў, сколькі сістэм, якія можаюць рассуждаваць, вызываць інструменты, працаваць разам і самостоятэльна выкананыць цэлыя робочыя працэсы. Гэта тэрытарыя агентных AI. Калі класычны прыстаўка выдае адну запітанне і чакае аднай адпаведзі, агент сам адлучвае, што робіць далей: ён можа вызваць API, запрашаць інформацыю, перадаць падзадачу спецыялісту або вярнуць структураваны рэзультат.

Кіт для разработкі агентоў Google (ADK) — гэта практычная парадка для выучэння гэтага. Ён дазволяе ствараць агентоў на мадэлях Gemini, выклікваць функцыі Python як інструменты, коордынаваць калькі агентоў і размістыць іх у Google Cloud. Наступныя раздзелы прагледваюць працэс, пры якому ад аднаго агента пераходзіць да размішчэння ў воблаку.

Ад запітанняў да агентоў

Традыцыяныя прыкладнікі на базе LLM працуююць за прынцыпам «запытка-адказ». Вы ставіце запытку, мадэль адказвае, і на гэтам усё. У агентнай схеме мадэль знаходзіцца ўнутрь большага сістэмы выканання. Яна можа мець цілі, выбіраць інструменты, взаімадзейваць з 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]
)

Хутчэй, мадэль разумее запіт, але замест таго, каб сама выконваць арыметычныя вычысленні, яна перадае ўсе вычысленні функцыі. LLM выконвае логічныя манёвры, а інструмент — фактычна выконанне. Такое раздзелення ёсць аднай з аснов серйозных корпоратыўскіх рашэнняў.

Рэальныя сістэмы рэдка калі паслугоўваюцься аднім інструментам. Асістэнт можа вызываць 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 адразу з Cloud Run задае інтэрфейс ADK. Рэзультатам являецца сервіс AI, які можна размясціць, а не проста іграшка для нотбука.

Адкрыцье 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, і працэс яўляецца чыстым, якім бы ні было там, што відбываецца пад спадом.

Чаму гэта важна

Агентныя AI-сістэмы — гэта іншы спосаб стварэння програмнага забезпечэння на адной з мовных модэлей, а не проста лепшыя запіты. Агенты разумуюць, выкарыстоўваюць інструменты, коордынуюць робочыя працэсы і работаюць з зовнішнімі сістэмамі, замест таго каб ствараць ізольаваныя адказы.

ADK ўжо ў сабе ёсць хорашым інструментам для навучэння, адколькі поступова прадстаўляе гэтыя ідэі. Вы пачынаеце з аднаго агента Gemini, дадаеце інструменты, з’ѐеднуеце калькі агентоў, а пазней доходзіце да корпоратыўных робочых працэсаў з вікорыстаннем RAG, інтэграцыяў MCP, практык ацэнкі і размешчэння на GCP. Тыя ж прынцыпы дапамагаюць, як у прыкладзе калькулятара, так і ў корпоратыўных сетках з калькіма агентамі: разумаванне, дэлегаванне, оркестрацыя і выкананне. Програмнае забезпечэнне пераходзіць ад адпаведзення на запытанні да працы ўнутры рэальных прыкладоў выкарыстоўвання.