Kompilowanie i wdrażanie agenta ADK w Cloud Run

1. Wprowadzenie

To laboratorium dotyczy wdrażania i wdrażania usługi agenta klienta. Do utworzenia agenta AI, który korzysta z narzędzi, użyjesz pakietu Agent Development Kit (ADK).

W tym laboratorium utworzymy agenta zoo, który będzie używać Wikipedii do odpowiadania na pytania dotyczące zwierząt.

Od lewej do prawej: lew, 2 pingwiny, osoba w kapeluszu safari, słoń i niedźwiedź stoją tyłem do widza i patrzą na dużą czerwoną i białą rakietę startującą w niebieskie niebo z białymi chmurami. W oddali widać też 2 mniejsze rakiety. Scena rozgrywa się w wybiegu w zoo z drewnianym płotem i skalistymi klifami.

Na koniec wdrożymy agenta przewodnika w usłudze Google Cloud Run, a nie tylko uruchomimy go lokalnie.

Wymagania wstępne

  • Znajomość Pythona i interfejsów wiersza poleceń.
  • projekt Google Cloud z włączonymi płatnościami;
  • Zainstalowane narzędzia CLI: gcloud, gsutil, uv.

Czego się nauczysz

  • Jak skonfigurować projekt w Pythonie na potrzeby wdrożenia ADK.
  • Jak wdrożyć agenta korzystającego z narzędzi za pomocą pakietu google-adk.
  • Jak wdrożyć aplikację w Pythonie jako bezserwerowy kontener w Cloud Run.
  • Jak skonfigurować bezpieczne uwierzytelnianie między usługami za pomocą ról uprawnień.
  • Jak usunąć zasoby Cloud, aby uniknąć przyszłych kosztów.

Czego potrzebujesz

  • Konto Google Cloud i projekt Google Cloud
  • przeglądarka, np. Chrome;

2. Dlaczego warto wdrożyć aplikację w Cloud Run?

Cloud Run to doskonały wybór do hostowania agentów ADK, ponieważ jest to platforma bezserwerowa, co oznacza, że możesz skupić się na kodzie, a nie na zarządzaniu bazową infrastrukturą. Zajmiemy się za Ciebie pracą operacyjną.

Można to porównać do sklepu tymczasowego: jest otwarty i korzysta z zasobów tylko wtedy, gdy pojawiają się klienci (żądania). Gdy nie ma klientów, sklep jest całkowicie zamykany i nie płacisz za pusty sklep.

Najważniejsze funkcje

Uruchamianie kontenerów w dowolnym miejscu:

  • Przekazujesz kontener (obraz Dockera) z aplikacją.
  • Cloud Run uruchamia go w infrastrukturze Google.
  • Nie musisz się martwić o stosowanie poprawek do systemu operacyjnego, konfigurowanie maszyn wirtualnych ani skalowanie.

Automatyczne skalowanie:

  • Jeśli z aplikacji nie korzysta żadna osoba → uruchomionych jest 0 instancji (skalowanie w dół do zera instancji, co jest opłacalne).
  • Jeśli otrzyma 1000 żądań, utworzy tyle kopii, ile będzie potrzebne.

Bezstanowość w standardzie:

  • Każde żądanie może trafić do innej instancji.
  • Jeśli musisz przechowywać stan, użyj usługi zewnętrznej, takiej jak Cloud SQL, Firestore lub Memorystore.

Obsługa dowolnego języka lub platformy:

  • Cloud Run nie ma znaczenia, czy jest to Python, Go, Node.js, Java czy .Net, o ile działa w kontenerze Linux.

Płać za to, z czego korzystasz:

3. Konfigurowanie projektu

Konto Google

Jeśli nie masz jeszcze osobistego konta Google, musisz utworzyć konto Google.

Używaj konta osobistego zamiast konta służbowego lub szkolnego.

Logowanie się w konsoli Google Cloud

Zaloguj się w konsoli Google Cloud, korzystając z osobistego konta Google.

Włącz płatności

Konfigurowanie osobistego konta rozliczeniowego

Jeśli skonfigurujesz płatności za pomocą środków w Google Cloud, możesz pominąć ten krok.

Aby skonfigurować osobiste konto rozliczeniowe, włącz płatności w konsoli Google Cloud.

Uwagi:

Tworzenie projektu (opcjonalnie)

Jeśli nie masz bieżącego projektu, którego chcesz użyć w tym laboratorium, utwórz nowy projekt.

4. Otwórz edytor Cloud Shell

  1. Kliknij ten link, aby przejść bezpośrednio do edytora Cloud Shell
  2. Jeśli w dowolnym momencie pojawi się prośba o autoryzację, kliknij Autoryzuj, aby kontynuować. Kliknij, aby uwierzytelnić się w Cloud Shell
  3. Jeśli terminal nie pojawia się u dołu ekranu, otwórz go:
    • Kliknij Wyświetl.
    • Kliknij TerminalOtwieranie nowego terminala w edytorze Cloud Shell.

5. Ustawianie projektu

  1. W terminalu ustaw projekt za pomocą tego polecenia:
    gcloud config set project [PROJECT_ID]
    Przykład: gcloud config set project lab-project-id-example Ustawianie identyfikatora projektu w terminalu edytora Cloud Shell
  2. Powinien wyświetlić się ten komunikat:
    Updated property [core/project].

6. Włącz interfejsy API

Aby korzystać z usług Cloud Run, Artifact Registry, Cloud Build, Gemini Enterprise Agent Platform i Compute Engine, musisz włączyć odpowiednie interfejsy API w projekcie w chmurze Google Cloud.

  • W terminalu włącz interfejsy API:
    gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com
    Po zakończeniu działania powinny pojawić się dane wyjściowe podobne do tych:
    Operation "operations/acat.p2-[GUID]" finished successfully.

Przedstawiamy interfejsy API

  • Cloud Run Admin API (run.googleapis.com) umożliwia uruchamianie usług frontendowych i backendowych, zadań wsadowych lub witryn w pełni zarządzanym środowisku. Zajmuje się infrastrukturą do wdrażania i skalowania skonteneryzowanych aplikacji.
  • Artifact Registry API (artifactregistry.googleapis.com) to bezpieczne, prywatne repozytorium do przechowywania obrazów kontenerów. Jest to rozwinięcie Container Registry, które jest w pełni zintegrowane z Cloud Run i Cloud Build.
  • Cloud Build API (cloudbuild.googleapis.com) to bezserwerowa platforma CI/CD, która wykonuje kompilacje w infrastrukturze w chmurze Google Cloud. Służy do kompilowania obrazu kontenera w chmurze na podstawie pliku Dockerfile.
  • Interfejs Gemini Enterprise Agent Platform API (aiplatform.googleapis.com) umożliwia wdrożonej aplikacji komunikację z modelami Gemini w celu wykonywania podstawowych zadań związanych z AI. Udostępnia ujednolicony interfejs API dla wszystkich usług AI od Google Cloud.
  • Compute Engine API (compute.googleapis.com) udostępnia bezpieczne i konfigurowalne maszyny wirtualne działające w infrastrukturze Google. Cloud Run jest usługą zarządzaną, ale interfejs Compute Engine API jest często wymagany jako podstawowa zależność w przypadku różnych zasobów sieciowych i obliczeniowych.

7. Przygotowywanie środowiska programistycznego

Tworzenie katalogu

  1. W terminalu utwórz katalog projektu i niezbędne podkatalogi:
    cd && mkdir zoo_guide_agent && cd zoo_guide_agent
  2. W terminalu uruchom to polecenie, aby otworzyć katalog zoo_guide_agent w eksploratorze edytora Cloud Shell:
    cloudshell open-workspace ~/zoo_guide_agent
  3. Panel eksploratora po lewej stronie zostanie odświeżony. Powinien pojawić się utworzony katalog.
    Zrzut ekranu nowego katalogu w panelu bocznym eksploratora
    CRITICAL otwarcie nowego obszaru roboczego powoduje zresetowanie edytora Cloud Shell i ponowne uruchomienie sesji terminala. Musisz ponownie otworzyć terminal, sprawdzić, czy jesteś w odpowiednim katalogu ~/zoo_guide_agent (w razie potrzeby uruchom polecenia pwd i cd ~/zoo_guide_agent) oraz czy projekt gcloud jest nadal wybrany (w razie potrzeby uruchom polecenie gcloud config set project [PROJECT_ID]).

Wymagania dotyczące instalacji

  1. Aby utworzyć plik requirements.txt, uruchom to polecenie w terminalu.
    cloudshell edit requirements.txt
  2. Dodaj do nowo utworzonego pliku requirements.txt te wiersze:
    google-adk==2.4.0
langchain-community==0.3.27
wikipedia==1.4.0
  3. W terminalu utwórz i aktywuj środowisko wirtualne za pomocą uv. Dzięki temu zależności projektu nie będą powodować konfliktów z systemowym Pythonem.
    uv venv
source .venv/bin/activate
  4. Zainstaluj wymagane pakiety w środowisku wirtualnym w terminalu.
    uv pip install -r requirements.txt

Tworzenie konta usługi i konfigurowanie uprawnień

Zanim utworzysz agenta, musisz utworzyć konto usługi i skonfigurować niezbędne uprawnienia. Dzięki temu Twój agent będzie mógł wywoływać modele Gemini Enterprise Agent Platform, a Cloud Build będzie mógł pomyślnie wdrożyć Twoją aplikację.

  1. W terminalu utwórz dedykowane konto usługi dla usługi Cloud Run:
    SA_NAME=lab-service-account
PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for Zoo Agent"
  2. Przypisz do konta usługi rolę użytkownika Gemini Enterprise Agent Platform, aby agent mógł wywoływać Gemini:
    gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
  3. Skonfiguruj uprawnienia Cloud Build. Nowoczesne projekty Google Cloud ograniczają uprawnienia domyślnego konta usługi, dlatego musisz przyznać domyślnemu kontu usługi Compute Engine role wymagane do tworzenia i wdrażania kontenera. Uruchom w terminalu te polecenia:
    PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# Grant Artifact Registry Writer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/artifactregistry.writer"

# Grant Storage Object Viewer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# Grant Logs Writer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/logging.logWriter"

Konfigurowanie zmiennych środowiskowych

Teraz utworzysz .env zawierający zmienne środowiskowe używane przez agenta i skrypt wdrożenia.

  1. Zmienne zostały już zdefiniowane w sesji terminala w poprzednim kroku, więc możesz bezpośrednio utworzyć plik .env:
    cat <<EOF > .env
PROJECT_ID=$PROJECT_ID
PROJECT_NUMBER=$PROJECT_NUMBER
SA_NAME=$SA_NAME
SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
MODEL="gemini-3.5-flash"
EOF

8. Tworzenie przepływu pracy agenta

Utwórz plik __init__.py

  1. Utwórz plik init.py, uruchamiając w terminalu to polecenie:
    cloudshell edit __init__.py
    Ten plik informuje Pythona, że katalog zoo_guide_agent jest pakietem.
  2. Dodaj do nowego pliku __init__.py ten kod:
    from . import agent

Tworzenie pliku agent.py

  1. Utwórz główny plik agent.py, wklejając to polecenie do terminala.
    cloudshell edit agent.py
  2. Importy i konfiguracja początkowa: dodaj ten kod do pustego pliku agent.py:
    import os
import logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

load_dotenv()

model_name = os.getenv("MODEL")
    Pierwszy blok pliku agent.py zawiera wszystkie niezbędne biblioteki z ADK i Google Cloud. Konfiguruje też rejestrowanie i wczytuje zmienne środowiskowe z pliku .env, co jest kluczowe w przypadku dostępu do modelu i adresu URL serwera.
  3. Określ narzędzia: agent jest tak dobry, jak narzędzia, z których może korzystać. Aby zdefiniować narzędzia, dodaj ten kod na końcu pliku agent.py:
    # Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)
    Wyjaśnienie działania narzędzi
    • add_prompt_to_state 📝: to narzędzie zapamiętuje pytania zadawane przez osoby odwiedzające zoo. Gdy odwiedzający zapyta „Gdzie są lwy?”, to narzędzie zapisze to konkretne pytanie w pamięci agenta, aby inni agenci w procesie mogli sprawdzić, czego szukać.
      Jak: jest to funkcja Pythona, która zapisuje prompt użytkownika w udostępnionym słowniku tool_context.state. Kontekst narzędzia to pamięć krótkotrwała agenta w ramach jednej rozmowy. Dane zapisane w stanie przez jednego agenta mogą być odczytywane przez kolejnego agenta w procesie.
    • LangchainTool 🌍: dzięki temu agent przewodnik będzie miał ogólną wiedzę o świecie. Gdy odwiedzający zada pytanie, którego nie ma w bazie danych zoo, np. „Co jedzą lwy na wolności?”, to narzędzie umożliwia pracownikowi wyszukanie odpowiedzi w Wikipedii. (Więcej informacji o konfigurowaniu i wywoływaniu narzędzia Wikipedia znajdziesz w przewodniku Korzystanie z narzędzia Wikipedia).
      Działanie: działa jako adapter, umożliwiając naszemu agentowi korzystanie z gotowego narzędzia WikipediaQueryRun z biblioteki LangChain.
      Przyjaźnie wyglądający robot trzyma notatnik z rysunkami zwierząt i dymek z myślą o lwie. Rozmawia z mężczyzną i chłopcem z plecakiem. W tle widać żyrafy i inne elementy zoo, a wejście otaczają palmy.
  4. Zdefiniuj agentów specjalistów: dodaj ten kod na dole sekcji agent.py, aby zdefiniować agentów comprehensive_researcher i response_formatter:
    # 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)
    • comprehensive_researcher Agent jest „mózgiem” naszej operacji. Pobiera prompt użytkownika z udostępnionego State, sprawdza, czy jest to narzędzie Wikipedia, i decyduje, których z nich użyć, aby znaleźć odpowiedź.
    • Rola agenta response_formatter to prezentacja. Pobiera surowe dane zebrane przez agenta badawczego (przekazywane za pomocą stanu) i wykorzystuje umiejętności językowe LLM, aby przekształcić je w przyjazną odpowiedź w formie rozmowy.
      Robot ze świecącymi niebieskimi oczami siedzi przed dużym zakrzywionym monitorem, na którym po lewej stronie wyświetla się MCP ZOO SERVER, a po prawej stronie strona ZOO w Wikipedii. Ikony zwierząt są widoczne w interfejsie serwera. Na biurku znajduje się kilka świecących na niebiesko touchpadów. W tle widać panoramę miasta za dużymi oknami.
  5. Zdefiniuj agenta przepływu pracy: dodaj ten blok kodu na końcu pliku agent.py, aby zdefiniować agenta sekwencyjnego tour_guide_workflow:
    tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)
    Agent przepływu pracy działa jako menedżer „back-office” wycieczki po zoo. Przyjmuje pytanie badawcze i pilnuje, aby 2 zdefiniowane powyżej agenty wykonywały swoje zadania w odpowiedniej kolejności: najpierw badania, a potem formatowanie. Dzięki temu proces odpowiadania na pytania odwiedzających jest przewidywalny i niezawodny.
    Jak to działa: to SequentialAgent, czyli specjalny rodzaj agenta, który nie myśli samodzielnie. Jego jedynym zadaniem jest uruchamianie listy sub_agents (badacza i formatera) w ustalonej kolejności oraz automatyczne przekazywanie pamięci współdzielonej z jednego do drugiego.
  6. Złóż główny przepływ pracy: dodaj ten ostatni blok kodu na dole pliku agent.py, aby zdefiniować root_agent:
    root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)
     Platforma ADK używa root_agent jako punktu początkowego dla wszystkich nowych rozmów. Jego głównym zadaniem jest koordynowanie całego procesu. Działa jako kontroler początkowy, który zarządza pierwszą turą rozmowy.
    Ilustracja przedstawia 3 roboty: po lewej stronie robot powitalny pisze na notatniku, a nad nim znajduje się dymek z myślą w postaci lwa; pośrodku robot badawczy siedzi przy biurku z komputerem, na którym wyświetlają się dane, a w jego stronę skierowana jest strzałka zapytania; po prawej stronie robot prezentujący uśmiecha się, trzymając wykres z etykietą „Przeanalizowane dane”, a w jego stronę skierowana jest strzałka od robota badawczego. W tle widać żyrafy i słonie, a scenę otaczają palmy.

pełny plik agent.py,

Plik agent.py został utworzony. Dzięki temu możesz zobaczyć, jak każdy komponent – narzędzia, agenci wykonawczy i agenci zarządzający – odgrywa określoną rolę w tworzeniu końcowego, inteligentnego systemu.

Pełny plik powinien wyglądać tak:

import os
import logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

load_dotenv()

model_name = os.getenv("MODEL")

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
        you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

Następny krok to wdrożenie.

9. Przygotowywanie aplikacji do wdrożenia

Sprawdź ostateczną strukturę

Przed wdrożeniem sprawdź, czy katalog projektu zawiera prawidłowe pliki.

  • Sprawdź, czy folder zoo_guide_agent wygląda tak:
    zoo_guide_agent/
├── .env
├── __init__.py
├── agent.py
└── requirements.txt

Konfigurowanie pliku .gcloudignore i wczytywanie zmiennych środowiskowych

  1. Utwórz plik .gcloudignore w katalogu zoo_guide_agent, aby zapobiec przesyłaniu środowiska wirtualnego (.venv/) i innych niepotrzebnych plików do Google Cloud:
    cloudshell edit .gcloudignore
  2. Dodaj do pliku .gcloudignore te wiersze:
    .gcloudignore
.git
.gitignore
.venv/
venv/
__pycache__/
.env
  3. Załaduj zmienne środowiskowe do sesji terminala:
    source .env

10. Wdrażanie agenta za pomocą interfejsu wiersza poleceń ADK

Gdy kod lokalny będzie gotowy, a projekt Google Cloud przygotowany, możesz wdrożyć agenta. Użyjesz polecenia adk deploy cloud_run, czyli wygodnego narzędzia, które automatyzuje cały proces wdrażania. To jedno polecenie pakuje kod, tworzy obraz kontenera, przesyła go do Artifact Registry i uruchamia usługę w Cloud Run, dzięki czemu jest ona dostępna w internecie.

  1. Aby wdrożyć agenta, uruchom w terminalu to polecenie:
    # Run the deployment command
uvx --from google-adk==2.4.0 \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --allow-unauthenticated \
  --set-env-vars=MODEL=$MODEL,GOOGLE_GENAI_USE_ENTERPRISE=true,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT
    Polecenie uvx umożliwia uruchamianie narzędzi wiersza poleceń opublikowanych jako pakiety Pythona bez konieczności globalnej instalacji tych narzędzi.
  2. Jeśli pojawi się ten komunikat:
    Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?
    Jeśli tak, wpisz Y i naciśnij ENTER.
  3. Po pomyślnym wykonaniu polecenia wyświetli się adres URL wdrożonej usługi Cloud Run. (Będzie wyglądać mniej więcej tak: https://zoo-tour-guide-123456789.europe-west1.run.app).
  4. Skopiuj adres URL wdrożonej usługi Cloud Run na potrzeby następnego zadania.

11. Testowanie wdrożonego agenta

Gdy agent będzie już aktywny w Cloud Run, przeprowadź test, aby potwierdzić, że wdrożenie się powiodło i agent działa zgodnie z oczekiwaniami. Aby uzyskać dostęp do interfejsu internetowego ADK i wchodzić w interakcję z agentem, użyjesz publicznego adresu URL usługi (np. https://zoo-tour-guide-123456789.europe-west1.run.app/).

  1. Otwórz publiczny adres URL usługi Cloud Run w przeglądarce. Ponieważ używasz --with_ui flag, powinien pojawić się interfejs programisty ADK.
  2. W prawym górnym rogu włącz Token Streaming.
     Możesz teraz wchodzić w interakcje z agentem Zoo.
  3. Wpisz hello i naciśnij Enter, aby rozpocząć nową rozmowę.
  4. Sprawdź wynik. Agent powinien szybko odpowiedzieć powitaniem, które będzie wyglądać mniej więcej tak:
    "Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
  5. Zadaj agentowi pytania takie jak:
    Where can I find the polar bears in the zoo and what is their diet?
    Zrzut ekranu agenta ADK wykonującego sekwencję działań: add_prompt_to_state, transfer_to_agent, wikipedia i get_animals_by_species. Pierwsza odpowiedź brzmi: „Nie mogę Ci powiedzieć, gdzie w tym konkretnym zoo znajdują się niedźwiedzie polarne, ale mogę Ci opowiedzieć o ich diecie”. Druga odpowiedź brzmi: „Niedźwiedzie polarne znajdują się na wystawie arktycznej na szlaku polarnym. Nie mogę uzyskać informacji o ich diecie za pomocą dostępnych narzędzi”. Trzecia, najbardziej wyczerpująca odpowiedź brzmi: „Chętnie opowiem Ci o naszych niedźwiedziach polarnych. Nasze niedźwiedzie polarne znajdziesz na wystawie Arktyka na szlaku polarnym. Mamy tu 3 niedźwiedzie polarne: Płatka Śniegu, który ma 7 lat. Blizzard, który ma 5 lat. Iceberg, który ma 9 lat. Niedźwiedzie polarne są głównie mięsożerne. Specjalizują się w polowaniu na foki, zwłaszcza foki obrączkowane. Zjadają też morsy, bieługi i niektóre zwierzęta lądowe”.

Wyjaśnienie przepływu agenta

System działa jako inteligentny zespół wieloagentowy. Proces ten jest zarządzany przez jasną sekwencję, aby zapewnić płynny i wydajny przepływ informacji od pytania użytkownika do ostatecznej, szczegółowej odpowiedzi.

1. Osoba witająca gości w zoo (stanowisko powitalne)

Cały proces zaczyna się od agenta witającego.

  • Jego zadanie: rozpoczęcie rozmowy. Jego instrukcja to powitanie użytkownika i zapytanie, o jakim zwierzęciu chce się dowiedzieć więcej.
  • Narzędzie: gdy użytkownik odpowie, Greeter użyje narzędzia add_prompt_to_state, aby zarejestrować jego dokładne słowa (np. „opowiedz mi o lwach”) i zapisać je w pamięci systemu.
  • Przekazanie: po zapisaniu prompta natychmiast przekazuje on kontrolę do swojego podagenta, czyli tour_guide_workflow.

2. Wszechstronny badacz (superbadacz)

Jest to pierwszy krok w głównym procesie i „mózg” całej operacji. Zamiast dużego zespołu masz teraz jednego, wysoce wykwalifikowanego agenta, który ma dostęp do wszystkich dostępnych informacji.

  • Zadanie: analizowanie pytania użytkownika i tworzenie inteligentnego planu. Wykorzystuje funkcję używania narzędzi modelu językowego, aby zdecydować, czy potrzebuje:
    • ogólna wiedza z internetu (za pomocą interfejsu Wikipedia API);
    • W przypadku złożonych pytań możesz użyć obu tych opcji.

3. Formatowanie odpowiedzi (prezenter)

Gdy wszechstronny badacz zbierze wszystkie fakty, ten agent jest uruchamiany jako ostatni.

  • Jego zadanie: być przyjaznym głosem przewodnika po zoo. Pobiera nieprzetworzone dane (które mogą pochodzić z jednego lub obu źródeł) i je przetwarza.
  • Działanie: syntetyzuje wszystkie informacje w jedną, spójną i angażującą odpowiedź. Zgodnie z instrukcjami najpierw podaje konkretne informacje o zoo, a potem dodaje ciekawe ogólne fakty.
  • Wynik końcowy: tekst wygenerowany przez tego agenta to pełna, szczegółowa odpowiedź, którą użytkownik widzi w oknie czatu.

Jeśli chcesz dowiedzieć się więcej o tworzeniu agentów, zapoznaj się z tymi materiałami:

  1. Dokumentacja pakietu ADK
  2. Tworzenie niestandardowych narzędzi dla agentów ADK

12. Zwalnianie miejsca w środowisku

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym samouczku, możesz usunąć projekt zawierający te zasoby lub zachować projekt i usunąć poszczególne zasoby.

Usuwanie usług, obrazów i zasobów Cloud Run

Jeśli chcesz zachować projekt w chmurze Google Cloud, ale usunąć konkretne zasoby utworzone w tym laboratorium, musisz usunąć działającą usługę, rejestr obrazów kontenerów, tymczasowy zasobnik pamięci źródłowej i konto usługi.

  • Uruchom w terminalu te polecenia:
    gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet
gsutil rm -r gs://run-sources-${PROJECT_ID}-europe-west1
gcloud iam service-accounts delete lab-service-account@${PROJECT_ID}.iam.gserviceaccount.com --quiet

Usuwanie projektu (opcjonalnie)

Jeśli na potrzeby tego ćwiczenia został przez Ciebie utworzony nowy projekt, którego już nie potrzebujesz, najłatwiej będzie go usunąć. Dzięki temu wszystkie zasoby (w tym konto usługi i ukryte artefakty kompilacji) zostaną całkowicie usunięte.

  • W terminalu uruchom to polecenie (zastąp [YOUR_PROJECT_ID] identyfikatorem swojego projektu):
    gcloud projects delete $PROJECT_ID

13. Gratulacje

Udało Ci się utworzyć i wdrożyć w Google Cloud aplikację AI z wieloma agentami.

Podsumowanie

W tym module utworzyliśmy działającą, publicznie dostępną usługę AI z pustego katalogu. Oto, co udało Ci się stworzyć:

  • Utworzono specjalistyczny zespół: zamiast jednej ogólnej AI utworzono „Badacza”, który wyszukuje fakty, oraz „Formatującego”, który dopracowuje odpowiedź.
  • Udostępniasz im narzędzia: łączysz agentów ze światem zewnętrznym za pomocą interfejsu Wikipedia API.
  • Wdrożono: lokalny kod Pythona został wdrożony jako kontener bezserwerowy w Cloud Run i zabezpieczony za pomocą dedykowanego konta usługi.

Omówione zagadnienia

  • Jak skonstruować projekt w Pythonie do wdrożenia za pomocą pakietu ADK.
  • Jak wdrożyć przepływ pracy z wieloma agentami za pomocą [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/).
  • Jak zintegrować zewnętrzne narzędzia, takie jak interfejs API Wikipedii.
  • Jak wdrożyć agenta w Cloud Run za pomocą polecenia adk deploy.

14. Ankieta

Dane wyjściowe:

Jak zamierzasz korzystać z tego samouczka?

Tylko przeczytaj Przeczytaj i wykonaj ćwiczenia