Agenci Google ADK: od pojedynczego agenta Gemini do implementacji w Cloud Run

Wielkie modele językowe zmieniły sposób, w jaki ludzie korzystają z oprogramowania, ale następny krok ma mniej wspólnego z inteligentniejszymi rozmowami, a więcej z systemami, które potrafią rozumować, wywoływać narzędzia, współpracować i samodzielnie realizować całe procesy. To właśnie jest obszar agentyjnego AI. Podczas gdy klasyczna aplikacja wysyła jeden prompt i czeka na jedną odpowiedź, agent decyduje, co robić dalej: może wywołać API, pobrać informacje, przekazać podzadanie specjaliście lub zwrócić ustrukturyzowany wynik.

Google Agent Development Kit (ADK) to praktyczne narzędzie do nauki tego tematu. Umożliwia tworzenie agentów na bazie modeli Gemini, udostępnianie funkcji w Pythonie jako narzędzi, koordynowanie kilku agentów oraz ich wdrażanie w Google Cloud. Poniższe sekcje omawiają temat od pojedynczego agenta aż po wdrożenie w chmurze.

Od promptów do agentów

Tradycyjne aplikacje oparte na modelach językowych działają w trybie pytanie-odpowiedź. Zadajesz pytanie, model odpowiada i to już koniec. W architekturze opartej na agentach model znajduje się w ramach większego systemu wykonawczego. Może on przechowywać cele, wybierać narzędzia, komunikować się z API oraz współpracować z innymi agentami. Kluczową koncepcją jest to, że agent to coś więcej niż tylko zapytanie – to komponent oprogramowania sterowany modelem językowym.

Aplikacja ADK koncentruje się wokół root_agent. Najprostsza wersja wygląda tak:

from google.adk.agents import Agent

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

Nawet to jest działającym agentem z imieniem, zachowaniem, modelem oraz możliwością działania. Może rozmawiać, ale nie może dotknąć niczego poza sobą, dopóki nie otrzyma narzędzi.

Narzędzia

To, co definiuje sztuczną inteligencję agentową, to użycie narzędzi. Bez nich model generuje jedynie tekst, natomiast dzięki nim agent może stosować rzeczywistą logikę. W ADK zwykła funkcja w Pythonie staje się narzędziem, gdy tylko zostanie przekazana do konfiguracji agenta. Agent kalkulatora pokazuje, jak to działa:

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]
)

Tutaj model rozumie żądanie, ale zamiast samodzielnie wykonywać obliczenia, przekazuje dokładne zadanie funkcji. LLM zajmuje się rozumowaniem, a narzędzie jego wykonaniem. Taki podział stanowi podstawę solidnych projektów korporacyjnych.

Rzeczywiste systemy rzadko polegają na jednym narzędziu. Asystent może wywoływać API, konwertować dane, wyszukiwać informacje w bazie danych, pobierać dokumenty, sprawdzać zasady i podsumowywać wyniki. Poniższy agent wielofunkcyjny łączy w sobie możliwości arytmetyki, konwersji jednostek oraz wyszukiwania informacji o pogodzie:

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,
    ],
)

Agent teraz pełni rolę orkiestratora. Wybiera narzędzia w czasie rzeczywistym na podstawie żądania, a użytkownik nie musi wskazywać, które z nich użyć.

Agenci jako narzędzia innych agentów

ADK umożliwia jednemu agentowi pełnienie funkcji narzędzia dla innego, co sprzyja specjalizacji. Zamiast jednego ogromnego promptu, który próbuje objąć wszystko, tworzy się mniejsze agenty o wąskich zadaniami. Przykładem może być planer podróży składający się z kilku agentów:

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)
    ]
)

Agent główny funkcjonuje jako orkiestrator bez ustalonego procesu pracy, a każdy agent podrzędny to specjalista, którego można wywołać w dowolnej kolejności. Taki system jest łatwiejszy w utrzymaniu, skalowaniu i zrozumieniu, co odpowiada kierunkowi, którym zmierzają wiele projektów sztucznej inteligencji w przedsiębiorstwach.

Ustrukturyzowane przepływy

Nie każdy proces powinien być w pełni autonomiczny, ponieważ systemy biznesowe często wymagają struktury. Powszechnym schematem jest najpierw planowanie, potem realizacja, a następnie raportowanie. ADK realizuje to za pomocą agentów sekwencyjnych, jak w tym łańcuchu: planer, wykonawca i raportownik.

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,
    ],
)

Rozwój lokalny

Proces lokalnego uruchamiania w ADK jest szybki. Najpierw plik .env określa projekt w Google Cloud, lokalizację oraz sposób wykorzystania Vertex AI:

GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=True

Następnie jeden polecenie uruchamia lokalne interfejsy WWW do interaktywnego testowania agentów:

adk web

Taki szybki cykl nadaje się do eksperymentowania.

Rozwijanie w Cloud Run

Testy lokalne dają tylko ograniczone możliwości, a Cloud Run to jeden z najprostszych sposobów na wdrożenie w produkcji. Dla pierwszego agenta powyżej wystarczy krótki plik 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"]

Rozwijaj z źródła za pomocą 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

Następnie sprawdź adres URL usługi:

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

Otwarcie tego adresu URL uruchamia interfejs ADK bezpośrednio z Cloud Run. Wynikiem jest usługa AI gotowa do wdrożenia, a nie tylko narzędzie do eksperymentów.

Ujawnianie API za pomocą FastAPI

Czasami API HTTP nadaje się lepiej niż interfejs przeglądarki, a ADK dobrze współpracuje z FastAPI. Minimalny plik main.py otaczający agent do przewidywania pogody wygląda następująco:

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
    }

Aby to zaimplementować, potrzebny jest nieco inny plik 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 może być również wdrażany w Google Agent Engine, zarządzanym środowisku wykonywania stworzonym do uruchamiania agentów w przedsiębiorstwach. Zacznij od włączenia niezbędnych API:

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

Następnie utwórz bucket stagingowy:

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

gsutil mb -l us-central1 $STAGING_BUCKET

Następnie zainstaluj agenta:

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

To tworzy zasób zarządzanego silnika rozumowania w Google Cloud, a proces jest prosty, biorąc pod uwagę to, ile działa w tle.

Dlaczego to ma znaczenie

Sztuczna inteligencja agentowa to inny sposób budowania oprogramowania wokół modeli językowych, a nie tylko lepsze instrukcje. Agenci rozumują, używają narzędzi, koordynują prace zespołowe i współpracują z zewnętrznymi systemami, zamiast generować izolowane odpowiedzi.

ADK jest dobrym narzędziem edukacyjnym, ponieważ stopniowo wprowadza te koncepcje. Zaczynasz od jednego agenta Gemini, dodajesz narzędzia, łączysz kilka agentów, a później przechodzisz do złożonych procesów biznesowych z wykorzystaniem RAG, integracji MCP, pipeline’ów oceny oraz wdrażania na GCP. Te same zasady obowiązują od przykładu kalkulatora po wieloagentową architekturę przedsiębiorstwa: rozumowanie, delegowanie zadań, orkiestracja i wykonywanie. Oprogramowanie przechodzi od odpowiadania na pytania do działania w ramach rzeczywistych aplikacji.

Podobne materiały

• Projektowanie systemu agentic checkout: upoważnienia delegowane, przestarzałe oferty, próby ponowne — Przewodnik po projektowaniu systemów zakupów zarządzanych przez agenty: wymagania, przestarzałe oferty, klucze idempotencji, które zawodzą, główny sprzedawca, ślady audytu oraz przewodnik oceniania.
• Jeden agent, trzy wersje: Interactions API vs ADK vs Antigravity SDK — Stwórz agenta do publikowania opinii na Hacker News w BigQuery przy użyciu Interactions API, ADK oraz Antigravity SDK, porównaj pętle, narzędzia i mechanizmy autoryzacji, a następnie zainstaluj każdą z wersji w Cloud Run.