Skip to content

Self-improving AI Employees for everyone

docs(agent_builder): SKILL.md (multi-op shape) + protocol + CLAUDE.md

trohitgb31ac66452f6
diff --git a/CLAUDE.md b/CLAUDE.md
index e238cd1f..31fb63fe 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -664,7 +664,7 @@ The project uses WebSocket as the primary communication method between frontend
- `server/routers/websocket.py` - WebSocket endpoint; the live handler set is the `MESSAGE_HANDLERS` dict plus plugin-registered handlers via `services.ws_handler_registry`. Don't hand-maintain a count here.
- `server/services/status_broadcaster.py` - Connection management and broadcasting
-**Canvas mutations from the backend** -- any handler that needs to add / move / delete nodes or edges (e.g., auto-add-skill on tool connect, future workflow-template features, AI-suggested edits) returns a workflow-ops batch (`{operations: [...]}`) and the frontend applies it through `applyOperations` in [client/src/lib/workflowOps.ts](./client/src/lib/workflowOps.ts). Backend builders live in [server/services/workflow_ops.py](./server/services/workflow_ops.py). Full spec: [docs-internal/workflow_ops_protocol.md](./docs-internal/workflow_ops_protocol.md). Do not invent a parallel "modify the canvas" RPC for new features -- target this protocol.
+**Canvas mutations from the backend** -- any handler that needs to add / move / delete nodes or edges (auto-add-skill on tool connect, Agent Builder runtime tools called by the LLM mid-execution, future workflow-template features) returns a workflow-ops batch (`{operations: [...]}`) and the frontend applies it through `applyOperations` in [client/src/lib/workflowOps.ts](./client/src/lib/workflowOps.ts). Backend builders live in [server/services/workflow_ops.py](./server/services/workflow_ops.py). Two delivery modes: request/response (frontend-driven, e.g. auto-skill) and push broadcast (`send_custom_event('workflow_ops_apply', ...)`, picked up by `useWorkflowOpsListener`). Full spec: [docs-internal/workflow_ops_protocol.md](./docs-internal/workflow_ops_protocol.md).
## Implemented Node Types
diff --git a/docs-internal/workflow_ops_protocol.md b/docs-internal/workflow_ops_protocol.md
index c4baf1e8..7aef415a 100644
--- a/docs-internal/workflow_ops_protocol.md
+++ b/docs-internal/workflow_ops_protocol.md
@@ -119,17 +119,42 @@ failures (toast, log, retry, etc.).
## Current consumers
-| Service | WS handler | Module |
+| Service | Trigger | Module |
|---|---|---|
-| Auto-add Skill on tool connect | `evaluate_auto_skill` | `server/services/auto_skill.py` |
+| Auto-add Skill on tool connect | WS request `evaluate_auto_skill` (frontend on edge connect/disconnect) | `server/services/auto_skill.py` |
+| Agent Builder runtime tools | WS broadcast `workflow_ops_apply` (backend, mid-execution) | `server/nodes/tool/agent_builder.py` |
+
+## Two delivery modes
+
+The protocol carries the same `{operations: [...]}` payload in both
+directions:
+
+* **Request/response** (auto-skill pattern). Frontend sends a WS
+ request, the backend handler returns ops in the response, the
+ frontend applies them. Used when the user takes an action on the
+ canvas and the backend decides what should happen.
+
+* **Push broadcast** (Agent Builder pattern). Backend code (often
+ inside an LLM tool execution) calls
+ `services.status_broadcaster.send_custom_event('workflow_ops_apply',
+ {workflow_id, caller_node_id, operations})`. The frontend's
+ `useWorkflowOpsListener` hook (mounted in `Dashboard`) subscribes
+ via `WebSocketContext.addEventListener('workflow_ops_apply', ...)`,
+ filters by current `workflow_id`, and pipes ops through
+ `applyOperations`. Events targeting other workflows surface as a
+ sonner toast with a "Switch" action.
## Adding a new consumer
-1. Write a backend service that returns `{operations: [...]}` using
- the builder helpers in `services/workflow_ops`.
-2. Add a thin `@ws_handler` that calls into the service.
-3. On the frontend, send the WS request and pass the returned
- `operations` into `applyOperations`. No new applier code.
-4. If you need a new op type, follow the steps in the docstring of
+1. Write a backend module that builds a workflow-ops batch using
+ the helpers in `services/workflow_ops`.
+2. Choose a delivery mode:
+ * Request/response: add a thin `@ws_handler` that returns
+ `{success: True, operations: [...]}`. On the frontend send the
+ WS request and pipe the result into `applyOperations`.
+ * Push broadcast: call `send_custom_event('workflow_ops_apply',
+ {workflow_id, caller_node_id, operations})`. No frontend code
+ -- the existing listener handles it.
+3. If you need a new op type, follow the steps in the docstring of
`server/services/workflow_ops.py` (mirror the TypedDict in TS,
add an apply branch, document here).
diff --git a/server/skills/autonomous/agent-builder-skill/SKILL.md b/server/skills/autonomous/agent-builder-skill/SKILL.md
new file mode 100644
index 00000000..1ba18fff
--- /dev/null
+++ b/server/skills/autonomous/agent-builder-skill/SKILL.md
@@ -0,0 +1,166 @@
+---
+name: agent-builder-skill
+description: How to use the Agent Builder tool's five canvas-mutation operations to inspect and grow your own toolset / skills / teammates / workflows mid-execution
+allowed-tools: "agentBuilder"
+metadata:
+ author: machina
+ version: "2.0"
+ category: autonomous
+---
+
+# Agent Builder
+
+You are connected to an **Agent Builder** node. It exposes ONE
+LLM-callable tool, `agentBuilder`, which dispatches to FIVE
+canvas-mutation operations via the `operation` field:
+
+| `operation` value | Purpose |
+|---|---|
+| `inspect_canvas` | Read-only view of nodes, edges, and what's already wired to you. ALWAYS call this first. |
+| `add_tool` | Spawn a tool node + wire it to your `input-tools` handle. |
+| `add_skill` | Toggle a skill on your Master Skill (auto-creates one if missing). |
+| `add_subagent` | Team-leads only -- spawn a delegate agent + wire to your `input-teammates`. |
+| `create_workflow` | Persist a fresh empty workflow + return its id. Doesn't switch the user's view. |
+
+Every call is `agentBuilder({operation: "<one-of-above>", ...op-specific-fields})`. There are no separate tools.
+
+## The cardinal rule
+
+**Call `agentBuilder({operation: "inspect_canvas"})` BEFORE any
+mutation operation.** Without it you cannot tell whether a tool /
+skill / subagent is already wired and will create duplicates.
+Workflow becomes cluttered and your tool list confused.
+
+The `inspect_canvas` summary tells you:
+- which tools are already connected to your `input-tools`
+- whether a Master Skill is wired to your `input-skill` (and what
+ skills it has enabled)
+- whether you have any teammate delegates (`input-teammates`)
+
+Pick the smallest action that solves the problem. If the tool you
+need is already on your canvas, USE IT -- don't add a duplicate.
+
+## Soft-reload semantics (important)
+
+LangGraph binds your tool list at the start of each invocation.
+Tools / skills / teammates added mid-run **do NOT become callable
+in the current run**. They become available on your **next
+invocation** (next chat message, next workflow trigger, next call).
+
+Each mutation returns a summary ending in "available on your next
+turn". Take this literally. Do NOT loop trying to call something
+you just added -- it isn't there yet. Tell the user what you added
+and that they can use it on the next message.
+
+## Operation reference
+
+### `operation: "inspect_canvas"`
+
+No additional fields. Returns:
+```json
+{
+ "operation": "inspect_canvas",
+ "nodes": [{ "id", "type", "label", "key_params" }, ...],
+ "edges": [{ "source", "target", "source_handle", "target_handle" }, ...],
+ "you": {
+ "node_id": "agent-1",
+ "incoming": [...], "outgoing": [...]
+ },
+ "summary": "5 nodes, 1 tool(s) wired to you (httpRequest), no skills."
+}
+```
+
+API keys, prompts, and other secrets are **stripped** from
+`key_params`. Only safe planner-relevant fields surface
+(`provider`, `model`, `operation`, `url`, `query`).
+
+### `operation: "add_tool"`
+
+Required field: `node_type` (string).
+
+Spawns a tool node and wires it to your `input-tools`. Allowed
+types are anything registered with `component_kind="tool"` --
+typically things like `httpRequest`, `braveSearch`,
+`pythonExecutor`, etc. (NOT `agentBuilder` itself; NOT
+`masterSkill`, which is managed via `add_skill` instead.)
+
+If the tool has a paired teaching skill, the auto-add-skill
+handler enables it too -- no separate `add_skill` call needed.
+
+### `operation: "add_skill"`
+
+Required field: `skill_folder` (string).
+
+Enables a skill on your Master Skill. If you don't have a Master
+Skill connected to `input-skill` yet, one is created and wired for
+you. The skill folder must exist under `server/skills/**`
+(e.g. `http-request-skill`, `memory-skill`, `python-skill`).
+
+The skill's `SKILL.md` instructions become part of your system
+message on your next turn.
+
+### `operation: "add_subagent"`
+
+Required field: `agent_type` (string).
+
+**Team-leads only** (`orchestrator_agent`, `ai_employee`,
+`deep_agent`). Spawns a specialized agent (`coding_agent`,
+`web_agent`, `task_agent`, etc.) and wires it to your
+`input-teammates` handle. The new agent appears as a
+`delegate_to_<name>` tool on your next turn.
+
+The new agent starts with empty configuration -- the user will
+need to set its provider/model after the run. Mention this in your
+response.
+
+### `operation: "create_workflow"`
+
+Required field: `workflow_name` (string).
+Optional field: `workflow_description` (string).
+
+Persists a fresh empty workflow with a single Start node and
+returns its `workflow_id`. The user's current view does NOT
+change; the frontend toasts a "Switch" link.
+
+Use sparingly. Prefer mutating the current workflow over creating
+new ones. Good cases for `create_workflow`:
+- Templating / saving a solved pattern as a starting point.
+- Splitting work into a separate workflow when the current one
+ is getting too large.
+
+## Worked example
+
+User: "Search the web for current weather in Tokyo and tell me."
+
+```
+1. agentBuilder({operation: "inspect_canvas"})
+ -> "1 nodes, no tool(s) wired to you, no skills."
+ You see no web-search tool exists. Plan: add one.
+
+2. agentBuilder({operation: "add_tool", node_type: "braveSearch"})
+ -> "Added 'braveSearch' as a tool. Available on your next turn."
+
+3. Reply to the user:
+ "I've added a Brave Search tool to my toolset. Send me the same
+ request on your next message and I'll search for the Tokyo
+ weather."
+```
+
+DO NOT try to call `brave_search` in the same turn -- it's not in
+your tool list yet. Just tell the user it's ready for next turn.
+
+## What NOT to do
+
+- **Don't skip `inspect_canvas`**. Always run it first; it's
+ read-only and cheap.
+- **Don't add a tool you already have**. The inspect summary tells
+ you what's wired.
+- **Don't loop on freshly-added tools**. They're not callable until
+ next invocation.
+- **Don't add `agentBuilder` to yourself via `add_tool`** (rejected
+ -- avoids recursion; `agentBuilder` is excluded from the allowed
+ tool types).
+- **Don't spawn another team-lead** as a subagent (rejected --
+ team-leads delegate to specialists, not to other team-leads).
+- **Don't call `create_workflow`** unless the user explicitly asks
+ to start a fresh workflow.