Managed Agents i Gemini API: en praktisk handledning

Hur mycket kostar Managed Agents i Gemini API?

Prissättningen för Gemini Managed Agents består av många delar, vilket gör det svårt att ge exakta kostnadsuppskattningar. Kostnaden drivs av fyra huvudfaktorer:

1. Modellanvändning (tokens): Vi debiteras baserat på antalet in- och utgående tokens som behandlas av den underliggande Gemini-modellen. Observera att dessa inkluderar tokens som genereras i mellanresultat. Till exempel, om agenten genererar ett Python-skript för att bygga en rapport, debiteras också tokens som krävs för det skriptet.
2. Infrastruktur- och plattformsavgifter: Managed agents körs i Googles integrerade miljö, vilket innebär tjänsteavgifter för att använda plattformsverktygen (såsom Vertex AI Agent Builder) för att hantera och driftsätta agenterna.
3. Context caching: Om agenterna ofta återanvänder samma data kan managed agents använda context caching. Detta ger vanligtvis en betydande kostnadsreduktion jämfört med standardprissättning per token.
4. Grounding: Om agenten använder Googles grunderbjudanden som Google Sök eller Google Maps, debiteras dessa separat, ofta baserat på en kvot av kostnadsfria förfrågningar följt av en kostnad per 1 000 förfrågningar (vanligtvis runt $14/1 000 förfrågningar). 

I den här handledningen bygger vi en agent ovanpå agenten antigravity-preview-05-2026 som drivs av Gemini 3.5 Flash. Token-kostnaderna för Gemini 3.5 Flash är följande:

Hur bygger man Managed Agents i Gemini API

I den här guiden bygger vi en managed agent med hjälp av Gemini API och Python. Eftersom managed agents är ett nyligen släppt verktyg som för närvarande är i beta kan vissa implementationsdetaljer komma att utvecklas.

All kod vi skriver i den här handledningen finns i detta GitHub-repo, som vi också använder för att dela data med dataanalytiker-agenten.

API-setup

För att skapa en AI-nyckel går du till Google AI Studio och klickar på ”Create API Key” uppe till höger.

API-nycklar måste kopplas till ett Google Cloud-projekt. Vi kan antingen välja ett befintligt eller skapa ett nytt. Här skapade jag ett som heter gemini-managed-agents.

Efter att ha skapat nyckeln kopierar vi den. Sedan skapar vi en fil med namnet .env i mappen där vi kommer skapa våra agenter och klistrar in den med följande format:

GEMINI_API_KEY=<paste_your_api_key_here>

Innan vi stänger Google AI Studio måste vi ställa in fakturering på API-nyckeln vi just skapade. Utan detta kommer våra förfrågningar att nekas eftersom Google inte kan debitera oss. För att ställa in fakturering, klicka på knappen ”Set up billing”.

Python-miljö

Vi kommer att använda Anaconda för att sätta upp en Python-miljö för det här projektet. För att skapa en miljö med Anaconda, använd kommandot:

conda create --name gemini_agents python=3.12 -y

Detta skapar en miljö med namnet gemini_agents som använder Python version 3.10. Parametern -y är helt enkelt en genväg för att svara ”ja” på alla frågor under skapandet av miljön.

Nästa steg är att aktivera den:

conda activate gemini_agents

Slutligen behöver vi installera nödvändiga beroenden. Så här gör du:

pip install google-genai requests python-dotenv

Skapa en grundläggande interaktion med en managed agent

Nu har vi allt på plats för att köra vår första agent. Den här första agenten kommer inte göra så mycket. Den kommer bara att installera matplotlib och rapportera vilken version som installerades.

Här är en steg-för-steg-förklaring av hur vi kan interagera med en managed agent (hela koden finns i skriptet simple_interaction.py i repot):

Först importerar vi nödvändiga paket och laddar API-nyckeln från filen .env som vi skapade tidigare:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Därefter initierar vi Gemini-klienten och skapar en interaktion med basagenten, som för närvarande heter antigravity-preview-05-2026, där vi ber den installera 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"
)

Slutligen hämtar vi utdata från agenten genom att inspektera egenskaperna status, environment_id och 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}")

Här är resultatet:

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

Sandboxens livscykel

I exemplet ovan visade vi miljöidentifieraren för den managed agent-interaktionen:

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

Detta värde är viktigt eftersom det representerar identifieraren för den miljö där agenten kördes. Agentinteraktioner lagras i en flyktig miljö som behålls i upp till 7 dagar efter den senaste aktiviteten innan den raderas.

Diagrammet nedan illustrerar livscykeln för sandboxen där agenten körs under en interaktion.

Så länge miljön inte är raderad kan vi komma åt den och genomföra fler interaktioner genom att använda miljöidentifieraren.

Utföra flera interaktioner

I detta exempel visar vi hur man utför flera interaktioner. Hela koden finns i filen multiple_interactions.py från repot.

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

Observera att vi i den andra interaktionen lade till två parametrar:

• previous_interaction_id: Identifieraren för den föregående interaktionen, så att agenten känner till konversationshistoriken.

• environment: Miljöidentifieraren så att agenten vet i vilken sandbox den ska köra.

Dela filer med en agent

Vi kan inte bygga en dataanalytiker-agent om vi inte kan ge agenten åtkomst till data. Det finns några olika sätt att dela data med en agent:

• Inline-data: Läsa in filinnehåll i en sträng och skicka det under interaktionen.
• Hostad fil: Lagra datan på en publik URL och ge agenten URL:en för nedladdning.
• GitHub-repository: Vi kan ge agenten en publik GitHub-repo-URL.
• Google Cloud Bucket: Lagra en fil i en Google Cloud Storage-bucket och konfigurera projektet så att agenten har åtkomst till den bucketen.

Vi kommer inte att gå igenom alla dessa lösningar i den här artikeln. Vi visar hur man skickar inline-data genom att läsa in en lokal fil till en sträng samt hur man delar ett GitHub-repo. Det första är idealiskt för att dela små lokala filer (upp till 1 MB per fil, med en totalgräns på 2 MB över alla filer), medan det senare är mer lämpligt för större filer, såsom dataset.

Dela inline-data

Här är ett exempel på hur man tillhandahåller inline-data (full kod i 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 tillhandahålls med parametern sources i environment-konfigurationen. target definierar platsen där datan ska lagras i agentens miljö. Filer bör placeras i mappen workspace. I det här fallet blir det en fil med namnet number.txt. 

Parametern content tillhandahåller filinnehållet. För inline-källor är det helt enkelt en sträng, som i detta fall läses med funktionen read_text_file() i filen utils.py.

Dela ett GitHub-repository

För att dela större filer kan vi ange en GitHub-repo-URL. Så här gör du:

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

I exemplet ovan klonas repot med URL https://github.com/fran-aubry/gemini-agents-tutorial till en mapp som heter repository inne i agentens arbetsyta.

Ladda ner en agents miljö

Vi har redan lärt oss hur man interagerar med managed agents och hur man tillhandahåller filer till dessa agenter. För att skapa vår dataanalytiker-agent är det sista vi behöver lära oss hur man laddar ner en agents miljö. Detta är nödvändigt för att vi ska kunna komma åt diagram och resultat som agenten genererar.

Varje arbetsyta kan laddas ner på URL:en:

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

Där <env_id> ska ersättas med identifieraren för den miljö vi vill ladda ner.

Här är en Python-funktion som använder paketet requests för att ladda ner ett paket (denna funktion är en del av filen utils.py som vi skapade):

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

Bygga en dataanalytiker-agent

I det här avsnittet lär vi oss hur man skapar en agent som utför dataanalys. För att testa agenten använder vi detta Netflix-dataset från Kaggle, som också finns i mappen data i vårt repo.

I alla tidigare exempel interagerade vi alltid med basagenten: antigravity-preview-05-2026. Här skapar vi först en agent med funktionen client.agents.create().

Skapa en agent

Så här kan vi skapa en 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"
                    }
                ]
            }

Låt oss gå igenom varje parameter:

• id: Detta definierar agentens namn, data-analyst i det här fallet. Vi kommer att använda denna identifierare i metoden client.interactions.create() i stället för antigravity-preview-05-2026 som vi har använt hittills. 

• base_agent: Agenten som ska användas som bas. Det betyder att vi bygger en agent ovanpå agenten antigravity-preview-05-2026.

• base_environment: Precis som tidigare låter detta oss tillhandahålla filer till agenten. Vi tillhandahöll två speciella filer: .agents/AGENTS.md och .agents/skills/csv-aggregator/SKILL.md. Dessa filer är där vi definierade agentens beteende. Filen AGENTS.md definierar agentens allmänna beteende, medan SKILL.md definierar en särskild färdighet för agenten. Vi gav också agenten tillgång till repot så att den har åtkomst till de datafiler vi vill analysera.

Förstå AGENTS.md

Den här filen kan ses som en systemprompt. Den fungerar som vår primära instruktionsmanual för agenten. Vi bör använda den för att tydligt definiera agentens specifika roll, dess huvudmål och gränserna den ska hålla sig inom när den arbetar. 

Det är också den bästa platsen för att lista specifika verktyg eller datakällor som agenten får använda samt ge exempel på hur vi vill att den kommunicerar eller hanterar uppgifter. 

Genom att hålla instruktionerna enkla och välorganiserade i filen hjälper vi agenten att förstå exakt hur den ska bete sig och vilka resultat vi förväntar oss.

Filens plats i agentens miljö ska vara .agents/AGENTS.md.

Förstå SKILL.md

Färdighetsfiler används för att förse agenten med specifika färdigheter. En agent kan ha flera färdigheter, och var och en ska beskrivas i en fil SKILL.md som ligger i .agents/skills/<skill_name>/SKILL.md, där <skill_name> ersätts med färdighetens namn.

Strukturen för en färdighetsfil bör vara:

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

För att exemplifiera detta utrustade vi agenten data-analyst med en färdighet som heter csv-aggregator definierad här. Denna färdighet används när vi vill gruppera rader i en CSV efter någon kolumn samtidigt som vi summerar en annan kolumn. 

I fallet med Netflix-datasetet, om vi vill veta vilka genrer som har flest visningar, vill vi gruppera raderna efter Genre och summera värdena i kolumnen Viewership. Denna färdighetsfil förklarar för agenten hur den ska utföra denna uppgift.

Ladda agenten

Eftersom agenter är persistenta får vi ett fel om vi försöker köra agentskapandet två gånger. Av den anledningen skapade vi funktionen load_or_create_agent() i filen utils.py. Denna funktion försöker skapa agenten och, om den redan finns, ladda den i stället med funktionen client.agents.load().

Allt tillsammans

Nu när vi har en dataanalytiker-agent är det dags att testa den genom att be den analysera Netflix-genrer. 

Vi börjar som tidigare med att importera biblioteken, ladda API-nyckeln och initiera klienten:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Sedan skapar vi (eller laddar, om det inte är första gången vi kör skriptet) agenten data-analyst med funktionen utils.load_or_create_agent():

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

Sedan kan vi interagera med agenten på samma sätt som tidigare. Den enda skillnaden är att vi i parametern agent nu anger vår agent i stället för antigravity-preview-05-2026.

Vi börjar med att be agenten installera paketet matplotlib:

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

Observera att eftersom miljön redan var konfigurerad på agentnivå behöver vi inte längre tillhandahålla filer, så vi anger bara strängen ”remote”.

Därefter ber vi den använda verktyget csv-aggregator för att analysera Netflix-data efter genrer för att se vilka genrer som är mest sedda:

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
)

Observera att vi anger identifieraren för den föregående interaktionens miljö så att agenten kan fortsätta arbeta ovanpå den.

Slutligen ber vi agenten att plotta datan genom att köra skriptet genres.py som skapades i föregående steg (filen SKILL.md instruerar agenten att skapa detta skript):

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

Efter denna interaktion bör diagrammet vara skapat. Vi kan hämta det lokalt genom att ladda ner miljön:

utils.download_env(inter3.environment_id)

Här är resultatet:

Hela koden för agentinteraktionen finns i analyze_netflix_genres.py.

Slutsats

Att kunna skapa komplexa agenter med ett enda API-anrop utan att behöva förlita sig på komplex molninfrastruktur för att skapa en sandbox är mycket kraftfullt. Denna förmåga gör det mycket enkelt att skapa kraftfulla agenter utan att behöva oroa sig för miljön där dessa agenter körs.

I den här handledningen gick vi igenom grunderna i Gemini Managed Agents, men skapade inte riktigt komplexa agenter. Jag uppmuntrar dig att fördjupa dig vidare och fortsätta bygga ovanpå denna grund för att vässa dina färdigheter.