Generative AI Google Brain

agents-managed-agents-intro-managed-agents-curl

3 min read

Intro to Managed Agents API on Agent Platform (cURL)

Source notebook

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

Shows how to manage and interact with Managed Agents on Agent Platform using REST and cURL.

Summary

The notebook teaches the Managed Agents API control plane for creating, listing, getting, updating, and deleting custom agents. It also demonstrates the Interactions API data plane for streaming conversations with the foundational base agent and a custom agent. The workflow covers authentication, project validation, remote environments, GCS-mounted skills, built-in tools, and cleanup.

Key code patterns

Project setup and token

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = "global"
ENDPOINT = "https://aiplatform.googleapis.com"
TOKEN = subprocess.check_output([
    "gcloud", "auth", "print-access-token"
]).decode().strip()

Sets the project, global location, Vertex AI endpoint, and bearer token required for REST calls.

Validate project

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

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

Create managed agent

requests.post(
  f"{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents",
  headers={"Authorization": f"Bearer {token[0]}"},
  data=json.dumps({
    "id": AGENT_ID,
    "base_agent": "antigravity-preview-05-2026",
    "tools": [{"type": "code_execution"}, {"type": "filesystem"}]
  })
)

Creates a reusable custom agent from a base agent with system instructions and tools.

Mount GCS skills

"base_environment": {
  "type": "remote",
  "sources": [{
    "type": "gcs",
    "source": GCS_BUCKET,
    "target": ".agent/skills"
  }]
}

Mounts a Cloud Storage path into the remote agent environment for skill use.

Stream interaction

curl -X POST \
  "https://aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/interactions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Api-Revision: 2026-05-20" \
  -d @interaction_payload.json

Calls the Interactions API with streaming, background execution, and persisted state.

Models & APIs used

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

When to use this

Use this pattern when you need to prototype managed, stateful Agent Platform agents through REST before relying on SDK support.

Gotchas & caveats

  • Managed Agents API is in Preview and schemas may change.
  • Notebook recommends isolated development or testing projects, not production applications.
  • Requires Agent Platform API enabled on the Google Cloud project.
  • Requires access tokens or ADC and suitable IAM roles such as owner, aiplatform.admin, or aiplatform.user.
  • Uses LOCATION set to global.
  • Interactions calls include Api-Revision: 2026-05-20.
  • The quick reference states agent update is not yet available in the Python SDK and uses REST API.
  • Cleanup section references client.agents even though the notebook primarily uses requests and curl.

Best practices

  • Validate authentication, API enablement, service agent role, and user IAM access before creating agents.
  • Use a targeted system_instruction to tailor custom agent behavior.
  • Delete custom agent configurations when no longer needed to keep the project clean.
  • Use update_mask when patching mutable agent fields.
  • Mount Cloud Storage sources into a remote environment instead of embedding skill content in requests.
  • Use streaming interactions for runtime conversations when incremental events are needed.

Graph View

Backlinks