Managed Agents in de Gemini API: een praktische tutorial

Wat kosten Managed Agents in de Gemini API?

Er zijn veel componenten die meespelen in de prijsstelling van Gemini Managed Agents, waardoor het lastig is om precieze kostenramingen te geven. De kosten worden bepaald door vier hoofdfactoren:

1. Modelgebruik (tokens): We betalen op basis van het aantal verwerkte input- en outputtokens door het onderliggende Gemini-model. Let op: dit omvat ook tokens die ontstaan in tussenresultaten. Als de agent bijvoorbeeld een Python-script genereert om een rapport te bouwen, worden de tokens voor dat script ook in rekening gebracht.
2. Infrastructuur- & platformkosten: Managed agents draaien in Google’s geïntegreerde omgeving, met servicekosten voor het gebruik van platformtools (zoals Vertex AI Agent Builder) om de agents te beheren en uit te rollen.
3. Context caching: Als agents vaak dezelfde data hergebruiken, kunnen managed agents context caching benutten. Dit levert doorgaans een aanzienlijke kostenreductie op ten opzichte van standaard tokenprijzen.
4. Grounding: Als de agent Google-diensten voor grounding gebruikt, zoals Google Search of Google Maps, worden die apart gefactureerd, vaak met een quotum gratis aanvragen gevolgd door een prijs per 1.000 queries (typisch rond $14/1.000 queries). 

In deze tutorial bouwen we een agent boven op de agent antigravity-preview-05-2026 die wordt aangedreven door Gemini 3.5 Flash. De tokenkosten van Gemini 3.5 Flash zijn als volgt:

Hoe bouw je Managed Agents in de Gemini API

In deze gids bouwen we een managed agent met de Gemini API en Python. Omdat managed agents recent zijn uitgebracht en momenteel in bèta zijn, kan het zijn dat sommige implementatiedetails nog veranderen.

Alle code die we in deze tutorial schrijven, staat in deze GitHub-repository, die we ook gebruiken om data met de data-analist-agent te delen.

API-setup

Om een AI-sleutel te maken, ga je naar Google AI Studio en klik je rechtsboven op “Create API Key”.

API-sleutels moeten gekoppeld zijn aan een Google Cloud-project. Je kunt een bestaand project selecteren of een nieuw project aanmaken. Hier heb ik er één gemaakt met de naam gemini-managed-agents.

Na het aanmaken kopiëren we de sleutel. Vervolgens maken we een bestand met de naam .env in de map waar we onze agents gaan maken en plakken we de sleutel in het volgende formaat:

GEMINI_API_KEY=<paste_your_api_key_here>

Voordat we Google AI Studio afsluiten, moeten we billing instellen op de zojuist gemaakte API-sleutel. Zonder billing worden onze requests geweigerd omdat Google ons niet kan factureren. Klik op de knop “Set up billing” om billing in te stellen.

Python-omgeving opzetten

We gebruiken Anaconda om een Python-omgeving voor dit project op te zetten. Om een omgeving met Anaconda te maken, gebruik je het commando:

conda create --name gemini_agents python=3.12 -y

Dit maakt een omgeving met de naam gemini_agents die Python versie 3.10 gebruikt. De parameter -y is simpelweg een snelkoppeling om tijdens het aanmaken overal “yes” op te antwoorden.

Activeer hem vervolgens:

conda activate gemini_agents

Tot slot installeren we de benodigde dependencies. Zo doe je dat:

pip install google-genai requests python-dotenv

Een basisinteractie met een managed agent maken

We hebben nu alles klaar om onze eerste agent te draaien. Deze eerste agent doet nog niet veel: hij installeert matplotlib en rapporteert welke versie is geïnstalleerd.

Hier is stap voor stap hoe we met een managed agent kunnen interageren (de volledige code staat in het script simple_interaction.py in de repository):

Eerst importeren we de benodigde pakketten en laden we de API-sleutel uit het eerder gemaakte .env-bestand:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Vervolgens initialiseren we de Gemini-client en maken we een interactie met de basisagent, momenteel antigravity-preview-05-2026 genaamd, met de vraag om matplotlib te installeren:

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

Tot slot halen we de output op door de properties status, environment_id en output_text te inspecteren:

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

Dit is het resultaat:

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

Sandbox-levenscyclus

In het bovenstaande voorbeeld toonden we de omgevings-ID van de managed agent-interactie:

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

Deze waarde is belangrijk, want het is de identifier van de omgeving waarin de agent werd uitgevoerd. Agentinteracties worden opgeslagen in een tijdelijke omgeving die tot 7 dagen na de laatste activiteit bewaard blijft en daarna wordt verwijderd.

Het onderstaande diagram toont de levenscyclus van de sandbox waarin de agent tijdens een interactie wordt uitgevoerd.

Zolang de omgeving niet is verwijderd, kunnen we die openen en verdere interacties uitvoeren met behulp van de omgevings-ID.

Meerdere interacties uitvoeren

In dit voorbeeld laten we zien hoe je meerdere interacties uitvoert. De volledige code staat in het bestand multiple_interactions.py uit de 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}")

Let op dat we in de tweede interactie twee parameters hebben toegevoegd:

• previous_interaction_id: De identifier van de vorige interactie, zodat de agent de gespreksgeschiedenis kent.

• environment: De omgevings-ID zodat de agent weet in welke sandbox hij moet draaien.

Bestanden delen met een agent

We kunnen geen data-analist-agent bouwen als we de agent geen toegang tot de data kunnen geven. Er zijn een paar manieren om data met een agent te delen:

• Inline data: De bestandsinhoud in een string laden en tijdens de interactie meesturen.
• Gehost bestand: De data hosten op een publieke URL en die URL geven zodat de agent het kan downloaden.
• GitHub-repository: We kunnen een publieke GitHub-repo-URL aan de agent geven.
• Google Cloud Bucket: Een bestand hosten in een Google Cloud Storage-bucket en het project zo configureren dat de agent toegang heeft tot die bucket.

We behandelen niet alle oplossingen in dit artikel. We laten zien hoe je inline data verstuurt door een lokaal bestand in een string te laden en hoe je een GitHub-repository deelt. De eerste is ideaal voor kleine lokale bestanden (tot 1 MB per bestand, met een totale limiet van 2 MB over alle bestanden), terwijl de tweede geschikter is voor grotere bestanden, zoals datasets.

Inline data delen

Hier is een voorbeeld van het aanleveren van inline data (volledige code 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")
            }
        ]
    }
)

Data wordt aangeleverd via de parameter sources in de environment-configuratie. De target bepaalt waar de data wordt opgeslagen in de omgeving van de agent. Bestanden horen in de map workspace te staan. In dit geval is dat een bestand number.txt. 

De parameter content levert de bestandsinhoud. Voor inline-bronnen is dat gewoon een string, die we hier lezen met de functie read_text_file() in het bestand utils.py.

Een GitHub-repository delen

Voor grotere bestanden kunnen we een GitHub-repo-URL aanleveren. Zo doe je dat:

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

In het bovenstaande voorbeeld wordt de repository met URL https://github.com/fran-aubry/gemini-agents-tutorial gekloond in een map repository binnen de workspace van de agent.

De omgeving van een agent downloaden

We hebben al geleerd hoe we met managed agents interageren en hoe we bestanden aan deze agents geven. Om onze data-analist-agent te maken, moeten we als laatste leren hoe we de omgeving van een agent downloaden. Zo krijgen we toegang tot de grafieken en resultaten die de agent genereert.

Elke workspace is te downloaden via de URL:

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

Waarbij je <env_id> vervangt door de identifier van de omgeving die je wilt downloaden.

Hier is een Python-functie die het pakket requests gebruikt om een package te downloaden (deze functie maakt deel uit van het bestand utils.py dat we hebben gemaakt):

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

Een data-analist-agent bouwen

In deze sectie leren we hoe je een agent maakt die data-analyse uitvoert. Om de agent te testen gebruiken we deze Netflix-dataset van Kaggle, die ook is opgeslagen in de map data van onze repository.

In alle eerdere voorbeelden praatten we steeds met de basisagent: antigravity-preview-05-2026. Hier maken we eerst een agent met de functie client.agents.create().

Een agent maken

Zo maak je een agent:

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

Laten we de parameters doornemen:

• id: Dit definieert de naam van de agent, in dit geval data-analyst. We gebruiken deze identifier in de methode client.interactions.create() in plaats van antigravity-preview-05-2026 die we tot nu toe gebruikten. 

• base_agent: De agent die als basis dient. We bouwen dus een agent boven op de agent antigravity-preview-05-2026.

• base_environment: Net als eerder kunnen we hiermee bestanden aan de agent meegeven. We leverden twee speciale bestanden: .agents/AGENTS.md en .agents/skills/csv-aggregator/SKILL.md. In deze bestanden definiëren we het gedrag van de agent. Het bestand AGENTS.md beschrijft het algemene gedrag van de agent, terwijl SKILL.md een specifieke vaardigheid definieert. We gaven de agent ook de repository zodat hij toegang heeft tot de datafiles die we willen analyseren.

AGENTS.md begrijpen

Dit bestand kun je zien als een systeem-prompt. Het is onze primaire handleiding voor de agent. We gebruiken het om duidelijk de specifieke rol van de agent, de hoofddoelen en de grenzen te definiëren waarbinnen hij moet werken. 

Het is ook de beste plek om de specifieke tools of databronnen te vermelden die de agent mag gebruiken en voorbeelden te geven van hoe we willen dat hij communiceert of taken afhandelt. 

Door deze instructies simpel en goed georganiseerd te houden, helpen we de agent precies te begrijpen hoe hij zich moet gedragen en welke resultaten we verwachten.

De locatie van het bestand in de omgeving van de agent moet .agents/AGENTS.md zijn.

SKILL.md begrijpen

De skill-bestanden worden gebruikt om de agent specifieke vaardigheden te geven. Een agent kan meerdere skills hebben, en elke skill wordt beschreven in een bestand SKILL.md op .agents/skills/<skill_name>/SKILL.md, waarbij je <skill_name> vervangt door de naam van de skill.

De structuur van een skill-bestand is:

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

Als voorbeeld hebben we de agent data-analyst uitgerust met een skill csv-aggregator, gedefinieerd hier. Deze skill gebruik je wanneer je rijen van een CSV wilt groeperen op een kolom en een andere kolom wilt optellen. 

Voor de Netflix-dataset: als we willen weten welke genres de meeste views hebben, groeperen we op Genre en tellen we de waarden in de kolom Viewership op. Dit skill-bestand legt de agent uit hoe deze taak uit te voeren.

De agent laden

Omdat agents persistent zijn, krijg je een fout als je het aanmaken twee keer probeert. Daarom maakten we de functie load_or_create_agent() in het bestand utils.py. Deze probeert de agent te maken en, als hij al bestaat, laadt hem in plaats daarvan met de functie client.agents.load().

Alles samenbrengen

Nu we een data-analist-agent hebben, is het tijd om hem te testen door Netflix-genres te laten analyseren. 

We beginnen zoals eerder met het importeren van libraries, het laden van de API-sleutel en het initialiseren van de client:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Daarna maken (of laden, als het niet de eerste keer is dat we het script draaien) we de agent data-analyst met de functie utils.load_or_create_agent():

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

Vervolgens interageren we met de agent op dezelfde manier als eerder. Het enige verschil is dat we bij de parameter agent nu onze eigen agent meegeven in plaats van antigravity-preview-05-2026.

We beginnen met de agent te vragen om het pakket matplotlib te installeren:

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

Omdat de omgeving al op agentniveau is geconfigureerd, hoeven we geen bestanden meer aan te leveren; we geven gewoon de string ”remote”.

Daarna vragen we om de tool csv-aggregator te gebruiken om de Netflix-data per genre te analyseren en te zien wat de meest bekeken genres zijn:

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
)

Let op dat we de omgevings-ID van de vorige interactie meegeven zodat de agent daarop kan voortbouwen.

Tot slot vragen we de agent om de data te plotten door het script genres.py uit te voeren dat in de vorige stap is gemaakt (het SKILL.md-bestand instrueert de agent om dit script te maken):

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

Na deze interactie zou de plot gemaakt moeten zijn. We kunnen hem lokaal ophalen door de omgeving te downloaden:

utils.download_env(inter3.environment_id)

Dit is het resultaat:

De volledige code van de agentinteractie staat in analyze_netflix_genres.py.

Conclusie

De mogelijkheid om complexe agents met één API-call te maken, zonder afhankelijk te zijn van complexe cloudcompute-infrastructuur om een sandbox te creëren, is erg krachtig. Het maakt het eenvoudig om sterke agents te bouwen zonder je zorgen te hoeven maken over de omgeving waarin ze draaien.

In deze tutorial behandelden we de basis van Gemini Managed Agents, maar bouwden we nog geen echt complexe agents. Ik moedig je aan om verder te graven en op deze basis door te bouwen om je skills te aanscherpen.