From ea8b7bc7427430fa398c6d6f63bf31c6a5e3fb76 Mon Sep 17 00:00:00 2001 From: technical-writer Date: Tue, 2 Jun 2026 07:14:42 -0700 Subject: [PATCH] docs: reconcile runtime catalog to real shipped set (add codex, drop crewai/deepagents/gemini-cli) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs claimed 'ten runtime adapters ship production-ready on main' listing crewai/deepagents/gemini-cli — none of which have a control-plane providers.yaml entry, a workspace-template-* repo, or adapter code in molecule-core / molecule-ai-workspace-runtime. Meanwhile codex (a real shipped runtime: in providers.yaml + the codex repo) was missing from every list. Confirmed against real sources (CP internal/providers/providers.yaml runtimes block; the org's workspace-template-* repos; the workspace-runtime adapter registry shim). Canonical shipped set = claude-code, langgraph, autogen, openclaw, hermes, codex, google-adk, + external (7 runtimes + BYO). Changes: - counts ten/10/six → seven/7 across overview, system, lifecycle, operations-and-roadmap, workspace-runtime. - enum lists updated (add codex, drop the 3 fakes): glossary, concepts, org-template, config-format, lifecycle, system, cli-runtime, architecture.mdx, index.mdx landing table, architecture/overview, architecture/architecture, technology-choices, hermes-recon, hermes-adapter-design. - cli-runtime: removed CrewAI/DeepAgents sections, added a Codex section. - frontend-and-patterns codebase tree: replaced stale inline adapter dirs with the real registry-shim layout (adapters live in standalone template repos). - architecture.mdx repo table: dropped fabricated repo rows; only asserts repos I verified exist (langgraph/claude-code/autogen/hermes/codex), notes openclaw/google-adk ship platform-bundled. - deleted the fabricated gemini-cli-runtime.md tutorial (no such runtime ships); removed its inbound link + Gemini-CLI mentions from the google-adk tutorial (also fixed a stray 'Gemini 1.5 Pro' → 2.5). - regenerated runtime chips in platform-architecture.svg + executor list in workspace-config.svg. Left as-is (legitimate): CrewAI/DeepAgents as external-product comparisons in glossary/positioning, historical changelog entries. Deferred: the agentskills plugin-compat matrix still lists deepagents as a plugin target — separate plugin-domain concern, needs its own review. Full-doc internal-link scan: NONE broken. npm run build green. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../docs/adapters/hermes-adapter-design.md | 4 +- content/docs/adapters/hermes-recon.md | 2 +- content/docs/agent-runtime/cli-runtime.md | 34 ++++----- content/docs/agent-runtime/config-format.md | 2 +- .../docs/agent-runtime/workspace-runtime.md | 6 +- content/docs/architecture.mdx | 14 ++-- content/docs/architecture/architecture.md | 4 +- content/docs/architecture/overview.md | 2 +- .../technical/frontend-and-patterns.md | 15 ++-- .../docs/architecture/technical/lifecycle.md | 9 +-- .../technical/operations-and-roadmap.md | 2 +- .../docs/architecture/technical/overview.md | 4 +- content/docs/architecture/technical/system.md | 7 +- .../docs/architecture/technology-choices.md | 2 +- content/docs/concepts.mdx | 4 +- content/docs/glossary.md | 2 +- content/docs/guides/quickstart-audio.md | 2 +- content/docs/index.mdx | 5 +- content/docs/org-template.mdx | 2 +- content/docs/tutorials/gemini-cli-runtime.md | 69 ------------------- content/docs/tutorials/google-adk-runtime.md | 5 +- public/diagrams/platform-architecture.svg | 18 +++-- public/diagrams/workspace-config.svg | 4 +- 23 files changed, 67 insertions(+), 151 deletions(-) delete mode 100644 content/docs/tutorials/gemini-cli-runtime.md diff --git a/content/docs/adapters/hermes-adapter-design.md b/content/docs/adapters/hermes-adapter-design.md index a915c58..9a53185 100644 --- a/content/docs/adapters/hermes-adapter-design.md +++ b/content/docs/adapters/hermes-adapter-design.md @@ -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. diff --git a/content/docs/adapters/hermes-recon.md b/content/docs/adapters/hermes-recon.md index 9efef10..0924c82 100644 --- a/content/docs/adapters/hermes-recon.md +++ b/content/docs/adapters/hermes-recon.md @@ -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. diff --git a/content/docs/agent-runtime/cli-runtime.md b/content/docs/agent-runtime/cli-runtime.md index 184f0ee..f508e53 100644 --- a/content/docs/agent-runtime/cli-runtime.md +++ b/content/docs/agent-runtime/cli-runtime.md @@ -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//` 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 ` 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`. diff --git a/content/docs/agent-runtime/config-format.md b/content/docs/agent-runtime/config-format.md index 202bd23..557fe32 100644 --- a/content/docs/agent-runtime/config-format.md +++ b/content/docs/agent-runtime/config-format.md @@ -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). | diff --git a/content/docs/agent-runtime/workspace-runtime.md b/content/docs/agent-runtime/workspace-runtime.md index 37e58d2..935f384 100644 --- a/content/docs/agent-runtime/workspace-runtime.md +++ b/content/docs/agent-runtime/workspace-runtime.md @@ -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) diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index f23156c..74d64cc 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -11,14 +11,14 @@ Molecule AI is an **open-source operating system for AI agent organizations** 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. 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`. diff --git a/content/docs/architecture/architecture.md b/content/docs/architecture/architecture.md index c5799fd..0221a41 100644 --- a/content/docs/architecture/architecture.md +++ b/content/docs/architecture/architecture.md @@ -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----------------------------------------------------+ diff --git a/content/docs/architecture/overview.md b/content/docs/architecture/overview.md index 82a0483..8eb013c 100644 --- a/content/docs/architecture/overview.md +++ b/content/docs/architecture/overview.md @@ -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 diff --git a/content/docs/architecture/technical/frontend-and-patterns.md b/content/docs/architecture/technical/frontend-and-patterns.md index 180035f..d4a4b24 100644 --- a/content/docs/architecture/technical/frontend-and-patterns.md +++ b/content/docs/architecture/technical/frontend-and-patterns.md @@ -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 diff --git a/content/docs/architecture/technical/lifecycle.md b/content/docs/architecture/technical/lifecycle.md index 658ffc0..72fbb54 100644 --- a/content/docs/architecture/technical/lifecycle.md +++ b/content/docs/architecture/technical/lifecycle.md @@ -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`. diff --git a/content/docs/architecture/technical/operations-and-roadmap.md b/content/docs/architecture/technical/operations-and-roadmap.md index 6e2b596..f55d5b2 100644 --- a/content/docs/architecture/technical/operations-and-roadmap.md +++ b/content/docs/architecture/technical/operations-and-roadmap.md @@ -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** | diff --git a/content/docs/architecture/technical/overview.md b/content/docs/architecture/technical/overview.md index 743451b..2079781 100644 --- a/content/docs/architecture/technical/overview.md +++ b/content/docs/architecture/technical/overview.md @@ -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) | diff --git a/content/docs/architecture/technical/system.md b/content/docs/architecture/technical/system.md index 0ac200b..bccbb11 100644 --- a/content/docs/architecture/technical/system.md +++ b/content/docs/architecture/technical/system.md @@ -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) diff --git a/content/docs/architecture/technology-choices.md b/content/docs/architecture/technology-choices.md index 9f827f9..8e3ae30 100644 --- a/content/docs/architecture/technology-choices.md +++ b/content/docs/architecture/technology-choices.md @@ -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 diff --git a/content/docs/concepts.mdx b/content/docs/concepts.mdx index bdf469c..608ae50 100644 --- a/content/docs/concepts.mdx +++ b/content/docs/concepts.mdx @@ -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 diff --git a/content/docs/glossary.md b/content/docs/glossary.md index 1f09a1d..5f73584 100644 --- a/content/docs/glossary.md +++ b/content/docs/glossary.md @@ -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 diff --git a/content/docs/guides/quickstart-audio.md b/content/docs/guides/quickstart-audio.md index 0692611..d94e231 100644 --- a/content/docs/guides/quickstart-audio.md +++ b/content/docs/guides/quickstart-audio.md @@ -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. diff --git a/content/docs/index.mdx b/content/docs/index.mdx index c205876..d18df2e 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -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 diff --git a/content/docs/org-template.mdx b/content/docs/org-template.mdx index 01ad3c6..0a8af63 100644 --- a/content/docs/org-template.mdx +++ b/content/docs/org-template.mdx @@ -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 | diff --git a/content/docs/tutorials/gemini-cli-runtime.md b/content/docs/tutorials/gemini-cli-runtime.md deleted file mode 100644 index 8397e92..0000000 --- a/content/docs/tutorials/gemini-cli-runtime.md +++ /dev/null @@ -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) diff --git a/content/docs/tutorials/google-adk-runtime.md b/content/docs/tutorials/google-adk-runtime.md index 04abcc5..cee8369 100644 --- a/content/docs/tutorials/google-adk-runtime.md +++ b/content/docs/tutorials/google-adk-runtime.md @@ -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) diff --git a/public/diagrams/platform-architecture.svg b/public/diagrams/platform-architecture.svg index a01abe1..822f598 100644 --- a/public/diagrams/platform-architecture.svg +++ b/public/diagrams/platform-architecture.svg @@ -163,16 +163,14 @@ Software agent frameworks - claude-code - langgraph - crewai - autogen - deepagents - openclaw - hermes - gemini-cli - google-adk - external / BYO agent + claude-code + langgraph + autogen + openclaw + hermes + codex + google-adk + external / BYO agent diff --git a/public/diagrams/workspace-config.svg b/public/diagrams/workspace-config.svg index 6284052..9458b15 100644 --- a/public/diagrams/workspace-config.svg +++ b/public/diagrams/workspace-config.svg @@ -41,9 +41,9 @@ claude-code → ClaudeSDKExecutor langgraph → LangGraphA2AExecutor - crewai · autogen · deepagents + autogen → AutoGenA2AExecutor hermes → HermesA2AExecutor - openclaw · gemini-cli (CLI exec) + openclaw · codex (CLI exec) google-adk → GoogleADKA2AExecutor external → no container (BYO) -- 2.52.0