Skip to content

Self-improving AI Employees for everyone

chore(docs): scrub remaining LangGraph + deep_agent residue

trohitg02ebee682e9c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3e722936..0069b066 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -36,7 +36,7 @@ Deep dives: [DESIGN.md](docs-internal/DESIGN.md) - [TEMPORAL_ARCHITECTURE.md](do
[![AI Agent Routing](docs/diagrams/ai-agent-routing.svg)](https://raw.githubusercontent.com/zeenie-ai/MachinaOS/main/docs/diagrams/ai-agent-routing.svg)
-AI execution splits into two paths. `execute_chat()` for direct chat completions prefers the native SDK layer in [services/llm/](server/services/llm/) (10 providers, lazy imports, normalized `LLMResponse`), falling back to LangChain for Groq and Cerebras. `execute_agent()` and `execute_chat_agent()` always use LangChain + LangGraph because tool-calling, state graphs, and the checkpointer have no native equivalent today. Team leads (`orchestrator_agent`, `ai_employee`) auto-inject `delegate_to_<type>` tools for every agent connected to their `input-teammates` handle. The Deep Agent variant uses [LangChain DeepAgents](https://github.com/langchain-ai/deepagents) with built-in filesystem tools, sub-agent delegation, and todo planning; the RLM Agent uses a REPL-based recursive language model pattern. Long-running activities (DeepAgent, browser automation) stay alive across Temporal's 2-minute heartbeat window via per-message `activity.heartbeat()` calls in the WebSocket read loop.
+AI execution splits into two paths. `execute_chat()` for direct chat completions prefers the native SDK layer in [services/llm/](server/services/llm/) (10 providers, lazy imports, normalized `LLMResponse`), falling back to LangChain for Groq and Cerebras. `execute_agent()` and `execute_chat_agent()` build a LangChain chat model (`ChatOpenAI` / `ChatAnthropic` / etc.) and drive it through `_run_agent_loop` — a plain async `for iteration in range(max):` that calls `chat_model.ainvoke`, dispatches any `tool_calls`, appends `ToolMessage` results, and loops. Team leads (`orchestrator_agent`, `ai_employee`) auto-inject `delegate_to_<type>` tools for every agent connected to their `input-teammates` handle. The RLM Agent uses a REPL-based recursive language model pattern. Long-running activities (browser automation, claude_code_agent) stay alive across Temporal's 2-minute heartbeat window via per-message `activity.heartbeat()` calls in the WebSocket read loop.
Deep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [native_llm_sdk.md](docs-internal/native_llm_sdk.md) - [agent_teams.md](docs-internal/agent_teams.md) - [memory_compaction.md](docs-internal/memory_compaction.md)
@@ -121,7 +121,6 @@ Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.
| [DESIGN.md](docs-internal/DESIGN.md) | Execution engine architecture, design patterns, execution modes |
| [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) | Distributed execution via Temporal activities |
| [workflow-schema.md](docs-internal/workflow-schema.md) | Workflow JSON schema and full node catalog (106 nodes) |
-| [deep_agent.md](docs-internal/deep_agent.md) | LangChain DeepAgents integration with filesystem tools and sub-agents |
| [ROADMAP.md](docs-internal/ROADMAP.md) | Implementation status and completed phases |
| [SETUP.md](docs-internal/SETUP.md) | Development environment setup |
| [SCRIPTS.md](docs-internal/SCRIPTS.md) | npm/shell scripts reference |
diff --git a/README.md b/README.md
index 8e591faa..b78bb326 100644
--- a/README.md
+++ b/README.md
@@ -133,7 +133,6 @@ Pick the right agent for the job:
| Travel Agent | Maps, location lookup, planning |
| Payments Agent | Stripe + financial workflows |
| Consumer Agent | Customer support, order management |
-| Deep Agent | LangChain DeepAgents with filesystem tools + sub-agent delegation |
| Claude Code Agent | Anthropic's Claude Code CLI for advanced coding sessions |
| Codex Agent | OpenAI Codex CLI integration |
| RLM Agent | Recursive Language Model — write code that calls itself recursively |
diff --git a/client/src/components/AIAgentNode.tsx b/client/src/components/AIAgentNode.tsx
index a56c16ee..3460f800 100644
--- a/client/src/components/AIAgentNode.tsx
+++ b/client/src/components/AIAgentNode.tsx
@@ -12,7 +12,7 @@ import { useNodeSpec } from '../lib/nodeSpec';
import { NodeIcon } from '../assets/icons';
import { Badge } from '@/components/ui/badge';
-// LangGraph phase icons and labels. Colors reference the dracula token
+// Agent-loop phase icons and labels. Colors reference the dracula token
// constants so a future palette change in tokens.css propagates without
// editing each phase entry.
const PHASE_CONFIG: Record<string, { icon: string; label: string; color: string }> = {
@@ -74,11 +74,10 @@ const AIAgentNode: React.FC<NodeProps<NodeData>> = ({ id, type, data, isConnecta
const isExecuting = nodeStatus?.status === 'executing';
const currentPhase = nodeStatus?.data?.phase as string | undefined;
const phaseConfig = currentPhase ? PHASE_CONFIG[currentPhase] : null;
- // Live LangGraph supervised-loop counter. Backed by the
- // `agent_progress` CloudEvents broadcast (services/ai.py emits one
- // per astream snapshot). `iteration` advances on each agent_node call;
- // `max_iterations` mirrors LangGraph's recursion_limit
- // (llm_defaults.json:agent.recursion_limit).
+ // Live agent-loop counter. Backed by the `agent_progress` CloudEvents
+ // broadcast (services/ai.py:_run_agent_loop emits one per iteration via
+ // the progress_callback). `iteration` advances per turn; `max_iterations`
+ // mirrors the loop's hard cap (llm_defaults.json:agent.recursion_limit).
const iteration = nodeStatus?.data?.iteration as number | undefined;
const maxIterations = nodeStatus?.data?.max_iterations as number | undefined;
const showIterationBadge =
@@ -161,7 +160,7 @@ const AIAgentNode: React.FC<NodeProps<NodeData>> = ({ id, type, data, isConnecta
</>
)}
- {/* Live LangGraph iteration counter (e.g. "12 / 500"). shadcn
+ {/* Live agent-loop iteration counter (e.g. "12 / 500"). shadcn
Badge primitive with `outline` variant — picks up `--border`
and `--foreground` from whichever theme is active. The
per-node-type accent rides via the `--node-color` custom
@@ -172,7 +171,7 @@ const AIAgentNode: React.FC<NodeProps<NodeData>> = ({ id, type, data, isConnecta
{showIterationBadge && (
<Badge
variant="outline"
- title={`Iteration ${iteration} of ${maxIterations} (LangGraph recursion_limit)`}
+ title={`Iteration ${iteration} of ${maxIterations} (agent.recursion_limit)`}
className="absolute top-1 left-1 z-20 tabular-nums pointer-events-none"
style={{
color: 'var(--node-color)',
diff --git a/client/src/contexts/WebSocketContext.tsx b/client/src/contexts/WebSocketContext.tsx
index 131baef1..e1acaf92 100644
--- a/client/src/contexts/WebSocketContext.tsx
+++ b/client/src/contexts/WebSocketContext.tsx
@@ -66,7 +66,7 @@ const LONG_RUNNING_NODE_TYPES = [
'aiAgent', 'chatAgent', 'rlm_agent',
'android_agent', 'coding_agent', 'web_agent', 'task_agent', 'social_agent',
'travel_agent', 'tool_agent', 'productivity_agent', 'payments_agent', 'consumer_agent',
- 'autonomous_agent', 'orchestrator_agent', 'ai_employee', 'deep_agent',
+ 'autonomous_agent', 'orchestrator_agent', 'ai_employee',
];
// Status types
diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.md
index 5ece843d..ae3ebdeb 100644
--- a/docs-internal/TEMPORAL_ARCHITECTURE.md
+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md
@@ -304,7 +304,8 @@ AgentWorkflow.run(context):
emit_phase("tool_completed", tool_name=...)
_serialise_tool_result unwraps F4.A's {success, result, ...}
envelope so the LLM sees only the handler's return value
- (matches services/ai.py:create_tool_node behavior).
+ (matches the in-process tool-call serialisation in
+ services/ai.py:_run_agent_loop).
4. execute_activity("agent.persist_turn.v1")
append_to_memory_markdown(content, "human", prompt) +
(content, "ai", response); trim window; broadcast
diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.md
index 0da80d49..16ff1eae 100644
--- a/docs-internal/agent_architecture.md
+++ b/docs-internal/agent_architecture.md
@@ -94,7 +94,7 @@ The agent loop is a plain `for iteration in range(max_iterations):` async functi
5. If `response.tool_calls` is empty → return `{messages, iteration, thinking_content, truncated: False}`.
6. Otherwise dispatch each `tool_call` via the supplied `tool_executor`, wrap each result as a `ToolMessage`, append, and loop.
-On hitting `max_iterations`, append a terminal `AIMessage` with a truncation note (same behaviour the old `GraphRecursionError` handler synthesised) and return `truncated: True`.
+On hitting `max_iterations`, append a terminal `AIMessage` with a truncation note and return `truncated: True`.
### Signature
diff --git a/docs/diagrams/ai-agent-routing.svg b/docs/diagrams/ai-agent-routing.svg
index 319912de..d7b336af 100644
--- a/docs/diagrams/ai-agent-routing.svg
+++ b/docs/diagrams/ai-agent-routing.svg
@@ -93,28 +93,28 @@
<rect class="method" x="920" y="215" width="360" height="75" rx="8"/>
<text x="1100" y="243" class="big" text-anchor="middle">execute_agent(parameters)</text>
<text x="1100" y="263" class="sub" text-anchor="middle">execute_chat_agent(parameters)</text>
- <text x="1100" y="283" class="caption" text-anchor="middle">aiAgent, chatAgent, 13 specialized agents</text>
+ <text x="1100" y="283" class="caption" text-anchor="middle">aiAgent, chatAgent, 11 specialized + 2 team leads</text>
<!-- Arrow -->
<path class="conn-lc" d="M 1100 290 L 1100 330" marker-end="url(#arrow)"/>
- <!-- LangChain + LangGraph box -->
+ <!-- LangChain chat model box -->
<rect class="langchain" x="920" y="330" width="360" height="130" rx="8"/>
- <text x="1100" y="358" class="title" text-anchor="middle" fill="#bd93f9">LangChain + LangGraph</text>
+ <text x="1100" y="358" class="title" text-anchor="middle" fill="#bd93f9">LangChain chat model</text>
<text x="1100" y="382" class="sub" text-anchor="middle">create_model() -&gt; LangChain class</text>
<text x="1100" y="402" class="path-lc" text-anchor="middle">ChatOpenAI / ChatAnthropic</text>
<text x="1100" y="420" class="path-lc" text-anchor="middle">ChatGoogleGenerativeAI / ChatGroq / ...</text>
<text x="1100" y="442" class="sub" text-anchor="middle">.bind_tools([StructuredTool, ...])</text>
- <!-- Arrow to state graph -->
+ <!-- Arrow to agent loop -->
<path class="conn-lc" d="M 1100 460 L 1100 500" marker-end="url(#arrow)"/>
- <!-- LangGraph StateGraph box -->
+ <!-- _run_agent_loop box -->
<rect class="langchain" x="900" y="500" width="400" height="155" rx="8"/>
- <text x="1100" y="528" class="title" text-anchor="middle" fill="#bd93f9">LangGraph StateGraph</text>
- <text x="1100" y="552" class="sub" text-anchor="middle">START -&gt; agent (LLM) -&gt; should_continue?</text>
- <text x="1100" y="572" class="sub" text-anchor="middle">if tools needed: tools node -&gt; loop back</text>
- <text x="1100" y="592" class="sub" text-anchor="middle">else: END</text>
+ <text x="1100" y="528" class="title" text-anchor="middle" fill="#bd93f9">_run_agent_loop (plain async)</text>
+ <text x="1100" y="552" class="sub" text-anchor="middle">for iteration in range(max): ainvoke -&gt; tool_calls?</text>
+ <text x="1100" y="572" class="sub" text-anchor="middle">if tools: dispatch each, append ToolMessage, loop</text>
+ <text x="1100" y="592" class="sub" text-anchor="middle">else: return final response</text>
<text x="1100" y="615" class="caption" text-anchor="middle">Max iterations guard against tool loops</text>
<text x="1100" y="635" class="caption" text-anchor="middle">Agent Teams: delegate_to_&lt;type&gt; tools auto-injected</text>
diff --git a/docs/diagrams/node-anatomy.svg b/docs/diagrams/node-anatomy.svg
index f41fcdec..8c383bb4 100644
--- a/docs/diagrams/node-anatomy.svg
+++ b/docs/diagrams/node-anatomy.svg
@@ -113,7 +113,7 @@
<rect class="ai-box" x="990" y="475" width="360" height="85" rx="8"/>
<text x="1010" y="500" class="title">D. AI layer (for AI nodes)</text>
<text x="1010" y="520" class="path-be">server/services/ai.py + llm/</text>
- <text x="1010" y="540" class="sub">Native SDK path or LangChain + LangGraph</text>
+ <text x="1010" y="540" class="sub">Native SDK path or LangChain agent loop</text>
<text x="1010" y="554" class="sub">with tool calling</text>
<!-- Arrows inside backend column (vertical flow) -->
diff --git a/server/config/llm_defaults.json b/server/config/llm_defaults.json
index 46c91124..1318bc42 100644
--- a/server/config/llm_defaults.json
+++ b/server/config/llm_defaults.json
@@ -4,7 +4,7 @@
"_description": "LLM provider defaults. Connection config (base_url, models_endpoint) drives both native SDK and LangChain paths. Model specs auto-enriched by model_registry.json (OpenRouter cache).",
"agent": {
- "_description": "Agent execution defaults shared across the LangGraph + compaction layers. recursion_limit is intentionally generous so the token-based compaction.ratio is the load-bearing termination signal, not the step cap.",
+ "_description": "Agent execution defaults shared across the agent loop + compaction layers. recursion_limit is intentionally generous so the token-based compaction.ratio is the load-bearing termination signal, not the step cap.",
"recursion_limit": 500,
"default_temperature": 0.7,
"compaction": {
diff --git a/server/requirements.txt b/server/requirements.txt
index 436341df..dad99151 100644
--- a/server/requirements.txt
+++ b/server/requirements.txt
@@ -48,7 +48,9 @@ langchain-google-genai>=3.1.0
langchain-groq>=0.1.0
langchain-cerebras>=0.1.0
-# DeepAgents - Batteries-included agent harness (LangChain)
+# DeepAgents - LocalShellBackend + validate_path + ExecuteResponse for the
+# filesystem/shell plugins (nodes/filesystem/_backend.py). Not used as the
+# agent harness itself (the deep_agent plugin was removed in 5335188).
deepagents>=0.4.12
# Temporal - Durable workflow execution (optional, requires TEMPORAL_ENABLED=true)
diff --git a/server/services/ai.py b/server/services/ai.py
index db688dd2..4b09face 100644
--- a/server/services/ai.py
+++ b/server/services/ai.py
@@ -743,11 +743,11 @@ async def _run_agent_loop(
4. If no tool calls, return.
On hitting ``max_iterations``, append a terminal ``AIMessage`` with
- a truncation note so downstream extraction has a usable response —
- same shape the old ``GraphRecursionError`` handler synthesised.
+ a truncation note so downstream extraction has a usable response.
``progress_callback(iteration)`` is awaited at the top of each turn
- (replaces the per-snapshot broadcast inside ``astream``).
+ so callers can drive per-iteration broadcasts (e.g. the FE iteration
+ badge).
Returns ``{messages, iteration, thinking_content, truncated}``.
``messages`` is the full accumulated list (system + history +
@@ -782,8 +782,7 @@ async def _run_agent_loop(
thinking_accumulated = new_thinking
# Gemini occasionally returns a blocked / safety-stopped response;
- # surface the same warning the legacy agent_node did so operators
- # can spot the cause in the logs.
+ # surface the cause so operators can spot it in the logs.
if hasattr(response, "response_metadata"):
meta = response.response_metadata or {}
if meta.get("finish_reason") == "SAFETY":
@@ -830,8 +829,7 @@ async def _run_agent_loop(
# Loop exited without returning -- hit max_iterations. Append a
# terminal AIMessage so downstream extraction (and post-loop token
- # tracking / memory persistence) still have a usable state, matching
- # the legacy ``GraphRecursionError`` handler.
+ # tracking / memory persistence) still have a usable state.
messages.append(AIMessage(content=(
f"[Recursion limit reached: {max_iterations} iterations. "
f"Adjust agent.recursion_limit in llm_defaults.json or "
diff --git a/server/services/temporal/agent_activities.py b/server/services/temporal/agent_activities.py
index 7d72ff2e..b211d8b4 100644
--- a/server/services/temporal/agent_activities.py
+++ b/server/services/temporal/agent_activities.py
@@ -138,8 +138,8 @@ async def execute_llm_step(payload: Dict[str, Any]) -> Dict[str, Any]:
from services.ai import filter_empty_messages
rehydrated = messages_from_dict(messages)
- # Same filter the legacy create_agent_node runs (services/ai.py:775)
- # — empty-content messages trigger 400s on Gemini/Anthropic.
+ # Same filter ``_run_agent_loop`` runs in services/ai.py — empty-content
+ # messages trigger 400s on Gemini / Anthropic.
rehydrated = filter_empty_messages(rehydrated)
activity.heartbeat("LLM step: invoking model")
diff --git a/server/services/temporal/agent_workflow.py b/server/services/temporal/agent_workflow.py
index 85ecf71a..27a6688b 100644
--- a/server/services/temporal/agent_workflow.py
+++ b/server/services/temporal/agent_workflow.py
@@ -586,13 +586,13 @@ class AgentWorkflow:
def _serialise_tool_result(result: Any) -> str:
"""Return a string body for a ``ToolMessage``.
- Mirrors the legacy ``create_tool_node`` in ``services/ai.py``: feed
- the LLM the handler's raw return value (``json.dumps(result,
- default=str)``), NOT the Temporal activity envelope. The F4.A
- per-type activity wraps the handler result as
- ``{"success": bool, "result": {...}, "node_id": ..., "node_type": ...,
- "timestamp": ...}``; we strip the envelope so the LLM doesn't see
- infrastructure metadata.
+ Mirrors the in-process tool-call serialisation in
+ ``services/ai.py:_run_agent_loop``: feed the LLM the handler's raw
+ return value (``json.dumps(result, default=str)``), NOT the Temporal
+ activity envelope. The F4.A per-type activity wraps the handler
+ result as ``{"success": bool, "result": {...}, "node_id": ...,
+ "node_type": ..., "timestamp": ...}``; we strip the envelope so the
+ LLM doesn't see infrastructure metadata.
"""
import json as _json
diff --git a/server/skills/assistant/agent-builder-skill/SKILL.md b/server/skills/assistant/agent-builder-skill/SKILL.md
index 1ba18fff..79111433 100644
--- a/server/skills/assistant/agent-builder-skill/SKILL.md
+++ b/server/skills/assistant/agent-builder-skill/SKILL.md
@@ -42,7 +42,7 @@ 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.
+The agent loop 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).
@@ -103,11 +103,11 @@ message on your next turn.
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.
+**Team-leads only** (`orchestrator_agent`, `ai_employee`).
+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