Support Required || ADK 2.0 Graph Based Workflow Deployment on Agent Engine

[vishalsolanki-AZ]

Hi
Can someone help, I wanna deploy ADK 2.0 on Agent Engine, currently we have ADK 1.0 and it is working as expected but I have doing some study around 2.0 and wanna deploy this as well.

Challenges During Deployment
Deployment Attempts
1. CLI Deployment (adk deploy agent_engine)

• Engine ID Created: 8332638425739952128
• Error: ModuleNotFoundError: No module named 'vertexai.agent_engines.templates.adk'
• What Happened: The ADK CLI auto-generates wrapper code that imports AdkApp, but Agent Engine runtime
  doesn't have this module

2. Programmatic Deployment - Direct Workflow

• Error: agent_engine has none of the following callable methods: query, stream_query, bidi_stream_query
• What Happened: Workflows don't implement the query interface that Agent Engine expects

3. Programmatic Deployment - With AdkApp Wrapper

• Engine ID Created: 7101466877607542784
• Error: Same ModuleNotFoundError: No module named 'vertexai.agent_engines.templates.adk'
• What Happened: Agent Engine runtime can't unpickle the AdkApp wrapper because the module is missing

[adk-bot]

GitHub Issue #5966 Analysis: Support Required || ADK 2.0 Graph Based Workflow Deployment on Agent Engine

Detailed Analysis

1. Root Cause Analysis ("What is broken?")

There are two main behaviors described in the issue during deployment to Vertex AI Agent Engine:

1. ModuleNotFoundError: No module named 'vertexai.agent_engines.templates.adk' (CLI Deployment & Programmatic with AdkApp Wrapper):

   • The Bug: When deploying an ADK 2.0 agent/application, the ADK CLI automatically stages a requirements.txt file or verifies dependencies to be sent to Agent Engine. It currently lists google-cloud-aiplatform[agent_engines] (missing the adk extra).
   • The Failure: The AdkApp class is defined under vertexai.agent_engines.templates.adk in the google-cloud-aiplatform SDK. Because the adk extra is not configured in the container runtime via requirements.txt during deployment, the template and its dependencies (google-adk) are missing when the Agent Engine runtime attempts to unpickle/load the deployed adk_app entrypoint object. This results in the ModuleNotFoundError.

2. agent_engine has none of the following callable methods: query, stream_query, bidi_stream_query (Direct Workflow):

   • Explanation: Workflows are graph configurations and design-time constructs. They do not implement the necessary runtime execution contracts (query, stream_query, or bidi_stream_query) that Vertex AI Agent Engine expects. To deploy they must be wrapped in AdkApp which acts as the adapter interface. Hence, direct programmatic deployment of workflows is unsupported by design, and wrapping them using AdkApp is the correct approach.

---

2. Legitimacy Analysis

• Status: Legitimate Bug
• Evidence:
  • In cli_deploy.py, during dependency enforcement in _ensure_agent_engine_dependency, it writes 'google-cloud-aiplatform[agent_engines]\n' instead of the required 'google-cloud-aiplatform[adk,agent_engines]\n' (which is globally defined at line 38 as _AGENT_ENGINE_REQUIREMENT).
  • In cli_deploy.py, when creating default templates for requirements.txt in to_agent_engine, it also hardcodes 'google-cloud-aiplatform[agent_engines]\n' instead of including the adk extra.
  • In test_cli_deploy.py, the unit test asserts this buggy/incorrect requirement setup during deployment.

---

3. Fix Recommendation

• Recommendation: Should Fix (High Priority)
• Rationale:
  • Impact: Currently blocks all ADK 2.0 deployments to Vertex AI Agent Engine via the ADK CLI/standard workflows.
  • Risk: Very low complexity, localized purely to staging correct dependencies in the deployment directory.
  • Proposed Fix: Change the hardcoded strings in cli_deploy.py and cli_deploy.py to use 'google-cloud-aiplatform[adk,agent_engines]\n' (safely referencing _AGENT_ENGINE_REQUIREMENT), and update the verification in test_cli_deploy.py.

---

4. Existing Pull Requests

• Linked PR: None
• PR URL: None
• Analysis: No open or closed Pull Requests currently mention or fix this issue.

---

Executive Summary

1. What is broken? Standard deployment to Agent Engine fails because google-cloud-aiplatform[agent_engines] is missing the crucial adk extra, causing the vertexai.agent_engines.templates.adk module to fail to unpickle/load on the server.
2. Is the issue legitimate? Yes, the CLI hardcodes the incorrect extra string and the tests validate this incorrect behavior.
3. Should we fix it? Yes, High Priority. It is a critical blocking issue for deployment workflows with a highly straightforward fix and minimal side effects.
4. Is there a linked PR that fixes this issue? None.

---

Would you like me to create and implement a fix for this issue in the workspace? (Note: The changes and tests will be created in a new branch but NOT committed, so you can review and iterate on them.)

[boyangsvl]

/adk-issue-fix

[boyangsvl]

/adk-issue-fix

[boyangsvl]

/adk-issue-fix

[yeesian]

Thanks for reporting this issue @vishalsolanki-AZ, can I check what is the setup you have with "currently we have ADK 1.0 and it is working as expected"? A few questions:

1. Do you maintain a requirements.txt, and if so, where do you store it? (Inside the same directory as the ADK project, or outside)
2. For the CLI deployment, are you specifying the path to the requirements.txt file, or is it automatically picked up by the CLI?
3. For programmatic deployment, what is the corresponding setup?

[vishalsolanki-AZ]

@yeesian
Sharing the claude code output,

Setup for Working ADK 1.31.0 Deployment (Engine ID: xxxxx)

Question 1: Do you maintain a requirements.txt, and if so, where do you store it?

Answer: Yes, we maintain a requirements.txt stored inside the same directory as the ADK project (project
root).

Structure:
di-chatbot/DI-Agent/
├── app/ # Agent code
│ ├── agent.py
│ ├── callbacks.py
│ └── ...
├── pyproject.toml # Source of truth for dependencies
├── requirements.txt # Auto-generated from pyproject.toml
├── deploy.sh # Deployment script
└── .env

requirements.txt content:
google-adk>=1.31.0
google-cloud-aiplatform[agent_engines,adk]>=1.80.0
google-genai>=1.14.0
pydantic>=2.6.0
opentelemetry-instrumentation-google-genai>=0.4b0
opentelemetry-instrumentation-vertexai>=2.0b0
opentelemetry-exporter-gcp-logging
opentelemetry-exporter-gcp-monitoring
opentelemetry-exporter-otlp-proto-grpc

Note: The requirements.txt is auto-generated on every deployment from pyproject.toml:
python3 -c "
import tomllib, pathlib
p = tomllib.loads(pathlib.Path('pyproject.toml').read_text())
for dep in p['project']['dependencies']:
print(dep)
" > requirements.txt

---

Question 2: For the CLI deployment, are you specifying the path to the requirements.txt file, or is it
automatically picked up?

Answer: We explicitly specify the path via --requirements_file flag.

Deployment command:
adk deploy agent_engine
--project="addv1-genai-diagint-2026"
--region="us-central1"
--display_name="DI-chatbot-agent"
--description="Diagnostic Intelligence chatbot"
--env_file=".env"
--requirements_file="requirements.txt" \ # ← Explicitly specified
--trace_to_cloud
--agent_engine_id="7960686836202864640"
app

The path is relative to the script execution directory (same directory as deploy.sh).

---

Question 3: For programmatic deployment, what is the corresponding setup?

Answer: We attempted programmatic deployment for ADK 2.0 using the same structure as ADK 1.31.0, but
encountered errors.

Setup:

File: graph-agent/app/graph_app.py
from google.adk.workflow import Workflow
from google.adk.apps import App

workflow = Workflow(
name="di_chatbot",
description="Diagnostic Intelligence chatbot with security pipeline",
edges=[...] # Graph nodes
)

root_agent = workflow
app = App(name="app", root_agent=workflow)

Programmatic deployment script: deploy_programmatic.py
import vertexai
from vertexai import agent_engines
from vertexai.agent_engines import AdkApp
from app.graph_app import app as adk_app

Initialize Vertex AI

vertexai.init(
project="addv1-genai-diagint-2026",
location="us-central1",
staging_bucket="gs://ad-alloydb-files-to-upload"
)

Wrap in AdkApp

wrapped_app = AdkApp(agent=adk_app)

Deploy

remote_app = agent_engines.create(
agent_engine=wrapped_app,
display_name="DI-chatbot-graph-agent-v2",
description="Diagnostic Intelligence chatbot using ADK 2.1.0 Workflows",
requirements=[
"google-adk>=2.1.0",
"google-cloud-aiplatform[agent_engines,adk]>=1.80.0",
"google-genai>=1.14.0",
"pydantic>=2.6.0",
"opentelemetry-instrumentation-google-genai>=0.4b0",
"opentelemetry-instrumentation-vertexai>=2.0b0",
"opentelemetry-exporter-gcp-logging",
"opentelemetry-exporter-gcp-monitoring",
"opentelemetry-exporter-otlp-proto-grpc",
],
env_vars={...}
)

---

Errors Encountered:

Attempt 1: Direct Workflow (No AdkApp Wrapper)

remote_app = agent_engines.create(
agent_engine=workflow, # Direct workflow object
...
)

Error:
agent_engine has none of the following callable methods:
query, stream_query, bidi_stream_query

Reason: Workflows don't implement the required query interface.

---

Attempt 2: With AdkApp Wrapper ✅ Correct Approach

wrapped_app = AdkApp(agent=adk_app)
remote_app = agent_engines.create(
agent_engine=wrapped_app,
...
)

Result:

• ✅ Deployment started successfully
• ✅ Engine ID created: xxxxxxx
• ✅ Requirements uploaded to GCS (with [agent_engines,adk])
• ✅ Logs show: The final list of requirements: ['google-adk>=2.1.0',
  'google-cloud-aiplatform[agent_engines,adk]>=1.80.0', ...]

Runtime Error:
ModuleNotFoundError: No module named 'vertexai.agent_engines.templates.adk'

Pickle load failed: Missing module. A required module, present when the
agent object was pickled locally, is missing in the remote environment.

Traceback:
File "/code/app/api/factory/utils.py", line 193, in get_local_object
return cloudpickle.loads(f.read())
ModuleNotFoundError: No module named 'vertexai.agent_engines.templates.adk'

Details:

• Agent Engine successfully created the resource
• Runtime started but failed during unpickling
• The AdkApp class from vertexai.agent_engines.templates.adk doesn't exist in Agent Engine runtime
  environment
• Even though requirements included [agent_engines,adk], the module was missing in runtime

---

Key Finding:

The programmatic deployment correctly configured everything locally:

• ✅ Used AdkApp wrapper
• ✅ Included [agent_engines,adk] in requirements
• ✅ Engine resource created successfully
• ❌ Runtime environment lacks the vertexai.agent_engines.templates.adk module