Generative AI Google Brain

agents-managed-agents-intro-managed-agents-python

3 min read

Intro to Managed Agents API on Agent Platform (Python)

Source notebook

Repo path: agents/managed-agents/intro_managed_agents_python.ipynb · Open on GitHub · intermediate

Shows how to create, inspect, interact with, and delete Managed Agents with google-genai.

Summary

This notebook introduces the Preview Managed Agents API on Gemini Enterprise Agent Platform using the Gen AI SDK for Python. It validates project setup, creates custom agents from a base agent, configures tools, GCS mounts, MCP servers, and skill sources, then streams interactions. It also demonstrates environment ID reuse for session state, per-request MCP overrides, and cleanup.

Key code patterns

Enterprise GenAI client

from google import genai
 
LOCATION = "global"
client = genai.Client(
    enterprise=True,
    project=PROJECT_ID,
    location=LOCATION,
)

Initializes the Gen AI SDK client for Agent Platform operations.

Project diagnostics

token = !gcloud auth application-default print-access-token
result = !gcloud services list --project={project_id} --enabled \
    --filter="name:aiplatform.googleapis.com" --format="value(name)"
user_roles = !gcloud projects get-iam-policy {project_id} \
    --flatten="bindings[].members" --format="value(bindings.role)"

Checks ADC, API enablement, service agent role, and user IAM before provisioning agents.

Create custom agent

agent = client.agents.create(
    id=AGENT_ID,
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a helpful coding assistant.",
    tools=[{"type": "code_execution"}, {"type": "google_search"}],
    base_environment={"type": "remote"},
)

Creates a reusable managed agent with instructions, tools, and remote environment settings.

Mount GCS workspace

base_environment={
    "type": "remote",
    "sources": [{
        "type": "gcs",
        "source": "gs://" + AGENT_GCS_BUCKET,
        "target": "/.agent",
    }],
}

Mounts a Cloud Storage bucket into the agent sandbox as a workspace path.

Stream interaction

stream = client.interactions.create(
    agent=AGENT_ID,
    input="Tell me the name of python packages used for data analysis.",
    stream=True,
    background=True,
    store=True,
)
for event in stream:
    print(event)

Uses the Interactions API data plane to stream runtime events from an agent.

Reuse environment state

env_id = event.interaction.environment_id
stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Read the file hello.txt and print its contents.",
    environment=env_id,
    stream=True,
)

Reuses a sandbox environment ID to preserve files and execution context across turns.

MCP tool override

stream = client.interactions.create(
    agent=AGENT_ID,
    input="Use the grep tool to search for 'fibonacci' in github.",
    tools=[{"type": "mcp_server", "url": "https://mcp.grep.app", "name": "grep-search"}],
    stream=True,
)

Adds or overrides MCP tools at interaction time without changing the agent configuration.

Models & APIs used

  • Models: antigravity-preview-05-2026
  • APIs / services: Vertex AI, Agent Platform, Managed Agents API, Interactions API, Cloud Storage
  • SDKs / libraries: google-genai, requests

When to use this

Use this pattern to prototype managed, stateful Agent Platform agents with tools, MCP integrations, skills, and remote sandbox state.

Gotchas & caveats

  • Managed Agents API is in Preview and schemas may change.
  • The sample is not intended for production applications.
  • The notebook recommends an isolated development or testing project.
  • Agent Platform API aiplatform.googleapis.com must be enabled.
  • ADC authentication and user IAM roles are required.
  • The AI Platform service agent needs roles/aiplatform.serviceAgent.
  • agents.update() is not yet available in the Python SDK; updates require REST PATCH with update_mask.
  • Sandbox environment state has a 7-day TTL that resets with each interaction.

Best practices

  • Validate authentication, API enablement, service agent role, and user access before creating agents.
  • Use unique agent IDs with uuid to avoid naming collisions.
  • Poll agent creation status with client.agents.get because creation is asynchronous.
  • Delete test agents after the demo to keep the project clean.
  • Reuse environment IDs when filesystem or execution context must persist across turns.
  • Use per-request MCP overrides for temporary tool customization.

Graph View

Backlinks