Budowanie zarządzanych agentów z Gemini API: kompletny przewodnik dla deweloperów

Autonomiczne agenty, które potrafią rozumować, pisać i wykonywać kod, przeglądać internet oraz zarządzać plikami, jeszcze niedawno wymagały tygodni pracy nad infrastrukturą. Wraz z premierą Managed Agents w Gemini API Google sprowadziło tę konfigurację do jednego wywołania API. Jedno żądanie uruchamia bezpieczne, efemeryczne środowisko Linux hostowane przez Google — oraz agenta gotowego do realnej pracy wewnątrz niego.

Ten przewodnik obejmuje wszystko, co deweloperzy powinni wiedzieć: jak działa agent Antigravity, jak budować i wdrażać własnych agentów, jak rozwidlać środowiska dla powtarzalnych uruchomień, jak zabezpieczać networking i poświadczenia oraz jak nowe Gemini CLI wpisuje się w workflow oparty na agentach.

Czym są zarządzani agenci Gemini API?

Managed Agents to nowy deweloperski prymityw Google dla autonomicznych agentów AI w Gemini API. Zamiast samodzielnie składać logikę orkiestracji, środowiska do wykonywania kodu, infrastrukturę do wywoływania narzędzi i mechanizmy bezpieczeństwa, API zajmuje się wszystkim.

Jedno wywołanie Interactions API tworzy izolowane środowisko Linux, uruchamia agenta zasilanego przez Gemini i wykonuje Twoje zadanie od początku do końca. Agent może rozumować i planować, wywoływać narzędzia, wykonywać kod, zarządzać plikami oraz przeglądać internet — wszystko w bezpiecznym runtime, który Google zarządza w Twoim imieniu.

Umożliwiają to dwa interfejsy:

• Interactions API — interfejs runtime. Wysyłasz zadanie, a otrzymujesz agenta, który rozumuje i działa.
• Agents API — warstwa kontroli. Definiujesz, rejestrujesz i zarządzasz nazwanymi agentami z własnymi instrukcjami, narzędziami, umiejętnościami i konfiguracją środowiska.

Agent Antigravity: gotowy do użycia agent ogólnego przeznaczenia

Pierwszym zarządzanym agentem ogólnego przeznaczenia w Gemini API jest Antigravity. Jest napędzany przez Gemini 3.5 Flash i działa na tym samym harnessie, co Antigravity IDE oraz inne pierwszopartyjne produkty Google oparte na agentach. Przed Antigravity jedynym dostępnym zarządzanym agentem był Deep Research — wyspecjalizowany agent do wieloetapowych workflow badawczych.

Antigravity jest odpowiednikiem ogólnego przeznaczenia: jedno wywołanie API tworzy zdalne środowisko Linux i od razu rozpoczyna pracę.

Co potrafi Antigravity

W swoim zarządzanym sandboxie agent Antigravity może:

• Rozumować i planować, korzystając z harnessu agenta Gemini
• Wykonywać kod i zarządzać plikami w bezpiecznym środowisku Linux
• Przeglądać internet, aby pobierać i przetwarzać dane na żywo
• Korzystać z narzędzi, w tym wyszukiwania w sieci, wykonywania kodu i operacji na plikach (I/O)

Twoje pierwsze wywołanie API Antigravity

Oto najprostsze możliwe użycie Antigravity — jedno wywołanie API, które tworzy zdalne środowisko, uruchamia agenta i zwraca wynik:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

To wszystko. Bez konfiguracji kontenera. Bez kodu do sandboxingu. Bez scaffoldu do wywoływania narzędzi. Google zajmuje się wszystkim.

Trwałe środowiska: stanowe agenty wieloetapowe

Środowiska utrzymują się pomiędzy wywołaniami. Pierwsza interakcja tworzy sandbox i zwraca environment_id. Przekaż ten identyfikator w kolejnych żądaniach, a agent wznowi pracę ze wszystkimi plikami, pakietami i stanem dokładnie tam, gdzie poprzednie wywołanie skończyło.

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

Ta stanowość sprawia, że wieloetapowe workflow stają się praktyczne. Agent, który instaluje pakiety, zapisuje pliki i uruchamia analizę w jednym wywołaniu, może przekazać wszystko płynnie do następnego — bez ponownej konfiguracji, bez ponownego pobierania, bez ponownego uruchamiania.

Środowiska mogą też przyjmować dane zewnętrzne przy starcie: repozytoria Git, obiekty Google Cloud Storage lub treści inline mogą zostać zamontowane do sandboxa, zanim agent zacznie pracę.

Budowanie własnych zarządzanych agentów

Agent Antigravity dobrze obsługuje zadania ogólne. Jednak przypadki produkcyjne niemal zawsze wymagają niestandardowego zachowania — konkretnych instrukcji, domenowych umiejętności, autorskich narzędzi lub wyselekcjonowanych źródeł danych. Do tego służy Agents API.

Gemini Managed Agents pozwalają spakować instrukcje, skills, narzędzia i środowisko w nazwanego agenta, którego wywołujesz po ID. Zamiast pisać złożony kod orkiestracji, definiujesz wszystko deklaratywnie — w plikach markdown, takich jak AGENTS.md i SKILL.md — i rejestrujesz to raz.

Definiowanie agenta na podstawie źródeł

Utwórz agenta od zera, określając instrukcje systemowe i źródła. Źródła mogą być repozytoriami GitHub, ścieżkami Google Cloud Storage lub treściami inline. Platforma tworzy świeży sandbox z Twoimi plikami przy każdym wywołaniu.

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

Po zarejestrowaniu data-analyst staje się trwałym agentem, którego możesz wywoływać po nazwie. Każde uruchomienie tworzy czyste środowisko z dokładnie taką konfiguracją, jaką zdefiniowałeś — bez przecieków stanu między wywołaniami.

Rozwidlanie istniejącego środowiska

Czasem najszybszą drogą do własnego agenta jest iteracja. Zacznij od interaktywnej pracy z bazowym agentem Antigravity — instaluj pakiety, twórz szablony, konfiguruj środowisko — a następnie rozwidlij ten snapshot środowiska do wielokrotnego użytku w postaci nazwanego agenta.

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

Po zapisaniu każde kolejne wywołanie my-data-analyst fork'u​je się z tego bazowego snapshotu — zawsze startując z czystego, wstępnie skonfigurowanego stanu.

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

Wzorzec fork-and-register jest szczególnie skuteczny dla agentów zależnych od ciężkiej konfiguracji: złożonych drzew zależności, dużych artefaktów modeli lub wstępnie skompilowanych szablonów, których przebudowa przy każdym wywołaniu trwałaby zbyt długo.

Bezpieczny networking i proxy poświadczeń

Agenty produkcyjne niemal zawsze muszą łączyć się z usługami zewnętrznymi — GitHubem, wewnętrznymi API, rejestrami pakietów — i niemal zawsze muszą robić to bez ujawniania wrażliwych poświadczeń wewnątrz sandboxa. Managed Agents obsługują oba te wymagania dzięki konfigurowalnemu egress proxy.

Konfiguracja sieci spełnia dwa zadania:

1. Allowlisty ograniczają połączenia wychodzące do wyraźnie dozwolonych domen, zapobiegając dostępowi agenta do niezamierzonych usług zewnętrznych.
2. Transformacje nagłówków wstrzykują poświadczenia po stronie serwera, dzięki czemu tokeny API i sekrety nigdy nie trafiają bezpośrednio do środowiska sandbox.

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

W tej konfiguracji agent może łączyć się wyłącznie z api.github.com i pypi.org. Każda próba połączenia z inną domeną jest blokowana. Żądania do GitHuba są automatycznie transformowane tak, aby zawierały nagłówek Authorization — kod w sandboxie nigdy nie widzi tokenu bezpośrednio.

Ta architektura jest kluczowa dla agentów wdrażanych wobec wewnętrznych repozytoriów kodu, autorskich API lub dowolnego środowiska, w którym higiena poświadczeń jest wymogiem zgodności.

Gemini API CLI: doświadczenie deweloperskie zorientowane na agenty

Obok API Google udostępniło eksperymentalne, otwartoźródłowe Gemini API CLI zaprojektowane tak, aby agenty kodujące mogły komunikować się z Gemini API w uporządkowany, przyjazny dla agentów sposób.

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

Workflow agents init / agents test / agents create odzwierciedla zmianę w tym, jak Google oczekuje, że deweloperzy będą budować na Gemini API: definiuj zachowanie agenta w plikach, testuj lokalnie, wdrażaj jako nazwanego zarządzanego agenta — to ten sam wzorzec, który znamy z narzędzi infrastructure-as-code.

Uzupełniające narzędzia

Poza CLI, dwie dodatkowe rzeczy pomagają agentom kodującym pozostawać na bieżąco z Gemini API:

• Gemini API Docs MCP server — zapewnia bieżący dostęp do dokumentacji Gemini, SDK i informacji o modelach przez MCP. Agenty kodujące mogą odpytywać dokumentację bezpośrednio, zamiast polegać na nieaktualnych danych treningowych.
• gemini-interactions-api Skill — automatycznie wstrzykuje wzorce i best practices Interactions API do kontekstu agenta, dzięki czemu agenty budowane z Gemini Managed Agents od początku piszą idiomatyczny kod interakcji.

Dlaczego Managed Agents mają znaczenie w zastosowaniach produkcyjnych

Główna teza stojąca za Managed Agents jest taka, że większość trudnej pracy przy tworzeniu agentów nie leży w modelu — tylko w infrastrukturze wokół niego. Sandboxing, integracja narzędzi, zarządzanie poświadczeniami, powtarzalność środowisk i bezpieczeństwo sieciowe to problemy, które każdy zespół wdrażający agentów musi rozwiązać samodzielnie. Managed Agents czynią z nich problem Google.

Ta zmiana ma praktyczne konsekwencje dla wdrożeń produkcyjnych:

Powtarzalne uruchomienia. Rozwidlone środowiska gwarantują, że każde wywołanie agenta startuje z identycznej bazy — bez dryfu zależności i bez zanieczyszczenia stanu między uruchomieniami.

Mniejsza powierzchnia ataku. Poświadczenia nigdy nie trafiają do sandboxa. Egress sieciowy jest ograniczony allowlistą. Środowisko wykonawcze jest efemeryczne i izolowane. To nie są opcjonalne kroki hardeningu; to domyślne zachowanie.

Szybsza iteracja. Workflow fork-and-register pozwala zespołom eksperymentować interaktywnie, ustabilizować konfigurację i promować ją do nazwanego agenta — bez przepisywania infrastruktury między prototypem a produkcją.

Zgodność z frameworkami. Managed Agents współpracują z frameworkami orkiestracji, których zespoły już używają. Wśród partnerów startowych są Vercel AI SDK, LiteLLM, Agno, Eigent i LlamaIndex — więc istniejące workflow nie wymagają pełnego przepisu, aby skorzystać z zarządzanej infrastruktury.

Managed Agents dla enterprise

Dla przedsiębiorstw, które muszą uruchamiać własnych zarządzanych agentów na dużą skalę, Google oferuje Gemini Enterprise Agent Platform — te same API, ale z dodatkowymi mechanizmami governance, scentralizowaną widocznością i kontrolami polityk na poziomie organizacji.

Managed Agents w Gemini API są obecnie dostępne w wersji preview. Zespoły enterprise mogą korzystać z tych samych prymitywów managed agentów przez Enterprise Agent Platform, z dodatkowymi kontrolami audytu, egzekwowania DLP i governance dla wielu zespołów.

Najważniejsze wnioski

Premiera Gemini API Managed Agents daje deweloperom trzy rzeczy, które wcześniej trudno było połączyć: gotowego do użycia, kompetentnego agenta ogólnego przeznaczenia (Antigravity), czyste API do definiowania i wdrażania własnych agentów z bezpieczeństwem klasy produkcyjnej oraz doświadczenie deweloperskie — CLI, serwer MCP, Skills — zaprojektowane tak, by agenci budowali agentów.

Decyzje infrastrukturalne są trafne: trwałe środowiska, rozwidlanie środowisk, allowlisty egress i server-side credential injection to właściwe prymitywy dla produkcyjnych wdrożeń agentów. Otwarta wersja CLI i Skill pokazują, że Google uznaje doświadczenie deweloperskie dla agentów za równie ważne jak możliwości samego modelu.

Dla zespołów budujących na model-agnostycznej platformie Eigent Gemini Managed Agents stanowią atrakcyjny cel wdrożeniowy — taki, który dobrze współgra ze zdolnością Eigent do inteligentnego routowania zadań między dostawcami modeli, podczas gdy Google obsługuje warstwę wykonania w sandboxie.

Aby zacząć, wypróbuj agenta Antigravity w AI Studio Playground, przeczytaj dokumentację Managed Agents i zainstaluj Python SDK lub JavaScript SDK.

Najczęściej zadawane pytania

Czym są zarządzani agenci Gemini API?

Zarządzani agenci Gemini API to autonomiczne agenty AI działające w hostowanych przez Google, izolowanych środowiskach Linux. Jedno wywołanie Interactions API tworzy sandbox, uruchamia agenta napędzanego przez Gemini i wykonuje Twoje zadanie — w tym wykonywanie kodu, przeglądanie internetu i zarządzanie plikami — bez żadnej konfiguracji infrastruktury z Twojej strony.

Czym jest agent Antigravity?

Antigravity to ogólnego przeznaczenia zarządzany agent Google w Gemini API, napędzany przez Gemini 3.5 Flash. Potrafi rozumować i planować, wykonywać kod, zarządzać plikami i przeglądać internet w bezpiecznym zdalnym środowisku Linux. Korzysta z tego samego harnessu agenta, który napędza Antigravity IDE i inne pierwszopartyjne produkty Google oparte na agentach.

Jak działają trwałe środowiska?

Pierwsze wywołanie interakcji z environment="remote" tworzy nowy sandbox i zwraca environment_id. Przekazanie tego identyfikatora w kolejnych wywołaniach wznawia agenta w tym samym środowisku — ze wszystkimi plikami, zainstalowanymi pakietami i zachowanym stanem. Umożliwia to stanowe, wieloetapowe workflow bez ponownej konfiguracji między wywołaniami.

Jak zbudować własnego zarządzanego agenta?

Użyj Agents API, aby zdefiniować nazwanego agenta, określając bazowego agenta, instrukcje i źródła (repozytoria GitHub, obiekty GCS lub treści inline). Po zarejestrowaniu wywołuj swojego agenta po nazwie przez Interactions API. Alternatywnie iteruj interaktywnie z Antigravity, a następnie rozwidlaj uzyskane środowisko do nazwanego agenta, używając client.agents.create() z base_environment wskazującym na istniejący environment_id.

Jak działa proxy poświadczeń?

Egress proxy zarządzanego agenta znajduje się pomiędzy sandboxem a internetem. Konfigurujesz allowlist dozwolonych domen oraz opcjonalnie reguły transform nagłówków dla każdej domeny. Proxy automatycznie wstrzykuje nagłówki (takie jak Authorization: Bearer <token>) do pasujących żądań wychodzących — dzięki czemu kod w sandboxie nigdy nie ma bezpośredniego dostępu do wartości tokenów.

Które frameworki są kompatybilne z Gemini Managed Agents?

Gemini Managed Agents działają out of the box z Vercel AI SDK, LiteLLM, Agno, Eigent i LlamaIndex. Interactions API jest oparte na REST, więc każdy framework orkiestracyjny obsługujący HTTP może się z nim zintegrować.

Czym jest Gemini API CLI?

Gemini API CLI to eksperymentalne, otwartoźródłowe narzędzie stworzone po to, aby agenty kodujące mogły komunikować się z Gemini API. Obsługuje uruchamianie promptów, generowanie obrazów i audio oraz zarządzanie pełnym cyklem życia zarządzanego agenta — init, test, create i run — z poziomu wiersza poleceń.

Czy Gemini Managed Agents są dostępne do użytku enterprise?

Tak. Te same API Managed Agents są dostępne przez Gemini Enterprise Agent Platform, z dodatkowymi kontrolami governance, scentralizowaną widocznością, egzekwowaniem DLP i zarządzaniem politykami organizacyjnymi. Managed Agents w Gemini API są obecnie dostępne w wersji preview.