Managed Agents în API-ul Gemini: Tutorial practic

Cât costă Managed Agents în API-ul Gemini?

Structura de preț pentru Gemini Managed Agents implică multe componente, ceea ce face dificilă o estimare precisă a costurilor. Costul este determinat de patru factori principali:

1. Utilizarea modelului (tokeni): Suntem taxați în funcție de numărul de tokeni de intrare și ieșire procesați de modelul Gemini subiacent. Reține că aceștia includ tokenii generați în rezultate intermediare. De exemplu, dacă agentul generează un script Python pentru a construi un raport, tokenii necesari pentru acel script sunt de asemenea facturați.
2. Taxe de infrastructură și platformă: Agenții gestionați rulează în cadrul mediului integrat Google, ceea ce implică taxe pentru utilizarea instrumentelor platformei (cum ar fi Vertex AI Agent Builder) pentru a gestiona și implementa agenții.
3. Context Caching: Dacă agenții reutilizează frecvent aceleași date, pot folosi context caching. Acest lucru oferă de obicei o reducere semnificativă a costurilor comparativ cu prețurile standard pe token.
4. Grounding: Dacă agentul folosește servicii de ancorare Google precum Google Search sau Google Maps, acestea sunt facturate separat, adesea pe baza unui contingent de cereri gratuite urmat de un cost per 1.000 de interogări (de obicei în jur de 14 $/1.000 de interogări). 

În acest tutorial, vom construi un agent peste agentul antigravity-preview-05-2026 care este aliat de Gemini 3.5 Flash. Costurile pe token pentru Gemini 3.5 Flash sunt următoarele:

Cum construiești Managed Agents în API-ul Gemini

În acest ghid, vom construi un agent gestionat folosind API-ul Gemini și Python. Deoarece agenții gestionați sunt o lansare recentă, aflată în prezent în beta, ține cont că unele detalii de implementare se pot schimba.

Tot codul pe care îl vom scrie în acest tutorial este stocat în acest repository GitHub, pe care îl vom folosi și pentru a partaja datele cu agentul analist de date.

Configurarea API-ului

Pentru a crea o cheie AI, mergi la Google AI Studio și dă clic pe „Create API Key” în dreapta sus.

Cheile API trebuie asociate cu un proiect Google Cloud. Putem selecta unul existent sau crea unul nou. Aici, am creat unul numit gemini-managed-agents.

După crearea cheii, o copiem. Apoi creăm un fișier numit .env în folderul unde vom crea agenții și îl lipim în formatul următor:

GEMINI_API_KEY=<paste_your_api_key_here>

Înainte de a închide Google AI Studio, trebuie să configurăm facturarea pentru cheia API pe care tocmai am creat-o. Fără asta, cererile noastre vor fi refuzate, deoarece Google nu ne poate taxa. Pentru a configura facturarea, dă clic pe butonul „Set up billing”.

Configurarea mediului Python

Vom folosi Anaconda pentru a configura un mediu Python pentru acest proiect. Pentru a crea un mediu folosind Anaconda, folosește comanda:

conda create --name gemini_agents python=3.12 -y

Aceasta creează un mediu numit gemini_agents care folosește Python versiunea 3.10. Parametrul -y este doar un shortcut pentru a răspunde „yes” la toate întrebările în timpul creării mediului.

Apoi trebuie să-l activăm:

conda activate gemini_agents

În final, trebuie să instalăm dependențele necesare. Iată cum:

pip install google-genai requests python-dotenv

Crearea unei interacțiuni de bază cu un agent gestionat

Acum avem totul pregătit pentru a rula primul nostru agent. Acest prim agent nu va face prea multe. Doar va instala matplotlib și va raporta versiunea instalată.

Iată o explicație pas cu pas despre cum putem interacționa cu un agent gestionat (codul complet se găsește în scriptul simple_interaction.py din repository):

Mai întâi, importăm pachetele necesare și încărcăm cheia API din fișierul .env pe care l-am creat anterior:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Apoi, inițializăm clientul Gemini și creăm o interacțiune cu agentul de bază, denumit în prezent antigravity-preview-05-2026, cerându-i să instaleze 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"
)

În final, obținem ieșirea de la agent inspectând proprietățile status, environment_id și 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}")

Iată rezultatul:

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

Stările ciclului de viață ale sandbox-ului

În exemplul de mai sus, am afișat identificatorul mediului interacțiunii agentului gestionat:

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

Această valoare este importantă deoarece reprezintă identificatorul mediului în care a fost executat agentul. Interacțiunile agentului sunt stocate într-un mediu efemer care este păstrat până la 7 zile după ultima activitate, înainte de a fi șters.

Diagrama de mai jos ilustrează ciclul de viață al sandbox-ului în care agentul este executat în timpul unei interacțiuni.

Cât timp mediul nu este șters, îl putem accesa și putem efectua interacțiuni suplimentare folosind identificatorul mediului.

Efectuarea de interacțiuni multiple

În acest exemplu, arătăm cum să efectuezi interacțiuni multiple. Codul complet este disponibil în fișierul multiple_interactions.py din 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}")

Observă că în a doua interacțiune am adăugat doi parametri:

• previous_interaction_id: Identificatorul interacțiunii anterioare, astfel încât agentul să cunoască istoricul conversației.

• environment: Identificatorul mediului pentru ca agentul să știe în ce sandbox trebuie să execute.

Partajarea fișierelor cu un agent

Nu putem construi un agent analist de date dacă nu îi putem oferi acces la date. Există câteva moduri prin care putem partaja date cu un agent:

• Date inline: Încărcarea conținutului fișierului într-un șir și trimiterea lui în timpul interacțiunii.
• Fișier găzduit: Găzduirea datelor la un URL public și furnizarea URL-ului pentru ca agentul să le descarce.
• Repository GitHub: Putem furniza agentului un URL de repository GitHub public.
• Google Cloud Bucket: Găzduirea unui fișier într-un bucket Google Cloud Storage și configurarea proiectului astfel încât agentul să aibă acces la acel bucket.

Nu vom explora toate aceste soluții în acest articol. Vom arăta cum să trimiți date inline prin încărcarea unui fișier local într-un șir și cum să partajezi un repository GitHub. Prima este ideală pentru partajarea fișierelor locale mici (până la 1 MB per fișier, cu o limită totală de 2 MB pentru toate fișierele), în timp ce a doua este mai potrivită pentru partajarea fișierelor mai mari, cum ar fi seturile de date.

Partajarea datelor inline

Iată un exemplu de furnizare a datelor inline (codul complet în 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")
            }
        ]
    }
)

Datele sunt furnizate folosind parametrul sources din configurația environment. target definește locația unde vor fi stocate datele în mediul agentului. Fișierele ar trebui să fie situate în folderul workspace. În acest caz, va fi un fișier numit number.txt. 

Parametrul content furnizează conținutul fișierului. Pentru sursele inline, este pur și simplu un șir, pe care în acest caz îl citim folosind funcția read_text_file() din fișierul utils.py.

Partajarea unui repository GitHub

Pentru a partaja fișiere mai mari, putem furniza un URL de repository GitHub. Iată cum:

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

În exemplul de mai sus, repository-ul cu URL-ul https://github.com/fran-aubry/gemini-agents-tutorial este clonat într-un folder numit repository, în interiorul workspace-ului agentului.

Descărcarea mediului unui agent

Am învățat deja cum să interacționăm cu agenții gestionați și cum să furnizăm fișiere acestor agenți. Pentru a crea agentul nostru analist de date, ultimul lucru pe care trebuie să-l învățăm este cum să descărcăm mediul unui agent. Acest lucru este necesar pentru a putea accesa graficele și rezultatele generate de agent.

Fiecare workspace poate fi descărcat la URL-ul:

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

Unde <env_id> trebuie înlocuit cu identificatorul mediului pe care vrem să-l descărcăm.

Iată o funcție Python care folosește pachetul requests pentru a descărca un pachet (această funcție face parte din fișierul utils.py pe care l-am creat):

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

Construirea unui agent analist de date

În această secțiune, învățăm cum să creăm un agent care efectuează analiză de date. Pentru a testa agentul, vom folosi acest set de date Netflix preluat de pe Kaggle, care este stocat și în folderul data din repository.

În toate exemplele anterioare, am interacționat mereu cu agentul de bază: antigravity-preview-05-2026. Aici vom crea mai întâi un agent folosind funcția client.agents.create().

Crearea unui agent

Iată cum putem crea un 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"
                    }
                ]
            }

Să detaliem fiecare parametru:

• id: Definește numele agentului, în acest caz data-analyst. Vom folosi acest identificator în metoda client.interactions.create() în locul antigravity-preview-05-2026 pe care l-am folosit până acum. 

• base_agent: Agentul care va fi folosit ca bază. Asta înseamnă că construim un agent peste agentul antigravity-preview-05-2026.

• base_environment: Ca și înainte, ne permite să furnizăm fișiere agentului. Am furnizat două fișiere speciale: .agents/AGENTS.md și .agents/skills/csv-aggregator/SKILL.md. Aceste fișiere sunt locul în care am definit comportamentul agentului. Fișierul AGENTS.md definește comportamentul general al agentului, în timp ce SKILL.md definește o abilitate specifică pentru agent. I-am oferit de asemenea agentului repository-ul pentru a avea acces la fișierele de date pe care vrem să le analizăm.

Înțelegerea AGENTS.md

Acest fișier poate fi considerat un „system prompt”. Acționează ca manualul nostru principal de instrucțiuni pentru agent. Ar trebui să-l folosim pentru a defini clar rolul specific al agentului, obiectivele sale principale și limitele pe care trebuie să le respecte în timpul lucrului. 

Este, de asemenea, cel mai bun loc unde să listăm orice instrumente sau surse de date specifice la care agentul are voie să acceseze și să oferim exemple despre cum dorim să comunice sau să gestioneze sarcinile. 

Păstrând aceste instrucțiuni simple și bine organizate în fișier, îl ajutăm pe agent să înțeleagă exact cum să se comporte și ce rezultate așteptăm să livreze.

Locația fișierului în mediul agentului ar trebui să fie .agents/AGENTS.md.

Înțelegerea SKILL.md

Fișierele de abilități sunt folosite pentru a dota agentul cu competențe specifice. Un agent poate avea mai multe abilități, iar fiecare dintre ele ar trebui descrisă într-un fișier SKILL.md situat în .agents/skills/<skill_name>/SKILL.md, înlocuind <skill_name> cu numele abilității.

Structura unui fișier de abilitate ar trebui să fie:

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

Pentru a exemplifica, am dotat agentul data-analyst cu o abilitate numită csv-aggregator definită aici. Această abilitate este folosită când vrem să grupăm rândurile unui CSV după o anumită coloană și să adunăm o altă coloană. 

În cazul setului de date Netflix, dacă vrem să știm genurile emisiunilor cu cele mai multe vizualizări, vrem să grupăm rândurile după Genre și să adunăm valorile din coloana Viewership. Acest fișier de abilitate explică agentului cum să efectueze această sarcină.

Încărcarea agentului

Deoarece agenții sunt persistenți, dacă încercăm să rulăm crearea agentului de două ori, vom primi o eroare. Din acest motiv, am creat funcția load_or_create_agent() în fișierul utils.py. Această funcție va încerca să creeze agentul și, dacă există, îl va încărca în schimb folosind funcția client.agents.load().

Punând totul cap la cap

Acum că avem un agent analist de date, e timpul să-l testăm cerându-i să analizeze genurile de pe Netflix. 

Începem ca înainte prin a importa bibliotecile, a încărca cheia API și a inițializa clientul:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Apoi creăm (sau îl încărcăm, dacă nu este prima dată când rulăm scriptul) agentul data-analyst folosind funcția utils.load_or_create_agent():

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

Apoi putem interacționa cu agentul în același mod ca înainte. Singura diferență este că în parametrul agent oferim acum agentul nostru în loc de antigravity-preview-05-2026.

Începem prin a-i cere agentului să instaleze pachetul matplotlib:

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

Observă că, deoarece mediul a fost deja configurat la nivelul agentului, nu mai trebuie să furnizăm fișiere, așa că oferim doar șirul ”remote”.

Apoi îi cerem să folosească instrumentul csv-aggregator pentru a analiza datele Netflix pe genuri ca să vedem care sunt genurile cele mai vizionate:

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
)

Observă că furnizăm identificatorul mediului interacțiunii anterioare astfel încât agentul să poată continua să lucreze peste el.

În final, îi cerem agentului să ploteze datele executând scriptul genres.py creat în pasul anterior (fișierul SKILL.md instruiește agentul să creeze acest script):

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

După această interacțiune, graficul ar trebui să fie creat. Îl putem obține local descărcând mediul:

utils.download_env(inter3.environment_id)

Iată rezultatul:

Codul complet al interacțiunii cu agentul se găsește în analyze_netflix_genres.py.

Concluzie

Posibilitatea de a crea agenți complecși cu un singur apel API fără a te baza pe o infrastructură cloud complicată pentru a crea un sandbox este foarte puternică. Această capabilitate face foarte ușoară crearea de agenți puternici fără să te îngrijorezi de mediul în care sunt executați.

În acest tutorial, am acoperit elementele de bază ale Gemini Managed Agents, dar nu am creat agenți cu adevărat complecși. Te încurajez să aprofundezi și să continui să construiești peste această fundație pentru a-ți exersa abilitățile.