diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index c2b52a8..5d968bf 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -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`. diff --git a/content/docs/concepts.mdx b/content/docs/concepts.mdx index c402722..ef70c56 100644 --- a/content/docs/concepts.mdx +++ b/content/docs/concepts.mdx @@ -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 diff --git a/content/docs/google-adk.mdx b/content/docs/google-adk.mdx new file mode 100644 index 0000000..f3de51b --- /dev/null +++ b/content/docs/google-adk.mdx @@ -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. + + + Google ADK adapter was added in PR #550 (issue #542). It passes 46/46 tests with 100% coverage. + + +--- + +## 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 +``` + + + Google ADK requires **Python 3.10+**. Ensure your workspace Dockerfile uses `python:3.11-slim` or newer. + + +--- + +## 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 + +
+ +```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 `:` 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 diff --git a/content/docs/meta.json b/content/docs/meta.json index ba4220c..7157fa9 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -15,6 +15,8 @@ "mcp-server", "self-hosting", "observability", - "troubleshooting" + "troubleshooting", + "---Runtimes---", + "google-adk" ] }