Managed Agents nell'API Gemini: un tutorial pratico

Quanto costano i Managed Agents nell'API Gemini?

Il prezzo dei Gemini Managed Agents dipende da diversi componenti, il che rende difficile fornire stime precise. Il costo è determinato da quattro fattori principali:

1. Uso del modello (token): Veniamo addebitati in base al numero di token in input e in output elaborati dal modello Gemini sottostante. Nota che includono i token generati nei risultati intermedi. Ad esempio, se l'agente genera uno script Python per creare un report, anche i token necessari per quello script vengono fatturati.
2. Costi di infrastruttura e piattaforma: Gli agenti gestiti vengono eseguiti nell'ambiente integrato di Google, che comporta costi di servizio per l'uso degli strumenti della piattaforma (come Vertex AI Agent Builder) per gestire e distribuire gli agenti.
3. Context caching: Se gli agenti riutilizzano spesso gli stessi dati, i managed agents possono sfruttare il context caching. In genere offre una significativa riduzione dei costi rispetto alla tariffazione standard per token.
4. Grounding: Se l'agente usa servizi di grounding di Google come Google Search o Google Maps, questi vengono fatturati separatamente, spesso con una quota di richieste gratuite seguita da un costo per 1.000 query (tipicamente circa $14/1.000 query). 

In questo tutorial, costruiremo un agente sopra l'agente antigravity-preview-05-2026 che è alimentato da Gemini 3.5 Flash. I costi per token di Gemini 3.5 Flash sono i seguenti:

Come creare Managed Agents nell'API Gemini

In questa guida, costruiremo un managed agent usando l'API Gemini e Python. Dato che i managed agents sono una novità attualmente in beta, tieni presente che alcuni dettagli di implementazione potrebbero evolvere.

Tutto il codice che scriveremo in questo tutorial è conservato in questo repository GitHub, che useremo anche per condividere i dati con l'agente data analyst.

Configurazione dell'API

Per creare una chiave AI, vai su Google AI Studio e fai clic su “Create API Key” in alto a destra.

Le API key devono essere associate a un progetto Google Cloud. Possiamo selezionarne uno esistente o crearne uno nuovo. Qui, ne ho creato uno chiamato gemini-managed-agents.

Dopo aver creato la chiave, la copiamo. Poi creiamo un file chiamato .env nella cartella dove creeremo i nostri agenti e la incolliamo con il seguente formato:

GEMINI_API_KEY=<paste_your_api_key_here>

Prima di chiudere Google AI Studio, dobbiamo configurare la fatturazione sulla API key appena creata. Senza questo, le nostre richieste verranno negate perché Google non potrà addebitarci i costi. Per impostare la fatturazione, fai clic sul pulsante “Set up billing”.

Configurazione dell'ambiente Python

Useremo Anaconda per configurare un ambiente Python per questo progetto. Per creare un ambiente con Anaconda, usa il comando:

conda create --name gemini_agents python=3.12 -y

Questo crea un ambiente chiamato gemini_agents che usa Python versione 3.10. Il parametro -y è semplicemente una scorciatoia per rispondere “sì” a tutte le domande durante la creazione dell'ambiente.

Successivamente, dobbiamo attivarlo:

conda activate gemini_agents

Infine, dobbiamo installare le dipendenze necessarie. Ecco come:

pip install google-genai requests python-dotenv

Creare un'interazione di base con un managed agent

Ora abbiamo tutto pronto per eseguire il nostro primo agente. Questo primo agente non farà molto. Installerà semplicemente matplotlib e riporterà la versione installata.

Ecco una spiegazione passo passo su come possiamo interagire con un managed agent (il codice completo si trova nello script simple_interaction.py nel repository):

Per prima cosa, importiamo i pacchetti necessari e carichiamo la API key dal file .env che abbiamo creato prima:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Poi inizializziamo il client Gemini e creiamo un'interazione con l'agente base, attualmente chiamato antigravity-preview-05-2026, chiedendogli di installare matplotlib:

# Initialize the GenAI Client
client = genai.Client()

# Create a basic interaction with a managed agent
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install the matplotlib package, verify its version, and report back.",
    environment="remote"
)

Infine, otteniamo l'output dall'agente ispezionando le proprietà status, environment_id e output_text:

# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")

Ecco il risultato:

Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.

Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9

Stati del ciclo di vita della sandbox

Nell'esempio sopra, abbiamo mostrato l'identificatore dell'ambiente dell'interazione con il managed agent:

Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6

Questo valore è importante perché rappresenta l'identificatore dell'ambiente in cui l'agente è stato eseguito. Le interazioni dell'agente sono archiviate in un ambiente effimero che viene conservato fino a 7 giorni dall'ultima attività prima di essere eliminato.

Il diagramma qui sotto illustra il ciclo di vita della sandbox in cui l'agente viene eseguito durante un'interazione.

Finché l'ambiente non viene eliminato, possiamo accedervi ed effettuare ulteriori interazioni usando l'identificatore dell'ambiente.

Eseguire più interazioni

In questo esempio, mostriamo come eseguire più interazioni. Il codice completo è disponibile nel file multiple_interactions.py dal repository.

# First interaction
inter1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script sum.py that adds all integers from 1 to 100.",
    environment="remote"
)

# Second interaction
inter2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=inter1.id, # Passes the conversation history
    environment=inter1.environment_id, # Keeps the same filesystem state
    input="Execute 'sum.py' using Python and display the standard output."
)

# Output the status of the agent
print(f"Output:\n{inter2.output_text}")

Nota che nella seconda interazione abbiamo aggiunto due parametri:

• previous_interaction_id: L'identificatore della precedente interazione, così l'agente è a conoscenza della cronologia della conversazione.

• environment: L'identificatore dell'ambiente in modo che l'agente sappia in quale sandbox deve eseguire.

Condivisione di file con un agente

Non possiamo creare un agente data analyst se non possiamo dargli accesso ai dati. Ci sono diversi modi per condividere i dati con un agente:

• Dati inline: Caricare il contenuto del file in una stringa e inviarlo durante l'interazione.
• File ospitato: Ospitare i dati su un URL pubblico e fornire l'URL per permettere all'agente di scaricarli.
• Repository GitHub: Possiamo fornire all'agente l'URL di un repository GitHub pubblico.
• Google Cloud Bucket: Ospitare un file in un bucket di Google Cloud Storage e configurare il progetto in modo che l'agente abbia accesso a quel bucket.

Non esploreremo tutte queste soluzioni in questo articolo. Mostreremo come inviare dati inline caricando un file locale in una stringa e come condividere un repository GitHub. La prima è ideale per condividere piccoli file locali (fino a 1 MB per file, con un limite totale di 2 MB su tutti i file), mentre la seconda è più adatta per file più grandi, come i dataset.

Condivisione di dati inline

Ecco un esempio di come fornire dati inline (codice completo in inline_example.py):

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                # The file where to store the data in the agent environment
                "target": "/workspace/numbers.txt",
                # Assumes that the file data/numbers.txt exists
                "content": utils.read_text_file("data/numbers.txt")
            }
        ]
    }
)

I dati vengono forniti usando il parametro sources nella configurazione dell'environment. Il target definisce la posizione in cui i dati verranno archiviati nell'ambiente dell'agente. I file dovrebbero essere posizionati nella cartella workspace. In questo caso, sarà un file chiamato number.txt. 

Il parametro content fornisce il contenuto del file. Per le sorgenti inline, è semplicemente una stringa, che in questo caso leggiamo usando la funzione read_text_file() nel file utils.py.

Condivisione di un repository GitHub

Per condividere file più grandi, possiamo fornire l'URL di un repository GitHub. Ecco come:

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/repository/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                "target": "/workspace/repository"
            }
        ]
    }
)

Nell'esempio sopra, il repository con URL https://github.com/fran-aubry/gemini-agents-tutorial viene clonato in una cartella chiamata repository, all'interno dello workspace dell'agente.

Scaricare l'ambiente di un agente

Abbiamo già visto come interagire con i managed agents e come fornire file a questi agenti. Per creare il nostro agente data analyst, l'ultima cosa che dobbiamo imparare è come scaricare l'ambiente di un agente. Questo è necessario per poter accedere ai grafici e ai risultati generati dall'agente.

Ogni workspace può essere scaricato all'URL:

https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:download

Dove <env_id> va sostituito con l'identificatore dell'ambiente che vogliamo scaricare.

Ecco una funzione Python che usa il pacchetto requests per scaricare un pacchetto (questa funzione fa parte del file utils.py che abbiamo creato):

def download_env(env_id, path="environments"):
    download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
    try:
        request_params = {"alt": "media"}  # Retrieves raw media binary
        request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
        # Download the environment
        print(f"Downloading environment: {env_id}")
        response = requests.get(
            download_url,
            params=request_params,
            headers=request_headers,
            allow_redirects=True
        )
        response.raise_for_status()
        # Save the compressed workspace archive locally
        archive_name = f"{env_id}.tar"
        output_path = os.path.join(path, archive_name)
        with open(output_path, "wb") as archive_file:
            archive_file.write(response.content)
        print(f"Successfully downloaded workspace snapshot archive: {output_path}")     
    except requests.exceptions.RequestException as error:
        print(f"Failed to download sandbox workspace via HTTP request: {error}")
    except tarfile.TarError as archive_error:
        print(f"Failed to unpack download tarball: {archive_error}")

Creare un agente Data Analyst

In questa sezione, impariamo a creare un agente che esegue analisi dei dati. Per testare l'agente, useremo questo dataset di Netflix preso da Kaggle, che è anche archiviato nella cartella data del nostro repository.

In tutti gli esempi precedenti abbiamo sempre interagito con l'agente base: antigravity-preview-05-2026. Qui creeremo prima un agente usando la funzione client.agents.create().

Creare un agente

Ecco come possiamo creare un agente:

agent = client.agents.create(
            id=”data-analyst”,
            base_agent="antigravity-preview-05-2026",
            base_environment={
                "type": "remote",
                "sources": [
                    {
                        "type": "inline", 
                        "target": ".agents/AGENTS.md", 
                        "content": read_text_file(".agents/AGENTS.md")
                    },
                    # Explicitly load the skill
                    {
                        "type": "inline", 
                        "target": ".agents/skills/csv-aggregator/SKILL.md", 
                        "content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
                    },	
                    {
                        "type": "repository",
                        "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                        "target": "/workspace/repository"
                    }
                ]
            }

Vediamo nel dettaglio ciascun parametro:

• id: Definisce il nome dell'agente, in questo caso data-analyst. Useremo questo identificatore nel metodo client.interactions.create() invece di antigravity-preview-05-2026 che abbiamo usato finora. 

• base_agent: L'agente da usare come base. Significa che stiamo costruendo un agente sopra l'agente antigravity-preview-05-2026.

• base_environment: Come prima, ci permette di fornire file all'agente. Abbiamo fornito due file speciali: .agents/AGENTS.md e .agents/skills/csv-aggregator/SKILL.md. Questi file sono dove abbiamo definito il comportamento dell'agente. Il file AGENTS.md definisce il comportamento generale dell'agente, mentre il SKILL.md definisce una particolare skill per l'agente. Abbiamo anche fornito al agente il repository in modo che abbia accesso ai file di dati che vogliamo analizzare.

Capire AGENTS.md

Questo file può essere considerato come un system prompt. Funziona come il nostro manuale d'istruzioni principale per l'agente. Dovremmo usarlo per definire chiaramente il ruolo specifico dell'agente, i suoi obiettivi principali e i confini che deve rispettare mentre lavora. 

È anche il posto migliore per elencare eventuali strumenti o fonti di dati specifici a cui l'agente può accedere e per fornire esempi di come vogliamo che comunichi o gestisca i task. 

Mantenendo queste istruzioni semplici e ben organizzate all'interno del file, aiutiamo l'agente a capire esattamente come comportarsi e quali risultati ci aspettiamo che fornisca.

La posizione del file nell'ambiente dell'agente deve essere .agents/AGENTS.md.

Capire SKILL.md

I file delle skill servono a dotare l'agente di competenze specifiche. Un agente può avere più skill, e ciascuna dovrebbe essere descritta in un file SKILL.md situato in .agents/skills/<skill_name>/SKILL.md, sostituendo <skill_name> con il nome della skill.

La struttura di un file di skill dovrebbe essere:

---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>

Per esemplificare, abbiamo dotato l'agente data-analyst di una skill chiamata csv-aggregator definita qui. Questa skill si usa quando vogliamo raggruppare le righe di un CSV per una colonna sommando un'altra colonna. 

Nel caso del dataset di Netflix, se vogliamo conoscere i generi degli show con più visualizzazioni, vogliamo raggruppare le righe per Genre e sommare i valori nella colonna Viewership. Questo file SKILL spiega all'agente come svolgere questo compito.

Caricare l'agente

Poiché gli agenti sono persistenti, se proviamo a eseguire la creazione dell'agente due volte, otterremo un errore. Per questo motivo, abbiamo creato la funzione load_or_create_agent() nel file utils.py. Questa funzione proverà a creare l'agente e, se esiste, lo caricherà invece usando la funzione client.agents.load().

Mettere tutto insieme

Ora che abbiamo un agente data analyst, è il momento di testarlo chiedendogli di analizzare i generi di Netflix. 

Iniziamo come prima importando le librerie, caricando la API key e inizializzando il client:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Poi creiamo (o carichiamo, se non è la prima volta che eseguiamo lo script) l'agente data-analyst usando la funzione utils.load_or_create_agent():

data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")

Quindi possiamo interagire con l'agente allo stesso modo di prima. L'unica differenza è che nel parametro agent ora indichiamo il nostro agente invece di antigravity-preview-05-2026.

Iniziamo chiedendo all'agente di installare il pacchetto matplotlib:

inter1 = client.interactions.create(
    agent=data_analyst.id,
    input="Install the matplotlib package.",
    environment="remote"
)

Nota che, dato che l'ambiente è già stato configurato a livello di agente, non dobbiamo più fornire file, quindi indichiamo semplicemente la stringa ”remote”.

Successivamente, gli chiediamo di usare lo strumento csv-aggregator per analizzare i dati Netflix per genere e vedere quali sono i generi più visti:

inter2 = client.interactions.create(
    agent=data_analyst.id,
    input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
    environment=inter1.environment_id
)

Nota che forniamo l'identificatore dell'ambiente dell'interazione precedente in modo che l'agente possa continuare a lavorare sopra di esso.

Infine, chiediamo all'agente di tracciare i dati eseguendo lo script genres.py creato nel passaggio precedente (il file SKILL.md istruisce l'agente a creare questo script):

inter3 = client.interactions.create(
    agent=data_analyst.id,
    input="Execute the genres.py script using python.",
    environment=inter2.environment_id
)

Dopo questa interazione, il grafico dovrebbe essere stato creato. Possiamo ottenerlo in locale scaricando l'ambiente:

utils.download_env(inter3.environment_id)

Ecco il risultato:

Il codice completo dell'interazione con l'agente si trova in analyze_netflix_genres.py.

Conclusione

La possibilità di creare agenti complessi con una singola chiamata API senza dover fare affidamento su un'infrastruttura cloud complessa per creare una sandbox è molto potente. Questa capacità rende molto facile creare agenti potenti senza doversi preoccupare dell'ambiente in cui vengono eseguiti.

In questo tutorial, abbiamo coperto le basi dei Gemini Managed Agents ma non abbiamo creato agenti davvero complessi. Ti invito a esplorare oltre e a continuare a costruire su queste fondamenta per affinare le tue competenze.