Creare un agente di riepilogo tecnico gestito con l'API Gemini

1. Panoramica

Il panorama dell'AI e della tecnologia si muove più velocemente di quanto chiunque possa tenere traccia. Ogni giorno vengono rilasciati nuovi modelli, articoli e prodotti. Un agente di riepilogo che recupera i titoli di oggi, scrive riepiloghi concisi e genera un PDF ogni mattina risolverebbe il problema, ma in passato la creazione di un agente di questo tipo richiedeva la scelta di un framework, la definizione di strumenti in Python, la scrittura di un ciclo di orchestrazione, il packaging di un container e il deployment su Cloud Run. Tutto questo prima che l'agente avesse effettuato una sola richiesta web.

Managed Agents nell'API Gemini cambia l'equazione. Scrivi due file di configurazione Markdown e uno script di rendering predefinito, effettua una chiamata API e viene avviata una sandbox Ubuntu reale, che naviga sul web, scrive i riepiloghi e genera un PDF. Nessun contenitore. Nessun deployment. Nessun codice di orchestrazione.

In questo codelab creerai esattamente questo agente: da una funzione vuota a un riepilogo giornaliero funzionante, un concetto alla volta.

Cosa creerai

• Crea ed esegui il tuo primo agente gestito in una sandbox Linux reale
• Personalizzare l'agente con istruzioni dettagliate
• Scarica l'output PDF dell'agente
• Continua la conversazione per perfezionare il riepilogo senza recuperare nuovamente il web
• Salva la configurazione dell'agente e richiamala per ID nelle esecuzioni future

Che cosa ti serve

• Python 3.10+
• Una chiave API Gemini con la fatturazione abilitata: aistudio.google.com/api-keys
• ~1 $ di credito API (ogni esecuzione completa costa 0,30-1,30 $)

2. Che cosa sono gli agenti gestiti nell'API Gemini?

Tre livelli di sistemi AI

Prima di passare al codice, ecco dove si inseriscono gli agenti gestiti rispetto alle due alternative:

Livello	Descrizione	Chi gestisce l'infrastruttura?
LLM standard	Tu inserisci un prompt e lui risponde con un testo. Nessuna mano, nessuna memoria, nessun internet.	N/A: non può fare nulla da solo
Agente self-hosted	Colleghi ADK/LangChain/AutoGen + Docker + strumenti + memoria.	Tu: tutto (o una piattaforma gestita come Agent Engine)
Agente gestito	Assegni un obiettivo. Google esegue il provisioning di una sandbox sicura. L'agente scrive il codice, lo esegue, legge gli errori, esegue ricerche sul web e corregge i bug in modo autonomo.	Google: tutto

Questo codelab riguarda la terza riga. Fornisci un file di attività e di configurazione. Google si occupa di tutto il resto.

Cosa creeresti con ADK + Cloud Run

Per creare un agente di riepilogo delle notizie che naviga sul web, esegue Python e genera un PDF, avresti bisogno di tutto questo con ADK + 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

Prima che l'agente venga eseguito per la prima volta. Mantieni l'isolamento della sandbox (in modo che l'agente non possa danneggiare il server), l'installazione dei pacchetti, la gestione dello stato tra le chiamate agli strumenti e l'infrastruttura di streaming per inviare eventi a un client.

Con cosa lo sostituisce Managed Agents

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

Requisiti di ADK + Cloud Run	Cosa gestiscono gli agenti gestiti per te
Immagine container + Dockerfile + CI/CD	Sandbox Ubuntu completamente gestita (Python 3.12, Node 22, 4 CPU / 16 GB di RAM)
Deployment e scalabilità di Cloud Run	Fornito per interazione, scade automaticamente dopo 7 giorni di inattività
Isolamento della sandbox	Isolato per interazione
Strumento PDF personalizzato + pip install	L'agente installa i pacchetti all'interno della sandbox
Infrastruttura di streaming SSE	stream=True restituisce un iterabile di eventi
Definizioni degli strumenti in Python	Strumenti integrati: navigazione web, esecuzione del codice, file system
Gestione dello stato tra le chiamate di strumenti	Integrato nel ciclo di ragionamento dell'agente

Scrivi i file di configurazione (AGENTS.md, SKILL.md, uno script predefinito) ed esegui una chiamata API. Google si occupa di tutto il resto.

Come funziona la 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

La sandbox viene mantenuta per 7 giorni di inattività. Puoi riprenderlo con environment_id per perfezionare l'output, eseguire attività di follow-up o creare una copia in un agente denominato salvato.

3. Configura

Opzione A: Cloud Shell (consigliata)

Fai clic sul pulsante di seguito per aprire questo codelab in Google Cloud Shell. Tutte le dipendenze sono preinstallate.

Apri in Cloud Shell

Opzione B: configurazione locale

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

Installa uv, se necessario:

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

Configura la chiave API

cp .env.example .env
cloudshell edit .env

Imposta la chiave:

GEMINI_API_KEY=your-key-here

Fatturazione obbligatoria. Gli agenti gestiti nell'API Gemini addebitano l'utilizzo dei token. Ogni esecuzione completa del digest costa circa 0,30-1,30 $. Il calcolo dell'ambiente (CPU, memoria, esecuzione della sandbox) è senza costi durante il periodo di anteprima. Il livello senza costi non copre l'API Interactions: aggiungi crediti prepagati all'indirizzo aistudio.google.com/billing.

Installa le dipendenze

uv sync

4. Effettuare la prima chiamata all'agente

Aprire il file iniziale

cloudshell edit run_digest.py

Configurazione locale:apri run_digest.py nell'editor che preferisci.

run_digest() ha un TODO da compilare ora e altri tre per il passaggio successivo. Sopra sono già precompilati due helper:

• load_source(path): legge un file da .agents/ rispetto allo script. Lo utilizzerai nel prossimo esercizio per montare la linea editoriale, la guida pratica PDF e il renderer nella sandbox.
• run_stream(stream): elabora il flusso di eventi e restituisce (environment_id, interaction_id). Non devi scrivere personalmente il ciclo di eventi.

Cosa aggiungere

DA FARE 1: sostituisci pass con (ignora i DA FARE 3 e 4 per ora, li vedremo nel passaggio successivo):

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

A cosa serve ogni parte

genai.Client() legge GEMINI_API_KEY dall'ambiente. Tutto il resto passa attraverso questo client.

interactions.create() è la chiamata principale. Perché funzioni, sono necessari quattro parametri:

• agent=BASE_AGENT: seleziona l'agente Antigravity (antigravity-preview-05-2026), un agente gestito per uso generico basato su Gemini 3.5 Flash. Viene fornito con tre strumenti integrati attivati per impostazione predefinita: code_execution (esegui Bash, Python, Node.js), google_search e url_context (recupera e leggi pagine web). Gli strumenti del file system (read_file, write_file, list_files) vengono attivati automaticamente quando passi il parametro environment. Una chiamata esegue il provisioning di un ambiente Ubuntu completamente gestito con Python 3.12, Node.js 22, git, pip e curl preinstallati. Nessun container da creare, nessun deployment da eseguire.
• input: l'attività per questa esecuzione. L'agente sfoglia Hacker News e ragiona sui risultati.
• environment="remote": esegue il provisioning di una nuova sandbox cloud per questa interazione.
• stream=True: restituisce un iterabile di eventi anziché bloccare. Senza, la chiamata attende 30-90 secondi e restituisce tutto l'output contemporaneamente come interaction.output_text. Con lo streaming, vedi il motivo dell'agente e agisci in tempo reale. Lo streaming non è una funzionalità avanzata: è l'impostazione predefinita corretta, perché una scatola nera di 90 secondi non ti dà alcun segnale se l'agente sta lavorando o è bloccato.

Elementi appena sottoposti a provisioning:ogni chiamata interactions.create() avvia una sandbox dedicata:

Componente	Specifica
Sistema operativo	Ambiente Ubuntu Linux isolato
Runtime preinstallati	Python 3.12, Node.js 22, Bash
Computing	4 core CPU, 16 GB di RAM
Gestione del contesto	La compressione automatica viene attivata a circa 135.000 token
Networking	Accesso web in uscita tramite il proxy in uscita

L'agente può installare qualsiasi pacchetto con pip o npm, leggere e scrivere file ed effettuare richieste web in uscita. Il tuo computer e le tue credenziali non vengono mai toccati.

environment_id è un handle della sandbox appena eseguita. Dopo interaction.completed, la sandbox non viene chiusa, ma rimane attiva per un massimo di 7 giorni. Il environment_id ti consente di tornare alla pagina. Passa a una seconda interactions.create() chiamata e l'agente riprende lo stesso file system, con gli stessi file e pacchetti installati, come se non avesse mai interrotto la chiamata. Il passaggio successivo lo utilizza per scaricare il PDF senza eseguire nuovamente l'agente, mentre il passaggio successivo lo utilizza per continuare la conversazione.

interaction_id è un handle del turno di conversazione appena completato. Passalo come previous_interaction_id nella chiamata successiva e l'agente avrà piena memoria di ciò che ha detto e fatto in questo turno.

Verifica

uv run python run_digest.py

Dovresti vedere l'output in tempo reale mentre l'agente lavora:

[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

L'API restituisce un environment_id reale anche con environment="remote". La sandbox è stata eseguita. Ciò che manca è la configurazione: nessuna voce, nessuna skill, nessun generatore di PDF. L'agente ha stampato le storie come testo e si è fermato. Il passaggio successivo aggiunge questi dati.

Perché run_code e non url_context? L'agente ha a disposizione tre strumenti web (code_execution, google_search, url_context) e li sceglie in autonomia. Per lo scraping strutturato (estrazione di punteggi, link e conteggi dei commenti), in genere preferisce code_execution: scrive uno script Python requests, lo esegue nella sandbox e analizza l'HTML in Python completo. Potresti visualizzare url_context in altre esecuzioni; entrambi sono validi.

Ogni riga di output corrisponde a un evento di run_stream():

step.type	Descrizione	Cosa stampa run_stream()
"url_context_call"	agente che recupera un URL	[tool] url_context (https://...)
"code_execution_call"	agente che esegue il codice nella sandbox	[tool] run_code
"google_search_call"	agente che cerca sul web	[tool] google_search
"function_call"	strumenti per i file e altri	[tool] read_file (/workspace/...)
step.delta dove delta.type == "text"	L'agente sta scrivendo	trasmesso in streaming direttamente a stdout

5. Personalizzare l'agente

L'agente non aveva istruzioni: nessuna voce, nessuna skill, nessun generatore di PDF. In questo passaggio carichi i file di configurazione da .agents/ e li monti nella sandbox.

Questo è il modo più rapido per creare un agente personalizzato. Stai personalizzando l'agente Antigravity per questa corsa senza registrare nulla. Il passaggio successivo mostra come incorporare definitivamente questa configurazione in un agente denominato in modo da non dover più passare le origini.

Cosa modificare

Apporta quattro modifiche a run_digest.py:

TODO 2: sotto load_source(), aggiungi le tre costanti a livello di modulo (si trovano al di fuori di run_digest(), nella parte superiore del file):

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

Apri ogni file per vedere cosa stai caricando: AGENTS.md imposta le regole di workflow e la linea editoriale; SKILL.md è la guida pratica PDF passo passo; generate_pdf.py è il renderer predefinito che verrà eseguito dall'agente.

Perché AGENTS.md invece di system_instruction? L'API Interactions accetta anche un parametro stringa system_instruction direttamente. Entrambi gli approcci funzionano e sono complementari se utilizzati insieme. AGENTS.md è la soluzione migliore in questo caso perché si trova insieme al codice nel repository, è controllato a livello di versione con il resto del progetto ed è sempre nel contesto dell'agente fin dal primo token. Utilizza system_instruction per modifiche rapide per chiamata; utilizza AGENTS.md per definizioni e linee guida dettagliate delle buyer persona che vuoi versionare insieme al tuo agente.

input ha importanza quando viene caricato AGENTS.md? Una volta montato AGENTS.md tramite sources, definisce l'intero flusso di lavoro: quali fonti recuperare, come riassumere e dove salvare il PDF. Il campo input può essere vuoto (""). L'agente legge AGENTS.md all'avvio e procede in autonomia. Puoi comunque passare un prompt per ignorare o estendere le istruzioni per un'esecuzione specifica, ma non è obbligatorio.

Ora apporta altre due modifiche all'interno di run_digest():

TODO 3: modifica environment da "remote" al dizionario delle origini e imposta input su "":

        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: aggiungi queste righe subito dopo print(f"\nDone. environment_id={environment_id}"):

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

(set_key è già stato importato nella parte superiore di run_digest.py.)

In questo modo, entrambi gli ID vengono scritti in .env durante l'esecuzione, quindi il passaggio successivo può scaricare il PDF senza eseguire nuovamente l'agente.

A cosa serve ogni origine

Ogni origine è un file montato nel file system della sandbox all'avvio prima dell'esecuzione dell'agente. I percorsi target corrispondono a quelli in cui la pettorina Antigravity prevede di trovarli:

.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

Percorso target	Variabile	Cosa fa la pettorina
.agents/AGENTS.md	AGENTS_MD	Caricamento automatico come istruzioni persistenti: linea editoriale, workflow, regole di esecuzione
.agents/skills/digest-pdf/SKILL.md	SKILL_MD	Rilevata e registrata automaticamente come competenza denominata; l'agente la richiama per nome
.agents/skills/digest-pdf/scripts/generate_pdf.py	GENERATE_PDF_PY	Renderer PDF predefinito; l'agente scrive summaries.json e poi esegue questo script

Le skill sono uno standard multipiattaforma (agentskills.io). Forniscono all'agente una memoria procedurale: non solo cosa sapere, ma come svolgere un'attività specifica passo dopo passo. Il corpo di SKILL.md viene caricato solo quando viene attivata la skill; i metadati (nome + descrizione) rimangono nel contesto per tutto il tempo. Questa tecnica è chiamata divulgazione progressiva e mantiene pulita la finestra contestuale.

Ecco due aspetti da notare:

• Skill vs AGENTS.md: AGENTS.md si trova sempre nel contesto dell'agente dal primo token: voce, regole del flusso di lavoro, vincoli di esecuzione. SKILL.md viene caricata on demand solo quando l'agente decide che la skill è necessaria per l'attività. AGENTS.md deve rimanere conciso; il pattern consigliato è quello di includere un breve catalogo in basso che elenca le skill disponibili, in modo che l'agente sappia cosa cercare. La tabella ## Skills in .agents/AGENTS.md è esattamente questo: indica all'agente che digest-pdf esiste, in modo che l'imbracatura possa caricare il relativo SKILL.md completo quando l'attività lo richiede.
• Agenti gestiti e ADK: ADK utilizza il percorso programmatico: load_skill_from_dir("skills/digest-pdf") e poi SkillToolset(skills=[skill]) nel codice Python. Con gli agenti gestiti utilizzi il percorso incorporato: monta il file tramite environment.sources e l'imbracatura lo rileva automaticamente da .agents/skills/*/SKILL.md. Nessun codice di registrazione.

Verifica

uv run python run_digest.py

L'esecuzione ora richiede 1-3 minuti. Dovresti vedere l'agente leggere i file di configurazione, scrivere i riepiloghi e salvare il 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 ora è un valore reale: la sandbox è stata eseguita con i file di configurazione e l'agente ha creato digest.pdf. Il passaggio successivo consiste nel scaricarlo.

6. Scarica il PDF

L'agente ha scritto digest.pdf a /workspace/digest.pdf all'interno della sandbox. Lo snapshot dell'ambiente è disponibile come archivio tar tramite l'API Gemini Files.

In un progetto reale, il download si troverebbe all'interno di run_digest() subito dopo il ciclo di eventi (stessa esecuzione, stesso environment_id, nessun file separato). In questo codelab si trova in download_pdf.py, quindi puoi scaricarlo di nuovo senza eseguire di nuovo l'agente. Le righe set_key che hai aggiunto nel passaggio precedente scrivono automaticamente entrambi gli ID in .env, quindi questo file può leggerli immediatamente.

Installa requests, se necessario:

uv pip install requests

Cosa compilare

Apri download_pdf.py. Ha due cose da fare.

TODO 1: compila la chiamata 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()

L'URL indirizza lo snapshot della sandbox. params={"alt": "media"} restituisce byte non elaborati anziché metadati. Il tuo GEMINI_API_KEY esistente autentica anche l'API Files.

TODO 2: trova ed estrai il PDF dall'archivio tar:

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

Il prefisso del percorso tar varia a seconda delle esecuzioni, quindi esegui la ricerca per suffisso anziché codificare il percorso esatto. filter="data" sopprime l'avviso di ritiro di Python 3.13 relativo all'estrazione di tar non sicura.

Verifica

uv run python download_pdf.py

Saved digest.pdf (48,231 bytes)

Apri digest.pdf nella stessa directory. Contiene il riepilogo formattato generato dall'agente dalle pagine web pubblicate.

7. Continua la conversazione

Hai già digest.pdf. Se volevi solo il file, hai finito. Questo passaggio riguarda un'altra operazione: chiedere all'agente di modificare il riepilogo senza recuperare nuovamente i contenuti web.

La sandbox è ancora attiva. L'agente ha ancora /workspace/digest.pdf e ricorda ogni storia che ha riassunto. Una seconda chiamata interactions.create() invia un messaggio di follow-up nella stessa sandbox. Qui chiedi di aggiungere una nota "Perché è importante" sotto ogni storia e il PDF viene aggiornato sul posto, senza recupero e riepilogo.

Cosa compilare

Apri refine_digest.py. Ha tre cose da fare.

TODO 1 e 2: compila i due parametri multi-turn all'interno di interactions.create():

    environment=environment_id,
    previous_interaction_id=interaction_id,

environment=environment_id ripristina la stessa sandbox con i relativi file e pacchetti. previous_interaction_id=interaction_id fornisce all'agente la cronologia delle conversazioni. Nessun altro elemento cambia rispetto alla prima chiamata.

TODO 3: mantieni il nuovo interaction_id di nuovo su .env dopo il ciclo di eventi:

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

Ogni chiamata interactions.create() produce un nuovo interaction_id. La riscrittura significa che l'esecuzione successiva passa questo perfezionamento come previous_interaction_id, concatenando correttamente i turni. L'ID sandbox non cambia mai, quindi non è necessario aggiornare ENVIRONMENT_ID.

I due parametri che consentono il funzionamento della conversazione multi-turno

ID	Che cosa conserva	Analogia
environment=environment_id	File, pacchetti installati, stato del sistema: tutto ciò che si trova nel file system Linux	Mantenere la stessa scrivania tra una riunione e l'altra
previous_interaction_id=interaction_id	Cronologia della conversazione: cosa ha detto e fatto l'agente nei turni precedenti	Ricordare cosa è stato discusso nell'ultima riunione

Puoi superare la verifica di uno dei due ID in modo indipendente:

• environment_id: riutilizza file e pacchetti, ma inizia una nuova conversazione. Utile per una nuova attività nello stesso spazio di lavoro.
• previous_interaction_id: continua il contesto della conversazione, ma in una nuova sandbox (i file non sono più presenti).
• Entrambi: continuità completa, che è ciò che utilizza questo passaggio.

Senza environment_id: sandbox vuota, nessun PDF. Senza previous_interaction_id: nessun contesto, l'agente non può perfezionare una sezione specifica.

Questo sostituisce la gestione delle sessioni che scriveresti con ADK + Cloud Run. Con ADK, memorizzi la cronologia delle conversazioni in un database e la inserisci in ogni richiesta. Con gli agenti gestiti, passi due ID e la piattaforma si occupa del resto.

Verifica

uv run python refine_digest.py

Lo streaming dovrebbe essere veloce, l'agente non recupera nulla. Al termine:

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

Apri digest_v2.pdf e confrontalo con digest.pdf. Ogni storia dovrebbe ora avere una riga "Perché è importante".

8. Persistenza di una configurazione dell'agente gestita

Tutte le chiamate finora hanno superato AGENTS.md, SKILL.md e generate_pdf.py inline. Funziona, ma il codice di chiamata trasporta l'intero contenuto del file a ogni esecuzione. agents.create() incorpora la configurazione in un agente denominato salvato sul lato di Google. La chiamata successiva passa solo l'ID agente:

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

Cosa compilare

Apri save_agent.py. Contiene un TODO (TODO 1).

AGENTS_MD, SKILL_MD e GENERATE_PDF_PY vengono importati da run_digest.py. Assicurati di aver completato il passaggio Personalizza e di aver aggiunto le tre righe di caricamento prima di eseguire questo file.

Tieni presente che le costanti vengono importate direttamente da run_digest.py (senza duplicazione):

from run_digest import BASE_AGENT, AGENTS_MD, SKILL_MD, GENERATE_PDF_PY

TODO 1: compila la chiamata 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 (non environment) è la differenza principale rispetto alla chiamata inline nel passaggio precedente: le origini vengono archiviate lato Google e montate automaticamente a ogni invocazione futura. Esegui una volta, non a ogni esecuzione del riepilogo.

Verifica: salva l'agente

uv run python save_agent.py

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

Conflitto 409? Esiste già un agente denominato my-digest da un'esecuzione precedente. Il file iniziale lo elimina automaticamente prima di crearne uno nuovo, quindi la riesecuzione è sicura.

Richiamare l'agente salvato

Apri invoke_agent.py. Chiama l'agente salvato per ID senza origini:

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

Confronta questo risultato con la chiamata inline: agent=BASE_AGENT viene sostituito da "my-digest" e l'intero blocco environment con tre fonti inline viene sostituito da environment="remote". La configurazione è già integrata nel sistema di Google.

Verifica: richiama l'agente salvato

uv run python invoke_agent.py

Dovresti vedere lo stesso live streaming dell'esecuzione in linea, ma la chiamata non contiene file di origine. Dopo la corsa, ENVIRONMENT_ID e INTERACTION_ID in .env vengono aggiornati in modo da poter continuare con refine_digest.py come prima.

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

La sandbox scade automaticamente dopo 7 giorni di inattività. Nessun server da arrestare. Nessun contenitore da eliminare.

Se hai salvato una configurazione dell'agente, eliminala:

uv run python delete_agent.py

10. Riepilogo

Hai creato un agente gestito da zero, un concetto alla volta. Ecco cosa insegnava ogni esercizio:

Esercizio	Concetto	API Key
Effettuare la prima chiamata	Esegui il provisioning di una sandbox Linux reale e trasmetti in streaming i relativi eventi in diretta	interactions.create(agent, input, environment, stream=True), event.event_type
Personalizzare l'agente	Monta i file di configurazione; mantieni gli ID in .env nella stessa esecuzione	environment.sources, set_key
Scarica il PDF	Scaricare il PDF senza eseguire di nuovo l'agente	API Gemini Files :download in download_pdf.py
Continua la conversazione	Continua la conversazione senza recuperare nuovamente il web	environment=environment_id, previous_interaction_id=interaction_id
Mantieni configurazione agente	Persistenza della configurazione dell'agente; richiamo per ID, senza bisogno di origini	agents.create(), agents.list()

Pattern chiave

1. Una chiamata, una sandbox: interactions.create() gestisce tutta l'infrastruttura (nessun container da eseguire il deployment, nessun pacchetto da installare localmente)
2. Streaming progressivo: stream=True trasforma una scatola nera di 90 secondi in un feed pubblicato di chiamate agli strumenti e blocchi di testo
3. Origini inline: monta AGENTS.md, SKILL.md e script predefiniti nella sandbox senza alcun passaggio di caricamento o deployment
4. Rilevamento automatico dell'imbracatura: i file inseriti in .agents/ vengono rilevati automaticamente (non è richiesta alcuna configurazione dell'SDK)
5. Stato bidimensionale: environment_id tiene traccia di file e pacchetti; previous_interaction_id tiene traccia del contesto della conversazione; entrambi possono essere passati in modo indipendente
6. Download dello snapshot: l'ambiente è un tar del file system completo, accessibile tramite l'API Gemini Files
7. Agenti denominati: agents.create() incorpora la configurazione in modo permanente; le chiamate future trasmettono solo l'ID agente e environment="remote", senza origini

ADK + Cloud Run e agenti gestiti: la differenza in sintesi

Capacità	ADK + Cloud Run	Managed Agents nell'API Gemini
Esegui il provisioning di una sandbox	docker build + gcloud run deploy	interactions.create()
Definisci gli strumenti	Funzioni Python registrate con l'agente	Funzionalità integrate: navigazione web, esecuzione di codice, file system
Installa pacchetti	pip install in Dockerfile	L'agente viene eseguito pip install all'interno della sandbox
Eventi di streaming	Infrastruttura SSE personalizzata	stream=True
Continuare una sessione	Database della sessione + inserimento del contesto	environment_id + previous_interaction_id
File di configurazione	Codificati nell'agente o inseriti all'avvio	Montato tramite environment.sources
Infrastruttura da gestire	Container, Cloud Run, IAM, secret	Nessuno

Passaggi successivi

• Leggi la documentazione dell'API Managed Agents nell'API Gemini