Verwalteten Tech Digest-Agent mit der Gemini API erstellen

1. Übersicht

Die KI- und Technologielandschaft entwickelt sich so schnell, dass niemand den Überblick behalten kann. Täglich werden neue Modelle, Publikationen und Produkte veröffentlicht. Ein Digest-Agent, der die Schlagzeilen des Tages abruft, prägnante Zusammenfassungen schreibt und jeden Morgen ein PDF generiert, würde das Problem lösen. Bisher musste man dafür jedoch ein Framework auswählen, Tools in Python definieren, eine Orchestrierungsschleife schreiben, einen Container erstellen und in Cloud Run bereitstellen. All das, bevor der Agent eine einzige Webanfrage gestellt hatte.

Verwaltete KI-Agenten in der Gemini API ändern die Gleichung. Sie schreiben zwei Markdown-Konfigurationsdateien und ein vorgefertigtes Renderer-Skript, führen einen API-Aufruf aus und eine echte Ubuntu-Sandbox wird gestartet, durchsucht das Web, schreibt Ihre Zusammenfassungen und generiert eine PDF-Datei. Keine Container. Keine Bereitstellung. Kein Orchestrierungscode.

In diesem Codelab erstellen Sie genau diesen Agenten: von einer leeren Funktion bis zu einem funktionierenden Tages-Digest, jeweils ein Konzept nach dem anderen.

Umfang

• Ersten verwalteten Agenten in einer echten Linux-Sandbox erstellen und ausführen
• Agent mit detaillierten Anweisungen anpassen
• PDF-Ausgabe des Agents herunterladen
• Unterhaltung fortsetzen, um die Zusammenfassung zu optimieren, ohne das Web neu abzurufen
• Agent-Konfiguration speichern und bei zukünftigen Ausführungen per ID aufrufen

Voraussetzungen

• Python 3.10 und höher
• Ein Gemini API-Schlüssel mit aktivierter Abrechnung: aistudio.google.com/api-keys
• API-Guthaben im Wert von etwa 1 $ (jeder vollständige Lauf kostet 0,30–1,30 $)

2. Was sind verwaltete KI-Agenten in der Gemini API?

Drei Ebenen von KI-Systemen

Bevor wir uns den Code ansehen, hier eine Übersicht, wie sich Managed Agents im Vergleich zu den beiden Alternativen einordnen:

Level	Beschreibung	Wer verwaltet die Infrastruktur?
Standard-LLM	Sie geben einen Prompt ein und das Modell antwortet mit Text. Keine Hände, kein Gedächtnis, kein Internet.	N/A: Kann nichts selbstständig tun
Selbst gehosteter Agent	Sie verbinden ADK/LangChain/AutoGen + Docker + Tools + Speicher.	Sie: alles (oder eine verwaltete Plattform wie Agent Engine)
Verwalteter Agent	Sie geben ihm ein Ziel vor. Google stellt eine sichere Sandbox bereit. Der Agent schreibt Code, führt ihn aus, liest Fehler, sucht im Web und behebt Fehler selbstständig.	Google: alles

In diesem Codelab geht es um die dritte Zeile. Sie stellen eine Aufgabe und Konfigurationsdateien bereit. Google kümmert sich um alles Weitere.

Was Sie mit ADK + Cloud Run entwickeln können

Wenn Sie einen Nachrichten-Digest-Agenten erstellen möchten, der im Web surft, Python ausführt und ein PDF generiert, benötigen Sie mit ADK + Cloud Run Folgendes:

# 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

Das ist vor der ersten Ausführung des Agents. Sie sind weiterhin für die Sandbox-Isolation (damit der Agent Ihren Server nicht beschädigen kann), die Paketinstallation, die Statusverwaltung zwischen Tool-Aufrufen und die Streaminginfrastruktur zuständig, um Ereignisse an einen Client zu senden.

Was durch Managed Agents ersetzt wird

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,
            },
        ],
    },
)

Voraussetzungen für ADK + Cloud Run	Was Managed Agents für Sie erledigen
Container-Image + Dockerfile + CI/CD	Vollständig verwaltete Ubuntu-Sandbox (Python 3.12, Node 22, 4 CPUs / 16 GB RAM)
Cloud Run-Bereitstellung + Skalierung	Wird pro Interaktion bereitgestellt, läuft nach 7 Tagen Inaktivität automatisch ab
Sandbox-Isolation	Isoliert pro Interaktion
Benutzerdefiniertes PDF-Tool + pip install	Agent installiert Pakete in der Sandbox
SSE-Streaminginfrastruktur	stream=True gibt einen iterierbaren Wert für Ereignisse zurück
Tool-Definitionen in Python	Integrierte Tools: Websuche, Codeausführung, Dateisystem
Statusverwaltung zwischen Tool-Aufrufen	In den Reasoning Loop des Agents integriert

Sie schreiben Konfigurationsdateien (AGENTS.md, SKILL.md, ein vorgefertigtes Skript) und führen einen API-Aufruf aus. Google kümmert sich um alles Weitere.

So funktioniert die Sandbox

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

Die Sandbox bleibt 7 Tage lang inaktiv. Sie können den Vorgang mit environment_id fortsetzen, um die Ausgabe zu optimieren, Folgeaufgaben auszuführen oder den Vorgang in einen gespeicherten benannten Agenten zu verzweigen.

3. Erstelle ein

Option A: Cloud Shell (empfohlen)

Klicken Sie auf den Button unten, um dieses Codelab in Google Cloud Shell zu öffnen. Alle Abhängigkeiten sind vorinstalliert.

In Cloud Shell öffnen

Option B: Lokale Einrichtung

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

Installieren Sie uv, falls erforderlich:

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

API-Schlüssel konfigurieren

cp .env.example .env
cloudshell edit .env

Schlüssel festlegen:

GEMINI_API_KEY=your-key-here

Abrechnung erforderlich. Für die Nutzung von verwalteten KI-Agenten in der Gemini API werden Gebühren für die Tokennutzung erhoben. Jeder vollständige Digest-Lauf kostet zwischen 0,30 $ und 1,30 $. Die Rechenleistung der Umgebung (CPU, Arbeitsspeicher, Sandbox-Ausführung) ist während des Vorschauzeitraums kostenlos. Die kostenlose Stufe umfasst nicht die Interactions API. Sie können unter aistudio.google.com/billing Guthaben hinzufügen.

Abhängigkeiten installieren

uv sync

4. Ersten Agent-Aufruf starten

Startdatei öffnen

cloudshell edit run_digest.py

Lokale Einrichtung:Öffnen Sie run_digest.py in einem Editor Ihrer Wahl.

run_digest() hat jetzt eine TODO-Aufgabe und drei weitere für den nächsten Schritt. Zwei Helfer sind bereits oben vorausgefüllt:

• load_source(path): Liest eine Datei aus .agents/ relativ zum Skript. Sie verwenden sie in der nächsten Übung, um die redaktionelle Stimme, das PDF-Playbook und den Renderer in die Sandbox einzubinden.
• run_stream(stream): Verarbeitet den Ereignisstream und gibt (environment_id, interaction_id) zurück. Sie müssen die Ereignisschleife nicht selbst schreiben.

Angaben

TODO 1:Ersetzen Sie pass durch (ignorieren Sie TODOs 3 und 4 vorerst – sie sind für den nächsten Schritt):

    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}")

Funktionsweise der einzelnen Teile

genai.Client() liest GEMINI_API_KEY aus der Umgebung. Alles andere läuft über diesen Client.

interactions.create() ist der Hauptanruf. Dazu sind vier Parameter erforderlich:

• agent=BASE_AGENT: Wählt den Antigravity-Agenten (antigravity-preview-05-2026) aus, einen verwalteten Agenten für allgemeine Zwecke, der auf Gemini 3.5 Flash basiert. Es enthält drei integrierte Tools, die standardmäßig aktiviert sind: code_execution (Bash, Python, Node.js ausführen), google_search und url_context (Webseiten abrufen und lesen). Dateisystemtools (read_file, write_file, list_files) werden automatisch aktiviert, wenn Sie den Parameter environment übergeben. Mit einem Aufruf wird eine vollständig verwaltete Ubuntu-Umgebung mit vorinstalliertem Python 3.12, Node.js 22, git, pip und curl bereitgestellt. Es gibt keinen Container, der erstellt werden muss, und keine Bereitstellung, die ausgeführt werden muss.
• input: Die Aufgabe für diesen Lauf. Der Agent durchsucht Hacker News und analysiert die Ergebnisse.
• environment="remote": Stellt eine neue Cloud-Sandbox für diese Interaktion bereit.
• stream=True: Gibt ein iterierbares Objekt mit Ereignissen zurück, anstatt zu blockieren. Ohne diesen Parameter wartet der Aufruf 30–90 Sekunden und gibt die gesamte Ausgabe auf einmal als interaction.output_text zurück. Beim Streaming sehen Sie den Grund für die Aktion des Agents und die Aktion selbst in Echtzeit. Streaming ist hier keine erweiterte Funktion, sondern die richtige Standardeinstellung, da eine 90 Sekunden lange Blackbox kein Signal dafür liefert, ob der Kundenservicemitarbeiter arbeitet oder feststeckt.

Was Sie gerade bereitgestellt haben:Bei jedem interactions.create()-Aufruf wird eine dedizierte Sandbox gestartet:

Komponente	Spezifikation
Betriebssystem	Isolierte Ubuntu Linux-Umgebung
Vorinstallierte Laufzeiten	Python 3.12, Node.js 22, Bash
Compute	4 CPU-Kerne, 16 GB RAM
Kontextverwaltung	Die automatische Verdichtung wird bei etwa 135.000 Tokens ausgelöst.
Netzwerk	Ausgehender Webzugriff über den Proxy für ausgehenden Traffic

Der Agent kann beliebige Pakete mit pip oder npm installieren, Dateien lesen und schreiben sowie ausgehende Webanfragen stellen. Ihre Maschine und Ihre Anmeldedaten werden nicht berührt.

environment_id ist ein Handle für die gerade ausgeführte Sandbox. Nach interaction.completed wird die Sandbox nicht heruntergefahren, sondern bleibt bis zu 7 Tage lang aktiv. Über environment_id gelangen Sie wieder dorthin. Übergeben Sie sie an einen zweiten interactions.create()-Aufruf und der Agent wird im selben Dateisystem mit denselben Dateien und installierten Paketen fortgesetzt, als wäre er nie unterbrochen worden. Im nächsten Schritt wird die Variable verwendet, um das PDF herunterzuladen, ohne den Agenten noch einmal auszuführen. Im Schritt danach wird sie verwendet, um die Unterhaltung fortzusetzen.

interaction_id ist ein Handle für den gerade abgeschlossenen Unterhaltungsabschnitt. Übergeben Sie sie als previous_interaction_id im nächsten Aufruf. Der KI-Agent hat dann den vollständigen Kontext dessen, was er in diesem Zug gesagt und getan hat.

Bestätigen

uv run python run_digest.py

Sie sollten die Live-Ausgabe sehen, während der Agent arbeitet:

[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

Die API gibt auch bei environment="remote" einen echten environment_id zurück. Die Sandbox wurde ausgeführt. Es fehlt die Konfiguration: keine Stimme, kein Skill, kein PDF-Generator. Der KI-Agent hat nur Geschichten als Text ausgegeben und dann aufgehört. Im nächsten Schritt werden diese hinzugefügt.

Warum run_code und nicht url_context? Dem Agenten stehen drei Web-Tools zur Verfügung (code_execution, google_search, url_context), die er autonom auswählt. Für strukturiertes Scraping (Extrahieren von Bewertungen, Links und Kommentaranzahlen) wird in der Regel code_execution bevorzugt: Es wird ein Python-requests-Skript geschrieben, in der Sandbox ausgeführt und das HTML wird vollständig in Python geparst. url_context kann auch in anderen Läufen angezeigt werden. Beide sind gültig.

Jede Ausgaberow entspricht einem Ereignis aus run_stream():

step.type	Beschreibung	Was run_stream() druckt
"url_context_call"	Agent ruft eine URL ab	[tool] url_context (https://...)
"code_execution_call"	KI-Agent führt Code in der Sandbox aus	[tool] run_code
"google_search_call"	Agent sucht im Web	[tool] google_search
"function_call"	Dateitools und andere	[tool] read_file (/workspace/...)
step.delta, wobei delta.type == "text"	Supportmitarbeiter schreibt Text	direkt an stdout gestreamt

5. Agent anpassen

Der Agent hatte keine Anweisungen: keine Stimme, keine Funktion, kein PDF-Generator. In diesem Schritt laden Sie die Konfigurationsdateien aus .agents/ und stellen sie in der Sandbox bereit.

Dies ist die schnellste Methode, um einen benutzerdefinierten Agent zu erstellen. Sie passen den Antigravity-Agent für diesen Lauf an, ohne etwas zu registrieren. Im nächsten Schritt wird gezeigt, wie Sie diese Konfiguration dauerhaft in einen benannten Agent einbinden, damit Sie Quellen nie wieder übergeben müssen.

Was soll geändert werden?

Nehmen Sie vier Änderungen an run_digest.py vor:

TODO 2:Fügen Sie unter load_source() die drei Konstanten auf Modulebene hinzu (diese befinden sich außerhalb von run_digest(), oben in der Datei):

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")

Öffnen Sie jede Datei, um zu sehen, was Sie laden: AGENTS.md legt die redaktionelle Stimme und die Workflowregeln fest, SKILL.md ist das schrittweise PDF-Playbook und generate_pdf.py ist der vorgefertigte Renderer, den der Agent ausführt.

Warum AGENTS.md statt system_instruction? Die Interactions API akzeptiert auch direkt einen system_instruction-Stringparameter. Beide Ansätze funktionieren und ergänzen sich, wenn sie zusammen verwendet werden. AGENTS.md ist hier besser geeignet, da sie sich zusammen mit Ihrem Code im Repository befindet, mit dem Rest des Projekts versionsverwaltet wird und ab dem ersten Token immer im Kontext des Agents liegt. Verwenden Sie system_instruction für schnelle Anpassungen pro Anruf und AGENTS.md für ausführliche Personadefinitionen und Richtlinien, die Sie zusammen mit Ihrem Agenten versionieren möchten.

Ist input wichtig, wenn AGENTS.md geladen wird? Sobald AGENTS.md über sources bereitgestellt wird, wird der vollständige Workflow definiert: welche Quellen abgerufen werden sollen, wie zusammengefasst werden soll und wo die PDF-Datei gespeichert werden soll. Das Feld input kann leer sein (""). Der Agent liest AGENTS.md beim Start und fährt autonom fort. Sie können weiterhin einen Prompt übergeben, um die Anweisungen für einen bestimmten Lauf zu überschreiben oder zu erweitern. Das ist aber nicht erforderlich.

Nehmen Sie nun zwei weitere Änderungen in run_digest() vor:

TODO 3:Ändern Sie environment von "remote" in das Quellen-Dictionary und legen Sie input auf "" fest:

        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:Fügen Sie diese Zeilen direkt nach print(f"\nDone. environment_id={environment_id}") ein:

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

(set_key wird bereits oben in run_digest.py importiert.)

Dadurch werden beide IDs in .env geschrieben. Im nächsten Schritt kann das PDF also heruntergeladen werden, ohne dass der Agent noch einmal ausgeführt werden muss.

Funktionsweise der einzelnen Quellen

Jede Quelle ist eine Datei, die beim Start in das Sandbox-Dateisystem eingebunden wird, bevor der Agent ausgeführt wird. Die target-Pfade stimmen mit den Pfaden überein, unter denen das Antigravity-Harness die Dateien erwartet:

.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

Pfad zu target	Variable	Was das Geschirr damit macht
.agents/AGENTS.md	AGENTS_MD	Automatisch geladen als dauerhafte Anweisungen: redaktioneller Stil, Workflow, Ausführungsregeln
.agents/skills/digest-pdf/SKILL.md	SKILL_MD	Automatisch erkannt und als benannter Skill registriert; der Agent ruft ihn über den Namen auf
.agents/skills/digest-pdf/scripts/generate_pdf.py	GENERATE_PDF_PY	Vordefinierter PDF-Renderer: Der Agent schreibt summaries.json und führt dann dieses Skript aus.

Skills sind ein plattformübergreifender Standard (agentskills.io). Sie geben dem KI-Agenten ein prozedurales Gedächtnis: nicht nur, was er wissen muss, sondern auch, wie er eine bestimmte Aufgabe Schritt für Schritt ausführt. Der Text von SKILL.md wird nur geladen, wenn der Skill ausgelöst wird. Metadaten (Name + Beschreibung) bleiben die ganze Zeit im Kontext. Das wird als progressive Offenlegung bezeichnet und sorgt dafür, dass das Kontextfenster übersichtlich bleibt.

Dabei sind zwei Dinge zu beachten:

• Skill vs. AGENTS.md: AGENTS.md befindet sich ab dem ersten Token immer im Kontext des Agenten: Stimme, Workflow-Regeln, Ausführungseinschränkungen. SKILL.md wird nur bei Bedarf geladen, wenn der KI-Agent entscheidet, dass die Skill für die Aufgabe benötigt wird. AGENTS.md sollte kurz gehalten werden. Das empfohlene Muster ist, unten einen kurzen Katalog mit den verfügbaren Skills aufzunehmen, damit der Agent weiß, wonach er suchen muss. Die Tabelle ## Skills in .agents/AGENTS.md ist genau das: Sie informiert den KI-Agenten darüber, dass digest-pdf vorhanden ist, sodass das Harness die vollständige SKILL.md laden kann, wenn die Aufgabe dies erfordert.
• Verwaltete KI-Agents im Vergleich zum ADK: Das ADK verwendet den programmatischen Ansatz: load_skill_from_dir("skills/digest-pdf") und dann SkillToolset(skills=[skill]) in Python-Code. Bei verwalteten Agents verwenden Sie den Inline-Pfad: Sie hängen die Datei über environment.sources ein und das Harness erkennt sie automatisch über .agents/skills/*/SKILL.md. Kein Registrierungscode.

Bestätigen

uv run python run_digest.py

Die Ausführung dauert jetzt 1–3 Minuten. Sie sollten sehen, dass der Agent Konfigurationsdateien liest, Zusammenfassungen schreibt und die PDF-Datei speichert:

[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 ist jetzt ein echter Wert: Die Sandbox wurde mit Ihren Konfigurationsdateien ausgeführt und der Agent hat digest.pdf erstellt. Im nächsten Schritt wird sie heruntergeladen.

6. PDF herunterladen

Der Agent hat digest.pdf in /workspace/digest.pdf in der Sandbox geschrieben. Der Umgebungs-Snapshot ist als TAR-Archiv über die Gemini Files API verfügbar.

In einem echten Projekt würde der Download direkt nach der Ereignisschleife in run_digest() erfolgen (gleicher Lauf, gleiches environment_id, keine separate Datei). In diesem Codelab befindet sie sich in download_pdf.py, sodass Sie sie herunterladen können, ohne den Agenten noch einmal auszuführen. Durch die set_key-Zeilen, die Sie im vorherigen Schritt hinzugefügt haben, werden beide IDs automatisch in .env geschrieben. Diese Datei kann sie also direkt lesen.

Installieren Sie requests, falls erforderlich:

uv pip install requests

Was muss ausgefüllt werden?

Öffnen Sie download_pdf.py. Es enthält zwei TODOs.

TODO 1:Füllen Sie den requests.get()-Aufruf aus:

    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()

Die URL verweist auf den Sandbox-Snapshot. params={"alt": "media"} gibt Rohbytes anstelle von Metadaten zurück. Mit Ihrem vorhandenen GEMINI_API_KEY wird auch die Files API authentifiziert.

TODO 2:Suchen Sie das PDF im TAR-Archiv und extrahieren Sie es:

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

Das Tar-Pfadpräfix variiert je nach Ausführung. Suchen Sie daher nach dem Suffix, anstatt den genauen Pfad fest zu codieren. filter="data" unterdrückt die Python 3.13-Warnung zur Einstellung der Unterstützung für unsichere tar-Extraktion.

Bestätigen

uv run python download_pdf.py

Saved digest.pdf (48,231 bytes)

Öffnen Sie digest.pdf im selben Verzeichnis. Sie enthält die formatierte Zusammenfassung, die der Agent aus Live-Webseiten generiert hat.

7. Unterhaltung fortsetzen

Sie haben bereits digest.pdf. Wenn Sie nur die Datei haben wollten, sind Sie fertig. In diesem Schritt geht es um etwas anderes: Der KI-Agent wird aufgefordert, das Kurzfassungsergebnis zu ändern, ohne die Webseiten noch einmal abzurufen.

Die Sandbox ist noch aktiv. Der KI-Agent hat weiterhin /workspace/digest.pdf und erinnert sich an jede Geschichte, die er zusammengefasst hat. Mit einem zweiten interactions.create()-Aufruf wird eine Follow-up-Nachricht in dieselbe Sandbox gesendet. Hier wird darum gebeten, unter jedem Beitrag eine Anmerkung zum Thema „Warum das wichtig ist“ hinzuzufügen. Das PDF wird dann aktualisiert, ohne dass die Inhalte neu abgerufen oder zusammengefasst werden müssen.

Was muss ausgefüllt werden?

Öffnen Sie refine_digest.py. Es gibt drei TODOs.

TODO 1 und 2:Füllen Sie die beiden Parameter für mehrere Durchgänge in interactions.create() aus:

    environment=environment_id,
    previous_interaction_id=interaction_id,

environment=environment_id setzt dieselbe Sandbox mit ihren Dateien und Paketen fort. previous_interaction_id=interaction_id stellt dem Agenten den Unterhaltungsverlauf zur Verfügung. Ansonsten ändert sich nichts im Vergleich zum ersten Aufruf.

TODO 3:Speichern Sie den neuen interaction_id nach der Ereignisschleife wieder in .env:

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

Bei jedem interactions.create()-Aufruf wird ein neues interaction_id erstellt. Wenn Sie sie zurückschreiben, wird diese Optimierung beim nächsten Lauf als previous_interaction_id übergeben und die Turns werden richtig verkettet. Die Sandbox-ID ändert sich nie. Daher muss ENVIRONMENT_ID nicht aktualisiert werden.

Die beiden Parameter, die die Funktion für mehrere aufeinanderfolgende Anfragen ermöglichen

ID	Was wird beibehalten?	Analogie
environment=environment_id	Dateien, installierte Pakete, Systemstatus: alles im Linux-Dateisystem	Zwischen Besprechungen am selben Schreibtisch bleiben
previous_interaction_id=interaction_id	Unterhaltungsverlauf: Was der Agent in früheren Runden gesagt und getan hat	Erinnern Sie sich an das, was im letzten Meeting besprochen wurde.

Sie können eine der beiden IDs unabhängig voneinander übergeben:

• environment_id: Dateien und Pakete wiederverwenden, aber eine neue Unterhaltung starten. Nützlich für eine neue Aufgabe im selben Arbeitsbereich.
• previous_interaction_id: Der Kontext der Unterhaltung wird fortgesetzt, aber in einer neuen Sandbox (Dateien sind nicht mehr vorhanden).
• Beide: volle Kontinuität, die in diesem Schritt verwendet wird.

Ohne environment_id: leere Sandbox, kein PDF. Ohne previous_interaction_id: kein Kontext, der Kundenservicemitarbeiter kann keinen bestimmten Abschnitt optimieren.

Dies ersetzt die Sitzungsverwaltung, die Sie mit dem ADK + Cloud Run schreiben würden. Mit dem ADK speichern Sie den Unterhaltungsverlauf in einer Datenbank und fügen ihn in jede Anfrage ein. Bei verwalteten Agenten übergeben Sie zwei IDs und die Plattform erledigt den Rest.

Bestätigen

uv run python refine_digest.py

Der Stream sollte schnell sein, da der Kundenservicemitarbeiter nichts neu abruft. Danach:

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

Öffnen Sie digest_v2.pdf und vergleichen Sie sie mit digest.pdf. Jeder Geschichte sollte nun eine Zeile „Warum das wichtig ist“ hinzugefügt werden.

8. Verwaltete Agent-Konfiguration beibehalten

Bisher wurden bei jedem Aufruf AGENTS.md, SKILL.md und generate_pdf.py inline übergeben. Das funktioniert, aber Ihr Aufrufcode überträgt bei jeder Ausführung den gesamten Dateiinhalt. agents.create() speichert die Konfiguration in einem benannten Agent auf Google-Seite. Beim nächsten Aufruf wird nur die Agenten-ID übergeben:

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

Was muss ausgefüllt werden?

Öffnen Sie save_agent.py. Es enthält einen TODO-Kommentar (TODO 1).

AGENTS_MD, SKILL_MD und GENERATE_PDF_PY werden aus run_digest.py importiert. Achten Sie darauf, dass Sie den Schritt „Anpassen“ abgeschlossen und die drei Ladezeilen hinzugefügt haben, bevor Sie diese Datei ausführen.

Die Konstanten werden direkt aus run_digest.py importiert (keine Duplizierung):

from run_digest import BASE_AGENT, AGENTS_MD, SKILL_MD, GENERATE_PDF_PY

TODO 1:Füllen Sie den agents.create()-Aufruf aus:

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 (nicht environment) ist der Hauptunterschied zum Inline-Aufruf im vorherigen Schritt: Die Quellen werden auf der Seite von Google gespeichert und bei jedem zukünftigen Aufruf automatisch eingebunden. Führen Sie sie nur einmal aus, nicht bei jeder Zusammenfassung.

Bestätigen: Agent speichern

uv run python save_agent.py

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

409-Fehler – Konflikt Ein Agent mit dem Namen my-digest ist bereits aus einem vorherigen Lauf vorhanden. Die Starterdatei löscht sie automatisch, bevor eine neue erstellt wird. Daher ist es kein Problem, den Vorgang noch einmal auszuführen.

Gespeicherten Agent aufrufen

Öffnen Sie invoke_agent.py. Der gespeicherte Agent wird anhand der ID ohne Quellen aufgerufen:

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

Vergleichen Sie dies mit dem Inline-Aufruf: agent=BASE_AGENT wird durch "my-digest" ersetzt und der vollständige environment-Block mit drei Inline-Quellen wird durch environment="remote" ersetzt. Die Konfiguration ist bereits auf Google-Seite integriert.

Überprüfen: Gespeicherten Agenten aufrufen

uv run python invoke_agent.py

Sie sollten denselben Livestream wie beim Inline-Lauf sehen, aber der Aufruf enthält keine Quelldateien. Nach dem Lauf werden ENVIRONMENT_ID und INTERACTION_ID in .env aktualisiert, sodass Sie wie gewohnt mit refine_digest.py fortfahren können.

[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. Bereinigen

Die Sandbox läuft nach 7 Tagen Inaktivität automatisch ab. Es gibt keine Server, die beendet werden können. Es sind keine Container zum Löschen vorhanden.

Wenn Sie eine Agent-Konfiguration gespeichert haben, löschen Sie sie:

uv run python delete_agent.py

10. Zusammenfassung

Sie haben einen verwalteten Agent von Grund auf erstellt, jeweils ein Konzept nach dem anderen. Das haben Sie in den einzelnen Übungen gelernt:

Training	Konzept	Key API
Ersten Anruf starten	Eine echte Linux-Sandbox bereitstellen und ihre Ereignisse live streamen	interactions.create(agent, input, environment, stream=True), event.event_type
Agent anpassen	Konfigurationsdateien bereitstellen; IDs im selben Lauf in .env beibehalten	environment.sources, set_key
PDF herunterladen	PDF herunterladen, ohne den Agenten noch einmal auszuführen	Gemini Files API :download in download_pdf.py
Unterhaltung fortsetzen	Unterhaltung fortsetzen, ohne das Web neu abzurufen	environment=environment_id, previous_interaction_id=interaction_id
KI-Agentenkonfiguration beibehalten	Agent-Konfiguration beibehalten; Aufruf über ID, keine Quellen erforderlich	agents.create(), agents.list()

Schlüsselmuster

1. Ein Aufruf, eine Sandbox: interactions.create() übernimmt die gesamte Infrastruktur (keine Container zum Bereitstellen, keine Pakete zur lokalen Installation)
2. Progressives Streaming: stream=True verwandelt eine 90-sekündige Blackbox in einen Live-Feed von Tool-Aufrufen und Textblöcken.
3. Inline-Quellen: AGENTS.md, SKILL.md und vorgefertigte Skripts ohne Upload- oder Bereitstellungsschritt in die Sandbox einbinden
4. Automatische Erkennung von Harness: Dateien, die in .agents/ platziert werden, werden automatisch erkannt (keine SDK-Konfiguration erforderlich).
5. Zweidimensionaler Status: environment_id verfolgt Dateien und Pakete, previous_interaction_id verfolgt den Unterhaltungskontext. Beide können unabhängig voneinander übergeben werden.
6. Snapshot-Download: Die Umgebung ist ein vollständiges Dateisystem-Tar, auf das über die Gemini Files API zugegriffen werden kann.
7. Benannte Agents: agents.create() wird dauerhaft konfiguriert. Bei zukünftigen Aufrufen werden nur die Agent-ID und environment="remote" ohne Quellen übergeben.

ADK + Cloud Run im Vergleich zu verwalteten Agents: der Unterschied auf einen Blick

Funktion	ADK + Cloud Run	Verwaltete KI-Agenten in der Gemini API
Sandbox bereitstellen	docker build + gcloud run deploy	interactions.create()
Tools definieren	Beim Agenten registrierte Python-Funktionen	Integrierte Tools: Websuche, Codeausführung, Dateisystem
Pakete installieren	pip install im Dockerfile	KI-Agent führt pip install in der Sandbox aus
Stream-Ereignisse	Benutzerdefinierte SSE-Infrastruktur	stream=True
Sitzung fortsetzen	Sitzungsdatenbank + Kontextinjektion	environment_id + previous_interaction_id
Konfigurationsdateien	Im Agent hartcodiert oder beim Start eingefügt	Eingebunden über environment.sources
Zu verwaltende Infrastruktur	Container, Cloud Run, IAM, Secrets	Keine

Nächste Schritte

• Dokumentation zu verwalteten KI-Agenten in der Gemini API lesen