Generative AI on Google Cloud

24 / 80·notebook

Chapter 24

Intro to Managed Agents API on Agent Platform (cURL)

NotebookPython 335 cells

In [ ]python · cell 1

python

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Intro to Managed Agents API on Agent Platform (cURL)

Authors
Tianyang Zhan
Eric Schmidt
Polong Lin

Overview

This notebook demonstrates operations for Managed Agents API on Gemini Enterprise Agent Platform using curl commands to interact with the REST APIs.

Covering:

Managed Agents API: Create, list, get, and delete custom agents
Interactions API: Interact with Antigravity (1P) and custom agents
Environment Features: Session state management, MCP tools, skills

Note: The Managed Agents API is in Preview.

Features and schemas are subject to change.
They are not intended for production applications.
It is highly recommended to run this sample in an isolated development or testing project.

For complete Managed Agents API documentation please visit: https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents.

Getting Started

Prerequisites

To use the REST API with curl, you need:

A Google Cloud project with the Agent Platform API enabled.
An access token for authentication.

Set up Environment Variables

Run the following cell to set your project ID and location.

Import Libraries

In [19]python · cell 7

python

import os
import sys
import requests
import json
from IPython.display import display, HTML, JSON as IPythonJSON

Authenticate your Notebook Environment

If you are running this notebook in Google Colab, execute the cell below to authenticate.

In [2]python · cell 9

python

if "google.colab" in sys.modules:
    from google.colab import auth
    auth.authenticate_user()

Set Google Cloud Project Information

To get started using Agent Platform, you must have an existing Google Cloud project and enable the Agent Platform API.

In [ ]python · cell 11

python

# fmt: off
PROJECT_ID = ""  # @param {type: "string", placeholder: "[your-project-id]", isTemplate: true}
# fmt: on
if not PROJECT_ID or PROJECT_ID == "[your-project-id]":
    PROJECT_ID = str(os.getenv("GOOGLE_CLOUD_PROJECT"))

LOCATION = "global"
ENDPOINT = "https://aiplatform.googleapis.com"

print(f"PROJECT_ID: {PROJECT_ID}")
print(f"LOCATION: {LOCATION}")

# Get access token
import subprocess
try:
    TOKEN = subprocess.check_output(["gcloud", "auth", "print-access-token"]).decode("utf-8").strip()
    print("Access token retrieved.")
except Exception as e:
    print(f"Failed to get access token: {e}")
    print("You may need to authenticate.")
    TOKEN = ""

Output

PROJECT_ID: polong-sandbox
LOCATION: global
Access token retrieved.

Project Validation

Before provisioning agents or starting conversations, verify that your Google Cloud project and permissions meet the platform requirements.

The following commands validate:

Authentication: Confirms active Application Default Credentials (ADC).
API Enablement: Verifies aiplatform.googleapis.com is enabled.
User Access: Confirms your identity is authorized.

In [10]python · cell 13

python

def check_project_settings(project_id: str) -> None:
    """Validates GCP project settings, APIs, and IAM roles for AI Platform."""

    # Extract Token
    printed_token = !gcloud auth application-default print-access-token
    token = printed_token[0] if printed_token else None

    if token:
        print("✅ Success on token creation.")
    else:
        print("❌ Token creation failed.")
        return

    # Extract project number
    project_info_response = !gcloud projects describe {project_id} --format="value(projectNumber)"
    if not project_info_response:
        print("❌ Failed to retrieve project number.")
        return

    project_number = project_info_response[0]
    print(f"✅ The project number for {project_id} is: {project_number}")

    # Is aiplatform enabled
    api_name = "aiplatform.googleapis.com"
    result = !gcloud services list --project={project_id} --enabled --filter="name:{api_name}" --format="value(name)"

    if any(api_name in service for service in result):
        print(f"✅ {api_name} is enabled.")
    else:
        print(f"❌ {api_name} is NOT enabled. You may need to run:")
        print(f"   !gcloud services enable {api_name} --project={project_id}")

    # Does service account have needed bindings
    sa_email = f"service-{project_number}@gcp-sa-aiplatform.iam.gserviceaccount.com"
    sa_info_response = !gcloud projects get-iam-policy {project_id} \
        --flatten="bindings[].members" \
        --filter="bindings.members:serviceAccount:{sa_email}" \
        --format="value(bindings.role)"

    if any("aiplatform.serviceAgent" in role for role in sa_info_response):
        print("✅ The service account has the aiplatform.serviceAgent role.")
    else:
        print("❌ The service account does NOT have the aiplatform.serviceAgent role.")
        print("Attempting to add role...")
        attempt_add_role = !gcloud projects add-iam-policy-binding {project_id} \
                            --member="serviceAccount:{sa_email}" \
                            --role="roles/aiplatform.serviceAgent"

    # Extract email from token
    email = None
    try:
        token_info_response = requests.get(f"https://oauth2.googleapis.com/tokeninfo?access_token={token}", timeout=10)

        if token_info_response.status_code == 200:
            data = token_info_response.json()
            # The email will only be present if the \"userinfo.email\" scope was requested
            email = data.get("email")
            print(f"Token belongs to: {email}")
        else:
            print("Invalid or expired token.")
            return
    except requests.RequestException as e:
        print(f"Failed to reach tokeninfo API: {e}")
        return

    if not email:
        print("Email scope not requested; cannot verify user IAM roles.")
        return

    # Does user have needed bindings
    user_roles_response = !gcloud projects get-iam-policy {project_id} \
        --flatten="bindings[].members" \
        --filter="bindings.members:user:{email}" \
        --format="value(bindings.role)"

    print(f"Raw roles found: {user_roles_response}")

    if not user_roles_response:
        print(f"❌ The user {email} has no direct project-level roles assigned.")
        return

    # Check for owner, admin, and user roles
    is_owner = any("roles/owner" in role for role in user_roles_response)
    is_ai_admin = any("aiplatform.admin" in role for role in user_roles_response)
    is_ai_user = any("aiplatform.user" in role for role in user_roles_response)

    if is_owner:
        print(f"✅ The user {email} is a project Owner, which inherits all AI Platform permissions.")
    elif is_ai_admin:
        print(f"✅ The user {email} has the explicit aiplatform.admin role.")
    elif is_ai_user:
        print(f"✅ The user {email} has the explicit aiplatform.user role (standard user access).")
    else:
        print(f"❌ The user {email} does NOT have the aiplatform.admin, aiplatform.user, or owner role.")

check_project_settings(PROJECT_ID)

Output

Raw roles found: ['roles/owner']
✅ The user polong@google.com is a project Owner, which inherits all AI Platform permissions.

Helper function to pretty print

In [17]python · cell 15

python

def pretty_print(data, color="inherit", label=None):
    """
    Prints strings, dicts, lists, or objects with color and formatting.
    """
    # 1. Print an optional bold label to identify the output
    if label:
        display(HTML(f"<b style='color: {color}; font-size: 16px;'>{label}:</b>"))

    # 2. Check if the data is a Dictionary or List (JSON-like)
    if isinstance(data, (dict, list)):
        pretty_json = json.dumps(data, indent=4)
        display(HTML(f"<pre style='color: {color}; font-weight: bold;'>{pretty_json}</pre>"))

    # 3. Check if it's a String
    elif isinstance(data, str):
        display(HTML(f"<div style='color: {color}; font-family: monospace; white-space: pre-wrap;'>{data}</div>"))

    # 4. Handle everything else (integers, objects, etc.)
    else:
        display(HTML(f"<span style='color: {color}; border-bottom: 1px solid {color};'>{repr(data)}</span>"))

Managed Agents API — Create, List, Get, Delete

The Managed Agents API serves as the Control Plane of the platform. It allows you to provision, configure, retrieve, and manage stateful, reusable agent resources that persist securely within your Google Cloud project.

Each custom agent is defined by extending a base_agent (such as antigravity-preview-05-2026) and configuring:

System Instructions: Tailor the agent's expertise and behavior policies.
Built-in Tools: Enable local capabilities like code execution, filesystem operations, or Google Search.
Workspace Mounts: Attach Google Cloud Storage (GCS) directories as sandboxed local paths.
Third-Party Integrations: Connect secure Model Context Protocol (MCP) servers.
Skill Registries: Mount reusable domain-expert instructions from the platform's Skill Registry.

1. Create a Custom Agent with GCS Mount and Default Tools

To start, create a custom agent resource. This agent will extend the foundational base agent with a targeted system instruction, enable built-in developer tools, and mount your Google Cloud Storage (GCS) bucket as a local directory path in its sandboxed environment.

In [ ]python · cell 18

python

token = !gcloud auth application-default print-access-token

AGENT_ID="my-demo-agent" # @param {type:"string"}
AGENT_DESCRIPTION="A demo agent showcasing Environment and Skills use case." # @param {type:"string"}
INSTRUCTIONS="You are a helpful assistant to user." # @param {type:"string"}
GCS_BUCKET="gs://agents-api-sample-skills" # @param {type:"string"}

response = requests.post(
    f"{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents",
    headers = {
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {token[0]}"
    },
    data=json.dumps({
        "id": AGENT_ID,
        "base_agent": "antigravity-preview-05-2026",
        "description": AGENT_DESCRIPTION,
        "system_instruction": INSTRUCTIONS,
        "tools": [
            {"type": "code_execution"},
            {"type": "filesystem"},
            {"type": "google_search"},
            {"type": "url_context"},
        ],
        "base_environment": {
            "type": "remote",
            "sources": [
                {
                    "type": "gcs",
                    "source": GCS_BUCKET,
                    "target": ".agent/skills"
                }
            ],
            "network": {
                "allowlist": [
                    { "domain": "*" }
                ]
            }
        },
    })
)

pretty_print(json.loads(response.content))

Output

<IPython.core.display.HTML object>

{
    "name": "projects/835358766633/locations/global/agents/my-demo-agent/operations/8629567588134813696",
    "metadata": {
        "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateAgentOperationMetadata",
        "genericMetadata": {
            "createTime": "2026-05-19T19:25:41.652154Z",
            "updateTime": "2026-05-19T19:25:41.652154Z"
        }
    }
}

2. List Registered Agents

List all agents in the project.

In [23]python · cell 20

python

print("Listing agents...")
!curl -X GET \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/agents" \
  -H "Authorization: Bearer $TOKEN"

Output

Listing agents...
{
  "agents": [
    {
      "name": "projects/835358766633/locations/global/agents/my-demo-agent",
      "id": "my-demo-agent",
      "created": "2026-05-19T19:25:41.652Z",
      "updated": "2026-05-19T19:25:44.171Z",
      "system_instruction": "You are a helpful assistant to user.",
      "tools": [
        {
          "type": "code_execution"
        },
        {
          "type": "filesystem"
        },
        {
          "type": "google_search"
        },
        {
          "type": "url_context"
        }
      ],
      "description": "A demo agent showcasing Environment and Skills use case.",
      "base_environment": {
        "type": "remote",
        "sources": [
          {
            "type": "gcs",
            "source": "gs://polong-sandbox-bucket",
            "target": ".agent/skills"
          }
        ],
        "network": {
          "allowlist": [
            {
              "domain": "*"
            }
          ]
        }
      },
      "base_agent": "antigravity-preview-05-2026",
      "object": "agent"
    },
    {
      "name": "projects/835358766633/locations/global/agents/my-demo-agent1",
      "id": "my-demo-agent1",
      "created": "2026-05-19T18:49:26.234Z",
      "updated": "2026-05-19T18:49:28.442Z",
      "system_instruction": "You are a helpful assistant to user.",
      "tools": [
        {
          "type": "code_execution"
        },
        {
          "type": "filesystem"
        },
        {
          "type": "google_search"
        },
        {
          "type": "url_context"
        }
      ],
      "description": "A demo agent showcasing Environment and Skills use case.",
      "base_environment": {
        "type": "remote",
        "sources": [
          {
            "type": "gcs",
            "source": "gs://polong-sandbox-bucket",
            "target": ".agent/skills"
          }
        ],
        "network": {
          "allowlist": [
            {
              "domain": "*"
            }
          ]
        }
      },
      "base_agent": "antigravity-preview-05-2026",
      "object": "agent"
    }
  ]
}

3. Get Agent

Retrieve details of a specific agent. You need to provide the AGENT_ID.

In [28]python · cell 22

python

print(f"Getting agent {AGENT_ID}...")
!curl -X GET \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Output

Getting agent my-demo-agent...
{
  "name": "projects/polong-sandbox/locations/global/agents/my-demo-agent",
  "id": "my-demo-agent",
  "created": "2026-05-19T19:25:41.652Z",
  "updated": "2026-05-19T19:25:44.171Z",
  "system_instruction": "You are a helpful assistant to user.",
  "tools": [
    {
      "type": "code_execution"
    },
    {
      "type": "filesystem"
    },
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ],
  "description": "A demo agent showcasing Environment and Skills use case.",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://polong-sandbox-bucket",
        "target": ".agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        {
          "domain": "*"
        }
      ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

4. Update Agent

For fast interactions, you may do in-place updates to your created Agents. All fields other than the identifier agent_id are mutable.

In this example, we will update the system_instruction field of the Agent.

In [29]python · cell 24

python

update_payload = """{
  "system_instruction": "You are a helpful coding assistant. You should always use available tools when relevant."
}"""

with open("update_payload.json", "w") as f:
    f.write(update_payload)

print(f"Updating agent {AGENT_ID}...")
!curl -X PATCH \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/agents/$AGENT_ID?update_mask=system_instruction" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @update_payload.json

Output

Updating agent my-demo-agent...
{
  "name": "projects/polong-sandbox/locations/global/agents/my-demo-agent",
  "id": "my-demo-agent",
  "created": "2026-05-19T19:25:41.652Z",
  "updated": "2026-05-19T19:34:47.236206Z",
  "system_instruction": "You are a helpful coding assistant. You should always use available tools when relevant.",
  "tools": [
    {
      "type": "code_execution"
    },
    {
      "type": "filesystem"
    },
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ],
  "description": "A demo agent showcasing Environment and Skills use case.",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://polong-sandbox-bucket",
        "target": ".agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        {
          "domain": "*"
        }
      ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

5. Delete Agent

Delete the custom agent when you are done.

In [ ]python · cell 26

python

print(f"Deleting agent {AGENT_ID}...")
!curl -X DELETE \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Interactions API — Interact with Agents

The Interactions API is the data plane for communicating with agents at runtime. It supports streaming responses, environment management, and dynamic tool overrides.

1. Interact with the Foundational Base Agent

You can stream conversational interactions directly against the platform's pre-configured foundational base_agent (e.g., antigravity-preview-05-2026) without establishing a custom agent profile first.

In [ ]python · cell 29

python

interaction_payload = """{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "antigravity-preview-05-2026",
  "environment": {"type": "remote"},
  "input": [
      {
          "type": "user_input",
          "content": [
              {
                  "type": "text",
                  "text": "Who are you, can you execute python code? Show me an example."
              }
          ]
      }
  ]
}"""

print("interaction_payload:")
print(interaction_payload)

with open("interaction_payload.json", "w") as f:
    f.write(interaction_payload)

print("Interacting with agent...")
!curl -X POST \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/interactions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d @interaction_payload.json

Output

Interacting with agent...
event: interaction.created
data: {"interaction":{"id":"ChAxZjE3NWZhZDIyNTRkZmVhEAgaAzI3NSoEbWFpbg","status":"in_progress","object":"interaction"},"event_type":"interaction.created"}

event: interaction.status_update
data: {"interaction_id":"ChAxZjE3NWZhZDIyNTRkZmVhEAgaAzI3NSoEbWFpbg","status":"in_progress","event_type":"interaction.status_update"}

event: step.start
data: {"index":0,"step":{"id":"d35bfe13-cfa5-40f4-9531-0a54fdfc57d9","type":"function_call","name":"run_command","arguments":{}},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"arguments":"{\"toolSummary\":\"Python execution demonstration\",\"toolAction\":\"Running Python command\",\"CommandLine\":\"python3 -c \\\"import sys; print(f'Hello from Python {sys.version}!')\\\"\",\"WaitMsBeforeAsync\":5000,\"Cwd\":\"/workspace\",\"explanation\":\"Executed a Python command to demonstrate the capability to run Python code.\"}","type":"arguments_delta"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"call_id":"d35bfe13-cfa5-40f4-9531-0a54fdfc57d9","signature":"","type":"function_result","name":"run_command"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"name":"run_command","is_error":false,"type":"function_result","result":{"Output":"[STDOUT]\nHello from Python 3.11.15 (main, Mar  3 2026, 09:26:23) [GCC 11.4.0]!\n\n\n[STDERR]\n","ExitCode":0}},"event_type":"step.delta"}

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: step.start
data: {"index":2,"step":{"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":2,"delta":{"text":"I am Antigravity, an AI assistant built by Google. Yes","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":", I can run Python code directly in my environment. \n\nHere is an example of running a simple Python script:","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":"\n\n```bash\n$ python3 -c \"import sys; print(f'Hello from Python {sys.version}!')\"\nHello","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" from Python 3.11.15 (main, Mar  3 2026, 0","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":"9:26:23) [GCC 11.4.0]!\n```\n\n### Summary of work","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":"\n- Introduced myself.\n- Demonstrated Python execution capabilities.","type":"text"},"event_type":"step.delta"}

event: step.stop
data: {"index":2,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"ChAxZjE3NWZhZDIyNTRkZmVhEAgaAzI3NSoEbWFpbg","status":"completed","usage":{"total_tokens":14330,"total_input_tokens":13216,"input_tokens_by_modality":[{"modality":"text","tokens":13216}],"total_output_tokens":250,"output_tokens_by_modality":[{"modality":"text","tokens":250}],"total_thought_tokens":864},"created":"2026-05-19T19:13:20Z","updated":"2026-05-19T19:13:20Z","environment_id":"env_CAEQgICAgIDQyIcuGiA5ZGVmMGE0ZTc2ZTk0MjA1OTM1ZjM0OGNjYjgxMjQxNA","object":"interaction"},"event_type":"interaction.completed"}

event: done
data: [DONE]

2. Interact with your Custom Agent

Execute stateful, multi-turn conversations against the custom agent you provisioned on the control plane. This request automatically invokes all mounted capabilities, system instructions, and customized tool suites.

In [30]python · cell 31

python

interaction_payload = f"""{{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "{AGENT_ID}",
  "environment": {{"type": "remote"}},
  "input": [
      {{
          "type": "user_input",
          "content": [
              {{
                  "type": "text",
                  "text": "Who are you, can you execute python code? Show me an example."
              }}
          ]
      }}
  ]
}}"""

print("interaction_payload:")
print(interaction_payload)

with open("interaction_payload.json", "w") as f:
    f.write(interaction_payload)

print("Interacting with agent...")
!curl -X POST \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/interactions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d @interaction_payload.json

Output

interaction_payload:
{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "my-demo-agent",
  "environment": {"type": "remote"},
  "input": [
      {
          "type": "user_input",
          "content": [
              {
                  "type": "text",
                  "text": "Who are you, can you execute python code? Show me an example."
              }
          ]
      }
  ]
}
Interacting with agent...
event: interaction.created
data: {"interaction":{"id":"ChA2M2U5NjA2Y2E5YmFlMDJiEAgaAzBhYSoEbWFpbg","status":"in_progress","object":"interaction"},"event_type":"interaction.created"}

event: interaction.status_update
data: {"interaction_id":"ChA2M2U5NjA2Y2E5YmFlMDJiEAgaAzBhYSoEbWFpbg","status":"in_progress","event_type":"interaction.status_update"}

event: step.start
data: {"index":0,"step":{"id":"e9749919-988b-4ceb-9dd6-efc3cfa43444","type":"function_call","name":"run_command","arguments":{}},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"arguments":"{\"WaitMsBeforeAsync\":5000,\"Cwd\":\"/workspace\",\"toolSummary\":\"Run Python command\",\"toolAction\":\"Running python3 command\",\"CommandLine\":\"python3 -c \\\"import sys; print(f'Python version: {sys.version}'); print('Hello, I am Antigravity! I can run Python code.')\\\"\",\"explanation\":\"Executed a simple inline Python command to demonstrate capability and print the Python version.\"}","type":"arguments_delta"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"call_id":"e9749919-988b-4ceb-9dd6-efc3cfa43444","signature":"","type":"function_result","name":"run_command"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"name":"run_command","is_error":false,"type":"function_result","result":{"ExitCode":0,"Output":"[STDOUT]\nPython version: 3.11.15 (main, Mar  3 2026, 09:26:23) [GCC 11.4.0]\nHello, I am Antigravity! I can run Python code.\n\n\n[STDERR]\n"}},"event_type":"step.delta"}

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: step.start
data: {"index":2,"step":{"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":2,"delta":{"text":"I am Antigravity, a powerful AI assistant designed by Google. \n\nYes, I can execute Python code!","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" Here is an example of running a Python snippet directly in this environment:\n\n```python\nimport sys\n\nprint(f\"Python version:","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" {sys.version}\")\nprint(\"Hello, I am Antigravity! I can run Python code.\")\n","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":"```\n\n**Output:**\n```\nPython version: 3.11.15 (main, Mar  3","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" 2026, 09:26:23)","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" [GCC 11.4.0]\nHello, I am Antigravity! I can run Python code.\n```","type":"text"},"event_type":"step.delta"}

event: step.stop
data: {"index":2,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"ChA2M2U5NjA2Y2E5YmFlMDJiEAgaAzBhYSoEbWFpbg","status":"completed","usage":{"total_tokens":15084,"total_input_tokens":14240,"input_tokens_by_modality":[{"modality":"text","tokens":14240}],"total_output_tokens":281,"output_tokens_by_modality":[{"modality":"text","tokens":281}],"total_thought_tokens":563},"created":"2026-05-19T19:35:07Z","updated":"2026-05-19T19:35:07Z","environment_id":"env_CAEQgICAgIDQyIcuGiA1NmNmNmUwNTlmZGY0NjI0OTJhOWY4MGQzMGQ3Nzk2Yw","object":"interaction"},"event_type":"interaction.completed"}

event: done
data: [DONE]

Cleanup

Delete the test agents we created. Agent configurations persist until explicitly deleted.

5. Clean Up Custom Agents

To release resources and keep your Google Cloud project clean, delete the custom agent configurations when they are no longer needed. Deleted agents are removed permanently from the control plane.

In [ ]python · cell 34

python

for agent_id_to_delete in [AGENT_ID]:
    try:
        response = client.agents.delete(id=agent_id_to_delete)
        print(f"Deleted agent: {agent_id_to_delete}")
    except Exception as e:
        print(f"Failed to delete {agent_id_to_delete}: {e}")

# Verify cleanup
response = client.agents.list()
remaining = [a.id for a in response.agents] if response.agents else []
print(f"\nRemaining agents: {remaining if remaining else 'None'}")

Quick Reference

Agents API

Method	Code	Description
Create	`client.agents.create(id=..., base_agent=..., ...)`	Create a reusable custom agent
List	`client.agents.list()`	List all agents (supports pagination)
Get	`client.agents.get(id="agent-id")`	Retrieve a specific agent by ID
Delete	`client.agents.delete(id="agent-id")`	Delete an agent
Update	Not yet available in Python SDK	Use REST API

Interactions API

Method	Code	Description
Create (streaming)	`client.interactions.create(agent=..., input=..., stream=True)`	Stream interaction events
Create (blocking)	`client.interactions.create(agent=..., input=...)`	Get final result
Session reuse	`environment="env_id_string"`	Reuse sandbox state
MCP override	`tools=[{"type": "mcp_server", ...}]`	Dynamic tool override

Key Parameters

Parameter	Description
`agent`	Base agent name or custom agent ID
`input`	User prompt (string or structured content)
`environment`	`"remote"`, env_id string, or config dict
`stream`	`True` for SSE streaming, `False` for blocking
`background`	`True` to run in background
`store`	`True` to persist for later retrieval
`tools`	List of tool configs (MCP override, etc.)

← 返回课程

Generative AI on Google Cloud

24 / 80·notebook

Chapter 24

Intro to Managed Agents API on Agent Platform (cURL)

NotebookPython 335 cells

In [ ]python · cell 1

python

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Intro to Managed Agents API on Agent Platform (cURL)

Authors
Tianyang Zhan
Eric Schmidt
Polong Lin

Overview

This notebook demonstrates operations for Managed Agents API on Gemini Enterprise Agent Platform using curl commands to interact with the REST APIs.

Covering:

Managed Agents API: Create, list, get, and delete custom agents
Interactions API: Interact with Antigravity (1P) and custom agents
Environment Features: Session state management, MCP tools, skills

Note: The Managed Agents API is in Preview.

Features and schemas are subject to change.
They are not intended for production applications.
It is highly recommended to run this sample in an isolated development or testing project.

For complete Managed Agents API documentation please visit: https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents.

Getting Started

Prerequisites

To use the REST API with curl, you need:

A Google Cloud project with the Agent Platform API enabled.
An access token for authentication.

Set up Environment Variables

Run the following cell to set your project ID and location.

Import Libraries

In [19]python · cell 7

python

import os
import sys
import requests
import json
from IPython.display import display, HTML, JSON as IPythonJSON

Authenticate your Notebook Environment

If you are running this notebook in Google Colab, execute the cell below to authenticate.

In [2]python · cell 9

python

if "google.colab" in sys.modules:
    from google.colab import auth
    auth.authenticate_user()

Set Google Cloud Project Information

To get started using Agent Platform, you must have an existing Google Cloud project and enable the Agent Platform API.

In [ ]python · cell 11

python

# fmt: off
PROJECT_ID = ""  # @param {type: "string", placeholder: "[your-project-id]", isTemplate: true}
# fmt: on
if not PROJECT_ID or PROJECT_ID == "[your-project-id]":
    PROJECT_ID = str(os.getenv("GOOGLE_CLOUD_PROJECT"))

LOCATION = "global"
ENDPOINT = "https://aiplatform.googleapis.com"

print(f"PROJECT_ID: {PROJECT_ID}")
print(f"LOCATION: {LOCATION}")

# Get access token
import subprocess
try:
    TOKEN = subprocess.check_output(["gcloud", "auth", "print-access-token"]).decode("utf-8").strip()
    print("Access token retrieved.")
except Exception as e:
    print(f"Failed to get access token: {e}")
    print("You may need to authenticate.")
    TOKEN = ""

Output

PROJECT_ID: polong-sandbox
LOCATION: global
Access token retrieved.

Project Validation

Before provisioning agents or starting conversations, verify that your Google Cloud project and permissions meet the platform requirements.

The following commands validate:

Authentication: Confirms active Application Default Credentials (ADC).
API Enablement: Verifies aiplatform.googleapis.com is enabled.
User Access: Confirms your identity is authorized.

In [10]python · cell 13

python

def check_project_settings(project_id: str) -> None:
    """Validates GCP project settings, APIs, and IAM roles for AI Platform."""

    # Extract Token
    printed_token = !gcloud auth application-default print-access-token
    token = printed_token[0] if printed_token else None

    if token:
        print("✅ Success on token creation.")
    else:
        print("❌ Token creation failed.")
        return

    # Extract project number
    project_info_response = !gcloud projects describe {project_id} --format="value(projectNumber)"
    if not project_info_response:
        print("❌ Failed to retrieve project number.")
        return

    project_number = project_info_response[0]
    print(f"✅ The project number for {project_id} is: {project_number}")

    # Is aiplatform enabled
    api_name = "aiplatform.googleapis.com"
    result = !gcloud services list --project={project_id} --enabled --filter="name:{api_name}" --format="value(name)"

    if any(api_name in service for service in result):
        print(f"✅ {api_name} is enabled.")
    else:
        print(f"❌ {api_name} is NOT enabled. You may need to run:")
        print(f"   !gcloud services enable {api_name} --project={project_id}")

    # Does service account have needed bindings
    sa_email = f"service-{project_number}@gcp-sa-aiplatform.iam.gserviceaccount.com"
    sa_info_response = !gcloud projects get-iam-policy {project_id} \
        --flatten="bindings[].members" \
        --filter="bindings.members:serviceAccount:{sa_email}" \
        --format="value(bindings.role)"

    if any("aiplatform.serviceAgent" in role for role in sa_info_response):
        print("✅ The service account has the aiplatform.serviceAgent role.")
    else:
        print("❌ The service account does NOT have the aiplatform.serviceAgent role.")
        print("Attempting to add role...")
        attempt_add_role = !gcloud projects add-iam-policy-binding {project_id} \
                            --member="serviceAccount:{sa_email}" \
                            --role="roles/aiplatform.serviceAgent"

    # Extract email from token
    email = None
    try:
        token_info_response = requests.get(f"https://oauth2.googleapis.com/tokeninfo?access_token={token}", timeout=10)

        if token_info_response.status_code == 200:
            data = token_info_response.json()
            # The email will only be present if the \"userinfo.email\" scope was requested
            email = data.get("email")
            print(f"Token belongs to: {email}")
        else:
            print("Invalid or expired token.")
            return
    except requests.RequestException as e:
        print(f"Failed to reach tokeninfo API: {e}")
        return

    if not email:
        print("Email scope not requested; cannot verify user IAM roles.")
        return

    # Does user have needed bindings
    user_roles_response = !gcloud projects get-iam-policy {project_id} \
        --flatten="bindings[].members" \
        --filter="bindings.members:user:{email}" \
        --format="value(bindings.role)"

    print(f"Raw roles found: {user_roles_response}")

    if not user_roles_response:
        print(f"❌ The user {email} has no direct project-level roles assigned.")
        return

    # Check for owner, admin, and user roles
    is_owner = any("roles/owner" in role for role in user_roles_response)
    is_ai_admin = any("aiplatform.admin" in role for role in user_roles_response)
    is_ai_user = any("aiplatform.user" in role for role in user_roles_response)

    if is_owner:
        print(f"✅ The user {email} is a project Owner, which inherits all AI Platform permissions.")
    elif is_ai_admin:
        print(f"✅ The user {email} has the explicit aiplatform.admin role.")
    elif is_ai_user:
        print(f"✅ The user {email} has the explicit aiplatform.user role (standard user access).")
    else:
        print(f"❌ The user {email} does NOT have the aiplatform.admin, aiplatform.user, or owner role.")

check_project_settings(PROJECT_ID)

Output

Raw roles found: ['roles/owner']
✅ The user polong@google.com is a project Owner, which inherits all AI Platform permissions.

Helper function to pretty print

In [17]python · cell 15

python

def pretty_print(data, color="inherit", label=None):
    """
    Prints strings, dicts, lists, or objects with color and formatting.
    """
    # 1. Print an optional bold label to identify the output
    if label:
        display(HTML(f"<b style='color: {color}; font-size: 16px;'>{label}:</b>"))

    # 2. Check if the data is a Dictionary or List (JSON-like)
    if isinstance(data, (dict, list)):
        pretty_json = json.dumps(data, indent=4)
        display(HTML(f"<pre style='color: {color}; font-weight: bold;'>{pretty_json}</pre>"))

    # 3. Check if it's a String
    elif isinstance(data, str):
        display(HTML(f"<div style='color: {color}; font-family: monospace; white-space: pre-wrap;'>{data}</div>"))

    # 4. Handle everything else (integers, objects, etc.)
    else:
        display(HTML(f"<span style='color: {color}; border-bottom: 1px solid {color};'>{repr(data)}</span>"))

Managed Agents API — Create, List, Get, Delete

Each custom agent is defined by extending a base_agent (such as antigravity-preview-05-2026) and configuring:

System Instructions: Tailor the agent's expertise and behavior policies.
Built-in Tools: Enable local capabilities like code execution, filesystem operations, or Google Search.
Workspace Mounts: Attach Google Cloud Storage (GCS) directories as sandboxed local paths.
Third-Party Integrations: Connect secure Model Context Protocol (MCP) servers.
Skill Registries: Mount reusable domain-expert instructions from the platform's Skill Registry.

1. Create a Custom Agent with GCS Mount and Default Tools

In [ ]python · cell 18

python

token = !gcloud auth application-default print-access-token

AGENT_ID="my-demo-agent" # @param {type:"string"}
AGENT_DESCRIPTION="A demo agent showcasing Environment and Skills use case." # @param {type:"string"}
INSTRUCTIONS="You are a helpful assistant to user." # @param {type:"string"}
GCS_BUCKET="gs://agents-api-sample-skills" # @param {type:"string"}

response = requests.post(
    f"{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents",
    headers = {
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {token[0]}"
    },
    data=json.dumps({
        "id": AGENT_ID,
        "base_agent": "antigravity-preview-05-2026",
        "description": AGENT_DESCRIPTION,
        "system_instruction": INSTRUCTIONS,
        "tools": [
            {"type": "code_execution"},
            {"type": "filesystem"},
            {"type": "google_search"},
            {"type": "url_context"},
        ],
        "base_environment": {
            "type": "remote",
            "sources": [
                {
                    "type": "gcs",
                    "source": GCS_BUCKET,
                    "target": ".agent/skills"
                }
            ],
            "network": {
                "allowlist": [
                    { "domain": "*" }
                ]
            }
        },
    })
)

pretty_print(json.loads(response.content))

Output

<IPython.core.display.HTML object>

{
    "name": "projects/835358766633/locations/global/agents/my-demo-agent/operations/8629567588134813696",
    "metadata": {
        "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateAgentOperationMetadata",
        "genericMetadata": {
            "createTime": "2026-05-19T19:25:41.652154Z",
            "updateTime": "2026-05-19T19:25:41.652154Z"
        }
    }
}

2. List Registered Agents

List all agents in the project.

In [23]python · cell 20

python

print("Listing agents...")
!curl -X GET \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/agents" \
  -H "Authorization: Bearer $TOKEN"

Output

Listing agents...
{
  "agents": [
    {
      "name": "projects/835358766633/locations/global/agents/my-demo-agent",
      "id": "my-demo-agent",
      "created": "2026-05-19T19:25:41.652Z",
      "updated": "2026-05-19T19:25:44.171Z",
      "system_instruction": "You are a helpful assistant to user.",
      "tools": [
        {
          "type": "code_execution"
        },
        {
          "type": "filesystem"
        },
        {
          "type": "google_search"
        },
        {
          "type": "url_context"
        }
      ],
      "description": "A demo agent showcasing Environment and Skills use case.",
      "base_environment": {
        "type": "remote",
        "sources": [
          {
            "type": "gcs",
            "source": "gs://polong-sandbox-bucket",
            "target": ".agent/skills"
          }
        ],
        "network": {
          "allowlist": [
            {
              "domain": "*"
            }
          ]
        }
      },
      "base_agent": "antigravity-preview-05-2026",
      "object": "agent"
    },
    {
      "name": "projects/835358766633/locations/global/agents/my-demo-agent1",
      "id": "my-demo-agent1",
      "created": "2026-05-19T18:49:26.234Z",
      "updated": "2026-05-19T18:49:28.442Z",
      "system_instruction": "You are a helpful assistant to user.",
      "tools": [
        {
          "type": "code_execution"
        },
        {
          "type": "filesystem"
        },
        {
          "type": "google_search"
        },
        {
          "type": "url_context"
        }
      ],
      "description": "A demo agent showcasing Environment and Skills use case.",
      "base_environment": {
        "type": "remote",
        "sources": [
          {
            "type": "gcs",
            "source": "gs://polong-sandbox-bucket",
            "target": ".agent/skills"
          }
        ],
        "network": {
          "allowlist": [
            {
              "domain": "*"
            }
          ]
        }
      },
      "base_agent": "antigravity-preview-05-2026",
      "object": "agent"
    }
  ]
}

3. Get Agent

Retrieve details of a specific agent. You need to provide the AGENT_ID.

In [28]python · cell 22

python

print(f"Getting agent {AGENT_ID}...")
!curl -X GET \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Output

Getting agent my-demo-agent...
{
  "name": "projects/polong-sandbox/locations/global/agents/my-demo-agent",
  "id": "my-demo-agent",
  "created": "2026-05-19T19:25:41.652Z",
  "updated": "2026-05-19T19:25:44.171Z",
  "system_instruction": "You are a helpful assistant to user.",
  "tools": [
    {
      "type": "code_execution"
    },
    {
      "type": "filesystem"
    },
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ],
  "description": "A demo agent showcasing Environment and Skills use case.",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://polong-sandbox-bucket",
        "target": ".agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        {
          "domain": "*"
        }
      ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

4. Update Agent

For fast interactions, you may do in-place updates to your created Agents. All fields other than the identifier agent_id are mutable.

In this example, we will update the system_instruction field of the Agent.

In [29]python · cell 24

python

update_payload = """{
  "system_instruction": "You are a helpful coding assistant. You should always use available tools when relevant."
}"""

with open("update_payload.json", "w") as f:
    f.write(update_payload)

print(f"Updating agent {AGENT_ID}...")
!curl -X PATCH \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/agents/$AGENT_ID?update_mask=system_instruction" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @update_payload.json

Output

Updating agent my-demo-agent...
{
  "name": "projects/polong-sandbox/locations/global/agents/my-demo-agent",
  "id": "my-demo-agent",
  "created": "2026-05-19T19:25:41.652Z",
  "updated": "2026-05-19T19:34:47.236206Z",
  "system_instruction": "You are a helpful coding assistant. You should always use available tools when relevant.",
  "tools": [
    {
      "type": "code_execution"
    },
    {
      "type": "filesystem"
    },
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ],
  "description": "A demo agent showcasing Environment and Skills use case.",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://polong-sandbox-bucket",
        "target": ".agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        {
          "domain": "*"
        }
      ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

5. Delete Agent

Delete the custom agent when you are done.

In [ ]python · cell 26

python

print(f"Deleting agent {AGENT_ID}...")
!curl -X DELETE \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Interactions API — Interact with Agents

The Interactions API is the data plane for communicating with agents at runtime. It supports streaming responses, environment management, and dynamic tool overrides.

1. Interact with the Foundational Base Agent

In [ ]python · cell 29

python

interaction_payload = """{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "antigravity-preview-05-2026",
  "environment": {"type": "remote"},
  "input": [
      {
          "type": "user_input",
          "content": [
              {
                  "type": "text",
                  "text": "Who are you, can you execute python code? Show me an example."
              }
          ]
      }
  ]
}"""

print("interaction_payload:")
print(interaction_payload)

with open("interaction_payload.json", "w") as f:
    f.write(interaction_payload)

print("Interacting with agent...")
!curl -X POST \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/interactions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d @interaction_payload.json

Output

Interacting with agent...
event: interaction.created
data: {"interaction":{"id":"ChAxZjE3NWZhZDIyNTRkZmVhEAgaAzI3NSoEbWFpbg","status":"in_progress","object":"interaction"},"event_type":"interaction.created"}

event: interaction.status_update
data: {"interaction_id":"ChAxZjE3NWZhZDIyNTRkZmVhEAgaAzI3NSoEbWFpbg","status":"in_progress","event_type":"interaction.status_update"}

event: step.start
data: {"index":0,"step":{"id":"d35bfe13-cfa5-40f4-9531-0a54fdfc57d9","type":"function_call","name":"run_command","arguments":{}},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"arguments":"{\"toolSummary\":\"Python execution demonstration\",\"toolAction\":\"Running Python command\",\"CommandLine\":\"python3 -c \\\"import sys; print(f'Hello from Python {sys.version}!')\\\"\",\"WaitMsBeforeAsync\":5000,\"Cwd\":\"/workspace\",\"explanation\":\"Executed a Python command to demonstrate the capability to run Python code.\"}","type":"arguments_delta"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"call_id":"d35bfe13-cfa5-40f4-9531-0a54fdfc57d9","signature":"","type":"function_result","name":"run_command"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"name":"run_command","is_error":false,"type":"function_result","result":{"Output":"[STDOUT]\nHello from Python 3.11.15 (main, Mar  3 2026, 09:26:23) [GCC 11.4.0]!\n\n\n[STDERR]\n","ExitCode":0}},"event_type":"step.delta"}

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: step.start
data: {"index":2,"step":{"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":2,"delta":{"text":"I am Antigravity, an AI assistant built by Google. Yes","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":", I can run Python code directly in my environment. \n\nHere is an example of running a simple Python script:","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":"\n\n```bash\n$ python3 -c \"import sys; print(f'Hello from Python {sys.version}!')\"\nHello","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" from Python 3.11.15 (main, Mar  3 2026, 0","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":"9:26:23) [GCC 11.4.0]!\n```\n\n### Summary of work","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":"\n- Introduced myself.\n- Demonstrated Python execution capabilities.","type":"text"},"event_type":"step.delta"}

event: step.stop
data: {"index":2,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"ChAxZjE3NWZhZDIyNTRkZmVhEAgaAzI3NSoEbWFpbg","status":"completed","usage":{"total_tokens":14330,"total_input_tokens":13216,"input_tokens_by_modality":[{"modality":"text","tokens":13216}],"total_output_tokens":250,"output_tokens_by_modality":[{"modality":"text","tokens":250}],"total_thought_tokens":864},"created":"2026-05-19T19:13:20Z","updated":"2026-05-19T19:13:20Z","environment_id":"env_CAEQgICAgIDQyIcuGiA5ZGVmMGE0ZTc2ZTk0MjA1OTM1ZjM0OGNjYjgxMjQxNA","object":"interaction"},"event_type":"interaction.completed"}

event: done
data: [DONE]

2. Interact with your Custom Agent

In [30]python · cell 31

python

interaction_payload = f"""{{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "{AGENT_ID}",
  "environment": {{"type": "remote"}},
  "input": [
      {{
          "type": "user_input",
          "content": [
              {{
                  "type": "text",
                  "text": "Who are you, can you execute python code? Show me an example."
              }}
          ]
      }}
  ]
}}"""

print("interaction_payload:")
print(interaction_payload)

with open("interaction_payload.json", "w") as f:
    f.write(interaction_payload)

print("Interacting with agent...")
!curl -X POST \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/interactions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d @interaction_payload.json

Output

interaction_payload:
{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "my-demo-agent",
  "environment": {"type": "remote"},
  "input": [
      {
          "type": "user_input",
          "content": [
              {
                  "type": "text",
                  "text": "Who are you, can you execute python code? Show me an example."
              }
          ]
      }
  ]
}
Interacting with agent...
event: interaction.created
data: {"interaction":{"id":"ChA2M2U5NjA2Y2E5YmFlMDJiEAgaAzBhYSoEbWFpbg","status":"in_progress","object":"interaction"},"event_type":"interaction.created"}

event: interaction.status_update
data: {"interaction_id":"ChA2M2U5NjA2Y2E5YmFlMDJiEAgaAzBhYSoEbWFpbg","status":"in_progress","event_type":"interaction.status_update"}

event: step.start
data: {"index":0,"step":{"id":"e9749919-988b-4ceb-9dd6-efc3cfa43444","type":"function_call","name":"run_command","arguments":{}},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"arguments":"{\"WaitMsBeforeAsync\":5000,\"Cwd\":\"/workspace\",\"toolSummary\":\"Run Python command\",\"toolAction\":\"Running python3 command\",\"CommandLine\":\"python3 -c \\\"import sys; print(f'Python version: {sys.version}'); print('Hello, I am Antigravity! I can run Python code.')\\\"\",\"explanation\":\"Executed a simple inline Python command to demonstrate capability and print the Python version.\"}","type":"arguments_delta"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"call_id":"e9749919-988b-4ceb-9dd6-efc3cfa43444","signature":"","type":"function_result","name":"run_command"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"name":"run_command","is_error":false,"type":"function_result","result":{"ExitCode":0,"Output":"[STDOUT]\nPython version: 3.11.15 (main, Mar  3 2026, 09:26:23) [GCC 11.4.0]\nHello, I am Antigravity! I can run Python code.\n\n\n[STDERR]\n"}},"event_type":"step.delta"}

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: step.start
data: {"index":2,"step":{"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":2,"delta":{"text":"I am Antigravity, a powerful AI assistant designed by Google. \n\nYes, I can execute Python code!","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" Here is an example of running a Python snippet directly in this environment:\n\n```python\nimport sys\n\nprint(f\"Python version:","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" {sys.version}\")\nprint(\"Hello, I am Antigravity! I can run Python code.\")\n","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":"```\n\n**Output:**\n```\nPython version: 3.11.15 (main, Mar  3","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" 2026, 09:26:23)","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":2,"delta":{"text":" [GCC 11.4.0]\nHello, I am Antigravity! I can run Python code.\n```","type":"text"},"event_type":"step.delta"}

event: step.stop
data: {"index":2,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"ChA2M2U5NjA2Y2E5YmFlMDJiEAgaAzBhYSoEbWFpbg","status":"completed","usage":{"total_tokens":15084,"total_input_tokens":14240,"input_tokens_by_modality":[{"modality":"text","tokens":14240}],"total_output_tokens":281,"output_tokens_by_modality":[{"modality":"text","tokens":281}],"total_thought_tokens":563},"created":"2026-05-19T19:35:07Z","updated":"2026-05-19T19:35:07Z","environment_id":"env_CAEQgICAgIDQyIcuGiA1NmNmNmUwNTlmZGY0NjI0OTJhOWY4MGQzMGQ3Nzk2Yw","object":"interaction"},"event_type":"interaction.completed"}

event: done
data: [DONE]

Cleanup

Delete the test agents we created. Agent configurations persist until explicitly deleted.

5. Clean Up Custom Agents

To release resources and keep your Google Cloud project clean, delete the custom agent configurations when they are no longer needed. Deleted agents are removed permanently from the control plane.

In [ ]python · cell 34

python

for agent_id_to_delete in [AGENT_ID]:
    try:
        response = client.agents.delete(id=agent_id_to_delete)
        print(f"Deleted agent: {agent_id_to_delete}")
    except Exception as e:
        print(f"Failed to delete {agent_id_to_delete}: {e}")

# Verify cleanup
response = client.agents.list()
remaining = [a.id for a in response.agents] if response.agents else []
print(f"\nRemaining agents: {remaining if remaining else 'None'}")

Quick Reference

Agents API

Method	Code	Description
Create	`client.agents.create(id=..., base_agent=..., ...)`	Create a reusable custom agent
List	`client.agents.list()`	List all agents (supports pagination)
Get	`client.agents.get(id="agent-id")`	Retrieve a specific agent by ID
Delete	`client.agents.delete(id="agent-id")`	Delete an agent
Update	Not yet available in Python SDK	Use REST API

Interactions API

Method	Code	Description
Create (streaming)	`client.interactions.create(agent=..., input=..., stream=True)`	Stream interaction events
Create (blocking)	`client.interactions.create(agent=..., input=...)`	Get final result
Session reuse	`environment="env_id_string"`	Reuse sandbox state
MCP override	`tools=[{"type": "mcp_server", ...}]`	Dynamic tool override

Key Parameters

Parameter	Description
`agent`	Base agent name or custom agent ID
`input`	User prompt (string or structured content)
`environment`	`"remote"`, env_id string, or config dict
`stream`	`True` for SSE streaming, `False` for blocking
`background`	`True` to run in background
`store`	`True` to persist for later retrieval
`tools`	List of tool configs (MCP override, etc.)