Tworzenie zarządzanego agenta z podsumowaniem informacji o technologii za pomocą Gemini API

1. Przegląd

Świat AI i technologii rozwija się szybciej, niż ktokolwiek jest w stanie za nim nadążyć. Codziennie pojawiają się nowe modele, artykuły i usługi. Agent podsumowujący, który pobiera dzisiejsze nagłówki, pisze zwięzłe podsumowania i generuje plik PDF każdego ranka, rozwiązałby ten problem, ale jego utworzenie wymagało wybrania platformy, zdefiniowania narzędzi w Pythonie, napisania pętli orkiestracji, spakowania kontenera i wdrożenia w Cloud Run. Wszystko to zanim agent wysłał jakiekolwiek żądanie internetowe.

Zarządzane agenty w Gemini API zmieniają tę sytuację. Piszesz 2 pliki konfiguracyjne w formacie Markdown i gotowy skrypt renderujący, wykonujesz 1 wywołanie interfejsu API, a prawdziwe środowisko testowe Ubuntu uruchamia się, przegląda internet, pisze podsumowania i generuje plik PDF. Brak kontenerów. Brak wdrożenia. Brak kodu orkiestracji.

W tym laboratorium kodowania stworzysz takiego agenta: od pustej funkcji po działające codzienne podsumowanie. Będziesz to robić krok po kroku.

Co utworzysz

  • Tworzenie i uruchamianie pierwszego agenta zarządzanego w prawdziwej piaskownicy Linux
  • Dostosowywanie agenta za pomocą szczegółowych instrukcji
  • Pobieranie pliku PDF wygenerowanego przez agenta
  • Kontynuuj rozmowę, aby dopracować podsumowanie bez ponownego pobierania informacji z internetu
  • Zapisywanie konfiguracji agenta i wywoływanie jej w przyszłych uruchomieniach za pomocą identyfikatora

Czego potrzebujesz

  • Python 3.10 lub nowszy
  • Klucz interfejsu Gemini API z włączonymi płatnościami: aistudio.google.com/api-keys
  • około 1 USD w kredytach na interfejs API (każde pełne uruchomienie kosztuje 0,30–1,30 USD);

2. Czym są zarządzane agenty w Gemini API?

3 poziomy systemów AI

Zanim przejdziemy do kodu, zobacz, gdzie na tle 2 alternatywnych rozwiązań plasują się zarządzane agenty:

Poziom

Co to jest?

Kto zarządza infrastrukturą?

Standardowy LLM

Ty podajesz prompt, a ona odpowiada tekstem. Bez rąk, bez pamięci, bez internetu.

Nie dotyczy: nie może niczego robić samodzielnie

Agent hostowany samodzielnie

Łączysz ADK/LangChain/AutoGen z Dockerem, narzędziami i pamięcią.

Ty: wszystko (lub zarządzana platforma, np. Agent Engine)

Zarządzany agent

Nadajesz mu cel. Google udostępnia bezpieczną piaskownicę. Agent pisze kod, uruchamia go, odczytuje błędy, przeszukuje internet i samodzielnie naprawia błędy.

Google: wszystkie usługi

To ćwiczenie dotyczy trzeciego wiersza. Podajesz zadanie i pliki konfiguracji. Google zajmie się resztą.

Co możesz utworzyć za pomocą pakietu ADK i Cloud Run

Aby utworzyć agenta do podsumowywania wiadomości, który przegląda internet, uruchamia Pythona i generuje plik PDF, potrzebujesz tego wszystkiego w połączeniu z pakietem ADK i Cloud Run:

# agent.py: define tools and wire up the agent
from google.adk.agents import LlmAgent
from google.adk.tools import google_search, built_in_code_execution

agent = LlmAgent(
    name="digest-agent",
    model=MODEL,
    instruction=AGENTS_MD,          # your editorial voice and rules
    tools=[google_search, built_in_code_execution],
)

# app.py: serve the agent over HTTP
from google.adk.runners import FastApiRunner
runner = FastApiRunner(agent=agent)
app = runner.app

# pdf_tool.py: custom tool, install reportlab, render PDF
# scraper.py: custom tool, fetch each news source
# streaming.py: wire agent events to your SSE endpoint

# Dockerfile: package everything
FROM python:3.12
COPY . /app
RUN pip install google-adk reportlab requests
CMD ["uvicorn", "app:app", "--host", "0.0.0.0"]

# Deploy to Cloud Run
gcloud run deploy digest-agent \
  --image gcr.io/your-project/digest-agent \
  --set-secrets GEMINI_API_KEY=gemini-key:latest \
  --memory 2Gi

Dzieje się to przed pierwszym uruchomieniem agenta. Nadal masz kontrolę nad izolacją piaskownicy (dzięki czemu agent nie może uszkodzić serwera), instalacją pakietów, zarządzaniem stanem między wywołaniami narzędzi i infrastrukturą przesyłania strumieniowego, która umożliwia dostarczanie zdarzeń do klienta.

Czym zastępują je zarządzane agenty

from google import genai
client = genai.Client()

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="",
    stream=True,
    environment={
        "type": "remote",
        "sources": [          # your config files, mounted at startup
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

Wymagania dotyczące ADK i Cloud Run

Co robią za Ciebie zarządzane agenty

Obraz kontenera + Dockerfile + CI/CD

W pełni zarządzane środowisko testowe Ubuntu (Python 3.12, Node 22, 4 rdzenie CPU / 16 GB pamięci RAM)

Wdrożenie i skalowanie Cloud Run

Dostępny w przypadku interakcji, automatycznie wygasa po 7 dniach nieaktywności

Izolacja piaskownicy

Izolowane na każdą interakcję

Narzędzie do tworzenia niestandardowych plików PDF + pip install

Agent instaluje pakiety w piaskownicy

Infrastruktura strumieniowania SSE

stream=True zwraca iterowalny obiekt wydarzenia

Definicje narzędzi w Pythonie

Wbudowane narzędzia: przeglądanie internetu, wykonywanie kodu, system plików

Zarządzanie stanem między wywołaniami narzędzi

Wbudowane w pętlę rozumowania agenta

Tworzysz pliki konfiguracyjne (AGENTS.md, SKILL.md, gotowy skrypt) i wykonujesz jedno wywołanie interfejsu API. Google zajmie się resztą.

Jak działa piaskownica

interactions.create() call
        │
        ▼
Google provisions Ubuntu sandbox (Python 3.12, Node 22, 4 CPU / 16 GB RAM)
        │
        ▼
Agent reasoning loop:
  plan → fetch URLs → run Python → write files → reason → repeat
        │
        ▼
Events stream back in real time: tool calls, text chunks, completion
        │
        ▼
interaction.completed → environment_id + interaction_id

Piaskownica jest dostępna przez 7 dni nieaktywności. Możesz wznowić rozmowę, klikając environment_id, aby dopracować wynik, uruchomić zadania uzupełniające lub rozwidlić ją w zapisany, nazwany model.

3. Skonfiguruj

Kliknij przycisk poniżej, aby otworzyć ten codelab w Google Cloud Shell. Wszystkie zależności są wstępnie zainstalowane.

Otwórz w Cloud Shell

Opcja B. Konfiguracja lokalna

git clone https://github.com/Saoussen-CH/tech-digest-managed-agent.git
cd tech-digest-managed-agent

W razie potrzeby zainstaluj uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Konfigurowanie klucza interfejsu API

cp .env.example .env
cloudshell edit .env

Ustaw klucz:

GEMINI_API_KEY=your-key-here

Instalowanie zależności

uv sync

4. Wykonywanie pierwszego połączenia z agentem

Otwieranie pliku początkowego

cloudshell edit run_digest.py

run_digest() ma teraz 1 element do zrobienia i 3 kolejne w następnym kroku. Powyżej są już wstępnie wypełnione 2 pomocnicze pytania:

  • load_source(path): odczytuje plik z lokalizacji .agents/ względem skryptu. Użyjesz go w następnym ćwiczeniu, aby zamontować w sandboxie styl dziennikarski, scenariusz w formacie PDF i mechanizm renderowania.
  • run_stream(stream): przetwarza strumień zdarzeń i zwraca wartość (environment_id, interaction_id). Nie musisz samodzielnie pisać pętli zdarzeń.

Co dodać

DO ZROBIENIA 1: zastąp pass tym kodem (na razie zignoruj DO ZROBIENIA 3 i 4 – będą potrzebne w następnym kroku):

    from google import genai
    client = genai.Client()

    stream = client.interactions.create(
        agent=BASE_AGENT,
        input="Fetch the Hacker News front page and list the top 5 stories.",
        stream=True,
        environment="remote",
    )

    environment_id, interaction_id = run_stream(stream)
    print(f"\nDone. environment_id={environment_id}")

Działanie poszczególnych części

genai.Client() odczytuje GEMINI_API_KEY ze środowiska. Wszystkie inne działania są wykonywane przez tego klienta.

interactions.create() to połączenie główne. W tym celu musisz uwzględnić 4 parametry:

  • agent=BASE_AGENT: wybiera agenta Antigravity (antigravity-preview-05-2026), agenta zarządzanego do zwykłych obciążeń opartego na Gemini 3.5 Flash. Domyślnie są włączone 3 wbudowane narzędzia: code_execution (uruchamianie skryptów Bash, Python i Node.js), google_search i url_context (pobieranie i odczytywanie stron internetowych). Narzędzia systemu plików (read_file, write_file, list_files) są włączane automatycznie po przekazaniu parametru environment. Jedno wywołanie udostępnia w pełni zarządzane środowisko Ubuntu z fabrycznie zainstalowanymi Pythonem 3.12, Node.js 22, git, pip i curl. Nie musisz tworzyć kontenera ani uruchamiać wdrożenia.
  • input: zadanie dla tego uruchomienia. Agent przegląda Hacker News i analizuje wyniki.
  • environment="remote": udostępnia nową piaskownicę w chmurze na potrzeby tej interakcji.
  • stream=True: zwraca iterowalny obiekt wydarzeń zamiast blokować. Bez niego połączenie czeka 30–90 sekund i zwraca wszystkie dane wyjściowe naraz jako interaction.output_text. W przypadku przesyłania strumieniowego widzisz powód działania agenta i możesz reagować na bieżąco. Strumieniowanie nie jest tutaj funkcją zaawansowaną: to właściwe ustawienie domyślne, ponieważ 90-sekundowe czarne pole nie daje żadnego sygnału, czy agent działa, czy się zawiesił.

Co zostało właśnie udostępnione: każde wywołanie interactions.create() uruchamia dedykowaną piaskownicę:

Komponent

Specyfikacja

System operacyjny

Odizolowane środowisko Ubuntu Linux

Wstępnie zainstalowane środowiska wykonawcze

Python 3.12, Node.js 22, Bash

Zasoby obliczeniowe

4-rdzeniowy procesor, 16 GB pamięci RAM

Zarządzanie kontekstem

Automatyczne kompresowanie jest wywoływane przy około 135 tys. tokenów.

Sieci

Dostęp do internetu za pomocą serwera proxy ruchu wychodzącego

Agent może instalować dowolne pakiety z pip lub npm, odczytywać i zapisywać pliki oraz wysyłać żądania internetowe. Twój komputer i dane logowania nigdy nie są używane.

environment_id to uchwyt do właśnie uruchomionej piaskownicy. Po interaction.completed piaskownica nie zostanie wyłączona: będzie działać jeszcze przez maksymalnie 7 dni. environment_id to sposób, aby do niego wrócić. Przekaż go do drugiego interactions.create() połączenia, a agent wznowi pracę w tym samym systemie plików, z tymi samymi plikami i zainstalowanymi pakietami, jakby nigdy nie przestał działać. W następnym kroku używa go do pobrania pliku PDF bez ponownego uruchamiania agenta, a w kolejnym kroku używa go do kontynuowania rozmowy.

interaction_id to uchwyt do zakończonej właśnie tury rozmowy. Przekaż go jako previous_interaction_id w następnym wywołaniu, a agent będzie pamiętać wszystko, co powiedział i zrobił w tej turze.

Zweryfikuj

uv run python run_digest.py

W trakcie pracy agenta powinny być widoczne dane wyjściowe na żywo:

[agent started]
  [tool] run_code
Here are the top 5 stories currently on the Hacker News front page, retrieved via the official Hacker News API:

1. **Qwen 3.6 27B is the sweet spot for local development** — 471 points
2. **.self: A new top-level domain designed to support self-hosting** — 116 points
...
Done. environment_id=e3de58774073f75a6ef42924c6ce2e88

Interfejs API zwraca rzeczywistą wartość environment_id nawet w przypadku wartości environment="remote". Piaskownica została uruchomiona. Brak konfiguracji: brak głosu, umiejętności i generatora plików PDF. Agent wydrukował tylko opowiadania w formie tekstu i przestał działać. W następnym kroku dodasz te uprawnienia.

Każdy wiersz danych wyjściowych jest mapowany na zdarzenie z run_stream():

step.type

Co to jest?

Co drukuje run_stream()

"url_context_call"

agent pobierający adres URL,

[tool] url_context (https://...)

"code_execution_call"

agent uruchamiający kod w piaskownicy,

[tool] run_code

"google_search_call"

agent wyszukuje informacje w internecie

[tool] google_search

"function_call"

narzędzia do obsługi plików i inne.

[tool] read_file (/workspace/...)

step.delta, gdzie delta.type == "text"

agent pisze tekst

przesyłane strumieniowo bezpośrednio do stdout,

5. Dostosowywanie agenta

Agent nie miał żadnych instrukcji: nie miał głosu, umiejętności ani generatora plików PDF. W tym kroku załadujesz pliki konfiguracyjne z .agents/ i zamontujesz je w środowisku testowym.

Co zmienić

Wprowadź 4 zmiany w run_digest.py:

TODO 2: poniżej load_source() dodaj 3 stałe na poziomie modułu (znajdują się one poza run_digest(), u góry pliku):

AGENTS_MD       = load_source(".agents/AGENTS.md")
SKILL_MD        = load_source(".agents/skills/digest-pdf/SKILL.md")
GENERATE_PDF_PY = load_source(".agents/skills/digest-pdf/scripts/generate_pdf.py")

Otwórz każdy plik, aby zobaczyć, co ładujesz: AGENTS.md określa styl dziennikarski i reguły przepływu pracy; SKILL.md to szczegółowy przewodnik w formacie PDF; generate_pdf.py to gotowy moduł renderujący, który będzie uruchamiany przez agenta.

Wprowadź jeszcze 2 zmiany w sekcji run_digest():

TODO 3: zmień environment z "remote" na słownik źródeł i ustaw input na "":

        environment={
            "type": "remote",
            "sources": [
                {
                    "type": "inline",
                    "target": ".agents/AGENTS.md",
                    "content": AGENTS_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/SKILL.md",
                    "content": SKILL_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                    "content": GENERATE_PDF_PY,
                },
            ],
        },

TODO 4: dodaj te wiersze bezpośrednio po print(f"\nDone. environment_id={environment_id}"):

    set_key(".env", "ENVIRONMENT_ID", environment_id)
    set_key(".env", "INTERACTION_ID", interaction_id)

(set_key jest już zaimportowany u góry pliku run_digest.py).

Podczas tego działania oba identyfikatory zostaną zapisane w .env, dzięki czemu w następnym kroku można pobrać plik PDF bez ponownego uruchamiania agenta.

Co robi każde źródło

Każde źródło to plik zamontowany w systemie plików piaskownicy podczas uruchamiania, zanim zostanie uruchomiony agent. Ścieżki target pasują do miejsc, w których uprząż Antigravity oczekuje ich znalezienia:

.agents/
├── AGENTS.md                              ← auto-loaded as global instructions
└── skills/
    └── digest-pdf/
        ├── SKILL.md                       ← auto-discovered and registered as a skill
        └── scripts/
            └── generate_pdf.py            ← pre-built renderer the agent can run

Ścieżka elementu „target”

Zmienna

Jakie działanie podejmuje uprząż

.agents/AGENTS.md

AGENTS_MD

Automatyczne wczytywanie jako trwałe instrukcje: styl dziennikarski, przepływ pracy, reguły wykonywania

.agents/skills/digest-pdf/SKILL.md

SKILL_MD

Automatycznie wykryta i zarejestrowana jako umiejętność o nazwie. Agent wywołuje ją po nazwie.

.agents/skills/digest-pdf/scripts/generate_pdf.py

GENERATE_PDF_PY

Gotowy moduł renderowania plików PDF; agent pisze summaries.json, a potem uruchamia ten skrypt

Zweryfikuj

uv run python run_digest.py

Wykonanie zajmuje teraz 1–3 minuty. Powinien być widoczny agent odczytujący pliki konfiguracyjne, tworzący podsumowania i zapisujący plik PDF:

[agent started]
  [tool] read_file (/.agents/skills/digest-pdf/SKILL.md)
  [tool] list_files (/.agents/skills/digest-pdf/scripts)
  [tool] read_file (/.agents/skills/digest-pdf/scripts/generate_pdf.py)
  [tool] run_code
  [tool] write_file (/workspace/summaries.json)
  [tool] run_code
  [tool] delete_file (/tmp/test_scrape.py)
I have successfully generated today's tech news digest and saved the formatted document to /workspace/digest.pdf.
Done. environment_id=4129ffd75574e308748e9425d7ec828f

environment_id to teraz rzeczywista wartość: piaskownica została uruchomiona z Twoimi plikami konfiguracyjnymi, a agent utworzył digest.pdf. W następnym kroku pobierzemy ten plik.

6. Pobierz plik PDF

Agent napisał digest.pdf do /workspace/digest.pdf w środowisku testowym. Zrzut środowiska jest dostępny jako archiwum tar w interfejsie Gemini Files API.

W razie potrzeby zainstaluj requests:

uv pip install requests

Co należy wypełnić

Otwórz pokój download_pdf.py. Zawiera 2 elementy do zrobienia.

TODO 1: wypełnij wywołanie requests.get():

    r = requests.get(
        f"https://generativelanguage.googleapis.com/v1beta/files/environment-{environment_id}:download",
        params={"alt": "media"},
        headers={"x-goog-api-key": api_key},
        allow_redirects=True,
    )
    r.raise_for_status()

Adres URL odnosi się do migawki środowiska piaskownicy. params={"alt": "media"} zwraca nieprzetworzone bajty zamiast metadanych. Twój dotychczasowy GEMINI_API_KEY uwierzytelnia też interfejs Files API.

TODO 2: znajdź i wyodrębnij plik PDF z archiwum tar:

            member = next(m for m in tar.getmembers() if m.name.endswith("workspace/digest.pdf"))
            tar.extract(member, path=tmp, filter="data")

Prefiks ścieżki tar różni się w zależności od uruchomienia, więc zamiast wpisywać na stałe dokładną ścieżkę, wyszukuj według sufiksu. filter="data" tłumi ostrzeżenie o wycofaniu Pythona 3.13 dotyczące niebezpiecznego wyodrębniania plików tar.

Zweryfikuj

uv run python download_pdf.py

Saved digest.pdf (48,231 bytes)

Otwórz plik digest.pdf w tym samym katalogu. Zawiera sformatowane podsumowanie wygenerowane przez agenta na podstawie aktywnych stron internetowych.

7. Kontynuowanie rozmowy

Masz już digest.pdf. Jeśli zależało Ci tylko na pliku, to wszystko. Ten krok dotyczy czegoś innego: poproś agenta o zmianę podsumowania bez ponownego pobierania informacji z internetu.

Piaskownica nadal działa. Agent nadal ma /workspace/digest.pdf i pamięta każdy podsumowany artykuł. Drugie wywołanie interactions.create() wysyła wiadomość uzupełniającą do tego samego środowiska testowego. W tym przypadku prosisz o dodanie notatki „Dlaczego to jest ważne” pod każdą historią. Usługa aktualizuje plik PDF w miejscu, bez ponownego pobierania i podsumowywania.

Co należy wypełnić

Otwórz pokój refine_digest.py. Ma 3 elementy do zrobienia.

TODO 1 i 2: wypełnij 2 parametry wieloetapowe w interactions.create():

    environment=environment_id,
    previous_interaction_id=interaction_id,

environment=environment_id wznawia tę samą piaskownicę z jej plikami i pakietami. previous_interaction_id=interaction_id przekazuje agentowi historię rozmowy. W porównaniu z pierwszym połączeniem nic się nie zmienia.

TODO 3: po zakończeniu pętli zdarzeń zapisz nowy obiekt interaction_id z powrotem w obiekcie .env:

set_key(".env", "INTERACTION_ID", interaction_id)

Każde wywołanie interactions.create() powoduje utworzenie nowego elementu interaction_id. Zapisanie go z powrotem oznacza, że w kolejnym przebiegu to ulepszenie zostanie przekazane jako previous_interaction_id, co pozwoli na prawidłowe połączenie kolejnych tur. Identyfikator piaskownicy nigdy się nie zmienia, więc nie musisz go aktualizować.ENVIRONMENT_ID

2 parametry, które umożliwiają działanie wieloetapowych odpowiedzi

Identyfikator

Co jest zachowywane

Analogie

environment=environment_id

Pliki, zainstalowane pakiety, stan systemu: wszystko w systemie plików Linux

Utrzymywanie tego samego biurka między spotkaniami

previous_interaction_id=interaction_id

Historia rozmowy: co agent powiedział i zrobił w poprzednich turach.

przypominanie sobie, o czym rozmawiano na ostatnim spotkaniu;

Możesz przekazywać każdy identyfikator osobno:

  • environment_id: ponownie używaj plików i pakietów, ale rozpoczynaj nową rozmowę. Przydatne w przypadku nowego zadania w tym samym obszarze roboczym.
  • previous_interaction_id: kontynuuj kontekst rozmowy, ale w nowym środowisku testowym (pliki znikną).
  • Oba: pełna ciągłość, która jest używana w tym kroku.

Bez environment_id: pusta piaskownica, bez pliku PDF. Bez previous_interaction_id: brak kontekstu, pracownik obsługi klienta nie może doprecyzować konkretnej sekcji.

Zweryfikuj

uv run python refine_digest.py

Strumień powinien być szybki, ponieważ agent nie pobiera ponownie żadnych informacji. Po zakończeniu:

Refinement done.
Saved digest_v2.pdf (52,418 bytes)

Otwórz digest_v2.pdf i porównaj go z digest.pdf. Do każdego artykułu powinna zostać dodana linia „Dlaczego to jest ważne”.

8. Zapisywanie konfiguracji zarządzanego agenta

Każde połączenie przeszło do tej pory w trybie inline weryfikację AGENTS.md, SKILL.md i generate_pdf.py. To działa, ale kod wywołujący przenosi pełną zawartość pliku przy każdym uruchomieniu. agents.create() zapisuje konfigurację w postaci nazwanego agenta po stronie Google. Następne wywołanie przekazuje tylko identyfikator agenta:

Inline calls:   send sources on every call
Named agent:    bake once → invoke by ID, no sources

Co należy wypełnić

Otwórz pokój save_agent.py. Ma 1 element TODO (TODO 1).

Zwróć uwagę, że stałe są importowane bezpośrednio z run_digest.py (bez duplikowania):

from run_digest import BASE_AGENT, AGENTS_MD, SKILL_MD, GENERATE_PDF_PY

TODO 1: wypełnij wywołanie agents.create():

agent = client.agents.create(
    id="my-digest",
    base_agent=BASE_AGENT,
    description="Daily tech digest with editorial voice and PDF generation.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

base_environment (nie environment) to kluczowa różnica w porównaniu z wywołaniem wbudowanym z poprzedniego kroku: źródła są przechowywane po stronie Google i automatycznie montowane przy każdym kolejnym wywołaniu. Uruchom go raz, a nie przy każdym uruchomieniu podsumowania.

Weryfikacja: zapisz agenta

uv run python save_agent.py

Saved: my-digest
my-digest: Daily tech digest with editorial voice and PDF generation.

Wywoływanie zapisanego agenta

Otwórz pokój invoke_agent.py. Wywołuje zapisanego agenta według identyfikatora bez źródeł:

stream = client.interactions.create(
    agent="my-digest",
    input="",
    stream=True,
    environment="remote",
)

Porównaj to z wywołaniem w wierszu: agent=BASE_AGENT jest zastępowane przez "my-digest", a cały blok environment z 3 źródłami w wierszu jest zastępowany przez environment="remote". Konfiguracja jest już wbudowana po stronie Google.

Weryfikacja: wywołanie zapisanego agenta

uv run python invoke_agent.py

Powinna pojawić się ta sama transmisja na żywo co w przypadku uruchomienia wbudowanego, ale wywołanie nie zawiera plików źródłowych. Po zakończeniu biegu wartości ENVIRONMENT_ID i INTERACTION_ID w .env zostaną zaktualizowane, dzięki czemu możesz kontynuować refine_digest.py jak wcześniej.

[agent started]
  [tool] read_file
  [tool] write_file
  [tool] run_code
I have successfully created today's tech news digest.
Done. environment_id=9a1c3e02-...

9. Czyszczenie

Piaskownica automatycznie wygasa po 7 dniach nieaktywności. Brak serwerów do zatrzymania. Brak kontenerów do usunięcia.

Jeśli masz zapisaną konfigurację agenta, usuń ją:

uv run python delete_agent.py

10. Podsumowanie

Zbudowano agenta zarządzanego od podstaw, po jednym koncepcie. Oto czego uczyło każde ćwiczenie:

Ćwiczenia

Pomysł

Key API

Wykonaj pierwsze połączenie

Udostępnianie prawdziwego środowiska testowego Linuksa i transmitowanie na żywo jego wydarzeń

interactions.create(agent, input, environment, stream=True), event.event_type

Dostosowywanie agenta

Podłącz pliki konfiguracyjne i zachowaj identyfikatory w .env w ramach tego samego uruchomienia.

environment.sources, set_key

Pobierz plik PDF

Pobieranie pliku PDF bez ponownego uruchamiania agenta

Gemini Files API :download w download_pdf.py

Kontynuuj rozmowę

Kontynuowanie rozmowy bez ponownego pobierania informacji z internetu

environment=environment_id, previous_interaction_id=interaction_id

Zachowywanie konfiguracji agenta

Utrwalanie konfiguracji agenta; wywoływanie według identyfikatora, bez konieczności podawania źródeł

agents.create(), agents.list()

Kluczowe wzorce

  1. Jedno wywołanie, jedna piaskownica: interactions.create() obsługuje całą infrastrukturę (nie trzeba wdrażać kontenerów ani instalować lokalnie pakietów).
  2. Strumieniowanie progresywne: stream=True zamienia 90-sekundowe czarne pole w aktywny kanał wywołań narzędzi i fragmentów tekstu.
  3. Źródła wbudowane: montowanie skryptów AGENTS.md, SKILL.md i gotowych w piaskownicy bez przesyłania ani wdrażania.
  4. Automatyczne wykrywanie komponentów: pliki umieszczone w .agents/ są automatycznie wykrywane (nie jest wymagana konfiguracja pakietu SDK).
  5. Stan dwuwymiarowy: environment_id śledzi pliki i pakiety; previous_interaction_id śledzi kontekst rozmowy; oba mogą być przekazywane niezależnie.
  6. Pobieranie stanu: środowisko to pełny system plików w formacie tar, dostępny za pomocą interfejsu Gemini Files API.
  7. Nazwani agenci: agents.create() trwale zapisuje konfigurację; przyszłe wywołania przekazują tylko identyfikator agenta i environment="remote" bez źródeł.

ADK + Cloud Run a zarządzani agenci: krótkie porównanie różnic

Możliwości

ADK + Cloud Run

Zarządzane agenty w Gemini API

Udostępnianie piaskownicy

docker build + gcloud run deploy

interactions.create()

Definiowanie narzędzi

Funkcje Pythona zarejestrowane w agencie

Wbudowane: przeglądanie internetu, wykonywanie kodu, system plików

Instalowanie pakietów

pip install w pliku Dockerfile

Agent działapip install w piaskownicy

Strumieniowanie wydarzeń

Infrastruktura niestandardowego szyfrowania po stronie serwera

stream=True

Kontynuowanie sesji

Baza danych sesji + wstrzykiwanie kontekstu

environment_id + previous_interaction_id

Pliki konfiguracyjne

Zakodowane na stałe w agencie lub wstrzykiwane podczas uruchamiania

Zamontowano za pomocą environment.sources

Infrastruktura do zarządzania

Kontener, Cloud Run, IAM, klucze tajne

Brak

Dalsze kroki