ADK: od podstaw do agentów wielofunkcyjnych

1. Wprowadzenie

To ćwiczenie zaczyna się od podstaw i przechodzi do tworzenia agentów z wieloma narzędziami, dzięki czemu stanowi kompleksowe wprowadzenie do tworzenia agentów za pomocą pakietu ADK.

W najprostszym ujęciu agent AI to system oprogramowania, który wykorzystuje duży model językowy (LLM) jako „silnik rozumowania” do osiągania celu poprzez autonomiczne wykonywanie sekwencji zadań.

Duży model językowy to wysoce kompetentny konsultant, który może udzielać porad, a agent AI to proaktywny inżynier, który może używać narzędzi do wdrażania tych porad.

LLM a agenci

Mózg (LLM): zapewnia rozumowanie, planowanie i rozumienie języka naturalnego. Decyduje, co należy zrobić.

Ręce (narzędzia): są to interfejsy API, pakiety SDK i funkcje niestandardowe, które umożliwiają agentowi interakcję z rzeczywistym światem. Wykonuje plan.

Pakiet Agent Development Kit (ADK)

Pakiet Agent Development Kit (ADK) to specjalistyczna platforma zaprojektowana z myślą o ułatwieniu tworzenia, wdrażania i orkiestracji agentów AI. Zapewnia standardowe elementy składowe potrzebne do przekształcenia statycznego dużego modelu językowego w dynamicznego agenta, który może wykonywać kod, wywoływać interfejsy API i zarządzać wieloetapowymi przepływami pracy.

Agent wielofunkcyjny to narzędzie, które może wybierać i sekwencjonować różne specjalistyczne funkcje, takie jak wyszukiwarka, baza danych i kalkulator, aby rozwiązywać złożone problemy. Inteligentnie określa, którego narzędzia użyć na każdym etapie, i może przekazywać dane wyjściowe z jednego działania jako dane wejściowe do następnego, aby osiągnąć ostateczny cel.

Co utworzysz

W tym ćwiczeniu utworzysz agenta „Zdrowe wskazówki”, czyli inteligentnego doradcę żywieniowego, który przechodzi od prostego rozumowania tekstowego do wielofunkcyjnego narzędzia. Zaczniesz od utworzenia podstawowego agenta konwersacyjnego, który rozumie koncepcje związane z odżywianiem. Następnie stopniowo wyposażysz go w narzędzie Storage SDK do archiwizowania obrazów składników oraz narzędzie Vision do „odczytywania” i analizowania tych obrazów. Po ukończeniu tego laboratorium będziesz mieć w pełni działający orkiestrator, który może pobrać przesłane zdjęcie etykiety produktu spożywczego, zapisać je w zasobniku w chmurze do celów dokumentacyjnych i natychmiast podać „zdrowe wskazówki” dotyczące każdego składnika.

2. Wymagania wstępne

projekt Google Cloud z włączonymi płatnościami;
przeglądarki internetowej,

Tworzenie projektu

W konsoli Google Cloud na stronie selektora projektów wybierz lub utwórz projekt Google Cloud.
Sprawdź, czy w projekcie w chmurze włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.

Aktywowanie Cloud Shell

Będziesz używać Cloud Shell, czyli środowiska wiersza poleceń działającego w konsoli Google Cloud, które ma już zainstalowane wymagane języki. W konsoli Cloud kliknij Aktywuj Cloud Shell w prawym górnym rogu:

Po połączeniu z Cloud Shell zobaczysz, że uwierzytelnianie zostało już przeprowadzone, a projekt jest już ustawiony na Twój identyfikator projektu. Aby potwierdzić, że uwierzytelnianie zostało przeprowadzone, uruchom w Cloud Shell to polecenie:

gcloud auth list

Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:

gcloud config list project

Jeśli projekt nie jest ustawiony, użyj tego polecenia, aby go ustawić:

gcloud config set project <YOUR_PROJECT_ID>

Informacje o poleceniach gcloud i ich użyciu znajdziesz w dokumentacji.

Otwórz edytor

W tym ćwiczeniu użyjemy wbudowanego edytora Cloud. W oknie Cloud Shell kliknij przycisk Otwórz edytor w prawym górnym rogu. Otworzy się edytor VSCode.

3. Konfiguracja ADK

Przejdźmy do terminala Cloud Shell, który został aktywowany w poprzedniej sekcji:

Tworzenie i aktywowanie środowiska wirtualnego (zalecane)

W terminalu Cloud Shell utwórz środowisko wirtualne:

python -m venv .venv

Aktywuj środowisko wirtualne:

source .venv/bin/activate

Instalowanie ADK

pip install google-adk

4. Klucz interfejsu API Google

Tworzenie klucza interfejsu API Google za pomocą AI Studio:

Otwórz stronę https://aistudio.google.com/ i w menu w lewym dolnym rogu kliknij Get API Key.

Pojawi się okno Klucze interfejsu API. Kliknij w nim Utwórz klucz interfejsu API:

Pojawi się wyskakujące okienko tworzenia nowego klucza. Nazwij klucz: healthy-hints-key

Otwórz menu „Wybierz zaimportowany projekt”.

Kliknij Import Project. Pojawi się okno boczne z listą wszystkich Twoich projektów Google Cloud. Wybierz ten, z którym chcesz pracować.

Kliknij Importuj.

Menu zostanie teraz zaktualizowane o zaimportowany przez Ciebie projekt. Wybierz projekt z menu. Kliknij Utwórz klucz. Zobaczysz teraz listę utworzonych kluczy interfejsu API. Kliknij ikonę kopiowania utworzonego przed chwilą klucza interfejsu API.

5. Przykładowy agent

W terminalu Cloud Shell utwórz katalog główny agenta w wybranej lokalizacji projektu:

adk create healthy_hints

Możesz wybrać dowolny model, ale w tym laboratorium użyjemy modelu gemini-2.5-flash.

W tym ćwiczeniu użyjemy AI od Google. Wklej klucz interfejsu API utworzony w poprzednim kroku.

Otwórzmy folder, który właśnie utworzyliśmy. W menu po lewej stronie kliknij ikonę , a następnie kolejno Plik –> Otwórz folder. Wybierz nowo utworzony folder healthy_hints, który zwykle znajduje się w folderze /home/<username>.
Struktura folderów healthy_hints wygląda zwykle tak:

Zobaczysz plik .env, który zawiera Twój klucz interfejsu Google API. Za pomocą tego pliku możesz ustawić dowolną zmienną środowiskową.
Zostanie też utworzony inny plik o nazwie agent.py, który jest naszym głównym plikiem agenta. W tym miejscu tworzony jest przykładowy agent główny. Przyjrzyjmy się bliżej zawartości tego pliku. Najpierw importujemy llm_agent z ADK. Następnie używamy pakietu ADK DSL do utworzenia agenta głównego. Podajemy nazwę modelu jako Gemini-2.5-flash, nazwę agenta i jego opis. Najważniejsze są instrukcje, w których w języku naturalnym informujemy agenta, co ma zrobić.
Ten przykładowy agent jest dość ogólny i odpowiada na każde pytanie użytkownika.
Teraz uruchomimy tego agenta lokalnie. Z tym agentem możesz wchodzić w interakcje na 2 sposoby : za pomocą interfejsu wiersza poleceń i przez internet.
CLI uruchom to polecenie spoza katalogu healthy_hints.

adk run healthy_hints

Jeśli jesteś w katalogu healthy_hints, uruchom to polecenie:

adk run .

Zobaczysz podobne dane wyjściowe:

Wpisz „cześć” lub zadaj dowolne pytanie. Odpowiedź może być inna dla każdej osoby, taka jest natura generatywnej AI.

Web: w katalogu nadrzędnym healthy_hints uruchom to polecenie :

adk web

6. Agent narzędzi wielofunkcyjnych

Narzędzie to modułowy fragment kodu – zwykle funkcja lub interfejs API – który umożliwia agentowi interakcję ze światem zewnętrznym, wykraczającą poza jego wewnętrzną wiedzę.

Rodzaje narzędzi w pakiecie ADK

Narzędzia funkcji: niestandardowa logika, którą piszesz samodzielnie. Może to być np. funkcja, która łączy się z Twoją bazą danych, lub niestandardowy „parser logów” dla unikalnego formatu Twojej firmy.
Narzędzia wbudowane: gotowe do użycia funkcje udostępniane przez Google lub ADK, takie jak wyszukiwarka Google, interpreter kodu czy silnik RAG od Google.
Agents-as-Tools: w zaawansowanych systemach „wielonarzędziowych” lub „wieloagentowych” jeden wyspecjalizowany agent może pełnić funkcję narzędzia dla innego agenta. Na przykład „Agent wyszukiwania” może być narzędziem używanym przez „Agenta menedżera ds. badań”.

W tym ćwiczeniu omówimy narzędzia funkcji. Teraz rozbudujmy agenta i sprawmy, aby mógł korzystać z wielu narzędzi.

Dodajmy nową metodę get_weather w pliku agent.py.

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

Zmodyfikujmy plik agent.py i zmieńmy nazwę, opis oraz instrukcje agenta:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

Do tej pory utworzyliśmy tylko jedno narzędzie. Teraz utwórzmy kilka narzędzi:

Utwórzmy kolejną metodę o nazwie get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

Zmodyfikujmy też agenta, aby wywoływał to narzędzie:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

Odpowiednio zmodyfikowaliśmy opis, instrukcje i narzędzia. Teraz uruchommy zaktualizowanego agenta. Tym razem agent odpowie, podając aktualną godzinę i pogodę.

7. Integracja pakietu SDK

Teraz, gdy wiemy już, jak korzystać z wielu narzędzi, Przyjrzyjmy się kilku przykładom z życia. Utwórzmy agenta z poradami dotyczącymi zdrowia. Chcemy przesłać do naszego agenta dowolny obraz z listą składników, a agent powie nam, które składniki są zdrowe, a które nie.

Najpierw utwórzmy zasobnik w Google Cloud Storage, aby przesłać obraz. Otwórz nową kartę i przejdź na stronę https://console.cloud.google.com/. Na pasku wyszukiwania wpisz Cloud Storage. Teraz w sekcji Produkty i strony wybierz Cloud Storage:

Przekierujemy Cię na stronę przeglądu Google Cloud Storage. Kliknij przycisk Create bucket. Na stronie tworzenia zasobnika wpisz jego nazwę. Nazwa może być dowolna, ale w tym ćwiczeniu użyjemy nazwy healthy-hints-bucket-kolkata . Pozostaw inne ustawienia bez zmian i kliknij przycisk Create.

Utwórzmy nowy plik o nazwie requirements.txt i dodajmy do niego google-cloud-storage. Aby przesłać obraz do usługi Pamięć, użyjemy pakietu Python Storage SDK.

Najpierw zainstalujmy zależności:

pip install -r requirements.txt

Najpierw może być konieczne włączenie interfejsu Storage API. Aby to zrobić, uruchom w terminalu to polecenie:

gcloud services enable storage.googleapis.com

Dodajmy teraz nowe narzędzie do przesyłania obrazu.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

Teraz zaktualizujmy agenta, aby korzystał z nowego narzędzia:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

Dodamy kolejne narzędzie do odczytywania składników z obrazu. Dodajmy google-cloud-vision w requirements.txt i zainstalujmy nową zależność.

pip install -r requirements.txt

Może być konieczne włączenie interfejsu Vision API. Aby to zrobić, uruchom w terminalu to polecenie:

gcloud services enable vision.googleapis.com

Teraz dodajmy nowe narzędzie read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

Teraz zaktualizujmy agenta, aby korzystał z tego narzędzia.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. Podsumowanie

Gratulujemy ukończenia ćwiczenia Healthy Hints! Udało Ci się przekształcić standardową AI z generatora tekstu w proaktywnego agenta wielofunkcyjnego. Korzystając z pakietu ADK do integracji interfejsu Vision API i pakietu SDK Cloud Storage, dajesz agentowi „oczy” do odczytywania etykiet i „pamięć” do ich archiwizowania. Widzisz, jak agent autonomicznie decyduje, kiedy zapisać plik, i jak interpretować surowe dane, aby udzielać porad zdrowotnych dotyczących świata rzeczywistego.

W przyszłości te zasady będą stanowić podstawę każdego zautomatyzowanego systemu. Niezależnie od tego, czy zarządzasz infrastrukturą w chmurze, czy tworzysz osobistych asystentów, podstawy pozostają te same: zdefiniuj specjalistyczne narzędzia i pozwól agentowi koordynować logikę. Następnie spróbuj dodać więcej narzędzi, takich jak „Baza danych o wartościach odżywczych” lub „Narzędzie do wysyłania e-maili”, aby zwiększyć skuteczność agenta.