molecule-core/docs/tutorials/google-adk-runtime.md

Running a Google ADK Workspace on Molecule AI

Status (2026-05-29): the google-adk runtime is landing, not yet on main. It's implemented in the template repo molecule-ai-workspace-template-google-adk (PR #1) with platform registration in molecule-core PR #2003 and the validator allowlist in molecule-ci PR #26. Design + approval: RFC internal#730. Remove this banner once those PRs merge.

Doc-accuracy note: a prior version of this page claimed ADK was "already first-class" and cited "PR #550" — that PR is unrelated (a MemoryTab test suite). No google-adk adapter existed at that time. This rewrite reflects the real implementation.

Google's Agent Development Kit (ADK) runs as a Molecule AI workspace runtime: ADK is the agent engine (LlmAgent + Runner), and the workspace participates in Molecule's A2A org like any other runtime.

How it actually works

• ADK = engine only. The adapter builds an ADK LlmAgent from the workspace config (model + system prompt + tools) and drives its Runner. It installs google-adk[mcp]==2.1.0 and never the [a2a] extra — ADK's a2a layer pins a2a-sdk<0.4, which is incompatible with the platform's a2a-sdk>=1.0. (Verified: google-adk[mcp]==2.1.0 + a2a-sdk 1.0.3 coexist.)
• A2A is provided by the platform's a2a-1.x server; a Molecule-authored executor bridges ADK's Runner event stream onto it, one ADK session per A2A context_id.
• Tools reach the agent via ADK's native McpToolset pointed at the workspace's a2a_mcp_server — the same MCP surface the CLI runtimes use (delegate_task, commit_memory, list_peers, …). No LangChain.

Auth — Vertex AI via ADC (keyless), or an AI Studio key

The runtime supports both google-genai auth paths:

• Vertex AI + Application Default Credentials (recommended; required if your org disallows API keys). Set model: vertex:gemini-2.5-pro and provide GOOGLE_CLOUD_PROJECT; the adapter sets GOOGLE_GENAI_USE_VERTEXAI=1 and google-genai authenticates via ADC — no API key. (Locally: gcloud auth application-default login.)
• AI Studio API key (where your org permits API keys): set model: google_genai:gemini-2.5-pro and GOOGLE_API_KEY.

Create a workspace

# Vertex AI + ADC (keyless)
curl -s -X POST http://localhost:8080/workspaces \
  -H "Content-Type: application/json" \
  -d '{
    "name": "adk-agent",
    "role": "Google ADK inference worker",
    "runtime": "google-adk",
    "model": "vertex:gemini-2.5-pro",
    "runtime_config": {"required_env": ["GOOGLE_CLOUD_PROJECT"]}
  }'

Send it a task via the A2A proxy (POST /workspaces/:id/a2a, JSON-RPC message/send) and it replies through the ADK Runner. Verified end-to-end: a Gemini 2.5 round-trip on Vertex via ADC returns through the built image.

Related

• Template + adapter: molecule-ai-workspace-template-google-adk (PR #1)
• Platform registration: molecule-core PR #2003 · validator: molecule-ci PR #26
• Design/approval: RFC internal#730
• Google ADK (adk-python)