Zarządzane Agenty w API Gemini: praktyczny tutorial

Ile kosztują Managed Agents w API Gemini?

Na cenę Gemini Managed Agents składa się wiele elementów, dlatego trudno precyzyjnie oszacować koszty. Koszt zależy głównie od czterech czynników:

1. Wykorzystanie modelu (tokeny): Opłata naliczana jest na podstawie liczby tokenów wejściowych i wyjściowych przetworzonych przez bazowy model Gemini. Obejmuje to także tokeny wygenerowane w wynikach pośrednich. Przykładowo, jeśli agent tworzy skrypt w Pythonie do zbudowania raportu, tokeny potrzebne na ten skrypt również są fakturowane.
2. Infrastruktura i opłaty platformowe: Managed agents działają w zintegrowanym środowisku Google, co wiąże się z opłatami za korzystanie z narzędzi platformowych (takich jak Vertex AI Agent Builder) do zarządzania i wdrażania agentów.
3. Cache kontekstu: Jeśli agenci często ponownie używają tych samych danych, mogą korzystać z cache’owania kontekstu. Zwykle zapewnia to istotne obniżenie kosztów względem standardowego rozliczania tokenów.
4. Grounding: Jeśli agent korzysta z usług ugruntowujących Google, takich jak Google Search czy Google Maps, są one rozliczane osobno, często według limitu bezpłatnych zapytań, a następnie kosztu za 1000 zapytań (zwykle około 14 USD/1000 zapytań). 

W tym tutorialu zbudujemy agenta na bazie agenta antigravity-preview-05-2026, który jest zasilany przez Gemini 3.5 Flash. Koszty tokenów dla Gemini 3.5 Flash są następujące:

Jak budować Managed Agents w API Gemini

W tym przewodniku zbudujemy zarządzanego agenta, korzystając z API Gemini i Pythona. Ponieważ managed agents to świeża funkcja w wersji beta, miej na uwadze, że niektóre szczegóły implementacji mogą się zmieniać.

Cały kod z tego tutorialu znajduje się w tym repozytorium na GitHubie, którego użyjemy też do współdzielenia danych z agentem-analitykiem.

Konfiguracja API

Aby utworzyć klucz AI, przejdź do Google AI Studio i kliknij „Create API Key” w prawym górnym rogu.

Klucze API muszą być powiązane z projektem Google Cloud. Możesz wybrać istniejący albo utworzyć nowy. Tutaj utworzyłem projekt o nazwie gemini-managed-agents.

Po utworzeniu klucza kopiujemy go. Następnie tworzymy plik .env w folderze, w którym będziemy tworzyć naszych agentów, i wklejamy go w następującym formacie:

GEMINI_API_KEY=<paste_your_api_key_here>

Zanim zamkniesz Google AI Studio, musimy skonfigurować rozliczenia dla właśnie utworzonego klucza API. Bez tego nasze żądania będą odrzucane, bo Google nie będzie mogło nas obciążyć. Aby skonfigurować rozliczenia, kliknij przycisk „Set up billing”.

Konfiguracja środowiska Pythona

Do przygotowania środowiska Pythona użyjemy Anacondy. Aby utworzyć środowisko w Anacondzie, użyj polecenia:

conda create --name gemini_agents python=3.12 -y

To tworzy środowisko o nazwie gemini_agents z Pythonem w wersji 3.10. Parametr -y to skrót, który automatycznie odpowiada „tak” na wszystkie pytania podczas tworzenia środowiska.

Następnie musimy je aktywować:

conda activate gemini_agents

Na końcu instalujemy potrzebne zależności. Oto jak:

pip install google-genai requests python-dotenv

Tworzenie podstawowej interakcji z zarządzanym agentem

Mamy już wszystko przygotowane, by uruchomić pierwszego agenta. Ten pierwszy agent nie zrobi wiele — zainstaluje matplotlib i poda wersję, która została zainstalowana.

Oto krok po kroku, jak możemy wejść w interakcję z zarządzanym agentem (pełny kod znajdziesz w skrypcie simple_interaction.py w repozytorium):

Najpierw importujemy potrzebne pakiety i ładujemy klucz API z utworzonego wcześniej pliku .env:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Następnie inicjalizujemy klienta Gemini i tworzymy interakcję z bazowym agentem, obecnie nazwanym antigravity-preview-05-2026, prosząc go o instalację 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"
)

Na końcu pobieramy wynik od agenta, sprawdzając właściwości 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}")

Oto wynik:

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

Stany cyklu życia piaskownicy

W powyższym przykładzie wyświetliliśmy identyfikator środowiska dla interakcji z zarządzanym agentem:

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

Ta wartość jest ważna, ponieważ reprezentuje identyfikator środowiska, w którym wykonano agenta. Interakcje agentów są przechowywane w efemerycznym środowisku, utrzymywanym do 7 dni od ostatniej aktywności, po czym jest ono usuwane.

Poniższy diagram ilustruje cykl życia piaskownicy, w której wykonywany jest agent podczas interakcji.

Dopóki środowisko nie zostanie usunięte, możemy uzyskać do niego dostęp i wykonywać kolejne interakcje, używając jego identyfikatora.

Wykonywanie wielu interakcji

W tym przykładzie pokazujemy, jak wykonać wiele interakcji. Pełny kod znajduje się w pliku multiple_interactions.py z repozytorium.

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

Zauważ, że w drugiej interakcji dodaliśmy dwa parametry:

• previous_interaction_id: Identyfikator poprzedniej interakcji, aby agent znał historię rozmowy.

• environment: Identyfikator środowiska, żeby agent wiedział, w której piaskownicy ma się wykonać.

Udostępnianie plików agentowi

Nie zbudujemy agenta-analityka danych, jeśli nie damy mu dostępu do danych. Istnieje kilka sposobów udostępniania danych agentowi:

• Dane inline: Załadowanie zawartości pliku do łańcucha znaków i wysłanie go podczas interakcji.
• Plik hostowany: Hostowanie danych pod publicznym adresem URL i przekazanie go agentowi do pobrania.
• Repozytorium GitHub: Możemy przekazać agentowi publiczny URL repozytorium na GitHubie.
• Bucket Google Cloud: Umieszczenie pliku w zasobniku Google Cloud Storage i skonfigurowanie projektu tak, aby agent miał do niego dostęp.

Nie będziemy omawiać tu wszystkich rozwiązań. Pokażemy, jak przesłać dane inline, ładując lokalny plik do łańcucha znaków, oraz jak udostępnić repozytorium GitHub. Pierwsze podejście jest idealne do małych lokalnych plików (do 1 MB na plik i łącznie 2 MB dla wszystkich plików), drugie — do większych plików, np. zbiorów danych.

Udostępnianie danych inline

Oto przykład przekazania danych inline (pełny kod w 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")
            }
        ]
    }
)

Dane przekazujemy w parametrze sources w konfiguracji environment. Pole target definiuje lokalizację, w której dane zostaną zapisane w środowisku agenta. Pliki powinny znajdować się w folderze workspace. W tym przypadku będzie to plik number.txt. 

Parametr content dostarcza zawartość pliku. Dla źródeł inline jest to po prostu łańcuch znaków, który w tym przypadku odczytujemy funkcją read_text_file() z pliku utils.py.

Udostępnianie repozytorium GitHub

Aby udostępnić większe pliki, możemy przekazać URL repozytorium GitHub. Oto jak:

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

W powyższym przykładzie repozytorium o URL https://github.com/fran-aubry/gemini-agents-tutorial jest klonowane do folderu repository w przestrzeni roboczej agenta.

Pobieranie środowiska agenta

Nauczyliśmy się już, jak wchodzić w interakcje z zarządzanymi agentami i jak dostarczać im pliki. Aby stworzyć agenta-analityka, musimy jeszcze dowiedzieć się, jak pobrać środowisko agenta — tak, by mieć dostęp do wykresów i wyników wygenerowanych przez agenta.

Każdą przestrzeń roboczą można pobrać spod adresu URL:

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

Gdzie <env_id> należy zastąpić identyfikatorem środowiska, które chcemy pobrać.

Oto funkcja w Pythonie, która używa pakietu requests do pobrania pakietu (funkcja ta jest częścią pliku utils.py):

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

Budowanie agenta-analityka danych

W tej części nauczymy się tworzyć agenta wykonującego analizy danych. Do testów wykorzystamy ten zbiór danych Netflix z Kaggle, który jest też zapisany w folderze data naszego repozytorium.

We wszystkich poprzednich przykładach wchodziliśmy w interakcje z bazowym agentem: antigravity-preview-05-2026. Tutaj najpierw utworzymy agenta za pomocą funkcji client.agents.create().

Tworzenie agenta

Oto jak możemy utworzyć agenta:

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

Omówmy każdy parametr:

• id: Definiuje nazwę agenta, w tym przypadku data-analyst. Tego identyfikatora będziemy używać w metodzie client.interactions.create() zamiast antigravity-preview-05-2026, którego używaliśmy do tej pory. 

• base_agent: Agent używany jako baza. Oznacza to, że budujemy agenta na szczycie agenta antigravity-preview-05-2026.

• base_environment: Jak wcześniej, pozwala dostarczyć pliki agentowi. Dodaliśmy dwa specjalne pliki: .agents/AGENTS.md i .agents/skills/csv-aggregator/SKILL.md. W tych plikach definiujemy zachowanie agenta. Plik AGENTS.md opisuje ogólne zachowanie agenta, a SKILL.md — konkretną umiejętność. Udostępniliśmy też repozytorium, aby agent miał dostęp do plików z danymi do analizy.

Zrozumieć AGENTS.md

Ten plik można traktować jak systemowy prompt. To nasza główna instrukcja dla agenta. Powinniśmy w nim jasno określić specyficzną rolę agenta, jego główne cele i granice, których ma przestrzegać podczas pracy. 

To także najlepsze miejsce, by wypisać konkretne narzędzia lub źródła danych, do których agent ma dostęp, oraz podać przykłady, jak ma komunikować się i realizować zadania. 

Utrzymując te wskazówki proste i dobrze zorganizowane w pliku, pomagamy agentowi dokładnie zrozumieć, jak ma się zachowywać i jakich rezultatów oczekujemy.

Plik powinien być umieszczony w środowisku agenta pod ścieżką .agents/AGENTS.md.

Zrozumieć SKILL.md

Pliki skill służą do wyposażania agenta w konkretne umiejętności. Agent może mieć wiele umiejętności, a każda z nich powinna być opisana w pliku SKILL.md zlokalizowanym w .agents/skills/<skill_name>/SKILL.md, gdzie <skill_name> zastępujemy nazwą umiejętności.

Struktura pliku umiejętności powinna wyglądać tak:

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

Aby to zobrazować, wyposażyliśmy agenta data-analyst w umiejętność o nazwie csv-aggregator, zdefiniowaną tutaj. Ta umiejętność służy do grupowania wierszy pliku CSV po wybranej kolumnie i sumowania innej kolumny. 

W przypadku zbioru Netflix, jeśli chcemy poznać gatunki z największą liczbą wyświetleń, grupujemy wiersze po kolumnie Genre i sumujemy wartości w kolumnie Viewership. Ten plik umiejętności wyjaśnia agentowi, jak wykonać to zadanie.

Ładowanie agenta

Ponieważ agenci są trwałymi obiektami, próba dwukrotnego utworzenia tego samego agenta spowoduje błąd. Dlatego w pliku utils.py przygotowaliśmy funkcję load_or_create_agent(). Próbuje ona utworzyć agenta, a jeśli już istnieje — ładuje go funkcją client.agents.load().

Składamy wszystko w całość

Mając agenta-analityka danych, pora go przetestować, prosząc o analizę gatunków Netflix. 

Zaczynamy jak wcześniej — importujemy biblioteki, ładujemy klucz API i inicjalizujemy klienta:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Następnie tworzymy (lub ładujemy, jeśli to nie pierwszy raz) agenta data-analyst za pomocą funkcji utils.load_or_create_agent():

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

Dalej wchodzimy w interakcję z agentem tak samo jak wcześniej. Jedyna różnica jest taka, że w parametrze agent podajemy teraz naszego agenta zamiast antigravity-preview-05-2026.

Zaczynamy od polecenia zainstalowania pakietu matplotlib:

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

Zauważ, że ponieważ środowisko zostało już skonfigurowane na poziomie agenta, nie musimy dostarczać plików — wystarczy podać ciąg ”remote”.

Następnie prosimy o użycie narzędzia csv-aggregator, aby przeanalizować dane Netflix wg gatunków i zobaczyć, które są najczęściej oglądane:

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
)

Zwróć uwagę, że przekazujemy identyfikator środowiska z poprzedniej interakcji, aby agent mógł kontynuować pracę na jego bazie.

Na końcu prosimy agenta o narysowanie wykresu przez uruchomienie skryptu genres.py utworzonego w poprzednim kroku (plik SKILL.md instruuje agenta, by utworzył ten skrypt):

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

Po tej interakcji wykres powinien być gotowy. Możemy pobrać go lokalnie, ściągając środowisko:

utils.download_env(inter3.environment_id)

Oto wynik:

Pełny kod interakcji z agentem znajdziesz w pliku analyze_netflix_genres.py.

Podsumowanie

Możliwość tworzenia złożonych agentów jednym wywołaniem API, bez konieczności polegania na skomplikowanej infrastrukturze chmurowej do tworzenia piaskownicy, jest bardzo potężna. Dzięki temu niezwykle łatwo tworzyć wydajne agenty, nie martwiąc się o środowisko ich wykonania.

W tym tutorialu omówiliśmy podstawy Gemini Managed Agents, ale nie tworzyliśmy naprawdę złożonych agentów. Zachęcam cię do dalszych eksperymentów i budowania na tym fundamencie, aby szlifować umiejętności.