molecule-ai/docs
47
0
Fork 0
Code Issues Pull Requests 11 Actions Packages Projects Releases Wiki Activity

docs: reconcile runtime catalog to real shipped set (add codex, drop crewai/deepagents/gemini-cli) #67

Merged
documentation-specialist merged 1 commits from docs/reconcile-runtime-catalog into main 2026-06-02 14:15:58 +00:00
Conversation 1 Commits 1 Files Changed 23
+67 -151
23 changed files with 67 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/docs/adapters/hermes-adapter-design.md
+2 -2
View File
@@ -67,7 +67,7 @@ No other platform Go changes are required for the minimal adapter shell. The `ru
Add `hermes` to the adapter build loop so `build-all.sh` (and the `build-all.sh claude-code`-style single-runtime path) includes it:
```bash
ADAPTERS=(langgraph claude_code openclaw deepagents crewai autogen hermes)
ADAPTERS=(langgraph claude_code openclaw autogen hermes codex google-adk)
```
---
@@ -79,7 +79,7 @@ ADAPTERS=(langgraph claude_code openclaw deepagents crewai autogen hermes)
| `NOUS_API_KEY` | Required (unless `OPENROUTER_API_KEY` set) | Nous Research Portal API key — primary model provider for Hermes; obtain from `nousresearch.com` |
| `OPENROUTER_API_KEY` | Optional | Fallback provider; lets operators use any Hermes-supported model via OpenRouter instead of Nous Portal |
| `HERMES_MODEL` | Optional | Model identifier (e.g. `nous-hermes-3`, `openrouter:anthropic/claude-sonnet-4-5`); adapter defaults to `nous-hermes-3` if unset |
| `HERMES_SKILLS_DIR` | Optional | Path inside the container where Hermes looks for skills; defaults to `/configs/skills` — consistent with the Claude Code and DeepAgents adapters |
| `HERMES_SKILLS_DIR` | Optional | Path inside the container where Hermes looks for skills; defaults to `/configs/skills` — consistent with the Claude Code and LangGraph adapters |
**Note:** `NOUS_API_KEY` and `OPENROUTER_API_KEY` must be set as workspace secrets via `POST /workspaces/:id/secrets`, not baked into the image. At least one of the two must be present at container start; `setup()` should `raise RuntimeError` early with a clear message if both are absent.
content/docs/adapters/hermes-recon.md
+1 -1
View File
@@ -260,4 +260,4 @@ ENTRYPOINT ["/opt/hermes/docker/entrypoint.sh"]
## f) Value Proposition
Integrating Hermes adds one capability that none of the six existing adapters (LangGraph, Claude Code, CrewAI, AutoGen, OpenClaw, DeepAgents) deliver end-to-end: **a closed learning loop that compounds across sessions at the skill, memory, and user-model layers simultaneously.** Concretely: after a complex task, Hermes autonomously creates a `SKILL.md` file in `~/.hermes/skills/` (prompted every `creation_nudge_interval=15` tool iterations), and those skills are re-injected as context in future sessions — agents get better at tasks they've done before without any human curation step. The `session_search` toolset adds FTS5 + Gemini Flash summarization over `state.db`, so the agent can recall specific conversations from months ago with semantic-quality results. Layered on top is **Honcho dialectic user modeling** (`plastic-labs/honcho`) — a cross-session profile that tracks user communication style, preferences, and expectations, shared across any Honcho-integrated tool (not just Hermes). Finally, the **Modal and Daytona serverless backends with `container_persistent`** give Molecule AI a path to hibernating, pay-per-use sandboxes that no existing adapter exposes — directly relevant to Molecule AI's multi-workspace billing model. The `hermes claw migrate` command (backed by `optional-skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py`) is also relevant: Molecule AI could offer equivalent migration tooling to attract OpenClaw's existing ~247k-user base, and the **`agentskills.io` skill-manifest spec** (referenced in `optional-skills/`) should be reviewed before Molecule AI finalises its own plugin manifest schema to ensure interoperability with what is rapidly becoming the de-facto file-based skill standard.
Integrating Hermes adds one capability that none of the other existing adapters (LangGraph, Claude Code, AutoGen, OpenClaw, Codex, Google ADK) deliver end-to-end: **a closed learning loop that compounds across sessions at the skill, memory, and user-model layers simultaneously.** Concretely: after a complex task, Hermes autonomously creates a `SKILL.md` file in `~/.hermes/skills/` (prompted every `creation_nudge_interval=15` tool iterations), and those skills are re-injected as context in future sessions — agents get better at tasks they've done before without any human curation step. The `session_search` toolset adds FTS5 + Gemini Flash summarization over `state.db`, so the agent can recall specific conversations from months ago with semantic-quality results. Layered on top is **Honcho dialectic user modeling** (`plastic-labs/honcho`) — a cross-session profile that tracks user communication style, preferences, and expectations, shared across any Honcho-integrated tool (not just Hermes). Finally, the **Modal and Daytona serverless backends with `container_persistent`** give Molecule AI a path to hibernating, pay-per-use sandboxes that no existing adapter exposes — directly relevant to Molecule AI's multi-workspace billing model. The `hermes claw migrate` command (backed by `optional-skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py`) is also relevant: Molecule AI could offer equivalent migration tooling to attract OpenClaw's existing ~247k-user base, and the **`agentskills.io` skill-manifest spec** (referenced in `optional-skills/`) should be reviewed before Molecule AI finalises its own plugin manifest schema to ensure interoperability with what is rapidly becoming the de-facto file-based skill standard.
content/docs/agent-runtime/cli-runtime.md
+15 -19
View File
@@ -5,14 +5,14 @@ title: "Agent Runtime Adapters"
## Overview
The workspace runtime uses a **pluggable adapter architecture** — each agent infrastructure (Claude Code, OpenClaw, LangGraph, CrewAI, AutoGen, etc.) has its own adapter that bridges the A2A protocol to the infra's native interface.
The workspace runtime uses a **pluggable adapter architecture** — each agent infrastructure (Claude Code, OpenClaw, LangGraph, AutoGen, Codex, etc.) has its own adapter that bridges the A2A protocol to the infra's native interface.
Adapters live in `workspace/adapters/<runtime>/` and are auto-discovered at startup. Each adapter implements `BaseAdapter` (from `adapters/base.py`) with `setup()` and `create_executor()` methods.
The runtime is selected via `config.yaml`:
```yaml
runtime: claude-code # or: langgraph, crewai, autogen, deepagents, openclaw, hermes, gemini-cli, google-adk, external
runtime: claude-code # or: langgraph, autogen, openclaw, hermes, codex, google-adk, external
runtime_config:
model: sonnet
auth_token_file: .auth-token
@@ -40,8 +40,8 @@ Response → A2A event queue → JSON-RPC response
Chat sessions in the Canvas UI send prior messages (up to 20) via `params.metadata.history` in each A2A `message/send` request. Executors extract this history:
- **LangGraph/DeepAgents**: Prepends history as `("human", text)` / `("ai", text)` tuples to the LangGraph message list
- **CrewAI/AutoGen**: Prepends history as a text prefix in the task description (`"Conversation so far:\n..."`)
- **LangGraph**: Prepends history as `("human", text)` / `("ai", text)` tuples to the LangGraph message list
- **AutoGen**: Prepends history as a text prefix in the task description (`"Conversation so far:\n..."`)
- **Claude Code**: Uses `--resume <session_id>` for native session continuity (history not needed)
- **OpenClaw**: Uses `--session-id` for native session continuity
@@ -74,17 +74,6 @@ The SDK uses the same Claude Code engine under the hood — plugins, CLAUDE.md d
**Important:** Claude Code refuses to run as root with `--dangerously-skip-permissions`. The Dockerfile creates a non-root `agent` user.
### CrewAI (`runtime: crewai`)
Role-based multi-agent framework. Creates a CrewAI Agent + Task + Crew per request with A2A delegation tools (`delegate_to_peer`, `list_available_peers`).
```yaml
runtime: crewai
model: openrouter:google/gemini-2.5-flash
```
**Auth:** Uses `OPENROUTER_API_KEY` or `OPENAI_API_KEY` env var.
### AutoGen (`runtime: autogen`)
Microsoft AutoGen AssistantAgent with tool use. Creates an `AssistantAgent` per request with A2A delegation tools.
@@ -96,15 +85,22 @@ model: openai:gpt-4.1-mini
**Auth:** Uses `OPENAI_API_KEY` env var.
### DeepAgents (`runtime: deepagents`)
### Codex (`runtime: codex`)
LangGraph-based agent with deep planning capabilities. Uses the same `LangGraphA2AExecutor` as the default runtime but with a specialized agent setup including delegation, memory, and search tools.
OpenAI Codex CLI runtime. Routes to OpenAI across three provider arms, mirroring
the `claude-code` OAuth/API split: `openai-subscription` (ChatGPT/Codex
subscription via OAuth — the default), `openai-api` (direct `OPENAI_API_KEY`
BYOK), and `platform` (platform-managed OpenAI via the proxy Responses surface).
```yaml
runtime: deepagents
model: openrouter:google/gemini-2.5-flash
runtime: codex
model: gpt-5.4-mini # or gpt-5.5, gpt-5.4, gpt-5.3-codex, …
```
**Auth:** `CODEX_AUTH_JSON` (subscription OAuth) or `OPENAI_API_KEY` (direct
BYOK); `DeriveProvider` disambiguates by the available auth env. The selectable
model set is the `codex` block of the control-plane provider registry.
### OpenClaw (`runtime: openclaw`)
Proxies A2A messages to OpenClaw via `openclaw agent` CLI subprocess. Handles its own session continuity via `--session-id`.
content/docs/agent-runtime/config-format.md
+1 -1
View File
@@ -123,7 +123,7 @@ env:
| `description` | Yes | What this workspace does |
| `version` | Yes | Semantic version |
| `tier` | Yes | 1-4, determines deployment method |
| `runtime` | No | Adapter to use: `claude-code`, `langgraph` (default), `crewai`, `autogen`, `deepagents`, `openclaw`, `hermes`, `gemini-cli`, `google-adk`, or `external`. See [Agent Runtime Adapters](./cli-runtime.md). The canonical set is the control-plane provider registry. |
| `runtime` | No | Adapter to use: `claude-code`, `langgraph` (default), `autogen`, `openclaw`, `hermes`, `codex`, `google-adk`, or `external`. See [Agent Runtime Adapters](./cli-runtime.md). The canonical set is the control-plane provider registry. |
| `model` | Yes | LangChain-compatible provider string (e.g. `anthropic:claude-sonnet-4-6`). Overridden by `MODEL_PROVIDER` env var if set. |
| `prompt_files` | No | Ordered list of markdown files to load as system prompt. Defaults to `["system-prompt.md"]` if omitted. `MEMORY.md` and `USER.md` are auto-appended when present so frozen memory snapshots do not need to be duplicated here. Supports any agent framework's file structure (OpenClaw, Claude Code, etc.) |
| `shared_context` | No | Files from this workspace's config dir to share with direct children. Children fetch these at startup and inject into their system prompt as `## Parent Context`. 1-level inheritance only (grandchildren don't see grandparent's context). |
content/docs/agent-runtime/workspace-runtime.md
+2 -4
View File
@@ -9,16 +9,14 @@ The `workspace/` directory is Molecule AI's unified runtime image. Every provisi
## Runtime Matrix In Current `main`
Current `main` ships ten runtimes:
Current `main` ships seven runtimes:
- `claude-code`
- `langgraph`
- `crewai`
- `autogen`
- `deepagents`
- `openclaw`
- `hermes`
- `gemini-cli`
- `codex`
- `google-adk`
- `external` (bring-your-own agent — no platform-managed container)
content/docs/architecture.mdx
+6 -8
View File
@@ -11,14 +11,14 @@ Molecule AI is an **open-source operating system for AI agent organizations**
<img
src="/diagrams/platform-architecture.svg"
alt="Molecule AI platform architecture: operator surfaces (Canvas, CLI, MCP server, channels, REST) drive a Go control plane (provisioner, registry/discovery with CanCommunicate ACL, A2A proxy, WebSocket hub, scheduler, secrets, audit) backed by Postgres and Redis; the control plane provisions an isolated org tenant of workspace containers that communicate directly peer-to-peer over A2A governed by the org hierarchy; runtimes (claude-code, langgraph, crewai, autogen, deepagents, openclaw, hermes, gemini-cli, google-adk, external) and model providers (Anthropic, OpenAI, Google Vertex, OpenRouter) are pluggable integrations."
alt="Molecule AI platform architecture: operator surfaces (Canvas, CLI, MCP server, channels, REST) drive a Go control plane (provisioner, registry/discovery with CanCommunicate ACL, A2A proxy, WebSocket hub, scheduler, secrets, audit) backed by Postgres and Redis; the control plane provisions an isolated org tenant of workspace containers that communicate directly peer-to-peer over A2A governed by the org hierarchy; runtimes (claude-code, langgraph, autogen, openclaw, hermes, codex, google-adk, external) and model providers (Anthropic, OpenAI, Google Vertex, OpenRouter) are pluggable integrations."
style={{ width: '100%', height: 'auto', margin: '1rem 0' }}
/>
Three properties define the architecture:
- **Hard isolation by machine.** Every workspace is one agent on its **own dedicated machine** (own OS, filesystem, secrets). Workspaces **cannot** read each other's environment — there is no shared disk or shared process space. **A2A over the network is the only sanctioned channel**, and it is gated by the org hierarchy (`CanCommunicate`).
- **Anything can be a runtime.** Behind one `BaseAdapter` contract, a workspace can be any agent framework (claude-code, langgraph, crewai, autogen, deepagents, openclaw, hermes, gemini-cli, **google-adk**), an external/BYO agent, or — on the roadmap — an **intelligent device**: smart glasses, watches, robots, home/building systems, vehicles. Any A2A/MCP-speaking endpoint joins the org as a governed workspace. Models are equally pluggable (Anthropic, OpenAI/-compatible, **Google Vertex/Gemini**, OpenRouter).
- **Anything can be a runtime.** Behind one `BaseAdapter` contract, a workspace can be any agent framework (claude-code, langgraph, autogen, openclaw, hermes, codex, **google-adk**), an external/BYO agent, or — on the roadmap — an **intelligent device**: smart glasses, watches, robots, home/building systems, vehicles. Any A2A/MCP-speaking endpoint joins the org as a governed workspace. Models are equally pluggable (Anthropic, OpenAI/-compatible, **Google Vertex/Gemini**, OpenRouter).
- **Deep, namespaced memory.** A hierarchical memory architecture (HMA) gives each workspace a durable namespace and three scopes — **LOCAL** (private), **TEAM** (parent + siblings), **GLOBAL** (org-wide) — whose reach follows the same org tree as communication.
A text summary of the same flow:
@@ -113,19 +113,17 @@ The Platform is the central control plane responsible for:
**Published as:** [`molecule-ai-workspace-runtime`](https://pypi.org/project/molecule-ai-workspace-runtime/) on PyPI
The shared runtime provides the base agent infrastructure: A2A server, heartbeat loop, config loading, platform auth, plugin system, and built-in tools. Each AI framework adapter lives in its own standalone repository.
The shared runtime provides the base agent infrastructure: A2A server, heartbeat loop, config loading, platform auth, plugin system, and built-in tools. Most AI framework adapters live in their own standalone repository.
| Runtime | Standalone Repo | Key Dependencies |
|---------|-----------------|------------------|
| LangGraph | `molecule-ai-workspace-template-langgraph` | langchain-anthropic, langgraph |
| Claude Code | `molecule-ai-workspace-template-claude-code` | claude-agent-sdk, @anthropic-ai/claude-code |
| OpenClaw | `molecule-ai-workspace-template-openclaw` | openclaw (npm) |
| CrewAI | `molecule-ai-workspace-template-crewai` | crewai |
| AutoGen | `molecule-ai-workspace-template-autogen` | autogen |
| 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 |
| Codex | `codex` | OpenAI Codex CLI |
`openclaw` and [`google-adk`](/docs/google-adk) ship as platform-bundled runtime templates (Gemini 2.5 Pro on Vertex AI via keyless ADC for `google-adk`); `external` is a bring-your-own agent with no platform-managed container. The canonical runtime set is the control-plane provider registry.
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`.
content/docs/architecture/architecture.md
+2 -2
View File
@@ -30,8 +30,8 @@ The platform consists of four distinct systems:
A2A HTTP (JSON-RPC 2.0) — direct workspace-to-workspace
+-----------------------------------------------------------+
| workspace/ pluggable workspace runtime |
| LangGraph / DeepAgents / Claude Code / CrewAI / AutoGen |
| / OpenClaw + a2a-sdk |
| LangGraph / Claude Code / AutoGen / OpenClaw / Hermes |
| / Codex / Google ADK + a2a-sdk |
+-----------------------------------------------------------+
|
+------v----------------------------------------------------+
content/docs/architecture/overview.md
+1 -1
View File
@@ -20,7 +20,7 @@ Canvas (Next.js :3000) ←WebSocket→ Platform (Go :8080) ←HTTP→ Postgres +
- **Workspace Server** (`workspace-server/`): Go/Gin control plane — workspace CRUD, registry, discovery, WebSocket hub, liveness monitoring.
- **Canvas** (`canvas/`): Next.js 15 + React Flow (@xyflow/react v12) + Zustand + Tailwind — visual workspace graph.
- **Workspace Runtime** (`workspace/`): Shared runtime published as [`molecule-ai-workspace-runtime`](https://pypi.org/project/molecule-ai-workspace-runtime/) on PyPI. Supports LangGraph, Claude Code, OpenClaw, DeepAgents, CrewAI, AutoGen. Each adapter lives in its own standalone template repo (e.g. `molecule-ai-workspace-template-claude-code`). See `docs/workspace-runtime-package.md` for the full picture.
- **Workspace Runtime** (`workspace/`): Shared runtime published as [`molecule-ai-workspace-runtime`](https://pypi.org/project/molecule-ai-workspace-runtime/) on PyPI. Supports LangGraph, Claude Code, OpenClaw, AutoGen, Hermes, Codex, and Google ADK. Most adapters live in their own standalone template repo (e.g. `molecule-ai-workspace-template-claude-code`). See `docs/workspace-runtime-package.md` for the full picture.
- **molecli** (`workspace-server/cmd/cli/`): Go TUI dashboard (Bubbletea + Lipgloss) — real-time workspace monitoring, event log, health overview, delete/filter operations.
## Key Architectural Patterns
content/docs/architecture/technical/frontend-and-patterns.md
+6 -9
View File
@@ -63,16 +63,13 @@ workspace/
├── plugins.py # Plugin rule/skill injection
├── coordinator.py # Team lead routing
├── prompt.py # System prompt builder
├── adapter_base.py # BaseAdapter + AdapterConfig contract
├── adapters/
│ ├── __init__.py # Adapter registry
│ ├── base.py # BaseAdapter interface
│ ├── shared_runtime.py # Shared execution logic
│ ├── langgraph/adapter.py
│ ├── deepagents/adapter.py
│ ├── claude_code/adapter.py
│ ├── crewai/adapter.py
│ ├── autogen/adapter.py
│ └── openclaw/adapter.py
│ ├── __init__.py # Adapter registry shim (resolves ADAPTER_MODULE)
│ ├── base.py # Re-exports the BaseAdapter interface
│ └── shared_runtime.py # Shared execution logic
│ # Per-runtime adapters live in standalone
│ # molecule-ai-workspace-template-* repos
├── tools/ # 14 tool files
├── skills/
│ ├── loader.py # SKILL.md parser + tool loader
content/docs/architecture/technical/lifecycle.md
+5 -4
View File
@@ -102,7 +102,7 @@ description: ""
version: "1.0.0"
tier: 2 # 1=sandboxed, 2=standard, 3=privileged, 4=full-host
model: "anthropic:claude-sonnet-4-6" # provider:model syntax
runtime: "langgraph" # claude-code | langgraph | crewai | autogen | deepagents | openclaw | hermes | gemini-cli | google-adk | external
runtime: "langgraph" # claude-code | langgraph | autogen | openclaw | hermes | codex | google-adk | external
runtime_config: # Runtime-specific settings
command: "claude" # For CLI runtimes
args: []
@@ -155,16 +155,17 @@ compliance:
max_task_duration_seconds: 300
```
### Six Runtime Adapters
### Seven Runtime Adapters
| Adapter | Core Strength | Image Tag |
|---------|--------------|-----------|
| **LangGraph** | Graph-based state machine, tool use, streaming | `workspace-template:langgraph` |
| **DeepAgents** | Deep planning, multi-step task decomposition | `workspace-template:deepagents` |
| **Claude Code** | Native coding workflows, CLI continuity, OAuth auth | `workspace-template:claude-code` |
| **CrewAI** | Role-based crews, structured task orchestration | `workspace-template:crewai` |
| **AutoGen** | Multi-agent conversations, explicit strategies | `workspace-template:autogen` |
| **OpenClaw** | CLI-native runtime, own session model | `workspace-template:openclaw` |
| **Hermes** | Stacked system messages, native tool calls, Kimi | `workspace-template:hermes` |
| **Codex** | OpenAI Codex CLI, OAuth/API/platform arms | `workspace-template:codex` |
| **Google ADK** | Gemini 2.5 Pro on Vertex AI, keyless ADC/WIF | `workspace-template:google-adk` |
**Branch-level WIP**: NemoClaw (NVIDIA T4 + Docker socket) on `feat/nemoclaw-t4-docker`.
content/docs/architecture/technical/operations-and-roadmap.md
+1 -1
View File
@@ -158,7 +158,7 @@ Molecule AI's workspace abstraction is **runtime-agnostic by design**. A workspa
| Phase | Era | Systems | Status |
|-------|-----|---------|--------|
| **NOW** | Software Agent Teams | LLM agents in Docker, 10 runtimes, HMA, Langfuse, A2A | **LIVE on main** |
| **NOW** | Software Agent Teams | LLM agents in Docker, 7 runtimes, HMA, Langfuse, A2A | **LIVE on main** |
| **NEXT** | Terminal + Device Agents | Terminal bots, browser agents, IoT controllers, CI/CD agents | **BUILDING** |
| **HORIZON** | Embodied Robot Teams | Warehouse robots, autonomous vehicles, manufacturing cells, field inspection | **HORIZON** |
content/docs/architecture/technical/overview.md
+2 -2
View File
@@ -16,7 +16,7 @@ Molecule AI is an **org-native control plane for heterogeneous AI agent teams**.
- **Canvas-based visual team building** with drag-to-nest hierarchy
- **Comprehensive control plane operations** — registry, heartbeats, lifecycle, approvals, secrets, traces, bundles
Ten runtime adapters ship production-ready on `main`: Claude Code, LangGraph, CrewAI, AutoGen, DeepAgents, OpenClaw, Hermes, Gemini CLI, Google ADK, plus `external` (bring-your-own agent). The canonical set is the control-plane provider registry.
Seven runtime adapters ship production-ready on `main`: Claude Code, LangGraph, AutoGen, OpenClaw, Hermes, Codex, Google ADK, plus `external` (bring-your-own agent). The canonical set is the control-plane provider registry.
---
@@ -32,7 +32,7 @@ Ten runtime adapters ship production-ready on `main`: Claude Code, LangGraph, Cr
|---|-----------|-------------|
| 1 | **Workspace = role, not task** | Internal AI model can swap, but organizational identity persists across model/framework changes |
| 2 | **Org chart = topology** | Hierarchy determines communication boundaries — no manual edge wiring needed |
| 3 | **Heterogeneous runtime support** | 10 runtimes shipped; teams choose freely without forced standardization |
| 3 | **Heterogeneous runtime support** | 7 runtimes shipped; teams choose freely without forced standardization |
| 4 | **Memory follows org boundaries** | HMA prevents over-sharing, aligns data isolation with organizational structure |
| 5 | **Skill evolution loop** | memory → signal → skill → hot-reload → operational improvement (self-improving flywheel) |
content/docs/architecture/technical/system.md
+3 -4
View File
@@ -27,9 +27,8 @@ description: "System architecture, database schema, Docker Compose orchestration
┌─────────────────────────────────────────────────────────────┐
│ Workspace Runtime (Python 3.11+ Docker image) │
│ Pluggable adapters: claude-code, langgraph, crewai, │
│ autogen, deepagents, openclaw, hermes, gemini-cli, │
│ google-adk, external │
│ Pluggable adapters: claude-code, langgraph, autogen, │
│ openclaw, hermes, codex, google-adk, external │
│ A2A protocol server · heartbeat · skills · HMA memory │
└─────────────────────────────────────────────────────────────┘
│
@@ -77,7 +76,7 @@ description: "System architecture, database schema, Docker Compose orchestration
**3. Workspace Runtime (Python 3.11+)**
- Unified `workspace/` Docker image
- Adapter-driven execution (10 runtimes)
- Adapter-driven execution (7 runtimes)
- A2A server via Uvicorn
- Heartbeat loop (30s default)
- Skill hot-reload system (~3 second propagation)
content/docs/architecture/technology-choices.md
+1 -1
View File
@@ -17,7 +17,7 @@ Go is **not** used for agent logic — just infrastructure coordination.
## Workspace Runtime Adapters
The workspace runtime is adapter-based. LangGraph and DeepAgents are Python-native, while Claude Code and OpenClaw are CLI-driven runtimes. The platform standardizes them behind the same A2A surface, heartbeat lifecycle, memory tools, and workspace contract instead of forcing one execution backend for every team.
The workspace runtime is adapter-based. LangGraph and AutoGen are Python-native, while Claude Code, OpenClaw, and Codex are CLI-driven runtimes. The platform standardizes them behind the same A2A surface, heartbeat lifecycle, memory tools, and workspace contract instead of forcing one execution backend for every team.
## Deep Agents + LangGraph
content/docs/concepts.mdx
+2 -2
View File
@@ -26,8 +26,8 @@ workspace has:
written to `/workspace/AGENTS.md` so peers can discover it)
- 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`, [`google-adk`](/docs/google-adk))
- A **runtime** (`claude-code`, `langgraph`, `autogen`,
`openclaw`, `hermes`, `codex`, [`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
content/docs/glossary.md
+1 -1
View File
@@ -26,7 +26,7 @@ lands in the watch list with a colliding term, add a row here.
| **team** | A named cluster of workspaces under a PM (org template `expand_team`). Used for role grouping in Canvas. | **CrewAI**: a "crew" is a sequence of agents that pass a task through a declared order. Our "team" is an org-chart abstraction, not an execution order. |
| **skill** | A directory with `SKILL.md` that an agent invokes via the `Skill` tool. Skills are documentation + optional scripts that teach an agent a recipe. | **Anthropic Skills API**: nearly identical. **CrewAI tool**: closer to our plugin's MCP tool, not our skill. |
| **channel** | An outbound/inbound social integration (Telegram, Slack, …) per-workspace, wired in `workspace_channels`. | Slack's "channel": the container for messages. We use "channel" for the adapter + credentials, not the conversation itself. |
| **runtime** | The execution engine image tag for a workspace, selected by the `runtime` field in `config.yaml`: `claude-code`, `langgraph`, `crewai`, `autogen`, `deepagents`, `openclaw`, `hermes`, `gemini-cli`, `google-adk`, plus `external` (no container — bring-your-own agent). New runtimes drop in behind one `BaseAdapter` contract; the canonical set lives in the control-plane provider registry, not here. | **LangGraph runtime**: the Python process running the graph. We use "runtime" for the Docker image + adapter pairing, not the inner process. |
| **runtime** | The execution engine image tag for a workspace, selected by the `runtime` field in `config.yaml`: `claude-code`, `langgraph`, `autogen`, `openclaw`, `hermes`, `codex`, `google-adk`, plus `external` (no container — bring-your-own agent). New runtimes drop in behind one `BaseAdapter` contract; the canonical set lives in the control-plane provider registry, not here. | **LangGraph runtime**: the Python process running the graph. We use "runtime" for the Docker image + adapter pairing, not the inner process. |
## GitHub Awesome Copilot disambiguation
content/docs/guides/quickstart-audio.md
+1 -1
View File
@@ -16,7 +16,7 @@ First, clone the repo and run the setup script. It boots Postgres, Redis, Langfu
Then start the workspace server on port 8080, and the canvas UI on port 3000. Open your browser to localhost 3000.
You land on the canvas — an empty org. The first thing to do is deploy a template. Pick LangGraph, Claude Code, CrewAI — or start blank. The template provisions a workspace and puts it on the canvas.
You land on the canvas — an empty org. The first thing to do is deploy a template. Pick LangGraph, Claude Code, Codex — or start blank. The template provisions a workspace and puts it on the canvas.
Open the chat tab. Send the agent a task. Watch it work.
content/docs/index.mdx
+2 -3
View File
@@ -57,11 +57,10 @@ rest.
| Claude Code | Anthropic Claude with code execution |
| LangGraph | LangChain ReAct agent with tools |
| OpenClaw | Multi-file prompt system with SOUL |
| CrewAI | Role-based agent with task delegation |
| AutoGen | Microsoft conversable agents |
| DeepAgents | Deep research with planning |
| Hermes | NousResearch Hermes-3 multi-provider |
| Gemini CLI | Google Gemini CLI workspace |
| Codex | OpenAI Codex CLI (OAuth / API / platform) |
| Google ADK | Gemini 2.5 Pro on Vertex AI, keyless ADC |
## Integrate with everything
content/docs/org-template.mdx
+1 -1
View File
@@ -55,7 +55,7 @@ Each workspace entry supports the following fields:
|-------|------|-------------|
| `name` | string | Display name shown on the canvas |
| `role` | string | Agent role (e.g. PM, Engineer, Researcher) |
| `runtime` | string | Runtime adapter (`claude-code`, `langgraph`, `crewai`, etc.) |
| `runtime` | string | Runtime adapter (`claude-code`, `langgraph`, `codex`, etc.) |
| `tier` | integer | Resource tier (2 = Standard, 3 = Privileged, 4 = Full-host) |
| `workspace_dir` | string | Host path for `/workspace` bind-mount |
| `plugins` | list | Plugins to install on this workspace |
content/docs/tutorials/gemini-cli-runtime.md
-69
View File
@@ -1,69 +0,0 @@
---
title: "Running a Gemini CLI Workspace on Molecule AI"
---
# Running a Gemini CLI Workspace on Molecule AI
Molecule AI now ships a `gemini-cli` runtime adapter alongside the existing `claude-code` adapter. This tutorial walks you from zero to a running Gemini agent workspace in under five minutes.
## What you'll need
- A Molecule AI account with at least one provisioned tenant
- A Google `GEMINI_API_KEY` (get one at [aistudio.google.com](https://aistudio.google.com))
- The Molecule AI CLI (`pip install molecule-ai`)
## Setup (10 steps)
```bash
# 1. Install / upgrade the CLI
pip install --upgrade molecule-ai
# 2. Authenticate
molecule auth login
# 3. Store your Gemini API key as a global secret
molecule secrets set GEMINI_API_KEY="YOUR_KEY_HERE" --global
# 4. Create a gemini-cli workspace
molecule workspace create my-gemini-agent --runtime gemini-cli
# 5. Confirm it's running (status → "ready" within ~30 s)
molecule workspace status my-gemini-agent
# 6. Send your first task
molecule workspace run my-gemini-agent "Summarise the last 5 git commits in this repo"
# 7. View the streamed response
molecule workspace logs my-gemini-agent --follow
# 8. Check the agent's memory file (GEMINI.md)
molecule workspace exec my-gemini-agent cat GEMINI.md
# 9. Delegate a cross-workspace task to your new Gemini peer
molecule workspace run orchestrator "delegate_task my-gemini-agent 'Draft release notes for v1.4'"
# 10. Tear down when done
molecule workspace delete my-gemini-agent
```
## Expected output
After step 5 you should see:
```
my-gemini-agent gemini-cli ready ord 2026-04-16T06:30:00Z
```
After step 6, Gemini CLI streams its reasoning and final answer directly to stdout. The agent uses `GEMINI.md` (seeded from your workspace's `system-prompt.md`) as persistent context — equivalent to `CLAUDE.md` for Claude Code workspaces.
## How it works
Molecule AI's `gemini-cli` adapter mirrors the battle-tested `claude-code` pattern: a Docker image installs `@google/gemini-cli` globally, and `CLIAgentExecutor` drives the subprocess. Because Gemini CLI reads MCP config from `~/.gemini/settings.json` rather than accepting a `--mcp-config` flag, the adapter's `setup()` method merges the A2A MCP server definition into that file at boot — preserving any user-defined tools.
## Multi-provider teams
The real power surfaces when you mix runtimes on the same Molecule AI tenant. Your orchestrator workspace can delegate tasks to both `claude-code` and `gemini-cli` workers simultaneously using `delegate_task_async`, then synthesize results — all through the same A2A protocol. This is provider diversity at the infrastructure layer, not at the application layer.
## Related
- PR #379: [feat(adapters): add gemini-cli runtime adapter](https://git.moleculesai.app/molecule-ai/molecule-core/pull/379)
- [Multi-provider Hermes docs](../architecture/hermes.md)
- [Workspace runtimes reference](../reference/runtimes.md)
content/docs/tutorials/google-adk-runtime.md
+2 -3
View File
@@ -3,7 +3,7 @@ title: "Running a Google ADK Workspace on Molecule AI"
---
# Running a Google ADK Workspace on Molecule AI
Google's Agent Development Kit (ADK) is now a first-class runtime on Molecule AI. This tutorial walks you from zero to a running ADK agent workspace — one that persists per-conversation session state and sits alongside your Claude Code and Gemini CLI workers in the same A2A network.
Google's Agent Development Kit (ADK) is now a first-class runtime on Molecule AI. This tutorial walks you from zero to a running ADK agent workspace — one that persists per-conversation session state and sits alongside your Claude Code and LangGraph workers in the same A2A network.
## What you'll need
@@ -67,11 +67,10 @@ The `google-adk` adapter wraps Google ADK's runner/session model behind the same
## Mixed-runtime teams
ADK workspaces participate in the same A2A network as Claude Code, Gemini CLI, Hermes, and LangGraph workers. An orchestrator can delegate long-context summarisation to a `google-adk` worker (Gemini 1.5 Pro's 1M token window) while routing tool-use tasks to a `claude-code` worker — with no provider-specific code in the orchestrator itself. Add an ADK peer with `POST /workspaces`, set `GOOGLE_API_KEY`, and it's available for `delegate_task` immediately.
ADK workspaces participate in the same A2A network as Claude Code, Codex, Hermes, and LangGraph workers. An orchestrator can delegate long-context summarisation to a `google-adk` worker (Gemini 2.5 Pro's large context window) while routing tool-use tasks to a `claude-code` worker — with no provider-specific code in the orchestrator itself. Add an ADK peer with `POST /workspaces`, set `GOOGLE_API_KEY`, and it's available for `delegate_task` immediately.
## Related
- PR #550: [feat(adapters): add google-adk runtime adapter](https://git.moleculesai.app/molecule-ai/molecule-core/pull/550)
- [Google ADK (adk-python)](https://github.com/google/adk-python)
- [Gemini CLI runtime tutorial](./gemini-cli-runtime.md)
- [Platform API reference](../api-reference.md)
public/diagrams/platform-architecture.svg
+8 -10
View File
@@ -163,16 +163,14 @@
<text x="66" y="1006" font-size="13" font-weight="700" fill="#0369a1">Software agent frameworks</text>
<g font-size="11.5" font-weight="600" text-anchor="middle">
<rect x="66" y="1016" width="148" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="140" y="1037" fill="#15181f">claude-code</text>
<rect x="224" y="1016" width="148" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="298" y="1037" fill="#15181f">langgraph</text>
<rect x="382" y="1016" width="130" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="447" y="1037" fill="#15181f">crewai</text>
<rect x="522" y="1016" width="130" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="587" y="1037" fill="#15181f">autogen</text>
<rect x="662" y="1016" width="150" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="737" y="1037" fill="#15181f">deepagents</text>
<rect x="66" y="1056" width="130" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="131" y="1077" fill="#15181f">openclaw</text>
<rect x="206" y="1056" width="120" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="266" y="1077" fill="#15181f">hermes</text>
<rect x="336" y="1056" width="130" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="401" y="1077" fill="#15181f">gemini-cli</text>
<rect x="476" y="1056" width="146" height="32" rx="8" fill="#fff7ed" stroke="#f4b860"/><text x="549" y="1077" fill="#b45309">google-adk</text>
<rect x="632" y="1056" width="180" height="32" rx="8" fill="#faf5ff" stroke="#d8b4fe"/><text x="722" y="1077" fill="#7c3aed">external / BYO agent</text>
<rect x="66" y="1016" width="148" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="140" y="1037" fill="#15181f">claude-code</text>
<rect x="224" y="1016" width="130" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="289" y="1037" fill="#15181f">langgraph</text>
<rect x="364" y="1016" width="120" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="424" y="1037" fill="#15181f">autogen</text>
<rect x="494" y="1016" width="130" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="559" y="1037" fill="#15181f">openclaw</text>
<rect x="66" y="1056" width="110" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="121" y="1077" fill="#15181f">hermes</text>
<rect x="186" y="1056" width="110" height="32" rx="8" fill="#fff" stroke="#bae6fd"/><text x="241" y="1077" fill="#15181f">codex</text>
<rect x="306" y="1056" width="150" height="32" rx="8" fill="#fff7ed" stroke="#f4b860"/><text x="381" y="1077" fill="#b45309">google-adk</text>
<rect x="466" y="1056" width="190" height="32" rx="8" fill="#faf5ff" stroke="#d8b4fe"/><text x="561" y="1077" fill="#7c3aed">external / BYO agent</text>
</g>
<line x1="66" y1="1104" x2="884" y2="1104" stroke="#e2e8f0" stroke-width="1"/>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

public/diagrams/workspace-config.svg
+2 -2
View File
@@ -41,9 +41,9 @@
<g font-size="12" font-weight="600" text-anchor="middle">
<rect x="462" y="182" width="256" height="32" rx="7" fill="#fff" stroke="#bae6fd"/><text x="590" y="203" fill="#15181f">claude-code → ClaudeSDKExecutor</text>
<rect x="462" y="220" width="256" height="32" rx="7" fill="#fff" stroke="#bae6fd"/><text x="590" y="241" fill="#15181f">langgraph → LangGraphA2AExecutor</text>
<rect x="462" y="258" width="256" height="32" rx="7" fill="#fff" stroke="#bae6fd"/><text x="590" y="279" fill="#15181f">crewai · autogen · deepagents</text>
<rect x="462" y="258" width="256" height="32" rx="7" fill="#fff" stroke="#bae6fd"/><text x="590" y="279" fill="#15181f">autogen → AutoGenA2AExecutor</text>
<rect x="462" y="296" width="256" height="32" rx="7" fill="#fff" stroke="#bae6fd"/><text x="590" y="317" fill="#15181f">hermes → HermesA2AExecutor</text>
<rect x="462" y="334" width="256" height="32" rx="7" fill="#fff" stroke="#bae6fd"/><text x="590" y="355" fill="#15181f">openclaw · gemini-cli (CLI exec)</text>
<rect x="462" y="334" width="256" height="32" rx="7" fill="#fff" stroke="#bae6fd"/><text x="590" y="355" fill="#15181f">openclaw · codex (CLI exec)</text>
<rect x="462" y="372" width="256" height="32" rx="7" fill="#fff7ed" stroke="#f4b860"/><text x="590" y="393" fill="#b45309">google-adk → GoogleADKA2AExecutor</text>
<rect x="462" y="410" width="256" height="32" rx="7" fill="#faf5ff" stroke="#d8b4fe"/><text x="590" y="431" fill="#7c3aed">external → no container (BYO)</text>
</g>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.6 KiB

After

Width:  |  Height:  |  Size: 7.6 KiB