Generative AI Google Brain

agents-managed-agents-managed-agents-world-cup-analysis

3 min read

Managed Agents API - Analyzing the 2026 World Cup

Source notebook

Repo path: agents/managed-agents/managed_agents_world_cup_analysis.ipynb · Open on GitHub · advanced

Deploys a Managed Agents API World Cup analyst agent with GCS skills and multi-turn interactions.

Summary

This notebook demonstrates an end-to-end Managed Agents API workflow on Gemini Enterprise Agent Platform for analyzing 2026 World Cup data. It configures a Google Cloud project and skill bucket, checks AI Platform API and IAM prerequisites, uploads a World Cup analyst skill to Cloud Storage, creates an agent configuration, and launches a multi-turn chat harness through the Interactions API. The sample uses REST APIs for learning rather than the genai SDK.

Key code patterns

Project and bucket configuration

PROJECT_ID = ""
SKILL_GCS_BUCKET = ""
ENDPOINT = "https://aiplatform.googleapis.com"
LOCATION = "global"
 
if not PROJECT_ID:
    raise ValueError("PROJECT_ID is not set")
if not SKILL_GCS_BUCKET:
    raise ValueError("SKILL_GCS_BUCKET is not set")

The workflow requires an explicit Google Cloud project and a GCS bucket for agent skills.

OAuth token management

scopes = ["https://www.googleapis.com/auth/cloud-platform"]
credentials, _ = google.auth.default(scopes=scopes)
credentials.refresh(Request())
self.token = credentials.token
self.expiry = credentials.expiry.replace(tzinfo=timezone.utc)

The Managed Agents REST calls rely on refreshed Google Cloud OAuth credentials.

Environment prerequisite checks

api_name = "aiplatform.googleapis.com"
result = !gcloud services list --project={project_id} --enabled --filter="name:{api_name}"
sa_email = f"service-{project_number}@gcp-sa-aiplatform.iam.gserviceaccount.com"
user_roles_response = !gcloud projects get-iam-policy {project_id}

The notebook validates API enablement and required AI Platform service agent and user roles before deployment.

Upload skill to Cloud Storage

client = storage.Client()
bucket = client.bucket(bucket_name)
blob = bucket.blob(destination_blob_name)
blob.upload_from_string(skill_content)
print(f"Skill uploaded to gs://{bucket_name}/{destination_blob_name}")

The agent skill is stored in GCS as source-bound support for the deployed agent.

Start multi-turn interaction

factory = AgentFactory(project_id=PROJECT_ID, endpoint=ENDPOINT, location=LOCATION)
harness = AgentHarness(factory)
harness.multi_turn_interact()

The harness lists agents and environments, then starts or reconnects to a chat interaction.

Models & APIs used

  • APIs / services: Vertex AI, Cloud Storage, Google OAuth tokeninfo API, Managed Agents API, Interactions API
  • SDKs / libraries: google-auth, google-cloud-storage, requests, ipywidgets, markdown

When to use this

Use this pattern to prototype a managed agent that combines REST-based lifecycle control, Cloud Storage-backed skills, and multi-turn interactions.

Gotchas & caveats

  • The notebook uses preview APIs and states they are not intended for production applications.
  • The sample recommends running in an isolated development or testing project.
  • PROJECT_ID and SKILL_GCS_BUCKET must be set, and the bucket name must not include gs://.
  • aiplatform.googleapis.com must be enabled for the project.
  • The AI Platform service account needs roles/aiplatform.serviceAgent.
  • The authenticated user needs owner, aiplatform.admin, or aiplatform.user project-level access.
  • Email role verification depends on the token including the userinfo.email scope.
  • The notebook uses REST APIs rather than the genai SDK for learning purposes.

Best practices

  • Validate project API enablement and IAM roles before creating the agent.
  • Mask access tokens in logs instead of printing full secrets.
  • Refresh OAuth tokens when missing or expired.
  • Use timezone-aware UTC expiry checks for credentials.
  • Keep agent skills in a configured Cloud Storage bucket or use the Google Cloud Skills Registry.
  • Clearly route domain-specific agent answers to prescribed sources in the skill instructions.
  • Reconnect to existing environments and interactions for multi-turn continuity.

Graph View

Backlinks