Kompilowanie i wdrażanie agenta ADK w Cloud Run

1. Wprowadzenie

Ten moduł 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 module utworzymy agenta zoo, który będzie odpowiadał na pytania o zwierzęta na podstawie informacji z Wikipedii.

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ą rakietę z białymi elementami, która startuje w błękitne niebo z białymi chmurami. W oddali widać też 2 mniejsze rakiety. Scena przedstawia wybieg 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

  • Projekt Google Cloud z włączonymi płatnościami.

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 w chmurze, 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 świetny 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 infrastrukturą bazową. Zajmujemy się za Ciebie pracą operacyjną.

Można to porównać do sklepu typu pop-up: 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:

  • Dostarczasz kontener (obraz Dockera) z aplikacją.
  • Cloud Run uruchamia go w infrastrukturze Google.
  • Nie musisz się martwić instalowaniem poprawek systemu operacyjnego, konfigurowaniem maszyn wirtualnych ani skalowaniem.

Automatyczne skalowanie:

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

Bezstanowe domyślnie:

  • Każde żądanie może być kierowane do innego wystąpienia.
  • 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:

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

Płać za to, z czego korzystasz:

3. Konfigurowanie projektu

Konto Google

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

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

Logowanie w konsoli Google Cloud

Zaloguj się w konsoli Google Cloud za pomocą 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 Cloud Console.

Uwagi:

Tworzenie projektu (opcjonalnie)

Jeśli nie masz bieżącego projektu, którego chcesz użyć w tym ćwiczeniu, 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 pojawi się u dołu ekranu, otwórz go:
    • Kliknij Wyświetl.
    • Kliknij TerminalOtwieranie nowego terminala w edytorze Cloud Shell.

5. Włącz interfejsy API

Aby korzystać z usług Cloud Run, Artifact Registry, Cloud Build, Vertex AI i Compute Engine, musisz włączyć odpowiednie interfejsy API w projekcie 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 frontendu i backendu, zadań wsadowych lub witryn w pełni zarządzanym środowisku. Zajmuje się infrastrukturą do wdrażania i skalowania aplikacji w kontenerach.
  • Artifact Registry API (artifactregistry.googleapis.com) udostępnia bezpieczne, prywatne repozytorium do przechowywania obrazów kontenerów. Jest to rozwinięcie Container Registry, które bezproblemowo integruje się z Cloud Run i Cloud Build.
  • Cloud Build API (cloudbuild.googleapis.com) to bezserwerowa platforma CI/CD, która wykonuje kompilacje w infrastrukturze Google Cloud. Służy do kompilowania obrazu kontenera w chmurze na podstawie pliku Dockerfile.
  • Vertex AI API (aiplatform.googleapis.com) umożliwia wdrożonej aplikacji komunikację z modelami Gemini w celu wykonywania podstawowych zadań związanych z AI. Zapewnia on ujednolicony interfejs API dla wszystkich usług AI w Google Cloud.
  • Interfejs 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.

6. 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 odświeży się. Powinien być widoczny utworzony katalog.
    Zrzut ekranu przedstawiający nowy katalog w panelu bocznym eksploratora

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

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==1.14.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

Konfigurowanie zmiennych środowiskowych

  • Aby utworzyć plik .env, użyj tego polecenia w terminalu.
    # 1. Set the variables in your terminal first
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
SA_NAME=lab2-cr-service

# 2. Create the .env file using those variables
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-2.5-flash"
EOF

7. Tworzenie przepływu pracy agenta

Tworzenie pliku __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
import google.cloud.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 ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")
    Ten 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. Zdefiniuj narzędzia: agent jest tak dobry, jak narzędzia, których może używać. 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
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)
    Wyjaśnienie działania narzędzi
    • add_prompt_to_state 📝: to narzędzie zapamiętuje pytania zadawane przez osoby odwiedzające zoo. Gdy gość zapyta „Gdzie są lwy?”, to narzędzie zapisze to konkretne pytanie w pamięci agenta, aby inni agenci w przepływie pracy wiedzieli, czego szukać.
      Jak: jest to funkcja Pythona, która zapisuje prompt użytkownika w słowniku tool_context.state. Kontekst narzędzia reprezentuje pamięć krótkotrwałą agenta w ramach jednej rozmowy. Dane zapisane w stanie przez jednego agenta mogą być odczytane przez kolejnego agenta w przepływie pracy.
    • 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 znalezienie odpowiedzi w Wikipedii.
      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. Określ agentów specjalistów: dodaj ten kod na końcu sekcji agent.py, aby określić 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 }
    """
)
    • Agent comprehensive_researcher to „mózg” 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ź.
    • response_formatter Rola agenta to prezentacja. Pobiera surowe dane zebrane przez agenta Researcher (przekazywane za pomocą stanu) i wykorzystuje umiejętności językowe LLM, aby przekształcić je w przyjazną, konwersacyjną odpowiedź.
      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 – 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 dole sekcji 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 pełni funkcję menedżera „back-office” wycieczki po zoo. Przyjmuje on prośbę o przeprowadzenie badań i pilnuje, aby 2 zdefiniowane powyżej agenty wykonywały swoje zadania w odpowiedniej kolejności: najpierw przeprowadzały badania, a potem formatowały wyniki. Dzięki temu proces odpowiadania na pytania odwiedzających jest przewidywalny i niezawodny.
    Jak: to SequentialAgent, czyli specjalny typ agenta, który nie myśli samodzielnie. Jego jedynym zadaniem jest uruchamianie listy sub_agents (badacza i formatującego) w ustalonej kolejności, automatyczne przekazywanie pamięci współdzielonej z jednego do drugiego.
  6. Złóż główny proces: 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 wyjścia dla wszystkich nowych rozmów. Jego głównym zadaniem jest koordynowanie całego procesu. Pełni rolę początkowego kontrolera, który zarządza pierwszą turą rozmowy.
    Ilustracja przedstawia 3 roboty: po lewej stronie znajduje się robot powitalny, który pisze na notatniku, a nad nim widoczny jest dymek z myślą w postaci lwa; pośrodku siedzi przy biurku robot badawczy z komputerem, na którym wyświetlają się dane, a w jego stronę skierowana jest strzałka z zapytaniem; po prawej stronie uśmiecha się robot prezentujący, który trzyma 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 jest gotowy. Dzięki temu możesz zobaczyć, jak każdy komponent – narzędzia, agenci roboczy i agenci zarządzający – odgrywa określoną rolę w tworzeniu końcowego, inteligentnego systemu.

Kompletny plik powinien wyglądać tak:

import os
import logging
import google.cloud.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 ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

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
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

# 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.

8. Przygotowywanie aplikacji do wdrożenia

Sprawdzanie ostatecznej struktury

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 uprawnień

Gdy masz już gotowy kod lokalny, następnym krokiem jest skonfigurowanie tożsamości, której agent będzie używać w chmurze.

  1. W terminalu załaduj zmienne do sesji powłoki.
    source .env
  2. Utwórz dedykowane konto usługi dla usługi Cloud Run, aby miało ono własne, konkretne uprawnienia. Wklej w terminalu ten tekst:
    gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for lab 2 "
    Tworząc dedykowaną tożsamość dla tej konkretnej aplikacji, masz pewność, że agent ma tylko te uprawnienia, których potrzebuje, zamiast korzystać z konta domyślnego o zbyt szerokim zakresie dostępu.
  3. Przyznaj kontu usługi rolę użytkownika Vertex AI, która daje mu uprawnienia do wywoływania modeli Google.
    # Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

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

Gdy lokalny kod 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, przenosi 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 \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --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. Jeśli pojawi się ten komunikat:
    Allow unauthenticated invocations to [your-service-name] (y/N)?.
    Wpisz y i naciśnij ENTER. Umożliwia to wywoływanie bez uwierzytelniania na potrzeby tego modułu, co ułatwia testowanie. 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, aby użyć go w następnym zadaniu.

10. Testowanie wdrożonego agenta

Gdy agent będzie już działać 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 interakcji 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ż korzystasz z --with_ui flag, powinien być widoczny interfejs dewelopera ADK.
  2. W prawym górnym rogu włącz Token Streaming.
     Możesz teraz korzystać z usług agenta 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 przedstawiający 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 można znaleźć niedźwiedzie polarne, ale mogę Ci opowiedzieć o ich diecie”. W drugiej odpowiedzi czytamy: „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 można zobaczyć na wystawie Arctic Exhibit na szlaku Polar Path. 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łuchy i niektóre zwierzęta lądowe”.

Wyjaśnienie funkcji typu flow agenta

System działa jako inteligentny zespół wielu agentów. Proces ten jest zarządzany przez jasną sekwencję, która zapewnia 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 rozpoczyna 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 zapisywać je w pamięci systemu.
  • Przekazanie: po zapisaniu prompta natychmiast przekazuje on kontrolę do swojego podagenta, czyli tour_guide_workflow.

2. Wyczerpujące wyszukiwanie (Super-Researcher)

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 metod.

3. Formatowanie odpowiedzi (prowadzący)

Gdy kompleksowy badacz zbierze wszystkie fakty, jest to ostatni agent, który zostanie uruchomiony.

  • 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: syntezuje 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.
  • Ostateczny wynik: 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 ADK
  2. Tworzenie niestandardowych narzędzi dla agentów ADK

11. Czyszczenie środowiska

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 i obrazów Cloud Run

Jeśli chcesz zachować projekt Google Cloud, ale usunąć konkretne zasoby utworzone w tym module, musisz usunąć zarówno działającą usługę, jak i obraz kontenera przechowywany w rejestrze.

  • 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

Usuwanie projektu (opcjonalnie)

Jeśli masz projekt utworzony specjalnie na potrzeby tego ćwiczenia i nie zamierzasz już z niego korzystać, najłatwiej będzie go usunąć. Dzięki temu wszystkie zasoby (w tym konto usługi i wszelkie 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

12. Gratulacje

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

Podsumowanie

W tym module udało Ci się przekształcić pusty katalog w działającą, publicznie dostępną usługę AI. Oto, co udało Ci się stworzyć:

  • Utworzono zespół specjalistów: 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 skonfigurować projekt w Pythonie do wdrożenia za pomocą ADK.
  • Jak wdrożyć przepływ pracy z udziałem wielu agentów za pomocą [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/).
  • Jak zintegrować narzędzia zewnętrzne, takie jak interfejs API Wikipedii.
  • Jak wdrożyć agenta w Cloud Run za pomocą polecenia adk deploy.

13. Ankieta

Dane wyjściowe:

Jak zamierzasz wykorzystać ten samouczek?

Tylko przeczytaj Przeczytaj i wykonaj ćwiczenia