`adk_a2a` (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with us-central1 for non-us-central1 deploys

[qingvincentyin]

Summary

Agents generated from the adk_a2a template with --deployment-target agent_runtime produce an A2A Agent Card whose url points at us-central1 when deployed to any other region (e.g. us-east1). The reasoningEngines/<id> resource is created in the correct region, but the served card url — which A2A clients use as the base for message:send — is wrong.

The root cause is in the Vertex SDK's A2aAgent (filed as googleapis/python-aiplatform#6877). This issue is the defense-in-depth side: the generated agent_runtime_app.py never initializes the Vertex SDK location to the deploy region before constructing the A2aAgent, so the scaffold could prevent the bug even before the SDK fix lands (and it pins google-cloud-aiplatform==1.149.0, so it won't pick up the SDK fix automatically).

Environment

• agents-cli (google-agents-cli) 0.4.0
• Template: adk_a2a, --deployment-target agent_runtime
• google-cloud-aiplatform==1.149.0 (pinned by the template's [tool.uv] override), a2a-sdk==0.3.26
• Deploy region: us-east1

Details

In the generated app/agent_runtime_app.py (template: scaffold/deployment_targets/agent_runtime/python/{{cookiecutter.agent_directory}}/agent_runtime_app.py):

• The A2aAgent subclass is constructed at module import (L151):

  agent_runtime = AgentEngineApp.create(...)

  A2aAgent.__init__ captures initializer.global_config.location at that point. Nothing has set it to the deploy region, so it is the SDK default us-central1.
• set_up() calls vertexai.init() with no location (L123), so the SDK location is never corrected — and even if it were, set_up() runs after __init__ already captured the location.
• build_agent_card() passes only a placeholder rpc_url="http://localhost:9999/" (L109), leaving the real URL to be stamped later by A2aAgent.set_up() using that (default) location.

The Agent Engine runtime injects the correct region as GOOGLE_CLOUD_AGENT_ENGINE_LOCATION (the same env var AdkApp reads), but the A2A path never consults it.

Steps to reproduce

1. agents-cli scaffold create my-a2a --agent adk_a2a --deployment-target agent_runtime
2. agents-cli deploy to a non-us-central1 region (e.g. us-east1).
3. GET https://us-east1-aiplatform.googleapis.com/v1beta1/projects/<p>/locations/us-east1/reasoningEngines/<id>/a2a/v1/card

Expected card.url: https://us-east1-aiplatform.googleapis.com/.../locations/us-east1/.../a2a
Actual card.url: https://us-central1-aiplatform.googleapis.com/.../locations/us-central1/.../a2a

Suggested fix (defense-in-depth)

Have the generated agent_runtime_app.py initialize the Vertex location from the runtime env var before the A2aAgent is constructed, e.g. near the module top:

_loc = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_LOCATION") or os.environ.get("GOOGLE_CLOUD_LOCATION")
if _loc:
    vertexai.init(location=_loc)

(or pass the resolved region into AgentCardBuilder / set_up()).

Workaround

Add the same vertexai.init(location=...) to your own app/agent.py — the scaffold imports it before constructing the agent, so the generated file stays untouched:

import os, vertexai
_loc = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_LOCATION")
if _loc:
    vertexai.init(location=_loc)

Related

Root cause in the Vertex SDK: googleapis/python-aiplatform#6877