Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(agent_builder): SKILL.md (multi-op shape) + protocol + CLAUDE.md
trohitgb31ac66452f6
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 Typesdiff --git a/docs-internal/workflow_ops_protocol.md b/docs-internal/workflow_ops_protocol.mdindex 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.mdnew file mode 100644index 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.