Deep Agent
A Deep Agent is an autonomous, goal-driven AI system that goes beyond single-prompt interactions to achieve complex objectives. It takes a high-level goal, breaks it down into smaller tasks, and continuously plans and executes the next best actions.
The agent interacts with external tools such as APIs, databases, and code execution environments to perform real operations. It monitors results, adapts to changing conditions, and dynamically handles failures.
It can maintain memory and state across tasks and may delegate work to specialized sub-agents when required. A Deep Agent acts as an intelligent operational partner that persists until the goal is achieved or a defined stopping point is reached.
Prerequisites
Before setting up the Deep Agent, make sure these are ready:
| Requirement | Details |
|---|---|
| Local Filesystem Sandbox | Must be turned ON to use Skills. |
| Skill Directories | Needed only if Enable Skills is ON. Each folder must include a SKILL.md file with valid YAML front-matter. |
| Downstream Component | A connected node or endpoint that either starts the agent or receives its output. |
Parameter
| Parameter | Description |
|---|---|
| Language Model | The AI model node that provides the agent’s reasoning and decision-making ability. It must support tool calling to enable interaction with external tools. |
| Tools | The tool nodes connected to the agent that define what actions (such as APIs, database queries, or file operations) the agent can perform. |
| Input | The initial message or task given to the agent. It serves as the starting point for the workflow. |
| Agent Instructions | Guidelines that define the agent’s role, behavior, rules, and constraints while performing tasks. |
| Number of Chat History Messages | Specifies how many previous messages are included as context for the agent. Default is 100. |
| Context ID | A unique identifier used to separate and manage different conversation sessions, ensuring the agent uses the correct chat history for each session without mixing contexts. |
| Use Local Filesystem Sandbox |
Enable: Allows the agent to read, write, and execute commands on workspace files.
Disable: Runs only in memory and does not persist any file changes. |
| Workspace Directory | The main folder where the agent can read and write files when the sandbox is enabled. Default is /app/data/deepagent-workspace. |
| Enable AGENTS.md Memory |
Enable: Loads AGENTS.md files as persistent memory for project context (requires sandbox).
Disable: Ignores AGENTS.md files. |
| Memory File Paths | Specifies file locations (comma-separated) of AGENTS.md memory files. Works only when AGENTS.md memory is enabled. |
| Enable Skills |
Enable: Loads predefined skills from configured folders at startup (requires sandbox).
Disable: Skills are not loaded or used. |
| Skills Source Paths | Specifies folder locations where the agent searches for skill files. Multiple paths can be provided, separated by commas. Used only when skills are enabled. |
| Verbose |
Enable: Shows detailed logs of agent steps (planning, tool usage, inputs/outputs).
Disable: Hides detailed logs for normal use. |
| Max Iterations | The maximum number of agent cycles (plan → act → observe). Prevents endless execution. Default is 15 cycles. |
| Recursion Limit | Defines the maximum number of workflow execution steps before stopping to prevent infinite loops. If set to 0, the default limit (typically 1000 steps) is used. |
Output
| Output | Description |
|---|---|
| Response | The final message generated by the agent after completing all its planned steps. It represents the agent’s output that is returned to the user once the task execution is finished. |
Tool Mode
In Tool Mode, the Deep Agent delivers its output using a standardized, slug-based format that uniquely identifies each response within the workflow. Instead of relying on a fixed or predefined response structure, the agent dynamically executes its full plan–act–observe cycle at runtime and returns the result through the appropriate action.
This design ensures that the output is directly aligned with the actions performed by the agent, making it consistent, traceable, and context-aware. As a result, downstream workflow components can reliably consume the output while maintaining accuracy and continuity across the entire process.
Output
| Slug | Description |
|---|---|
| MESSAGE_RESPONSE | Returns the final message produced by the agent after all steps are complete. This is the agent's direct output, passed to the next component in the workflow. |
Best Practices
1. Set Max iterations based on task complexity
For simple tasks, 10–15 iterations are usually sufficient. More complex scenarios, such as open-ended research or multi-step workflows, may require 50 or more iterations. Start with a lower value and increase only if the agent stops before completing the task.
2. Keep Recursion limit at default unless necessary
A value of 0 (defaulting to 1000 steps) works for most workflows. Increase it only when working with deeply nested or multi-agent pipelines that encounter recursion limits.
3. Use Verbose mode only during development
Verbose mode generates detailed logs for debugging, which can impact performance and produce large outputs. Enable it while building or troubleshooting workflows, and disable it in production environments.
4. Organize skill directories with clear scope
Each skill should represent a single, well-defined workflow. Avoid overly broad or generic skills, as they make it harder for the agent to select the appropriate one. Prefer multiple focused skills over a few generalized ones.
5 Validate skill files before enabling them
Ensure all SKILL.md files are correctly formatted and include valid YAML front matter. Improperly structured files may fail to load without visible errors, leading to missing functionality.
6. Use absolute paths for Skills source paths
Always provide full (absolute) paths to avoid resolution issues. Relative paths can behave inconsistently depending on the execution environment, especially in containerized or server-based deployments.
