docs: add Google ADK runtime adapter documentation (#4)
Pre-draft docs for the google-adk workspace adapter (issue #542, PR #550). Covers installation, secrets, config reference, A2A compatibility, plugin support, and troubleshooting. Also adds google-adk to the runtimes table in architecture.mdx and the runtime list in concepts.mdx. Closes #542 Co-authored-by: Molecule AI Documentation Specialist <documentation-specialist@agents.moleculesai.app> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
molecule-ai[bot]
GitHub
parent
e2a772d561
commit
0a4b8119c4
@ -111,6 +111,7 @@ The shared runtime provides the base agent infrastructure: A2A server, heartbeat
|
||||
| DeepAgents | `molecule-ai-workspace-template-deepagents` | deepagents |
|
||||
| Hermes | `molecule-ai-workspace-template-hermes` | openai, anthropic, google-genai |
|
||||
| Gemini CLI | `molecule-ai-workspace-template-gemini-cli` | @google/gemini-cli (npm) |
|
||||
| [Google ADK](/docs/google-adk) | `molecule-ai-workspace-template-google-adk` | google-adk>=1.0.0 |
|
||||
|
||||
Each adapter repo has its own `Dockerfile` that installs `molecule-ai-workspace-runtime` from PyPI plus adapter-specific dependencies. Templates are cloned at Docker build time into the platform image via `manifest.json`.
|
||||
|
||||
|
||||
@ -12,7 +12,7 @@ workspace has:
|
||||
- An **initial prompt** (run once at first boot — typically clone repo,
|
||||
read docs, memorise context)
|
||||
- A **runtime** (`claude-code`, `langgraph`, `crewai`, `autogen`, `deepagents`,
|
||||
`openclaw`, `hermes`, `gemini-cli`)
|
||||
`openclaw`, `hermes`, `gemini-cli`, [`google-adk`](/docs/google-adk))
|
||||
- A **tier** (resource budget — T1 sandboxed, T2 standard, T3 privileged, T4 full-host)
|
||||
- An optional **parent** (forms the org tree)
|
||||
- An optional **workspace_dir** (a host path bind-mounted into the
|
||||
|
||||
244
content/docs/google-adk.mdx
Normal file
244
content/docs/google-adk.mdx
Normal file
@ -0,0 +1,244 @@
|
||||
---
|
||||
title: Google ADK Runtime
|
||||
description: Run Molecule AI workspaces on Google's Agent Development Kit (ADK) — Gemini-native agents with sequential, parallel, and loop workflows.
|
||||
---
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
# Google ADK Runtime
|
||||
|
||||
The `google-adk` runtime adapter integrates [Google's Agent Development Kit](https://github.com/google/adk-python) (v1.0+, Apache-2.0) into Molecule AI workspaces. ADK is Google's production-grade Python framework for building AI agents backed by Gemini models, with built-in support for sequential, parallel, and loop execution patterns.
|
||||
|
||||
<Callout type="info">
|
||||
Google ADK adapter was added in PR #550 (issue #542). It passes 46/46 tests with 100% coverage.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## When to use Google ADK vs other runtimes
|
||||
|
||||
| | Google ADK | LangGraph | AutoGen |
|
||||
|---|---|---|---|
|
||||
| **Best for** | Gemini-native agents, Google Cloud integrations | Complex stateful graphs, fine-grained flow control | Multi-agent dialogue and code-execution workflows |
|
||||
| **Model family** | Gemini (gemini-2.0-flash, gemini-1.5-pro, …) | Any LangChain-supported model | Any AutoGen-supported model |
|
||||
| **Execution model** | Sequential / Parallel / Loop built-in | Explicit graph with nodes and edges | Conversation-driven, agents negotiate through dialogue |
|
||||
| **Tool support** | Google-native + LangChain tools | LangChain tools | Python functions, code execution |
|
||||
| **State persistence** | ADK SessionService | LangGraph checkpointer | In-process conversation history |
|
||||
| **Google Cloud fit** | First-class | Via LangChain integrations | Via plugin |
|
||||
|
||||
**Choose Google ADK when:**
|
||||
- Your workload is Google Cloud–native (Vertex AI, Cloud Tools, Google Workspace)
|
||||
- You want Gemini models with minimal adapter overhead
|
||||
- You prefer ADK's opinionated sequential/parallel/loop composition over explicit graph edges
|
||||
- You're building agents that call Google APIs (Maps, Search, Drive, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
Each Molecule AI workspace template is a standalone Docker image. The Google ADK workspace template (`molecule-ai-workspace-template-google-adk`) ships with the adapter pre-configured. To use it, set the runtime in your workspace `config.yaml`:
|
||||
|
||||
```yaml title="config.yaml"
|
||||
runtime: google-adk
|
||||
model: google:gemini-2.0-flash
|
||||
```
|
||||
|
||||
If you are building a custom image on top of `molecule-ai-workspace-runtime`, add the adapter dependency to your `requirements.txt`:
|
||||
|
||||
```text title="requirements.txt"
|
||||
molecule-ai-workspace-runtime>=0.1.0
|
||||
google-adk>=1.0.0
|
||||
```
|
||||
|
||||
Install manually with pip:
|
||||
|
||||
```bash
|
||||
pip install google-adk
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Google ADK requires **Python 3.10+**. Ensure your workspace Dockerfile uses `python:3.11-slim` or newer.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Secrets
|
||||
|
||||
The adapter reads your Google credentials from workspace secrets. Set these before starting a Google ADK workspace:
|
||||
|
||||
| Secret key | Required | Purpose |
|
||||
|---|---|---|
|
||||
| `GOOGLE_API_KEY` | Yes (unless using Vertex AI) | Gemini API key from [Google AI Studio](https://aistudio.google.com/app/apikey) |
|
||||
| `GOOGLE_CLOUD_PROJECT` | Vertex AI only | GCP project ID |
|
||||
| `GOOGLE_CLOUD_LOCATION` | Vertex AI only | Region (e.g. `us-central1`) |
|
||||
| `GOOGLE_GENAI_USE_VERTEXAI` | Vertex AI only | Set to `true` to route via Vertex AI instead of the public API |
|
||||
|
||||
Set secrets via the canvas Settings panel or the API:
|
||||
|
||||
```bash
|
||||
curl -X PUT http://localhost:8080/settings/secrets \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"key":"GOOGLE_API_KEY","value":"AIza..."}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic usage
|
||||
|
||||
### Minimal `config.yaml`
|
||||
|
||||
```yaml title="config.yaml"
|
||||
name: My ADK Agent
|
||||
runtime: google-adk
|
||||
model: google:gemini-2.0-flash
|
||||
role: |
|
||||
You are a helpful assistant. Answer questions clearly and concisely.
|
||||
tier: 2
|
||||
```
|
||||
|
||||
### With runtime configuration
|
||||
|
||||
```yaml title="config.yaml"
|
||||
name: Research Agent
|
||||
runtime: google-adk
|
||||
model: google:gemini-1.5-pro
|
||||
role: |
|
||||
You are a research specialist. Gather and synthesise information from multiple sources.
|
||||
tier: 2
|
||||
|
||||
runtime_config:
|
||||
max_iterations: 20
|
||||
enable_code_execution: true
|
||||
temperature: 0.3
|
||||
```
|
||||
|
||||
### Org template example
|
||||
|
||||
```yaml title="org-template/org.yaml"
|
||||
org_name: Research Team
|
||||
defaults:
|
||||
runtime: google-adk
|
||||
model: google:gemini-2.0-flash
|
||||
tier: 2
|
||||
|
||||
workspaces:
|
||||
- name: Research Lead
|
||||
role: Coordinate research tasks and synthesise findings from your team.
|
||||
children:
|
||||
- name: Web Researcher
|
||||
role: Search the web and extract relevant information.
|
||||
runtime_config:
|
||||
enable_code_execution: false
|
||||
- name: Data Analyst
|
||||
role: Analyse datasets and produce statistical summaries.
|
||||
runtime_config:
|
||||
enable_code_execution: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration reference
|
||||
|
||||
All options go under `runtime_config:` in `config.yaml`.
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `max_iterations` | integer | `10` | Maximum agent reasoning steps per turn |
|
||||
| `temperature` | float | `0.0` | Sampling temperature passed to the Gemini model (0.0–2.0) |
|
||||
| `enable_code_execution` | boolean | `false` | Allow the agent to execute Python code via ADK's built-in code-execution tool |
|
||||
| `output_key` | string | `"output"` | Key in the ADK session state that holds the agent's final response |
|
||||
| `session_db_url` | string | `null` | SQLite or Postgres URL for ADK session persistence across restarts. If null, uses in-memory session storage. |
|
||||
|
||||
---
|
||||
|
||||
## Tools and plugins
|
||||
|
||||
The Google ADK adapter is fully compatible with Molecule AI's plugin system. Plugins installed in a workspace are injected into the ADK agent's tool list via the runtime's plugin registry.
|
||||
|
||||
**Supported plugin shapes with Google ADK:**
|
||||
|
||||
| Plugin shape | Supported | Notes |
|
||||
|---|---|---|
|
||||
| MCP server | Yes | Tools exposed via MCP are wrapped as ADK `FunctionTool` instances |
|
||||
| Skill files | Yes | Skills are injected into the system prompt |
|
||||
| Hook scripts | Yes | `PreToolUse` / `PostToolUse` / `UserPromptSubmit` hooks fire normally |
|
||||
| Slash commands | Yes | Commands are routed through the workspace A2A server as usual |
|
||||
|
||||
Example: adding the `superpowers` plugin to a Google ADK workspace:
|
||||
|
||||
```yaml title="config.yaml"
|
||||
runtime: google-adk
|
||||
model: google:gemini-2.0-flash
|
||||
plugins:
|
||||
- superpowers
|
||||
- molecule-dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## A2A communication
|
||||
|
||||
Google ADK workspaces participate in the full Molecule AI A2A network — they can receive tasks from parent agents, delegate to children, and send messages to siblings — identically to any other runtime.
|
||||
|
||||
The adapter injects the standard A2A MCP tools (`list_peers`, `delegate_task`, `delegate_task_async`, `send_message_to_user`, `commit_memory`, `recall_memory`) into the ADK agent's tool list automatically.
|
||||
|
||||
---
|
||||
|
||||
## Transcript support
|
||||
|
||||
The Google ADK adapter exposes live session transcripts to the canvas "look over shoulder" view. Each agent turn (tool calls, model responses) is streamed as it completes.
|
||||
|
||||
---
|
||||
|
||||
## Comparison: config.yaml across runtimes
|
||||
|
||||
<br />
|
||||
|
||||
```yaml title="LangGraph workspace"
|
||||
runtime: langgraph
|
||||
model: anthropic:claude-sonnet-4-6
|
||||
```
|
||||
|
||||
```yaml title="AutoGen workspace"
|
||||
runtime: autogen
|
||||
model: openai:gpt-4o
|
||||
```
|
||||
|
||||
```yaml title="Google ADK workspace"
|
||||
runtime: google-adk
|
||||
model: google:gemini-2.0-flash
|
||||
runtime_config:
|
||||
temperature: 0.1
|
||||
```
|
||||
|
||||
The `model` field follows `<provider>:<model-id>` format. For Google ADK, the `google:` prefix routes through the `google-genai` LangChain integration.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `google.api_core.exceptions.InvalidArgument: 400 API key not valid`
|
||||
|
||||
Your `GOOGLE_API_KEY` secret is missing or invalid. Check it in the canvas Settings panel and verify it in [Google AI Studio](https://aistudio.google.com/app/apikey).
|
||||
|
||||
### `RuntimeError: google-adk is not installed`
|
||||
|
||||
The workspace image is missing the `google-adk` Python package. If you are using a custom image, ensure `requirements.txt` includes `google-adk>=1.0.0` and rebuild the image.
|
||||
|
||||
### Agent returns empty response after tool calls
|
||||
|
||||
Check `max_iterations` in `runtime_config`. If the agent hits the iteration cap mid-task, it returns the last partial result. Increase `max_iterations` or break the task into smaller sub-tasks via A2A delegation.
|
||||
|
||||
### Vertex AI 403 Permission Denied
|
||||
|
||||
Ensure `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, and `GOOGLE_GENAI_USE_VERTEXAI=true` are all set, and that your service account has the `roles/aiplatform.user` IAM role on the project.
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- [Architecture — Workspace Runtime](/docs/architecture#workspace-runtime) — how adapters fit into the runtime
|
||||
- [Concepts — Workspaces](/docs/concepts#workspaces) — workspace primitives
|
||||
- [Org Template](/docs/org-template) — deploy a full team from a YAML definition
|
||||
- [Plugins](/docs/plugins) — extend your ADK agents with hooks, skills, and MCP servers
|
||||
- [Google ADK Python on GitHub](https://github.com/google/adk-python) — upstream documentation
|
||||
@ -15,6 +15,8 @@
|
||||
"mcp-server",
|
||||
"self-hosting",
|
||||
"observability",
|
||||
"troubleshooting"
|
||||
"troubleshooting",
|
||||
"---Runtimes---",
|
||||
"google-adk"
|
||||
]
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user