Управляемые агенты в Gemini API: практический учебник

Сколько стоят управляемые агенты в Gemini API?

На ценообразование Gemini Managed Agents влияет множество компонентов, поэтому дать точную оценку сложно. Стоимость определяется четырьмя основными факторами:

1. Использование модели (токены): Оплата взимается за количество входных и выходных токенов, обработанных базовой моделью Gemini. Учтите, что сюда входят токены, сгенерированные в промежуточных результатах. Например, если агент генерирует Python-скрипт для построения отчёта, токены для этого скрипта тоже тарифицируются.
2. Инфраструктура и плата за платформу: Управляемые агенты запускаются в интегрированной среде Google, что предполагает сервисные сборы за использование платформенных инструментов (таких как Vertex AI Agent Builder) для управления и развертывания агентов.
3. Кеширование контекста: Если агенты часто повторно используют одни и те же данные, можно применять кеширование контекста. Обычно это значительно снижает стоимость по сравнению со стандартной ценой за токены.
4. Граундирование: Если агент использует сервисы «ground» Google, такие как Google Поиск или Google Карты, они тарифицируются отдельно — часто с квотой бесплатных запросов, после чего взимается плата за 1 000 запросов (обычно около $14/1 000 запросов). 

В этом руководстве мы создадим агента на базе агента antigravity-preview-05-2026, который работает на Gemini 3.5 Flash. Стоимость токенов для Gemini 3.5 Flash следующая:

Как создавать управляемых агентов в Gemini API

В этом гайде мы создадим управляемого агента с помощью Gemini API и Python. Поскольку управляемые агенты — свежий релиз в статусе беты, имейте в виду, что некоторые детали реализации могут изменяться.

Весь код из этого руководства хранится в этом репозитории GitHub, который мы также используем для обмена данными с агентом-аналитиком.

Настройка API

Чтобы создать ключ ИИ, перейдите в Google AI Studio и нажмите «Create API Key» в правом верхнем углу.

Ключи API должны быть привязаны к проекту Google Cloud. Можно выбрать существующий проект или создать новый. Здесь я создал проект с именем gemini-managed-agents.

После создания ключа скопируйте его. Затем создайте файл .env в папке, где будут создаваться агенты, и вставьте ключ в следующем формате:

GEMINI_API_KEY=<paste_your_api_key_here>

Прежде чем закрыть Google AI Studio, нужно подключить биллинг к только что созданному ключу API. Без этого запросы будут отклоняться, так как Google не сможет списывать плату. Чтобы настроить биллинг, нажмите кнопку «Set up billing».

Настройка Python-среды

Мы используем Anaconda для настройки Python-среды для этого проекта. Чтобы создать среду через Anaconda, выполните команду:

conda create --name gemini_agents python=3.12 -y

Эта команда создаёт среду с именем gemini_agents на Python версии 3.10. Параметр -y — это просто автоматический ответ «yes» на все вопросы при создании среды.

Далее активируем её:

conda activate gemini_agents

Наконец, установим необходимые зависимости. Вот как это сделать:

pip install google-genai requests python-dotenv

Создание базового взаимодействия с управляемым агентом

Теперь всё готово, чтобы запустить нашего первого агента. Этот первый агент сделает немногое: он установит matplotlib и сообщит установленную версию.

Вот пошаговое объяснение, как можно взаимодействовать с управляемым агентом (полный код — в скрипте simple_interaction.py в репозитории):

Сначала импортируем необходимые пакеты и загрузим ключ API из ранее созданного файла .env:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Затем инициализируем клиент Gemini и создадим взаимодействие с базовым агентом, который сейчас называется antigravity-preview-05-2026, попросив установить 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"
)

Наконец, получим вывод агента, проверив свойства status, environment_id и 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}")

Вот результат:

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

Состояния жизненного цикла песочницы

В примере выше мы вывели идентификатор среды взаимодействия управляемого агента:

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

Это значение важно, поскольку представляет идентификатор среды, где выполнялся агент. Взаимодействия агента хранятся во временной среде, которая сохраняется до 7 дней после последней активности, а затем удаляется.

Диаграмма ниже иллюстрирует жизненный цикл песочницы, в которой агент выполняется во время взаимодействия.

Пока среда не удалена, мы можем обращаться к ней и выполнять дальнейшие взаимодействия, используя её идентификатор.

Выполнение нескольких взаимодействий

В этом примере показано, как выполнить несколько взаимодействий. Полный код доступен в файле multiple_interactions.py из репозитория.

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

Обратите внимание, что во втором взаимодействии мы добавили два параметра:

• previous_interaction_id: идентификатор предыдущего взаимодействия, чтобы агент знал историю беседы.

• environment: идентификатор среды, чтобы агент понимал, в какой песочнице нужно выполняться.

Обмен файлами с агентом

Мы не сможем создать агента-аналитика, если не предоставим ему доступ к данным. Есть несколько способов поделиться данными с агентом:

• Встроенные данные (inline): Загрузка содержимого файла в строку и отправка её во время взаимодействия.
• Размещённый файл: Разместить данные по публичному URL и передать ссылку, чтобы агент скачал файл.
• Репозиторий GitHub: Можно передать агенту URL публичного репозитория GitHub.
• Объектное хранилище Google Cloud: Разместить файл в бакете Google Cloud Storage и настроить проект так, чтобы агент имел к нему доступ.

Мы не будем рассматривать все решения в этой статье. Мы покажем, как отправлять встроенные данные, загружая локальный файл в строку, и как делиться репозиторием GitHub. Первый способ идеально подходит для небольших локальных файлов (до 1 МБ на файл, с общим лимитом 2 МБ на все файлы), второй — для более крупных файлов, например датасетов.

Передача встроенных данных

Вот пример передачи встроенных данных (полный код в 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")
            }
        ]
    }
)

Данные передаются через параметр sources в конфигурации environment. Параметр target определяет расположение, где данные будут храниться в среде агента. Файлы должны находиться в папке workspace. В нашем случае это будет файл number.txt. 

Параметр content задаёт содержимое файла. Для источников типа inline это просто строка, которую в данном случае мы читаем функцией read_text_file() из файла utils.py.

Передача репозитория GitHub

Чтобы поделиться крупными файлами, можно указать URL репозитория GitHub. Вот как это сделать:

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

В примере выше репозиторий по адресу https://github.com/fran-aubry/gemini-agents-tutorial клонируется в папку repository внутри рабочего пространства агента.

Загрузка среды агента

Мы уже разобрались, как взаимодействовать с управляемыми агентами и как передавать им файлы. Чтобы создать агента-аналитика, осталось понять, как скачивать среду агента. Это нужно, чтобы получить локально графики и результаты, которые агент создаёт.

Каждое рабочее пространство можно скачать по URL:

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

Где вместо <env_id> следует подставить идентификатор нужной среды.

Вот функция на Python, которая с помощью пакета requests скачивает пакет (эта функция — часть файла 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}")

Создание агента-аналитика данных

В этом разделе мы создадим агента, который выполняет анализ данных. Для тестирования возьмём этот датасет Netflix с Kaggle, который также находится в папке data нашего репозитория.

Во всех предыдущих примерах мы взаимодействовали с базовым агентом: antigravity-preview-05-2026. Здесь мы сначала создадим агента с помощью функции client.agents.create().

Создание агента

Вот как можно создать агента:

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

Разберём каждый параметр:

• id: определяет имя агента, в нашем случае — data-analyst. Этот идентификатор мы будем использовать в методе client.interactions.create() вместо antigravity-preview-05-2026, который применяли ранее. 

• base_agent: агент, используемый как база. Это значит, что мы строим агента поверх агента antigravity-preview-05-2026.

• base_environment: как и раньше, позволяет передавать файлы агенту. Мы передали два специальных файла: .agents/AGENTS.md и .agents/skills/csv-aggregator/SKILL.md. В этих файлах определено поведение агента. Файл AGENTS.md задаёт общее поведение агента, а SKILL.md описывает конкретный навык. Мы также предоставили агенту репозиторий, чтобы у него был доступ к данным для анализа.

Понимание AGENTS.md

Этот файл можно рассматривать как системный промпт. Он служит нашим основным руководством для агента. В нём следует чётко определить конкретную роль агента, его главные цели и границы, которых он должен придерживаться в работе. 

Также это лучшее место, чтобы перечислить доступные агенту инструменты или источники данных, а ещё — привести примеры того, как мы хотим, чтобы он общался и выполнял задачи. 

Держа инструкции простыми и хорошо структурированными, мы помогаем агенту точно понимать, как себя вести и какого результата мы ожидаем.

Расположение файла в среде агента должно быть .agents/AGENTS.md.

Понимание SKILL.md

Файлы навыков используются, чтобы наделить агента конкретными умениями. У агента может быть несколько навыков, и каждый из них следует описывать в файле SKILL.md, расположенном по пути .agents/skills/<skill_name>/SKILL.md, где <skill_name> заменяется именем навыка.

Структура файла навыка должна быть такой:

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

Для примера мы добавили агенту data-analyst навык csv-aggregator, определённый здесь. Этот навык используется, когда нужно сгруппировать строки CSV по столбцу и просуммировать значения другого столбца. 

В случае датасета Netflix, если нам нужно узнать жанры шоу с наибольшими просмотрами, мы группируем строки по Genre и суммируем значения в столбце Viewership. Файл навыка объясняет агенту, как выполнить эту задачу.

Загрузка агента

Поскольку агенты персистентны, при повторном запуске создания агента возникнет ошибка. Поэтому мы создали функцию load_or_create_agent() в файле utils.py. Она попытается создать агента, а если он уже существует — загрузит его с помощью client.agents.load().

Собираем всё вместе

Теперь, когда у нас есть агент-аналитик, проверим его, попросив проанализировать жанры Netflix. 

Начнём, как и раньше, с импорта библиотек, загрузки ключа API и инициализации клиента:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Затем создадим (или загрузим, если это не первый запуск скрипта) агента data-analyst с помощью функции utils.load_or_create_agent():

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

Далее взаимодействуем с агентом так же, как раньше. Единственное отличие — в параметре agent теперь указываем нашего агента, а не antigravity-preview-05-2026.

Сначала попросим агента установить пакет matplotlib:

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

Обратите внимание: поскольку среда уже была настроена на уровне агента, больше не нужно передавать файлы — достаточно строки ”remote”.

Затем попросим использовать инструмент csv-aggregator для анализа данных Netflix по жанрам, чтобы увидеть самые просматриваемые жанры:

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
)

Здесь мы передаём идентификатор среды предыдущего взаимодействия, чтобы агент продолжил работу в той же песочнице.

Наконец, попросим агента построить график, выполнив скрипт genres.py, созданный на предыдущем шаге (файл SKILL.md инструктирует агента создать этот скрипт):

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

После этого шага график должен быть создан. Мы можем получить его локально, скачав среду:

utils.download_env(inter3.environment_id)

Вот результат:

Полный код взаимодействия с агентом находится в analyze_netflix_genres.py.

Заключение

Возможность создавать сложных агентов одним вызовом API без развёртывания сложной облачной инфраструктуры для песочницы — это очень мощно. Эту возможность легко использовать для создания сильных агентов, не задумываясь о среде их выполнения.

В этом руководстве мы рассмотрели основы управляемых агентов Gemini, но не создавали по-настоящему сложных агентов. Призываю вас копнуть глубже и продолжать строить решения поверх этой базы, чтобы отточить навыки.