1. Wprowadzenie
Z tego ćwiczenia dowiesz się, jak krok po kroku utworzyć pierwszego agenta AI za pomocą pakietu Agent Development Kit (ADK) od Google i Gemini. Utworzysz podstawowego agenta do pisania blogów, który planuje i tworzy treści, prezentując podstawowe koncepcje rozumowania i działania.
Jakie zadania wykonasz
- Skonfiguruj środowisko programistyczne pod kątem ADK.
- Utwórz system wieloagentowy z planistą i pisarzem.
- Uruchom agenta lokalnie i wchodź z nim w interakcje za pomocą interfejsu internetowego ADK.
Czego potrzebujesz
- przeglądarka, np. Chrome;
- Na komputerze musi być zainstalowany Python 3.10 lub nowszy.
- Klucz interfejsu API Google AI Studio.
To ćwiczenie jest przeznaczone dla deweloperów na wszystkich poziomach zaawansowania, w tym dla początkujących.
Szacowany czas trwania: 30 minut.
2. Przewodnik wizualny: czym są agenci AI?
Zanim zaczniemy tworzyć agentów AI, dowiedzmy się, czym są i jakie są ich typowe wzorce.
Co to jest agent AI?
W najprostszym ujęciu agent to oprogramowanie, które nie tylko odpowiada, ale też może podejmować decyzje i działać. Zamiast generować pojedynczą odpowiedź jak tradycyjny chatbot, analizuje Twoje żądanie, określa, jakie kroki należy podjąć, być może wywołuje interfejs API, uruchamia kod, sprawdza wynik, a potem decyduje, co zrobić dalej.
Jedno z najbardziej przejrzystych wyjaśnień pochodzi z publikacji naukowej ReAct: Synergizing Reasoning and Acting in Language Models (ReAct: synergiczne rozumowanie i działanie w modelach językowych). Pomysł przedstawiony w tej publikacji był prosty, ale skuteczny: modele językowe nie powinny generować tekstu za jednym razem. Mogą one w rzeczywistości rozumować krok po kroku, podejmować działania, takie jak wywoływanie narzędzia lub interfejsu API, obserwować wynik, a następnie decydować, co zrobić dalej.
Ten cykl rozumowania, działania, obserwacji i dostosowywania stanowi podstawę działania nowoczesnych agentów AI. Jest on zgodny z definicją Google Cloud: systemy, które potrafią rozumować, planować i zapamiętywać, a także mają wystarczającą autonomię, aby dostosowywać się i podejmować decyzje w imieniu użytkownika.
3 wzorce zachowań agentów
Nie wszystkie modele zachowują się tak samo. Można je podzielić na 3 główne kategorie:
- Agenci sekwencyjni: działają krok po kroku, jak linia montażowa: krok 1, potem krok 2, a następnie krok 3. Są przewidywalne, ale sztywne.
- Reaktywne agenty: podejmują decyzje w danym momencie. Patrzą na obecną sytuację i pytają: „Co mam teraz zrobić?”. Może raz użyjesz narzędzia A, a następnym razem narzędzia B. Są elastyczni, ale nie planują z wyprzedzeniem.
- Agenci deliberatywni lub planujący: robią przerwę, aby nakreślić plan, a potem go realizują. Pomyśl o rezerwacji podróży – nie kupujesz lotu losowo, tylko wybierasz daty, hotele, kolejność działań, a potem realizujesz rezerwację.
Który z nich jest „właściwy”? To zależy od problemu. W przypadku prostych, przewidywalnych procesów sekwencyjne działanie jest w porządku. W przypadku dynamicznych zadań lepiej sprawdza się działanie reaktywne. W przypadku celów wieloetapowych z zależnościami potrzebni są agenci planujący.
W tym module utworzymy agenta rozważnego/planującego, który najpierw tworzy konspekt, a potem pisze post na blogu.
3. Zanim zaczniesz
Tworzenie konta i projektu Google Cloud
Aby w dalszej części tego laboratorium wdrożyć agenta w Google Cloud Run, musisz mieć konto Google Cloud i projekt z włączonym rozliczeniem.
- Zaloguj się w konsoli Google Cloud. Utwórz nowy projekt lub użyj istniejącego. Jeśli nie masz jeszcze konta Google, musisz je utworzyć.
- Następnie musisz włączyć płatności w konsoli Google Cloud, aby korzystać z zasobów Google Cloud. Ukończenie tego modułu powinno kosztować mniej niż kilka centów. Nowi użytkownicy Google Cloud mogą też skorzystać z programu bezpłatnego okresu próbnego o wartości 300 USD.
- Zapisz Identyfikator projektu (unikalną nazwę we wszystkich projektach Google Cloud). Będzie ona potrzebna do skonfigurowania i wdrożenia agenta.
Uzyskiwanie klucza interfejsu API Google AI Studio
Aby korzystać z modeli Gemini, potrzebujesz klucza interfejsu API z Google AI Studio.
- Otwórz Google AI Studio.
- Kliknij Get API Key (Pobierz klucz interfejsu API).
- Utwórz nowy klucz lub użyj istniejącego. Skopiuj klucz, aby użyć go później.
4. Tworzenie struktury projektu agenta do pisania blogów
W tym kroku skonfigurujesz katalog i pliki, w których będziesz przechowywać kod agenta do pisania bloga na komputerze lokalnym.
1. Tworzenie obszaru roboczego agenta do pisania bloga
Otwórz terminal i uruchom te polecenia, aby utworzyć dedykowany katalog dla agenta do pisania blogów i przejść do niego:
mkdir bloggeragent
cd bloggeragent
2. Zainicjuj pliki agenta
Platforma Google ADK wczytuje procesy agenta bezpośrednio z katalogu projektu. Utwórz niezbędne pliki bezpośrednio w katalogu głównym bloggeragent:
touch requirements.txt .env __init__.py agent.py
5. Instalowanie zależności i konfigurowanie środowiska
W tym kroku skonfigurujesz wirtualne środowisko Pythona, zainstalujesz platformę Google ADK i skonfigurujesz zmienne środowiskowe, aby uwierzytelnić agenta bloga w modelu Gemini.
1. Skonfiguruj wymagania dotyczące agenta
Otwórz plik requirements.txt w katalogu bloggeragent i określ pakiety potrzebne agentowi do pisania bloga, dodając do niego ten kod:
google-adk==2.2.0
python-dotenv
2. Tworzenie środowiska wirtualnego dla agenta
W katalogu bloggeragent utwórz i aktywuj wirtualne środowisko Pythona, aby odizolować pakiety agenta:
python3 -m venv .venv
source .venv/bin/activate
3. Instalowanie platformy ADK
Zainstaluj zależności zdefiniowane w pliku requirements.txt, aby wyposażyć lokalne miejsce pracy w pakiet Google ADK:
pip install -r requirements.txt
4. Konfigurowanie danych logowania interfejsu API agenta
Otwórz plik .env utworzony w katalogu głównym projektu i dodaj klucz interfejsu Gemini API:
GOOGLE_API_KEY=your_api_key
Zastąp your_api_key kluczem skopiowanym z Google AI Studio.
6. Tworzenie narzędzia do pisania bloga z udziałem wielu agentów
W tym kroku zaimplementujesz podstawowy przepływ pracy systemu agenta do pisania blogów.
Zamiast prostego chatbota z jednym promptem stworzysz złożony system wieloagentowy, który wykorzystuje pętle samokorekcyjne i weryfikację konspektu do pisania wysokiej jakości postów technicznych. Jest to zgodne z omówionym wcześniej wzorcem rozważania/planowania.
Omówienie architektury
Oto jak wchodzą w interakcje specjaliści w Twoim systemie:
Konfigurowanie pliku init.py
Otwórz plik __init__.py w edytorze tekstu i dodaj ten import, aby udostępnić przepływ pracy agenta narzędziu do uruchamiania:
from . import agent
Napisz przepływ pracy agenta do pisania bloga
Otwórz plik agent.py w edytorze kodu i dodaj ten kod, który definiuje narzędzia Planner, Writer, Validation Checkers i głównego agenta Blogger:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
Architektura agenta
Przyjrzyjmy się głównym komponentom kodu, który został dodany w agent.py, aby zrozumieć, jak wdraża on przepływ pracy związany z planowaniem i pisaniem przez wiele modeli:
1. The BlogPlanner Sub-Agent
blog_planner odpowiada za planowanie treści. Na podstawie tematu podanego przez użytkownika tworzy strukturalny konspekt w formacie Markdown (z tytułem, wprowadzeniem, 4–6 sekcjami i zakończeniem). Konspekt jest zapisywany w słowniku stanu współdzielonego pod kluczem "blog_outline".
2. The OutlineValidationChecker
OutlineValidationChecker pełni rolę kontroli jakości. Sprawdza wygenerowany "blog_outline" w stanie. Jeśli konspekt jest prawidłowy, odpowiada "ok". W przeciwnym razie zwraca "retry" wraz z listą brakujących elementów.
3. Pętla RobustBlogPlanner
Aby zapobiec tworzeniu przez agenta nieprawidłowych konspektów, umieszczamy planistę i sprawdzanie poprawności w funkcji LoopAgent o nazwie robust_blog_planner. Jeśli weryfikacja się nie powiedzie i zwróci wartość "retry", pętla automatycznie uruchomi ponownie planowanie (maksymalnie 3 razy), aby zapewnić samokorektę przed przejściem do następnego etapu.
4. The BlogWriter Sub-Agent
Gdy konspekt zostanie sfinalizowany, blog_writer agent odczytuje "blog_outline" ze stanu i generuje pełny artykuł techniczny w języku Markdown, dopasowując go do struktury konspektu i dostosowując go do potrzeb inżynierów oprogramowania.
5. Pętla BlogPostValidationChecker i RobustBlogWriter
Podobnie jak w przypadku konspektu, gotowy artykuł jest weryfikowany przez BlogPostValidationChecker, aby upewnić się, że zawiera wszystkie kluczowe sekcje i są one jasne. Autor i weryfikator są objęci pętlą robust_blog_writer, co pozwala na samodzielne poprawianie artykułu do 3 razy, jeśli weryfikator znajdzie problemy.
6. Udostępnianie pętli jako narzędzi
Pętle planowania (robust_blog_planner) i pisania (robust_blog_writer) traktujemy jako narzędzia (planner_tool i writer_tool) za pomocą AgentTool. Dzięki temu inni agenci mogą wywoływać te złożone przepływy pracy tak, jakby były prostymi narzędziami.
7. Agent główny Bloggera
root_agent (o nazwie Blogger) zarządza całym przepływem pracy. Po otrzymaniu tematu instrukcje prowadzą go do:
- Wywołaj interfejs API
planner_tool, aby wygenerować zweryfikowany konspekt. - Wywołaj interfejs API
writer_tool, aby napisać wersję roboczą na podstawie tego konspektu. - Na koniec wygeneruj 3 alternatywne tytuły i 2 wstępy do tweetów.
Ta architektura pętli z wieloma agentami zapewnia niezawodność, ponieważ wychwytuje i koryguje błędy formatowania lub strukturalne LLM przed wyświetleniem danych wyjściowych użytkownikowi.
7. Uruchamianie i testowanie agenta
Teraz zobaczmy, jak działa Twój agent.
1. Uruchamianie interfejsu internetowego ADK
Sprawdź, czy w terminalu znajdujesz się w bloggeragentgłównym katalogu projektusource .venv/bin/activate i czy środowisko wirtualne jest aktywne (source .venv/bin/activate). Następnie uruchom interfejs internetowy:
adk web
2. Korzystanie z agenta
- Otwórz przeglądarkę i wejdź na stronę
http://127.0.0.1:8000(lub port, który został przez Ciebie określony). - Powinien wyświetlić się interfejs ADK Web UI z załadowanym agentem
Bloggeri jego układem wizualnym (pokazującym agenta głównego Bloggera wskazującego narzędzia RobustBlogPlanner i RobustBlogWriter):
- Wpisz w polu wiadomości temat techniczny i naciśnij Enter. Oto kilka ciekawych promptów testowych, których możesz użyć do oceny agenta:
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- Śledź wykonanie w interfejsie. Zobaczysz, jak
BlogPlannertworzy konspekt,OutlineValidationCheckergo weryfikuje, aBlogWriterpisze ostateczną wersję na podstawie konspektu:
8. Wdrożenie w Cloud Run
Po sprawdzeniu, czy agent działa lokalnie, wdróżmy go w Google Cloud Run, aby inni mogli z niego korzystać.
Google Cloud Run to zarządzana platforma obliczeniowa, która umożliwia uruchamianie bezstanowych kontenerów wywoływanych przez żądania sieciowe lub zdarzenia Pub/Sub.
1. Wymagania wstępne wdrożenia
Aby wdrożyć agenta do pisania blogów w Cloud Run, musisz zainstalować i uwierzytelnić Google Cloud CLI (gcloud) na komputerze lokalnym:
- Zainstaluj Google Cloud CLI: jeśli nie masz go zainstalowanego, postępuj zgodnie z przewodnikiem instalacji Google Cloud CLI dla swojego systemu operacyjnego (macOS, Windows lub Linux).
- Uwierzytelnij terminal lokalny: po zainstalowaniu uruchom w terminalu to polecenie, aby zalogować się na konto Google Cloud:
gcloud auth login - Weryfikacja uwierzytelniania: sprawdź, czy logowanie na konto przebiegło pomyślnie i czy masz dostęp do zasobów Google Cloud:
gcloud auth list
2. Konfigurowanie projektu Google Cloud
Ustaw aktywny projekt w terminalu:
gcloud config set project <YOUR_PROJECT_ID>
Włącz usługi Google Cloud niezbędne do tworzenia i wdrażania skonteneryzowanego agenta:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Polecenie wdrażania ADK używa Google Cloud Build do automatyzacji procesu kompilacji, dlatego musisz przyznać domyślnemu kontu usługi Compute uprawnienia do korzystania z Cloud Build.
Aby znaleźć numer projektu, uruchom to polecenie:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
Uruchom te polecenia, aby powiązać wymagane role IAM (zastąp
- Przyznaj Cloud Build uprawnienia do tworzenia kontenera:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- Przyznaj uprawnienia dostępu do Gemini Enterprise, aby wdrożony agent mógł wywoływać modele Gemini bez konieczności używania klucza interfejsu API:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. Konfigurowanie lokalnych zmiennych środowiskowych
Aby uprościć polecenie wdrażania i zapobiec błędom w pisowni, ustaw identyfikator projektu jako zmienną środowiskową w sesji terminala:
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. Wdrażanie za pomocą interfejsu wiersza poleceń pakietu ADK
Interfejs ADK CLI udostępnia uproszczone polecenie do wdrażania agenta w Cloud Run.
Upewnij się, że środowisko wirtualne jest aktywne i że znajdujesz się w katalogu projektu bloggeragent, a potem uruchom polecenie wdrożenia:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
Podczas procesu wdrażania w terminalu pojawią się te 2 pytania:
- Potwierdź utworzenie repozytorium:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Yi naciśnij Enter. - Zezwalaj na dostęp nieuwierzytelniony:
Allow unauthenticated invocations to [bloggeragent] (y/N)?
yi naciśnij Enter (umożliwi to publiczny dostęp do interfejsu ADK w przeglądarce).
5. Dostęp do wdrożonego agenta
Po zakończeniu wdrażania polecenie wygeneruje adres URL. Otwórz ten adres URL w przeglądarce, aby uzyskać dostęp do aktywnego, publicznie dostępnego interfejsu ADK Web UI.
9. Czyszczenie danych
Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tego ćwiczenia.
1. Usuwanie usługi Cloud Run
Usuń wdrożoną usługę bloggeragent:
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Usuwanie repozytorium Artifact Registry
Usuń repozytorium Dockera utworzone do przechowywania skompilowanych obrazów kontenerów:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. Zatrzymywanie serwera lokalnego
Aby zatrzymać lokalny serwer ADK, naciśnij CTRL+C w terminalu, w którym jest uruchomiony, i dezaktywuj środowisko wirtualne:
deactivate
10. Gratulacje
Gratulacje! Udało Ci się utworzyć pierwszego agenta AI za pomocą ADK od Google i Gemini.
Czego się dowiedziałeś(-aś)
- Podstawowe pojęcia związane z agentami AI (rozumowanie i działanie).
- Jak używać pakietu Google ADK do tworzenia systemu wieloagentowego
- Jak uruchomić i przetestować agenta za pomocą interfejsu internetowego.
Dalsze kroki
- Spróbuj dodać do agenta narzędzia (np. wyszukiwanie w internecie lub wywołania interfejsu API).
- Obejrzyj film 2, w którym zintegrujemy serwer MCP.