Skip to content

Self-improving AI Employees for everyone

fix: deep agent tool execution, memory support, and output formatting

trohitg684bbd3317b4
diff --git a/CLAUDE.md b/CLAUDE.md
index 94211bca..cd6b0041 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -37,6 +37,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Status Broadcaster](./docs-internal/status_broadcaster.md)** | WebSocket-first communication: StatusBroadcaster singleton, 89 handlers, broadcast message types, Android two-state model |
| **[RLM Service](./docs-internal/rlm_service.md)** | Recursive Language Model agent with REPL-based execution (llm_query, rlm_query, FINAL) |
| **[Claude Code Agent](./docs-internal/claude_code_agent_architecture.md)** | Claude Code SDK integration as a specialized agent node |
+| **[Deep Agent](./docs-internal/deep_agent.md)** | LangChain DeepAgents integration with filesystem tools, sub-agent delegation, auto-summarization, and planning |
| **[Autonomous Agent Creation](./docs-internal/autonomous_agent_creation.md)** | Creating autonomous agents with Code Mode patterns and agentic loops |
| **[Polyglot Server](../polyglot-server/ARCHITECTURE.md)** | Plugin registry microservice with MCP gateway (optional integration) |
@@ -395,7 +396,7 @@ class CacheEntry(SQLModel, table=True):
## Codebase Summary
- **Hybrid architecture**: Node.js + Python + React TypeScript
-- **96 implemented workflow nodes** with clean service separation (9 AI models + 3 AI agents/memory + 15 specialized agents + 1 skill + 4 dedicated tools + 3 search + 16 Android + 3 WhatsApp + 4 Twitter + 2 Telegram + 2 Social + 3 Location + 3 Code + 6 Utility + 6 Document + 2 Chat + 2 Scheduler + 2 Workflow + 7 Google Workspace + 1 Apify + 1 Crawlee + 3 Proxy)
+- **97 implemented workflow nodes** with clean service separation (9 AI models + 3 AI agents/memory + 16 specialized agents + 1 skill + 4 dedicated tools + 3 search + 16 Android + 3 WhatsApp + 4 Twitter + 2 Telegram + 2 Social + 3 Location + 3 Code + 6 Utility + 6 Document + 2 Chat + 2 Scheduler + 2 Workflow + 7 Google Workspace + 1 Apify + 1 Crawlee + 3 Proxy)
- **WebSocket-First Architecture**: WebSocket as primary frontend-backend communication (89 message handlers)
- **Recent optimizations**: REST APIs replaced with WebSocket, AI endpoints migrated to Python, Android automation integrated
@@ -791,7 +792,7 @@ Search API nodes that work BOTH as standalone workflow nodes AND as AI Agent too
- Brave Search and Perplexity in **Search** category
- Serper in **Scrapers** category (Google SERP scraping)
-### Specialized AI Agents (14 nodes)
+### Specialized AI Agents (15 nodes)
Specialized agents are AI Agents pre-configured for specific domains. They inherit full AI Agent functionality (provider, model, prompt, system message, thinking/reasoning) while being tailored for specific capabilities. All specialized agents route to `handle_chat_agent` in the backend and support the same input handles. Node colors use centralized dracula theme constants imported from `client/src/styles/theme.ts`.
**Input Handles:**
@@ -816,9 +817,10 @@ Specialized agents are AI Agents pre-configured for specific domains. They inher
- **orchestrator_agent**: Orchestrator Agent - Team lead agent for coordinating multiple agents. Connect specialized agents via `input-teammates` handle; they become `delegate_to_*` tools the AI can invoke.
- **ai_employee**: AI Employee - Team lead agent similar to orchestrator_agent. Connect specialized agents via `input-teammates` handle for intelligent task delegation.
- **rlm_agent**: RLM Agent - Recursive Language Model agent using REPL-based code execution with recursive LM calls. Replaces LangGraph tool-calling with RLM's `exec()` REPL loop (`llm_query()`, `rlm_query()`, `FINAL()`). Routes to dedicated `handle_rlm_agent` handler and `RLMService` (not `handle_chat_agent`). Connect AI chat model nodes as small LMs for depth>=1 calls. See `docs-internal/rlm_service.md`.
+- **deep_agent**: Deep Agent - AI agent powered by LangChain DeepAgents with built-in filesystem tools (read, write, edit, glob, grep, execute), sub-agent delegation, auto-summarization, and todo planning. Routes to dedicated `handle_deep_agent` handler and `DeepAgentService` (not `handle_chat_agent`). Supports memory, skills, connected tools, and teammate delegation via `input-teammates`. See `docs-internal/deep_agent.md`.
**Backend Routing:**
-Specialized agents are detected by `SPECIALIZED_AGENT_TYPES` and routed to `handle_chat_agent` (except `rlm_agent` which routes to `handle_rlm_agent`):
+Specialized agents are detected by `SPECIALIZED_AGENT_TYPES` and routed to `handle_chat_agent` (except agents with dedicated execution engines):
```python
# In node_executor.py - most specialized agents route to handle_chat_agent
SPECIALIZED_AGENT_TYPES = {
@@ -827,6 +829,7 @@ SPECIALIZED_AGENT_TYPES = {
'autonomous_agent', 'orchestrator_agent', 'ai_employee',
}
# rlm_agent routes to handle_rlm_agent -> RLMService (dedicated handler + service)
+# deep_agent routes to handle_deep_agent -> DeepAgentService (dedicated handler + service)
```
**Team Lead Types (Agent Teams Pattern):**
@@ -834,6 +837,7 @@ Team leads (`orchestrator_agent`, `ai_employee`) have a special `input-teammates
```python
# In handlers/ai.py
TEAM_LEAD_TYPES = {'orchestrator_agent', 'ai_employee'}
+# deep_agent collects teammates in handle_deep_agent and converts to deepagents SubAgent dicts
# Teammates become delegate_to_* tools automatically
if node_type in TEAM_LEAD_TYPES:
@@ -2216,6 +2220,7 @@ The system supports specialized agent variants that inherit from the base AI Age
| Orchestrator | `orchestrator_agent` | conductor | cyan |
| AI Employee | `ai_employee` | briefcase | purple |
| RLM Agent | `rlm_agent` | brain | orange |
+| Deep Agent | `deep_agent` | brain (U+1F9E0) | green |
All specialized agents share the same handle configuration:
- **Left**: `input-main` (Input, 30%), `input-memory` (Memory, 55%), `input-task` (Task, 85%)
diff --git a/docs-internal/deep_agent.md b/docs-internal/deep_agent.md
index a9ac721c..44a37197 100644
--- a/docs-internal/deep_agent.md
+++ b/docs-internal/deep_agent.md
@@ -13,9 +13,11 @@ Specialized agent node powered by [LangChain DeepAgents](https://github.com/lang
2. [Architecture](#architecture)
3. [DeepAgents Package](#deepagents-package)
4. [MachinaOs Integration](#machinaos-integration)
-5. [Node Definition](#node-definition)
-6. [Key Files](#key-files)
-7. [Comparison with Other Agent Types](#comparison-with-other-agent-types)
+5. [Tool Execution](#tool-execution)
+6. [Memory Integration](#memory-integration)
+7. [Node Definition](#node-definition)
+8. [Key Files](#key-files)
+9. [Comparison with Other Agent Types](#comparison-with-other-agent-types)
---
@@ -32,11 +34,11 @@ Deep Agent combines MachinaOs's existing agent infrastructure (skill injection,
**What MachinaOs provides:**
- Provider/model selection from `llm_defaults.json` (9 providers)
-- Tool node connections (calculator, search, WhatsApp, Android, etc.)
+- Executable tool node connections (calculator, search, WhatsApp, Android, etc.)
- Skill injection from Master Skill / SKILL.md files
-- Memory via Simple Memory node
+- Memory via Simple Memory node (markdown + vector store)
- Teammate delegation via `input-teammates` handle
-- Real-time status broadcasting via WebSocket
+- Real-time status broadcasting via WebSocket (including tool node glow effects)
---
@@ -46,56 +48,48 @@ Deep Agent combines MachinaOs's existing agent infrastructure (skill injection,
User clicks "Run" on Deep Agent
|
v
-useExecution.executeNode() client/src/hooks/useExecution.ts
- |
- v
-WebSocket: handle_execute_node() server/routers/websocket.py
- |
- v
NodeExecutor._dispatch() server/services/node_executor.py
- Registry: 'deep_agent' -> handle_chat_agent (via partial)
+ Registry: 'deep_agent' -> handle_deep_agent (via partial)
|
v
-handle_chat_agent() server/services/handlers/ai.py
- 1. _collect_agent_connections()
+handle_deep_agent() server/services/handlers/deep_agent.py
+ 1. _collect_agent_connections() [REUSE from handlers/ai.py]
- input-memory -> memory_data
- input-skill -> skill_data[]
- input-tools -> tool_data[]
- input-main -> input_data
- input-task -> task_data
- 2. deep_agent in TEAM_LEAD_TYPES
- -> _collect_teammate_connections()
- -> teammates added as delegation tool_data
- 3. Delegates to execute_chat_agent(node_type='deep_agent')
+ 2. _format_task_context() [REUSE from handlers/ai.py]
+ 3. Auto-prompt fallback [same pattern as handle_rlm_agent]
+ 4. _build_tool_from_node() -> schema stubs
+ _make_executable_tool() -> real async coroutines
+ 5. _collect_teammate_connections() [REUSE from handlers/ai.py]
+ 6. Delegates to ai_service.deep_agent_service.execute()
|
v
-AIService.execute_chat_agent() server/services/ai.py
- Shared setup (same as chatAgent/all specialized agents):
+DeepAgentService.execute() server/services/deep_agent_service.py
+ Reuses module-level helpers from ai.py:
- _build_skill_system_prompt() -> system_message
- - _build_tool_from_node() for each tool_data entry -> all_tools[]
- - Model validation via is_model_valid_for_provider()
- - API key resolution
- - Temperature, max_tokens resolution from model registry
+ - is_model_valid_for_provider(), get_default_model_async()
+ - _resolve_max_tokens(), _resolve_temperature()
+ - self._create_model() -> pre-built BaseChatModel
+ - _parse_memory_markdown(), _get_memory_vector_store() [memory load]
+ - _append_to_memory_markdown(), _trim_markdown_window() [memory save]
|
v
- Branch: node_type == 'deep_agent'
+deepagents.create_deep_agent() deepagents package
+ model = pre-built BaseChatModel (API key baked in)
+ tools = executable MachinaOs tools + deepagents built-in tools
+ system_prompt = system_message (includes skills + long-term memory context)
|
v
-deepagents.create_deep_agent() deepagents package
- model = "{provider}:{model}"
- tools = all_tools (MachinaOs connected tools)
- system_prompt = system_message (includes skills)
- + built-in: read_file, write_file, edit_file, ls, glob,
- grep, execute, write_todos, task
+agent.ainvoke(messages) LangGraph CompiledStateGraph
+ messages = history from SimpleMemory + current prompt
+ Middleware stack: TodoList -> Filesystem -> SubAgent
+ -> Summarization -> ToolCallPatching -> PromptCaching
|
v
-agent.ainvoke(messages, config)
- Middleware stack processes request:
- TodoList -> Skills -> Filesystem -> SubAgent
- -> Summarization -> ToolCallPatching -> PromptCaching
- |
- v
-Extract final AI message -> return result
+Extract response + thinking -> save memory -> return result
```
---
@@ -123,7 +117,6 @@ agent = create_deep_agent(
subagents=None, # Sequence[SubAgent | CompiledSubAgent | AsyncSubAgent]
skills=None, # list[str] (paths to skill dirs)
memory=None, # list[str] (paths to AGENTS.md files)
- response_format=None, # ResponseFormat | type | dict
backend=None, # BackendProtocol | BackendFactory
interrupt_on=None, # dict[str, bool | InterruptOnConfig]
debug=False, # bool
@@ -133,7 +126,7 @@ agent = create_deep_agent(
Returns a **`CompiledStateGraph`** -- a compiled LangGraph graph compatible with streaming, Studio, checkpointers, and all LangGraph features.
-**Default model:** `claude-sonnet-4-6` (via `ChatAnthropic`).
+**Default model:** `claude-sonnet-4-6` (via `ChatAnthropic`). MachinaOs passes a pre-built `BaseChatModel` instance instead to avoid credential resolution issues.
### Built-in Tools
@@ -160,22 +153,7 @@ Returns a **`CompiledStateGraph`** -- a compiled LangGraph graph compatible with
7. **AnthropicPromptCachingMiddleware** -- Prompt caching (Anthropic models only)
8. **MemoryMiddleware** (conditional) -- Persistent memory from AGENTS.md files
-Custom tools passed via `tools=` parameter are added alongside (not replacing) the built-in tools.
-
-### Backends
-
-Backends control where filesystem tools operate:
-
-| Backend | Description |
-|---------|-------------|
-| `StateBackend` | Default. Files stored in LangGraph state (in-memory, ephemeral) |
-| `FilesystemBackend` | Direct local filesystem access |
-| `LocalShellBackend` | Filesystem + unrestricted shell execution |
-| `StoreBackend` | Persistent storage via LangGraph BaseStore |
-| `LangSmithSandbox` | Remote sandboxed execution |
-| `CompositeBackend` | Route paths to different backends |
-
-The `execute` tool requires a `SandboxBackendProtocol` backend (e.g., `LocalShellBackend`). Without it, `execute` returns an error message.
+Custom tools passed via `tools=` parameter are added alongside (not replacing) the built-in tools. deepagents uses LangGraph's `ToolNode` which calls `tool.ainvoke()` directly -- tools must have real executor functions.
### Sub-Agent Types
@@ -185,79 +163,91 @@ The `execute` tool requires a `SandboxBackendProtocol` backend (e.g., `LocalShel
| `CompiledSubAgent` | Pre-built runnable (any LangGraph/LangChain Runnable) |
| `AsyncSubAgent` | Remote/background agent via graph_id + url |
-### Model Resolution
-
-Format: `"provider:model"` -- e.g., `"openai:gpt-5.4"`, `"google_genai:gemini-2.5-flash"`, `"anthropic:claude-sonnet-4-6"`, `"openrouter:anthropic/claude-sonnet-4.6"`.
-
-Default: `claude-sonnet-4-6` via `ChatAnthropic`.
-
---
## MachinaOs Integration
### Execution Path
-Deep Agent reuses the **entire** `handle_chat_agent` pipeline. No separate handler or service file exists. The only new code is a branch inside `execute_chat_agent` at the graph creation point:
+Deep Agent has a **dedicated handler and service** following the RLMService pattern:
+
+- **Handler** (`handlers/deep_agent.py`): Thin wrapper that collects connections, builds executable tools, delegates to service
+- **Service** (`deep_agent_service.py`): Execution engine that handles skill injection, model resolution, memory lifecycle, and `create_deep_agent()` invocation
+- **Composition**: `AIService.__init__` creates `self.deep_agent_service = DeepAgentService(auth=self.auth, model_factory=self.create_model)`
+
+### Reused Helpers (from ai.py)
+
+| Helper | Used For |
+|--------|----------|
+| `_build_skill_system_prompt()` | Skill injection into system_message |
+| `_build_tool_from_node()` | Schema-only tool stubs from tool_data |
+| `is_model_valid_for_provider()` | Model validation against provider |
+| `get_default_model_async()` | Default model from llm_defaults.json |
+| `_resolve_max_tokens()` | Max tokens from model registry |
+| `_resolve_temperature()` | Temperature clamped to provider range |
+| `self.create_model()` | Pre-built BaseChatModel with API key |
+| `_parse_memory_markdown()` | Parse SimpleMemory markdown to messages |
+| `_get_memory_vector_store()` | Long-term vector store retrieval |
+| `_append_to_memory_markdown()` | Append exchange to memory |
+| `_trim_markdown_window()` | Trim + archive removed messages |
+| `extract_thinking_from_response()` | Extract thinking/reasoning content |
+| `log_execution_time()`, `log_api_call()` | Metrics tracking |
-```python
-# server/services/ai.py - inside execute_chat_agent()
-# After all shared setup: skill injection, tool building, model resolution...
+---
-if node_type == 'deep_agent':
- from deepagents import create_deep_agent
+## Tool Execution
- _da_prefix = {"gemini": "google_genai"}
- model_id = f"{_da_prefix.get(provider, provider)}:{model}"
- max_turns = int(parameters.get('maxTurns', 25))
+### Problem
+`_build_tool_from_node()` returns schema-only stubs with `placeholder_func` that echo kwargs back. deepagents' `ToolNode` calls `tool.ainvoke()` directly, so these stubs fail silently.
- agent = create_deep_agent(
- model=model_id,
- tools=all_tools if all_tools else None,
- system_prompt=system_message,
- )
+### Solution
+The handler wraps each stub with a real async coroutine via `_make_executable_tool()`:
- da_result = await agent.ainvoke(
- {"messages": [{"role": "user", "content": prompt}]},
- config={"recursion_limit": max_turns * 2},
+```python
+def _make_executable_tool(tool, config, workflow_id, broadcaster):
+ async def _execute(**kwargs):
+ from services.handlers.tools import execute_tool
+ # Broadcast glow effect to tool node
+ # Call execute_tool(tool_name, kwargs, config)
+ # Broadcast success/error
+ return result
+
+ return StructuredTool.from_function(
+ name=tool.name,
+ description=tool.description,
+ coroutine=_execute,
+ args_schema=tool.get_input_schema(),
)
- # ... extract response from last AI message
```
-### What is Reused (from execute_chat_agent)
+This follows the deepagents pattern: `StructuredTool.from_function(coroutine=async_fn, args_schema=...)`.
-| Step | Function | Description |
-|------|----------|-------------|
-| Skill injection | `_build_skill_system_prompt()` | SKILL.md instructions merged into system_message |
-| Tool building | `_build_tool_from_node()` | Connected tool nodes -> LangChain StructuredTool |
-| Model validation | `is_model_valid_for_provider()` | Validates model against provider's model list |
-| Default model | `get_default_model_async()` | Falls back to llm_defaults.json default |
-| API key | `self.auth.get_api_key()` | Fetches from encrypted credentials |
-| Max tokens | `_resolve_max_tokens()` | Resolves from model registry + llm_defaults |
-| Temperature | `_resolve_temperature()` | Clamped to provider range, thinking-aware |
-| Status broadcast | `broadcast_status()` | Real-time UI updates via WebSocket |
-| Token logging | `log_execution_time()`, `log_api_call()` | Metrics tracking |
+Connected MachinaOs tools (calculator, search, WhatsApp, etc.) execute via `handlers/tools.py execute_tool()`, with real-time glow effects broadcast to tool nodes.
-### Provider Mapping
+---
-MachinaOs providers map to deepagents model prefixes:
+## Memory Integration
-| MachinaOs Provider | deepagents Prefix | Example |
-|-------------------|-------------------|---------|
-| `openai` | `openai` | `openai:gpt-5.4` |
-| `anthropic` | `anthropic` | `anthropic:claude-sonnet-4-6` |
-| `gemini` | `google_genai` | `google_genai:gemini-2.5-flash` |
-| `openrouter` | `openrouter` | `openrouter:anthropic/claude-sonnet-4.6` |
-| `groq` | `groq` | `groq:llama-4-scout` |
-| `cerebras` | `cerebras` | `cerebras:llama3.1-8b` |
-| `deepseek` | `deepseek` | `deepseek:deepseek-chat` |
-| `kimi` | `kimi` | `kimi:kimi-k2.5` |
-| `mistral` | `mistral` | `mistral:mistral-large-latest` |
+Deep Agent supports MachinaOs's SimpleMemory node (markdown-based + vector store), following the same lifecycle as `execute_chat_agent`:
-Only `gemini` differs (`google_genai`). All others use the MachinaOs provider name directly.
+### Load (before agent invocation)
+1. Parse markdown via `_parse_memory_markdown()` into LangChain messages
+2. If `long_term_enabled`: retrieve relevant context from `_get_memory_vector_store()` via `similarity_search()`, append to system_message
+3. Prepend history messages to the deepagents input messages list
-### Team Mode (Teammate Delegation)
+### Save (after agent invocation)
+1. Append human prompt and AI response via `_append_to_memory_markdown()`
+2. Trim to `window_size` via `_trim_markdown_window()`
+3. Archive removed messages to vector store if `long_term_enabled`
+4. Persist updated markdown to database via `save_node_parameters()`
-`deep_agent` is in `TEAM_LEAD_TYPES` alongside `orchestrator_agent` and `ai_employee`. Agents connected to the `input-teammates` handle become delegation tools in `tool_data`, which are then built as `delegate_to_*` StructuredTools and passed to `create_deep_agent(tools=...)`.
+### Result Metadata
+```python
+result["memory"] = {
+ "session_id": session_id,
+ "history_loaded": history_count,
+}
+```
---
@@ -299,22 +289,45 @@ Plus one additional property:
- **Dimensions:** 300x200px
- **Component:** `AIAgentNode` (shared with all specialized agents)
+### Output Schema
+
+Matches `execute_chat_agent` format for frontend compatibility:
+```python
+{
+ "response": str, # AI text response
+ "thinking": str | None, # Extracted thinking/reasoning
+ "thinking_enabled": bool,
+ "model": str, "provider": str,
+ "agent_type": str, # "deep_agent", "deep_agent_with_tools", etc.
+ "iterations": int, # Tool-call loop count
+ "messages_count": int,
+ "finish_reason": "stop",
+ "timestamp": str,
+ "input": {"prompt": str, "system_message": str},
+ "memory": {"session_id": str, "history_loaded": int}, # if connected
+ "skills": {"connected": [str], "count": int}, # if connected
+ "tools": {"connected": [str], "count": int}, # if connected
+}
+```
+
---
## Key Files
-| File | What Changed |
+| File | Description |
|------|-------------|
+| `server/services/deep_agent_service.py` | DeepAgentService execution engine |
+| `server/services/handlers/deep_agent.py` | Thin handler with `_make_executable_tool()` |
+| `server/services/ai.py` | AIService.__init__ composes `self.deep_agent_service` |
+| `server/services/node_executor.py` | Handler registry entry |
+| `server/services/handlers/__init__.py` | Import/export |
+| `server/services/handlers/tools.py` | Delegation tuple |
+| `server/constants.py` | `AI_AGENT_TYPES` |
| `client/src/nodeDefinitions/specializedAgentNodes.ts` | Node definition + `SPECIALIZED_AGENT_TYPES` |
| `client/src/components/AIAgentNode.tsx` | `AGENT_CONFIGS` visual entry |
| `client/src/components/parameterPanel/MiddleSection.tsx` | `AGENT_WITH_SKILLS_TYPES` |
| `client/src/components/parameterPanel/InputSection.tsx` | `AGENT_WITH_SKILLS_TYPES` + `aiAgentTypes` |
| `client/src/contexts/WebSocketContext.tsx` | `LONG_RUNNING_NODE_TYPES` |
-| `server/constants.py` | `AI_AGENT_TYPES` |
-| `server/services/node_executor.py` | Handler registry -> `handle_chat_agent` |
-| `server/services/handlers/ai.py` | `TEAM_LEAD_TYPES`, passes `node_type` to service |
-| `server/services/ai.py` | `execute_chat_agent` branch + delegation tool name |
-| `server/services/handlers/tools.py` | Delegation tuple |
| `server/requirements.txt` | `deepagents>=0.4.12` |
| `server/pyproject.toml` | `deepagents>=0.4.12` |
@@ -322,17 +335,18 @@ Plus one additional property:
## Comparison with Other Agent Types
-| Aspect | chatAgent | deep_agent | claude_code_agent |
-|--------|-----------|------------|-------------------|
-| **Handler** | `handle_chat_agent` | `handle_chat_agent` | `handle_claude_code_agent` |
-| **Graph creation** | Manual LangGraph `build_agent_graph()` | `deepagents.create_deep_agent()` | Claude Code CLI subprocess |
-| **Built-in tools** | None (only connected tools) | 9 (filesystem, todos, task, execute) | 6 (Read, Edit, Bash, Glob, Grep, Write) |
-| **Connected tools** | Yes (via `input-tools`) | Yes (passed to `create_deep_agent(tools=)`) | No |
-| **Skills** | Yes | Yes | Yes (system prompt only) |
-| **Memory** | Yes (markdown + vector) | No (deepagents manages its own) | No |
-| **Teammates** | Only for team leads | Yes (TEAM_LEAD_TYPES) | No |
-| **Properties** | `AI_AGENT_PROPERTIES` | `AI_AGENT_PROPERTIES` + maxTurns | Custom (prompt, model, allowedTools, etc.) |
-| **Providers** | All 9 | All 9 | Anthropic only |
-| **Middleware** | None | 8-layer stack (auto-summarization, caching, etc.) | None |
-| **Auto-summarization** | No | Yes (SummarizationMiddleware) | No |
-| **Planning** | No | Yes (`write_todos` tool) | No |
+| Aspect | chatAgent | deep_agent | claude_code_agent | rlm_agent |
+|--------|-----------|------------|-------------------|-----------|
+| **Handler** | `handle_chat_agent` | `handle_deep_agent` | `handle_claude_code_agent` | `handle_rlm_agent` |
+| **Service** | `AIService.execute_chat_agent()` | `DeepAgentService.execute()` | `ClaudeCodeService.execute()` | `RLMService.execute()` |
+| **Graph creation** | `build_agent_graph()` | `create_deep_agent()` | Claude Code CLI | RLM REPL loop |
+| **Built-in tools** | None | 9 (filesystem, todos, task) | 6 (Read, Edit, Bash, etc.) | 3 (llm_query, rlm_query, FINAL) |
+| **Connected tools** | Yes | Yes (executable) | No | Yes (bridged) |
+| **Skills** | Yes | Yes | Yes (prompt only) | Yes |
+| **Memory** | Yes (markdown + vector) | Yes (markdown + vector) | No | Yes (context only) |
+| **Teammates** | Team leads only | Yes | No | No |
+| **Providers** | All 9 | All 9 | Anthropic only | All 9 |
+| **Middleware** | None | 8-layer stack | None | None |
+| **Auto-summarization** | No | Yes | No | No |
+| **Planning** | No | Yes (`write_todos`) | No | No |
+| **Tool glow effects** | Yes | Yes | No | No |
diff --git a/server/services/ai.py b/server/services/ai.py
index 6a8e6fb9..76904a28 100644
--- a/server/services/ai.py
+++ b/server/services/ai.py
@@ -906,7 +906,7 @@ class AIService:
self.rlm_service = RLMService(auth=self.auth)
# Deep Agent service (deepagents package)
from services.deep_agent_service import DeepAgentService
- self.deep_agent_service = DeepAgentService(auth=self.auth)
+ self.deep_agent_service = DeepAgentService(auth=self.auth, model_factory=self.create_model)
def detect_provider(self, model: str) -> str:
"""Detect AI provider from model name."""
diff --git a/server/services/deep_agent_service.py b/server/services/deep_agent_service.py
index 513ade45..efd94363 100644
--- a/server/services/deep_agent_service.py
+++ b/server/services/deep_agent_service.py
@@ -12,11 +12,6 @@ from core.logging import get_logger, log_execution_time, log_api_call
logger = get_logger(__name__)
-# MachinaOs provider -> deepagents model prefix.
-# deepagents uses "provider:model" strings (see deepagents.utils.resolve_model).
-# Only gemini differs; all others use their MachinaOs name directly.
-_PROVIDER_PREFIX = {"gemini": "google_genai"}
-
class DeepAgentService:
"""Dedicated service for Deep Agent execution.
@@ -25,13 +20,15 @@ class DeepAgentService:
following the same pattern as RLMService.
"""
- def __init__(self, auth=None):
+ def __init__(self, auth=None, model_factory=None):
self.auth = auth
+ self._create_model = model_factory
async def execute(
self,
node_id: str,
parameters: Dict[str, Any],
+ memory_data: Optional[Dict[str, Any]] = None,
skill_data: Optional[List[Dict[str, Any]]] = None,
tools: Optional[List] = None,
teammates: Optional[List[Dict[str, Any]]] = None,
@@ -42,9 +39,11 @@ class DeepAgentService:
"""Execute Deep Agent via deepagents.create_deep_agent().
Same interface pattern as RLMService.execute().
- Reuses existing MachinaOS utilities for shared concerns.
+ Result structure matches execute_chat_agent for frontend compatibility.
"""
start_time = time.time()
+ provider = 'unknown'
+ model = 'unknown'
async def broadcast_status(phase: str, details: Dict[str, Any] = None):
if broadcaster:
@@ -77,6 +76,10 @@ class DeepAgentService:
provider = parameters.get('provider', 'openai')
model = parameters.get('model', '')
+ # Strip [FREE] prefix (OpenRouter models)
+ if model.startswith('[FREE] '):
+ model = model[7:]
+
if not model or not is_model_valid_for_provider(model, provider):
model = await get_default_model_async(provider, database)
@@ -86,14 +89,30 @@ class DeepAgentService:
if not api_key:
raise ValueError(f"API key required for Deep Agent (provider: {provider})")
+ # Resolve max_tokens, temperature, thinking config (same as execute_chat_agent)
+ from services.ai import _resolve_max_tokens, _resolve_temperature, ThinkingConfig
+ max_tokens = _resolve_max_tokens(flattened, model, provider)
+ thinking_config = None
+ if flattened.get('thinkingEnabled'):
+ thinking_config = ThinkingConfig(
+ enabled=True,
+ budget=int(flattened.get('thinkingBudget', 2048)),
+ effort=flattened.get('reasoningEffort', 'medium'),
+ level=flattened.get('thinkingLevel', 'medium'),
+ format=flattened.get('reasoningFormat', 'parsed'),
+ )
+ temperature = _resolve_temperature(flattened, model, provider, bool(thinking_config and thinking_config.enabled))
+
+ # Check for proxy URL
+ proxy_url = await self.auth.get_api_key(f"{provider}_proxy") if self.auth else None
+
await broadcast_status("initializing", {
"message": f"Initializing Deep Agent with {provider}/{model}",
"provider": provider, "model": model,
})
- # === Build deepagents model string ===
- prefix = _PROVIDER_PREFIX.get(provider, provider)
- model_id = f"{prefix}:{model}"
+ # === Build BaseChatModel with API key baked in ===
+ chat_model = self._create_model(provider, api_key, model, temperature, max_tokens, thinking_config, proxy_url)
# === Convert teammates to deepagents SubAgent dicts ===
subagents = None
@@ -107,59 +126,200 @@ class DeepAgentService:
for tm in teammates
]
+ # === Load memory if connected (same as execute_chat_agent) ===
+ from services.ai import (
+ _parse_memory_markdown, _get_memory_vector_store,
+ _append_to_memory_markdown, _trim_markdown_window,
+ is_valid_message_content,
+ )
+
+ session_id = None
+ history_count = 0
+ memory_content = None
+ input_messages = []
+
+ if memory_data and memory_data.get('node_id'):
+ session_id = memory_data.get('session_id', 'default')
+ memory_content = memory_data.get('memory_content', '# Conversation History\n\n*No messages yet.*\n')
+
+ await broadcast_status("loading_memory", {
+ "message": "Loading conversation history...",
+ "session_id": session_id,
+ })
+
+ history_messages = _parse_memory_markdown(memory_content)
+ history_count = len(history_messages)
+
+ # Long-term memory retrieval
+ if memory_data.get('long_term_enabled'):
+ store = _get_memory_vector_store(session_id)
+ if store:
+ try:
+ k = memory_data.get('retrieval_count', 3)
+ docs = store.similarity_search(prompt, k=k)
+ if docs:
+ ctx = "\n---\n".join(d.page_content for d in docs)
+ system_message = f"{system_message}\n\nRelevant past context:\n{ctx}"
+ except Exception as e:
+ logger.debug("[DeepAgent Memory] Long-term retrieval skipped: %s", e)
+
+ # Convert history to dicts for deepagents message format
+ for msg in history_messages:
+ input_messages.append({"role": getattr(msg, "type", "user"), "content": msg.content})
+
+ logger.info("[DeepAgent Memory] Loaded %d messages from markdown", history_count)
+
+ # Build input messages: history + current prompt
+ input_messages.append({"role": "user", "content": prompt})
+
# === Create and invoke deep agent ===
from deepagents import create_deep_agent
max_turns = int(parameters.get('maxTurns', 25))
await broadcast_status("executing", {
- "message": f"Running Deep Agent ({model_id})...",
+ "message": f"Running Deep Agent ({provider}/{model})...",
"tool_count": len(tools or []),
})
agent = create_deep_agent(
- model=model_id,
+ model=chat_model,
tools=tools or None,
system_prompt=system_message,
subagents=subagents,
)
result = await agent.ainvoke(
- {"messages": [{"role": "user", "content": prompt}]},
+ {"messages": input_messages},
config={"recursion_limit": max_turns * 2},
)
- # === Extract final AI response ===
+ # === Extract response and thinking (same patterns as execute_chat_agent) ===
messages = result.get("messages", [])
response_content = ""
+ thinking_content = None
+ iterations = 0
+
+ # Count iterations (tool-call messages indicate agent loops)
+ for msg in messages:
+ if getattr(msg, "type", None) == "ai" and getattr(msg, "tool_calls", None):
+ iterations += 1
+
+ # Extract final AI response
for msg in reversed(messages):
if getattr(msg, "type", None) == "ai" and hasattr(msg, "content"):
- response_content = msg.content if isinstance(msg.content, str) else str(msg.content)
+ raw_content = msg.content
+
+ # Handle list content (Gemini format: [{type: "text", text: "..."}])
+ if isinstance(raw_content, list):
+ text_parts = []
+ for block in raw_content:
+ if isinstance(block, dict) and block.get("type") == "text":
+ text_parts.append(block.get("text", ""))
+ elif isinstance(block, str):
+ text_parts.append(block)
+ response_content = "\n".join(text_parts)
+ elif isinstance(raw_content, str):
+ response_content = raw_content
+ else:
+ response_content = str(raw_content)
+
+ # Extract thinking from last AI message
+ from services.ai import extract_thinking_from_response
+ _, thinking_content = extract_thinking_from_response(msg)
break
+ iterations = max(iterations, 1)
+
+ # === Save memory if connected (same as execute_chat_agent) ===
+ if memory_data and memory_data.get('node_id') and is_valid_message_content(prompt) and is_valid_message_content(response_content):
+ await broadcast_status("saving_memory", {
+ "message": "Saving to conversation memory...",
+ "session_id": session_id,
+ })
+
+ updated_content = memory_content or '# Conversation History\n\n*No messages yet.*\n'
+ updated_content = _append_to_memory_markdown(updated_content, 'human', prompt)
+ updated_content = _append_to_memory_markdown(updated_content, 'ai', response_content)
+
+ # Trim to window size, archive removed to vector DB
+ window_size = memory_data.get('window_size', 10)
+ updated_content, removed_texts = _trim_markdown_window(updated_content, window_size)
+
+ if removed_texts and memory_data.get('long_term_enabled'):
+ store = _get_memory_vector_store(session_id)
+ if store:
+ try:
+ store.add_texts(removed_texts)
+ except Exception as e:
+ logger.warning("[DeepAgent Memory] Failed to archive: %s", e)
+
+ # Persist to database
+ memory_node_id = memory_data['node_id']
+ if database:
+ current_params = await database.get_node_parameters(memory_node_id) or {}
+ current_params['memoryContent'] = updated_content
+ await database.save_node_parameters(memory_node_id, current_params)
+ logger.info("[DeepAgent Memory] Saved markdown to memory node '%s'", memory_node_id)
+
log_execution_time(logger, "deep_agent", start_time, time.time())
log_api_call(logger, provider, model, "deep_agent", True)
+ # === Build result matching execute_chat_agent format ===
+ agent_type = "deep_agent"
+ if skill_data and tools:
+ agent_type = "deep_agent_with_skills_and_tools"
+ elif skill_data:
+ agent_type = "deep_agent_with_skills"
+ elif tools:
+ agent_type = "deep_agent_with_tools"
+
+ result_data = {
+ "response": response_content,
+ "thinking": thinking_content,
+ "thinking_enabled": thinking_config.enabled if thinking_config else False,
+ "model": model,
+ "provider": provider,
+ "agent_type": agent_type,
+ "iterations": iterations,
+ "messages_count": len(messages),
+ "finish_reason": "stop",
+ "timestamp": datetime.now().isoformat(),
+ "input": {
+ "prompt": prompt,
+ "system_message": system_message,
+ },
+ }
+
+ if session_id:
+ result_data["memory"] = {
+ "session_id": session_id,
+ "history_loaded": history_count,
+ }
+
+ if skill_data:
+ result_data["skills"] = {
+ "connected": [s.get('skill_name', s.get('node_type', '')) for s in skill_data],
+ "count": len(skill_data),
+ }
+
+ if tools:
+ result_data["tools"] = {
+ "connected": [t.name for t in tools],
+ "count": len(tools),
+ }
+
return {
"success": True,
"node_id": node_id,
"node_type": "deep_agent",
- "result": {
- "response": response_content,
- "model": model,
- "provider": provider,
- "messages_count": len(messages),
- "finish_reason": "stop",
- "timestamp": datetime.now().isoformat(),
- },
+ "result": result_data,
"execution_time": time.time() - start_time,
}
except Exception as e:
logger.error("[DeepAgent] Execution failed", node_id=node_id, error=str(e))
- log_api_call(logger, provider if 'provider' in dir() else 'unknown',
- model if 'model' in dir() else 'unknown',
- "deep_agent", False, error=str(e))
+ log_api_call(logger, provider, model, "deep_agent", False, error=str(e))
return {
"success": False,
"node_id": node_id,
diff --git a/server/services/handlers/deep_agent.py b/server/services/handlers/deep_agent.py
index 30856e55..e180b63c 100644
--- a/server/services/handlers/deep_agent.py
+++ b/server/services/handlers/deep_agent.py
@@ -1,9 +1,10 @@
"""Deep Agent handler -- thin wrapper following handle_rlm_agent pattern.
-Collects connections, builds tools, delegates to DeepAgentService.
+Collects connections, builds executable tools, delegates to DeepAgentService.
"""
-from typing import Dict, Any, TYPE_CHECKING
+from typing import Any, Dict, TYPE_CHECKING
+from langchain_core.tools import StructuredTool
from core.logging import get_logger
if TYPE_CHECKING:
@@ -13,6 +14,60 @@ if TYPE_CHECKING:
logger = get_logger(__name__)
+def _make_executable_tool(
+ tool: StructuredTool,
+ config: Dict[str, Any],
+ workflow_id: str = None,
+ broadcaster=None,
+) -> StructuredTool:
+ """Wrap a schema-only tool with a real async executor.
+
+ _build_tool_from_node() returns tools with placeholder_func (schema only).
+ deepagents' ToolNode calls tool.ainvoke() directly, so each tool needs
+ a real coroutine. This follows the deepagents pattern:
+ StructuredTool.from_function(coroutine=async_fn, args_schema=...)
+ """
+ tool_name = tool.name
+ tool_node_id = config.get('node_id')
+
+ async def _execute(**kwargs) -> Any:
+ from services.handlers.tools import execute_tool
+
+ if tool_node_id and broadcaster:
+ await broadcaster.update_node_status(
+ tool_node_id, "executing",
+ {"message": f"Executing {tool_name}"},
+ workflow_id=workflow_id,
+ )
+
+ cfg = {**config, 'workflow_id': workflow_id}
+ try:
+ result = await execute_tool(tool_name, kwargs, cfg)
+ if tool_node_id and broadcaster:
+ await broadcaster.update_node_status(
+ tool_node_id, "success",
+ {"message": f"{tool_name} completed"},
+ workflow_id=workflow_id,
+ )
+ return result
+ except Exception as e:
+ logger.error("[Deep Agent] Tool %s failed: %s", tool_name, e)
+ if tool_node_id and broadcaster:
+ await broadcaster.update_node_status(
+ tool_node_id, "error",
+ {"message": str(e)},
+ workflow_id=workflow_id,
+ )
+ return {"error": str(e)}
+
+ return StructuredTool.from_function(
+ name=tool.name,
+ description=tool.description,
+ coroutine=_execute,
+ args_schema=tool.get_input_schema(),
+ )
+
+
async def handle_deep_agent(
node_id: str,
node_type: str,
@@ -25,17 +80,17 @@ async def handle_deep_agent(
Follows handle_rlm_agent pattern:
1. _collect_agent_connections() [REUSE]
- 2. _collect_teammate_connections() [REUSE]
- 3. _format_task_context() [REUSE]
- 4. Tool stripping on task completion [REUSE]
- 5. Auto-prompt fallback [REUSE]
- 6. Build LangChain tools from tool_data [ai_service._build_tool_from_node]
- 7. Delegate to DeepAgentService.execute()
+ 2. _format_task_context() [REUSE]
+ 3. Auto-prompt fallback [REUSE]
+ 4. Build executable tools [_build_tool_from_node + _make_executable_tool]
+ 5. Collect teammates [_collect_teammate_connections]
+ 6. Delegate to DeepAgentService.execute()
"""
from .ai import _collect_agent_connections, _collect_teammate_connections, _format_task_context
from services.status_broadcaster import get_status_broadcaster
workflow_id = context.get('workflow_id')
+ broadcaster = get_status_broadcaster()
# 1. Collect connections
memory_data, skill_data, tool_data, input_data, task_data = await _collect_agent_connections(
@@ -62,14 +117,16 @@ async def handle_deep_agent(
)
parameters = {**parameters, 'prompt': prompt}
- # 4. Build LangChain tools from connected tool nodes
- built_tools = []
+ # 4. Build executable tools from connected tool nodes
+ executable_tools = []
if tool_data:
for tool_info in tool_data:
try:
- tool, _config = await ai_service._build_tool_from_node(tool_info)
- if tool:
- built_tools.append(tool)
+ tool, config = await ai_service._build_tool_from_node(tool_info)
+ if tool and config:
+ executable_tools.append(
+ _make_executable_tool(tool, config, workflow_id, broadcaster)
+ )
except Exception as e:
logger.warning("[Deep Agent] Failed to build tool from %s: %s",
tool_info.get("node_type"), e)
@@ -78,11 +135,11 @@ async def handle_deep_agent(
teammates = await _collect_teammate_connections(node_id, context, database)
# 6. Delegate to DeepAgentService
- broadcaster = get_status_broadcaster()
return await ai_service.deep_agent_service.execute(
node_id, parameters,
+ memory_data=memory_data if memory_data else None,
skill_data=skill_data if skill_data else None,
- tools=built_tools if built_tools else None,
+ tools=executable_tools if executable_tools else None,
teammates=teammates if teammates else None,
broadcaster=broadcaster,
workflow_id=workflow_id,