Hongming Wang 24fec62d7f initial commit — Molecule AI platform

Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1)
with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo.

Brand: Starfire → Molecule AI.
Slug: starfire / agent-molecule → molecule.
Env vars: STARFIRE_* → MOLECULE_*.
Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform.
Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent.
DB: agentmolecule → molecule.

History truncated; see public repo for prior commits and contributor
attribution. Verified green: go test -race ./... (platform), pytest
(workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-13 11:55:37 -07:00

3.6 KiB

Raw Blame History

Core Concepts

Workspace

The fundamental unit of the platform. A workspace is:

A role (e.g. "Marketing", "Developer PM", "QA") — what this position in the org chart does
A container that holds one AI agent (swappable without changing the role)
An A2A server with a public endpoint and an Agent Card
Optionally a team — it can contain sub-workspaces recursively

A workspace appears as a single node on the canvas regardless of whether it contains one agent or an entire team. The internal structure is opaque to parent workspaces — exactly as A2A intends.

Why This Matters

From the outside, a workspace containing a single agent and a workspace containing a team of five agents look identical. Both have the same A2A endpoint. Both publish an Agent Card. The parent workspace delegates without knowing or caring what's inside.

Practical consequence: users can start with a single "Developer" agent, and when they need more capacity, expand it into a Developer Team (PM + Frontend + Backend + QA) without rewiring anything. The relationship between Business Core and Developer stays the same.

When expanded, the workspace becomes the team lead — its agent stays as a coordinator that receives incoming messages and delegates to sub-workspaces. Sub-workspaces can talk to each other and to the team lead, but not to workspaces outside the team. This is recursive — sub-workspaces can themselves expand into teams.

See Team Expansion for the full mechanics.

Agent

The AI inside a workspace. An agent is swappable — you can replace Claude with GPT-4o or a local Ollama model without changing the workspace role, hierarchy position, or config.

The agent is powered by Deep Agents (LangGraph harness) and can:

Plan using a TODO list tool
Use tools
Spawn sub-agents
Maintain filesystem-backed memory
Pause and escalate approval up the hierarchy (human-in-the-loop)

See System Prompt Structure — Human-in-the-Loop for the escalation mechanics.

Agent Handoff

When an agent is replaced (AGENT_REPLACED), the workspace performs a graceful handoff:

The outgoing agent wraps up its current task
The outgoing agent writes a comprehensive handoff document to the workspace's memory (saved files — current work state, in-progress tasks, decisions made, context)
The new agent starts and reads the handoff document from memory
The new agent picks up where the old one left off

This is why workspaces always persist their current state and TODO list as files — it's the handoff mechanism. The workspace's memory survives agent replacement (the volume or store persists), so the new agent inherits full context.

Workspace Bundle

The portable, exportable artifact for a workspace. A .bundle.json file contains everything needed to recreate the workspace: system prompt, skills, prompt templates, tool configs, and sub-workspace definitions recursively.

Bundles are the unit of:

Copy/paste
Import/export
Future marketplace

See Bundle System for the full specification.

Agent Card

A JSON file published at /.well-known/agent-card.json on every workspace's A2A endpoint. It describes the workspace's identity, skills, capabilities, input/output modes, and authentication requirements.

This is how:

Workspaces discover each other
The canvas renders node UI dynamically
Calling agents know what skills are available

See Agent Card for the full specification.

3.6 KiB Raw Blame History