Od prototypów do agentów za pomocą ADK

Od prototypów do agentów za pomocą ADK

Informacje o tym ćwiczeniu (w Codelabs)

Ostatnia aktualizacja: cze 12, 2025

Autorzy: Author: Abirami Sukumaran

1. Omówienie

Jak zaczyna się tworzenie z wykorzystaniem AI? Większość z nas zaczyna od prostego pytania: „Czy model może pomóc w rozwiązaniu tego problemu, nad którym myślę?”. Właśnie w tym przypadku przydaje się Google AI Studio. Jest to miejsce, w którym można szybko tworzyć prototypy. Chcę odnowić kuchnię i myślę, że Gemini może mi pomóc. Jestem inżynierem, a nie generalnym wykonawcą. Nie wiem nawet, o co mam prosić – trzeba wziąć pod uwagę tak wiele kwestii: przepisy, wyposażenie itp. Dlatego podzielmy to na części i poprośmy Gemini o wygenerowanie bardzo szczegółowego promptu, a potem o opracowanie pełnego planu renowacji i wizualizację przebudowy. Ale chwila. Jak mogę pomóc firmom w rozwijaniu się? Wpisz AGENTS!!!

Agent to autonomiczny program, który komunikuje się z modelem AI, aby wykonywać operacje oparte na celach, korzystając z dostępnych narzędzi i kontekstu. Jest też zdolny do autonomicznego podejmowania decyzji opartych na prawdzie.

Pakiet SDK agenta

Pakiet narzędzi do tworzenia agentów (ADK) to elastyczna i modułowa platforma do tworzenia i wdrażania agentów AI. ADK umożliwia tworzenie zaawansowanych aplikacji przez łączenie wielu różnych instancji agenta w system wieloagentowy (MAS).

W ADK system wieloagentowy to aplikacja, w której różne elementy, często tworzące hierarchię, współpracują lub koordynują swoje działania w celu osiągnięcia większego celu. Takie ustrukturyzowanie aplikacji niesie ze sobą wiele korzyści, w tym większą modularność, specjalizację, możliwość ponownego użycia, łatwość konserwacji oraz możliwość definiowania uporządkowanych przepływów sterowania za pomocą dedykowanych agentów przepływu pracy.

Co utworzysz

Czy jesteś gotowy przejść z prototypu na tworzenie agenta? Utworzymy agenta, który pomoże Ci wygenerować dokument z ofertą na potrzeby projektu renowacji kuchni. W ramach tego laboratorium wykonasz te czynności:

1. Tworzenie prostego agenta do generowania dokumentu propozycji renowacji za pomocą ADK
2. Przechowywanie wygenerowanego dokumentu propozycji renowacji w zasobniku Cloud Storage
3. Testowanie agenta w Cloud Shell i w wyjściu agenta w przeglądarce

Wymagania

• przeglądarka, np. Chrome lub Firefox;
• projekt Google Cloud z włączonymi płatnościami;

2. Zanim zaczniesz

Utwórz projekt

1. W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt Google Cloud.
2. Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności .
3. Jeśli czytasz ten artykuł i chcesz otrzymać środki, które pomogą Ci rozpocząć korzystanie z Google Cloud i używać ADK, kliknij ten link, aby je otrzymać. Złóż wniosek o środki.
4. Aby go wykorzystać, postępuj zgodnie z tymiinstrukcjami. Pamiętaj, że ten link jest ważny tylko do 15 lipca 2025 r.
5. Aby aktywować Cloud Shell, kliknij ten link. Możesz przełączać się między terminalem Cloud Shell (do uruchamiania poleceń w chmurze) a edytorem (do kompilowania projektów) przez kliknięcie odpowiedniego przycisku w Cloud Shell.
6. Po połączeniu z Cloud Shell sprawdź, czy jesteś już uwierzytelniony i czy projekt jest ustawiony na identyfikator Twojego projektu, używając tego polecenia:

gcloud auth list

5. Aby sprawdzić, czy polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:

gcloud config list project

6. Jeśli projekt nie jest ustawiony, użyj tego polecenia:

gcloud config set project <YOUR_PROJECT_ID>

7. Upewnij się, że masz zainstalowany Python w wersji 3.9 lub nowszej.

Inne polecenia gcloud i informacje o ich używaniu znajdziesz w dokumentacji.

3. Prototyp

Otwórz Google AI Studio. Zacznij pisać prompt. Oto prompt:

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

Aby uzyskać optymalną odpowiedź, dostosuj i skonfiguruj parametry po prawej stronie.

Na podstawie tego prostego opisu Gemini stworzył niezwykle szczegółowy prompt, który pomógł mi rozpocząć remont. W efekcie używamy Gemini, aby uzyskać jeszcze lepsze odpowiedzi z AI Studio i naszych modeli. Możesz też wybrać różne modele do użycia w zależności od przypadku użycia.

Wybraliśmy Gemini 2.5 Pro. Jest to model myślący, co oznacza, że otrzymujemy jeszcze więcej tokenów wyjściowych, w tym przypadku do 65 tys. tokenów, na potrzeby długich analiz i szczegółowych dokumentów. Po włączeniu Gemini 2.5 Pro, który ma natywne funkcje wnioskowania i może obsługiwać długie zapytania o kontekst, pojawi się okno myślenia Gemini.

Poniżej znajdziesz fragment odpowiedzi:

AI Studio przeanalizowało moje dane i wygenerowało wszystkie te elementy, takie jak szafki, blaty, okładziny ścienne, podłogi, umywalki, spójność, paleta kolorów i wybór materiałów. Gemini podaje nawet źródła!

Teraz spróbuj zobaczyć, jak pomysł nabiera realnych kształtów przy użyciu innego prompta.

1. Skopiuj ten prompt i wklej go do Edytora promptów:

Add flat and circular light accessories above the island area for my current kitchen in the attached image.

2. Załącz zdjęcie swojej kuchni (możesz też użyć mojego przykładowego zdjęcia kuchni).
3. Zmień model na „Gemini 2.0 Flash Preview Image Generation”, aby mieć dostęp do generowania obrazów.

Otrzymałem(-am) te dane wyjściowe:

To jest właśnie potęga Gemini.

Od rozumienia filmów po generowanie obrazów natywnych i uzyskiwanie prawdziwych informacji za pomocą wyszukiwarki Google – są rzeczy, które można tworzyć tylko za pomocą Gemini.

W Vertex AI Studio możesz pobrać ten prototyp, uzyskać klucz interfejsu API i skalować go do pełnej aplikacji z użyciem interfejsu Vertex AI ADK.

4. Konfiguracja ADK

Teraz przejdź do terminala Cloud Shell, który został aktywowany w sekcji „Przed rozpoczęciem”.

1. Tworzenie i aktywowanie środowiska wirtualnego (zalecane)

W terminalu Cloud Shell utwórz środowisko wirtualne:

python -m venv .venv

Aktywowanie środowiska wirtualnego:

source .venv/bin/activate

2. Instalowanie pakietu ADK

pip install google-adk

5. Struktura projektu

3. W terminalu Cloud Shell utwórz w wybranej lokalizacji projektu główny katalog aplikacji agentycznych:

mkdir agentic-apps

4. W katalogu głównym utwórz jeden folder przeznaczony do bieżącego projektu:

mkdir renovation-agent

5. Otwórz edytor Cloud Shell i utwórz następującą strukturę projektu, tworząc pliki (na początku puste):

renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Kod źródłowy

6. Otwórz plik „init.py” i wpisz w nim następujący kod:

from . import agent

7. Otwórz plik agent.py i zaktualizuj go, używając tych danych:

https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py

W pliku agent.py importujemy niezbędne zależności, pobieramy parametry konfiguracji z pliku .env i definiujemy root_agent, który generuje dokument propozycji i przechowuje go w zasośniku Cloud Storage. Do wykonania tego kroku w Cloud Storage użyjemy narzędzia o nazwie store_pdf.

8. Upewnij się, że masz zasobnik Cloud Storage

Służy do przechowywania dokumentu oferty wygenerowanego przez agenta. Utwórz go i przydziel dostęp, aby system agentów utworzony za pomocą Vertex AI mógł uzyskać do niego dostęp. Oto jak to zrobić:

https://cloud.google.com/storage/docs/creating-buckets#console

Nazwij zasóbnik „next-demo-store”. Jeśli nadasz mu inną nazwę, pamiętaj, aby zaktualizować wartość zmiennej STORAGE_BUCKET w pliku .env (w kroku konfiguracji zmiennych środowiskowych).

9. Aby skonfigurować dostęp do zasobnika, otwórz konsolę Cloud Storage i przejdź do zasobnika Cloud Storage (w naszym przypadku jego nazwa to „next-demo-storage”: https://console.cloud.google.com/storage/browser/next-demo-storage).

Kliknij Uprawnienia -> Wyświetl podmioty zabezpieczeń -> Przyznaj dostęp. W polu „Podmioty zabezpieczeń” wybierz „allUsers”, a w polu „Rola” – „Użytkownik obiektów Cloud Storage”.

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.

10. Tworzenie listy zależności

Wymień wszystkie zależności w pliku requirements.txt. Możesz go skopiować z repozytorium.

Objaśnienie kodu źródłowego systemu dla jednego agenta

Plik agent.py definiuje strukturę i zachowanie systemu wieloagentowego remontu kuchni za pomocą pakietu narzędzi dla deweloperów agentów (ADK). Omówmy kluczowe elementy:

Definicja agenta

Główny agent (aranżer): proposal_agent

root_agent działa jako aranżer tego systemu z jednym agentem. Odbiera ono początkowe żądanie odnowienia i określa, których narzędzi użyć na podstawie potrzeb związanych z tym żądaniem.

Następnie root_agent zbiera odpowiedzi z narzędzi i łączy je, aby zapewnić użytkownikowi kompleksową odpowiedź. W tym przypadku mamy tylko jedno narzędzie „store_pdf”.

7. Przepływ danych i kluczowe pojęcia

Użytkownik inicjuje żądanie za pomocą interfejsu ADK (terminalu lub interfejsu internetowego).

1. Żądanie jest odbierane przez root_agent.
2. Usługa root_agent analizuje żądanie i przekierowuje je do narzędzia w odpowiednim czasie.
3. Narzędzie „store_pdf” służy do zapisywania zrewitalizowanego tekstu w pliku PDF, a następnie do przesyłania go do Google Cloud Storage.
4. Następnie zwraca odpowiedź do root_agent.
5. Element root_agent łączy odpowiedzi i przekazuje użytkownikowi ostateczny wynik.

LLM (duże modele językowe)

Używają oni dużych modeli językowych do generowania tekstu, odpowiadania na pytania i wykonywania zadań wymagających rozumowania. LLM to „mózg” agentów, który umożliwia im zrozumienie żądań użytkowników i na nie reagowanie. W tej aplikacji używamy Gemini 2.5.

Google Cloud Storage

służy do przechowywania wygenerowanych dokumentów propozycji renowacji; Musisz utworzyć zasobnik i przyznać agentom niezbędne uprawnienia dostępu.

Cloud Run (opcjonalnie)

Usługa OrderingAgent korzysta z funkcji Cloud Run do komunikacji z AlloyDB. Cloud Run udostępnia środowisko bezserwerowe do wykonywania kodu w odpowiedzi na żądania HTTP.

AlloyDB

Jeśli używasz usługi OrderingAgent, musisz skonfigurować bazę danych AlloyDB, aby przechowywać informacje o zamówieniu.

plik.env

Plik .env przechowuje informacje poufne, takie jak klucze interfejsu API, dane logowania do bazy danych i nazwy zasobników. Pamiętaj, aby chronić ten plik i nie przekazywać go do repozytorium. Zawiera też ustawienia konfiguracji agentów i Twojego projektu Google Cloud. Z tego pliku zwykle odczytują wartości funkcja root_agent lub funkcje pomocnicze. Sprawdź, czy wszystkie wymagane zmienne są prawidłowo ustawione w pliku .env. Obejmuje to nazwę zasobnika Cloud Storage.

8. Konfiguracja modelu

Umiejętność agenta do rozumienia próśb użytkowników i generowania odpowiedzi jest obsługiwana przez duży model językowy (LLM). Twój pracownik musi wykonywać bezpieczne wywołania do tej zewnętrznej usługi LLM, która wymaga danych uwierzytelniających. Bez prawidłowego uwierzytelnienia usługa LLM odrzuca żądania agenta, który nie może wtedy działać.

1. Uzyskaj klucz interfejsu API w Google AI Studio.
2. W następnym kroku, w którym skonfigurujesz plik .env, zastąp <<your API KEY>> rzeczywistą wartością klucza API.

9. Konfiguracja zmiennych środowiskowych

3. Ustaw wartości parametrów w szablonie pliku .env w tym repozytorium. W moim przypadku plik .env zawiera te zmienne:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

Zastąp obiekty zastępcze swoimi wartościami.

10. Uruchamianie agenta

4. W terminalu przejdź do katalogu nadrzędnego projektu agenta:

cd agentic-apps/renovation-agent

5. Instalowanie wszystkich zależności

pip install -r requirements.txt

6. Aby uruchomić agenta, w terminalu Cloud Shell uruchom to polecenie:

adk run .

7. Aby uruchomić go w interfejsie internetowym obsługiwanym przez ADK:

adk web

8. Przeprowadź testy, korzystając z tych promptów:

user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

11. Wynik

W przypadku polecenia adk run: Wynik jest następujący:

…

Możesz sprawdzić, czy dokument Propozycja renowacji został utworzony w zasobniku Cloud Storage.

12. Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby wykorzystane w tym poście, wykonaj te czynności:

1. W konsoli Google Cloud otwórz stronę Zarządzanie zasobami.
2. Na liście projektów wybierz projekt do usunięcia, a potem kliknij Usuń.
3. W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.

13. Gratulacje

Gratulacje! Udało Ci się utworzyć aplikację wieloagentową i wykonać w niej interakcje za pomocą ADK. System wieloagentowy ma na celu usprawnienie procesu renowacji kuchni poprzez automatyzację zadań takich jak tworzenie ofert, sprawdzanie pozwoleń i śledzenie stanu zamówień. Każdy agent ma określoną rolę, a root_agent koordynuje ich działania, aby zapewnić kompleksowe rozwiązanie. System korzysta z LLM, usług Google Cloud i ewentualnych zewnętrznych interfejsów API, aby zapewniać swoje funkcje. Tutaj znajdziesz link do dokumentacji urządzenia.