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

1. Przegląd

Od czego zacząć tworzenie z wykorzystaniem AI? W przypadku większości z nas zaczyna się to od prostego pytania: „Czy model może pomóc w rozwiązaniu problemu, nad którym się zastanawiam?”. Właśnie w tym pomaga Google AI Studio. To miejsce, w którym możesz szybko tworzyć prototypy dowolnych rozwiązań. Chcę wyremontować kuchnię i myślę, że Gemini może mi w tym pomóc. Jestem inżynierem, a nie wykonawcą. Nie wiem nawet, o co mam zapytać – jest tak wiele kwestii do rozważenia: przepisy, wyposażenie itp. Podzielmy więc to zadanie na mniejsze części i poprośmy Gemini o wygenerowanie bardzo szczegółowego promptu, a następnie o utworzenie pełnego planu remontu i wizualizacji przebudowy. Ale zaraz. Jak mogę pomóc firmom w rozwoju? Wpisz AGENTS!!!

Agent to autonomiczny program, który komunikuje się z modelem AI, aby wykonać operację opartą na celu, korzystając z dostępnych narzędzi i kontekstu. Potrafi podejmować autonomiczne decyzje oparte na faktach.

Pakiet Agent Development Kit (ADK)

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

W ADK system wieloagentowy to aplikacja, w której różne agenty, często tworzące hierarchię, współpracują lub koordynują działania, aby osiągnąć większy cel. Taka struktura aplikacji zapewnia wiele korzyści, w tym większą modułowość, specjalizację, możliwość ponownego użycia, łatwość konserwacji i możliwość definiowania strukturalnych przepływów sterowania za pomocą dedykowanych agentów przepływu pracy.

Co utworzysz

Chcesz przejść od prototypu PROMPT do tworzenia agenta? Utworzymy agenta, który pomoże wygenerować dokument z propozycją projektu remontu kuchni. W tym module wykonasz następujące zadania:

  1. Tworzenie prostego agenta do generowania dokumentu z propozycją remontu za pomocą pakietu ADK
  2. Zapisz wygenerowany dokument z propozycją remontu w zasobniku Cloud Storage.
  3. Testowanie agenta w Cloud Shell i w danych wyjściowych agenta w internecie

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 wyboru 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 pakietu ADK, kliknij ten link, aby odebrać środki.
  4. Aby skorzystać z tej oferty, postępuj zgodnie z instrukcjamitutaj. Pamiętaj, że ten link jest ważny tylko do 15 lipca 2025 r.
  5. Aktywuj Cloud Shell, klikając ten link. Możesz przełączać się między terminalem Cloud Shell (do uruchamiania poleceń w chmurze) a edytorem (do tworzenia projektów), klikając odpowiedni przycisk w Cloud Shell.
  6. Po połączeniu z Cloud Shell sprawdź, czy jesteś już uwierzytelniony i czy projekt jest ustawiony na Twój identyfikator projektu, używając tego polecenia:
gcloud auth list
  1. Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:
gcloud config list project
  1. Jeśli projekt nie jest ustawiony, użyj tego polecenia, aby go ustawić:
gcloud config set project <YOUR_PROJECT_ID>
  1. Upewnij się, że masz Pythona w wersji 3.9 lub nowszej.

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

3. Prototyp

Otwórz Google AI Studio. Zacznij wpisywać prompta. Oto mój 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.

Dostosuj i skonfiguruj parametry po prawej stronie, aby uzyskać optymalną odpowiedź.

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

Wybraliśmy Gemini 2.5 Pro. Jest to model Thinking, co oznacza, że otrzymujemy jeszcze więcej tokenów wyjściowych, w tym przypadku do 65 tys., na potrzeby długich analiz i szczegółowych dokumentów. Pole myślenia Gemini pojawia się po włączeniu Gemini 2.5 Pro, który ma natywne możliwości wnioskowania i może przyjmować długie żądania kontekstowe.

Fragment odpowiedzi znajdziesz poniżej:

4e4361663df80964.png

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

Teraz spróbuj zobaczyć, jak pomysł nabiera kształtu dzięki innemu promptowi.

  1. Skopiuj ten prompt i wklej go w edytorze promptów:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
  1. Załącz zdjęcie obecnej kuchni (możesz też użyć mojego przykładowego zdjęcia kuchni).
  2. Zmień model na „Gemini 2.0 Flash Preview Image Generation”, aby mieć dostęp do generowania obrazów.

Otrzymuję te dane wyjściowe:

fb33e7b1f6560a0c.png

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

Od rozumienia filmów po natywne generowanie obrazów i weryfikowanie prawdziwych informacji za pomocą wyszukiwarki Google – są rzeczy, które można stworzyć tylko dzięki Gemini.

W AI Studio możesz wziąć ten prototyp, pobrać klucz interfejsu API i skalować go do pełnej aplikacji opartej na agentach, korzystając z możliwości pakietu ADK Vertex AI.

4. Konfiguracja pakietu ADK

Teraz przejdźmy do terminala Cloud Shell, który został aktywowany w sekcji „Zanim zaczniesz”:

  1. 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
  1. Instalowanie ADK
pip install google-adk

5. Struktura projektu

  1. W terminalu Cloud Shell utwórz główny katalog aplikacji opartych na agentach w wybranej lokalizacji projektu:
mkdir agentic-apps
  1. W katalogu głównym utwórz folder dla bieżącego projektu:
mkdir renovation-agent
  1. Otwórz edytor Cloud Shell i utwórz tę strukturę projektu, tworząc pliki (na początku puste):
renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Kod źródłowy

  1. Otwórz plik „init.py” i zaktualizuj go, dodając te treści:
from . import agent
  1. Otwórz plik agent.py i zastąp jego zawartość treścią z tej ścieżki:

W pliku agent.py importujemy niezbędne zależności, pobieramy parametry konfiguracji z pliku .env i definiujemy root_agent, który generuje dokument z propozycją i zapisuje go w zasobniku Cloud Storage. W kroku Cloud Storage używamy narzędzia o nazwie store_pdf.

UWAGA: obecnie plik PDF jest NIEFORMATOWANY! Na podstawie żądania scalenia od dewelopera z społeczności w tym miejscu umieszczono ten fragment [nie został przetestowany]. Możesz go dostosować w metodzie store_pdf:

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"
  1. Sprawdź, czy masz zasobnik Cloud Storage

Służy do przechowywania dokumentu z propozycją wygenerowanego przez agenta. Utwórz go i przyznaj dostęp, aby system agentów utworzony za pomocą Vertex AI mógł z niego korzystać. Aby to zrobić:

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

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

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

Kliknij kolejno Uprawnienia –> Wyświetl podmioty zabezpieczeń –> Przyznaj dostęp. Wybierz podmioty zabezpieczeń „allUsers” i rolę „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.
  1. Tworzenie listy zależności

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

Wyjaśnienie kodu źródłowego systemu pojedynczego agenta

Plik agent.py definiuje strukturę i działanie naszego systemu wieloagentowego do remontu kuchni za pomocą zestawu Agent Development Kit (ADK). Przyjrzyjmy się kluczowym komponentom:

Definicja agenta

Agent główny (Orchestrator): proposal_agent

Agent główny pełni rolę aranżera tego systemu z jednym agentem. Otrzymuje początkową prośbę o renowację i określa, które narzędzia należy wywołać na podstawie potrzeb żądania.

Główny agent zbiera następnie odpowiedzi z narzędzi i łączy je, aby przekazać użytkownikowi wyczerpującą 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 (terminala lub interfejsu internetowego).

  1. Żądanie jest odbierane przez root_agent.
  2. Główny agent analizuje żądanie i w razie potrzeby przekierowuje je do narzędzia.
  3. Narzędzie „store_pdf” służy do zapisywania odnowionej treści tekstowej w pliku PDF, a następnie przesyłania go do Google Cloud Storage.
  4. Następnie zwraca odpowiedź do root_agent.
  5. Główny agent łączy odpowiedzi i przekazuje użytkownikowi ostateczny wynik.

LLM (duże modele językowe)

Agenci w dużej mierze polegają na LLM w zakresie generowania tekstu, odpowiadania na pytania i wykonywania zadań wymagających rozumowania. LLM to „mózgi” agentów, które umożliwiają im rozumienie żądań użytkowników i odpowiadanie na nie. W tej aplikacji używamy Gemini 2.5.

Google Cloud Storage

Służy do przechowywania wygenerowanych dokumentów z propozycją remontu. 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 OrderingAgent, musisz skonfigurować bazę danych AlloyDB do przechowywania informacji o zamówieniach.

plik.env

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

8. Konfiguracja modelu

Zdolność agenta do rozumienia próśb użytkowników i generowania odpowiedzi jest oparta na dużym modelu językowym (LLM). Agent musi wykonywać bezpieczne wywołania tej zewnętrznej usługi LLM, co wymaga danych uwierzytelniających. Bez prawidłowego uwierzytelnienia usługa LLM odrzuci żądania agenta, a agent nie będzie mógł działać.

  1. Uzyskaj klucz interfejsu API z 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

  1. Skonfiguruj wartości parametrów w 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 symbole zastępcze swoimi wartościami.

10. Uruchamianie agenta

  1. W terminalu przejdź do katalogu nadrzędnego projektu agenta:
cd agentic-apps/renovation-agent
  1. Instalowanie wszystkich zależności
pip install -r requirements.txt
  1. Aby uruchomić agenta, możesz wykonać to polecenie w terminalu Cloud Shell:
adk run .
  1. Aby uruchomić go w interfejsie internetowym udostępnionym przez ADK, wykonaj to polecenie:

Uwaga: to polecenie musisz uruchomić POZA folderem projektu agenta. Wyjdź z niego i dopiero wtedy uruchom polecenie:

adk web
  1. 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:

2703603a907329ae.png

ae56b38cc6da9afe.png

…

91452a4de933a75b.png

Możesz sprawdzić, czy dokument z propozycją remontu został utworzony w zasobniku Cloud Storage.

12. Wdrożenie w Cloud Run

  1. W folderze głównym projektu utwórz plik o nazwie Dockerfile:
cd agentic-apps/renovation-agent
  1. Skopiuj zawartość z repozytorium GitHub.
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

do tego pliku Dockerfile.

  1. Wdróż w Cloud Run za pomocą tego polecenia:
adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

To wszystko. Po wdrożeniu w terminalu powinien pojawić się punkt końcowy, który będzie gotowy do użycia.

13. Czyszczenie danych

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

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

14. Gratulacje

Gratulacje! Udało Ci się utworzyć aplikację z wieloma agentami i z niej korzystać za pomocą ADK. System wielu agentów ma na celu usprawnienie procesu remontu kuchni poprzez automatyzację zadań takich jak generowanie propozycji, sprawdzanie zezwoleń i śledzenie stanu zamówienia. Każdy agent ma określoną rolę, a agent główny koordynuje ich działania, aby zapewnić kompleksowe rozwiązanie. System wykorzystuje LLM, usługi Google Cloud i potencjalnie zewnętrzne interfejsy API do realizacji swoich funkcji. Tutaj znajdziesz link do dokumentacji produktu.