# create_cli_agent

> **Function** in `deepagents_code`

📖 [View in docs](https://reference.langchain.com/python/deepagents-code/agent/create_cli_agent)

Create a CLI-configured agent with flexible options.

This is the main entry point for creating a Deep Agents Code agent, usable
both internally and from external code (e.g., benchmarking frameworks).

## Signature

```python
create_cli_agent(
    model: str | BaseChatModel,
    assistant_id: str,
    *,
    tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
    mcp_tools: Sequence[BaseTool] | None = None,
    sandbox: SandboxBackendProtocol | None = None,
    sandbox_type: str | None = None,
    system_prompt: str | None = None,
    interactive: bool = True,
    auto_approve: bool = False,
    auto_mode_enabled: bool = False,
    interrupt_shell_only: bool = False,
    shell_allow_list: list[str] | None = None,
    fs_tools: list[FsToolName] | None = None,
    enable_ask_user: bool = True,
    enable_memory: bool = True,
    memory_auto_save: bool = True,
    enable_skills: bool = True,
    enable_shell: bool = True,
    enable_interpreter: bool = False,
    interpreter_config: InterpreterConfig | None = None,
    rubric_model: str | BaseChatModel | None = None,
    rubric_max_iterations: int | None = None,
    auto_classifier_model: str | BaseChatModel | None = None,
    recursion_limit: int | None = None,
    checkpointer: BaseCheckpointSaver | None = None,
    store: BaseStore | None = None,
    mcp_server_info: list[MCPServerInfo] | None = None,
    cwd: str | Path | None = None,
    project_context: ProjectContext | None = None,
    async_subagents: list[AsyncSubAgent] | None = None,
    goal_criteria_tools: Sequence[BaseTool | Callable[..., Any]] | None = None,
    rubric_grader_tools: Sequence[BaseTool | Callable[..., Any]] | None = None,
    model_retries: int = DEFAULT_MODEL_RETRIES,
    cli_max_retries: int | None = None,
    summarization_model: str | None = None,
    enforce_model_policy: bool = True,
    extension_registry: ExtensionRegistry | None = None,
    environ: Mapping[str, str] | None = None,
    credentials_snapshot: CredentialsSnapshot | None = None,
    model_result: ModelResult | None = None,
    profile_overrides: dict[str, object] | None = None,
) -> tuple[Pregel[Any, Any, Any, Any], CompositeBackend]
```

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `model` | `str \| BaseChatModel` | Yes | LLM model to use (e.g., `'provider:model'`) |
| `assistant_id` | `str` | Yes | Agent identifier for memory/state storage |
| `tools` | `Sequence[BaseTool \| Callable \| dict[str, Any]] \| None` | No | Additional tools to provide to agent. (default: `None`) |
| `mcp_tools` | `Sequence[BaseTool] \| None` | No | Exact MCP tools within `tools`, used to extend approval policy from their protocol annotations. (default: `None`) |
| `sandbox` | `SandboxBackendProtocol \| None` | No | Optional sandbox backend for remote execution (e.g., `ModalSandbox`).  If `None`, uses local filesystem + shell. (default: `None`) |
| `sandbox_type` | `str \| None` | No | Type of sandbox provider (`'agentcore'`, `'daytona'`, `'langsmith'`, `'modal'`, `'runloop'`). Used for system prompt generation. (default: `None`) |
| `system_prompt` | `str \| None` | No | Override the default system prompt.  If `None`, a system prompt is auto-generated with dynamic context interpolated in (model identity, working directory, sandbox vs. local execution mode, skills path, and interactive-vs-headless guidance).  !!! warning      Passing a value here replaces that auto-generated prompt     entirely — none of the dynamic context above is added, and     `sandbox_type` and `interactive` no longer influence the     prompt. Only pass an explicit prompt when you intend to take     full ownership of the system prompt's content. (default: `None`) |
| `interactive` | `bool` | No | When `False`, the auto-generated system prompt is tailored for headless non-interactive execution, and every stack gains terminal-stall recovery middleware (a runtime no-op unless the resolved model is Fireworks GLM-5.2). Only the system-prompt tailoring is ignored when `system_prompt` is provided explicitly; the recovery wiring still applies. (default: `True`) |
| `auto_approve` | `bool` | No | If `True`, no tools trigger human-in-the-loop interrupts — all calls (shell execution, file writes/edits, web search, URL fetch) run automatically.  If `False`, tools pause for user confirmation via the approval menu. See `_add_interrupt_on` for the full list of gated tools. (default: `False`) |
| `auto_mode_enabled` | `bool` | No | Install classifier-backed Auto for local TUI or ACP runtimes. Callers must leave this disabled for headless and sandbox-backed graphs. (default: `False`) |
| `interrupt_shell_only` | `bool` | No | If `True`, all HITL interrupts are disabled; shell commands are validated inline by `ShellAllowListMiddleware` against the configured allow-list instead.  Used in non-interactive mode with a restrictive shell allow-list to avoid splitting traces into multiple LangSmith runs.  Has no effect when `auto_approve` is `True` (interrupts are already disabled) or when `shell_allow_list` is `SHELL_ALLOW_ALL`. (default: `False`) |
| `shell_allow_list` | `list[str] \| None` | No | Explicit restrictive shell allow-list forwarded from the CLI process. When provided (and `interrupt_shell_only` is `True`), used directly instead of resolving `shell.allow_list` again in the server subprocess. (default: `None`) |
| `fs_tools` | `list[FsToolName] \| None` | No | Allowlist of filesystem tools to expose to the agent, from `--allow-fs-tools`. `None` (default; also what `--allow-fs-tools all` parses to) leaves `FilesystemMiddleware` at its SDK default (all tools). An explicit list (which must include `"read_file"`) installs a `FilesystemMiddleware` restricted to those tool names, replacing the SDK's default for the main agent and every synchronous subagent (including `general-purpose`) as well as the nested goal-criteria agent, so delegation cannot bypass the restriction. Async subagents are unaffected (they run on their own remote backend, not the local filesystem). (default: `None`) |
| `enable_ask_user` | `bool` | No | Enable `AskUserMiddleware` so the agent can ask clarifying questions.  Non-interactive callers without a resume loop must explicitly pass `enable_ask_user=False`. (default: `True`) |
| `enable_memory` | `bool` | No | Enable `MemoryMiddleware` for persistent memory (default: `True`) |
| `memory_auto_save` | `bool` | No | When `True` (default), the memory prompt tells the agent to proactively persist learnings to the `AGENTS.md` sources.  When `False`, memory is still loaded into context but the read-only prompt is used instead, so the agent does not auto-save; explicit saves (e.g. the `remember` skill) still work.  No effect when `enable_memory` is `False`. (default: `True`) |
| `enable_skills` | `bool` | No | Enable `SkillsMiddleware` for custom agent skills (default: `True`) |
| `enable_shell` | `bool` | No | Enable shell execution via `LocalShellBackend` (only in local mode). When enabled, the `execute` tool is available. (default: `True`) |
| `enable_interpreter` | `bool` | No | Wire `CodeInterpreterMiddleware` from `langchain-quickjs` into the main agent.  Local-mode only — passing a non-`None` `sandbox` while `enable_interpreter=True` raises `ValueError`. Subagents do not receive the interpreter in v1.  PTC (`tools.*` host bridge) calls bypass `interrupt_on`/HITL approval, so `InterpreterConfig.ptc` is the only effective control over which host tools can be invoked from inside the REPL. `js_eval` itself is intentionally not gated by HITL — per-call approval would be unusably noisy and would not block PTC fan-out anyway. The `"safe"` preset is therefore restricted to tools that are already non-HITL outside the REPL (read-only file inspection); exposing HITL-gated tools — network fetch, subagent dispatch, shell, file writes — requires an explicit list or `interpreter_ptc="all"` with `interpreter_ptc_acknowledge_unsafe=True`.  Requires the core `langchain-quickjs` dependency. (default: `False`) |
| `interpreter_config` | `InterpreterConfig \| None` | No | Resolver-backed interpreter settings snapshot.  Direct callers may omit this to resolve one for the current process. The server supplies a snapshot that incorporates its invocation-scoped PTC overrides. (default: `None`) |
| `rubric_model` | `str \| BaseChatModel \| None` | No | Default grader model. `None` makes the grader follow the active main model. Either way a thread's recorded `_rubric_model_spec` selection takes precedence.  A `'provider:model'` string or `BaseChatModel`.  When `None`, the main `model` is reused. (default: `None`) |
| `rubric_max_iterations` | `int \| None` | No | Explicit grader iterations per rubric attempt before the agent terminates with `'max_iterations_reached'`; `None` uses the SDK default. (default: `None`) |
| `auto_classifier_model` | `str \| BaseChatModel \| None` | No | Model the Auto approval classifier reviews with.  A `'provider:model'` string or `BaseChatModel`.  When `None`, `DEEPAGENTS_CODE_AUTO_CLASSIFIER_MODEL` is consulted, then `[models].auto_classifier`, and the main `model` is reused when both are unset. A blank string is *not* the same as `None`: it means "inherit the main model" directly and, unlike `None`, does not consult the env var or `config.toml`. Only meaningful when `auto_mode_enabled` is `True`. (default: `None`) |
| `recursion_limit` | `int \| None` | No | Explicit LangGraph `recursion_limit` (graph step budget) for the main agent. When `None`, it is resolved from runtime configuration. If unset, no `recursion_limit` is bound. (default: `None`) |
| `checkpointer` | `BaseCheckpointSaver \| None` | No | Optional checkpointer for session persistence. When `None`, the graph is compiled without a checkpointer. (default: `None`) |
| `store` | `BaseStore \| None` | No | Optional LangGraph Store for runtime approval state. (default: `None`) |
| `mcp_server_info` | `list[MCPServerInfo] \| None` | No | MCP server metadata to surface in the system prompt. (default: `None`) |
| `cwd` | `str \| Path \| None` | No | Override the working directory for the agent's filesystem backend and system prompt. (default: `None`) |
| `project_context` | `ProjectContext \| None` | No | Explicit project path context for project-sensitive behavior such as project `AGENTS.md` files, skills, subagents, and MCP trust. (default: `None`) |
| `async_subagents` | `list[AsyncSubAgent] \| None` | No | Remote LangGraph deployments to expose as async subagent tools.  Loaded from `[async_subagents]` in `config.toml` or passed directly. (default: `None`) |
| `goal_criteria_tools` | `Sequence[BaseTool \| Callable[..., Any]] \| None` | No | External read-only context tools available to server-side goal criteria generation. `None` disables goal criteria requests. (default: `None`) |
| `rubric_grader_tools` | `Sequence[BaseTool \| Callable[..., Any]] \| None` | No | External read-only context tools available to rubric grading for verifying work completed in MCP-backed or web-accessible systems. (default: `None`) |
| `model_retries` | `int` | No | Model-node retry attempts after the first call. `0` disables retries. Resolved upstream from config/CLI. (default: `DEFAULT_MODEL_RETRIES`) |
| `cli_max_retries` | `int \| None` | No | The `--max-retries` flag value, or `None` when unset. Forwarded to subagent, Auto classifier, and runtime offload models so each one resolves its own provider's configured budget unless the user overrode it globally. (default: `None`) |
| `summarization_model` | `str \| None` | No | Model spec used only for context-compaction summaries.  The model is resolved lazily when compaction first runs. `None` reuses the effective main model. (default: `None`) |
| `enforce_model_policy` | `bool` | No | Check every model string against `models.allowed`. Pass `False` **only** from callers that compile a graph they never invoke (tool enumeration), so a blocked subagent model degrades the listing rather than raising. Any caller that can run the graph must leave this `True`. (default: `True`) |
| `extension_registry` | `ExtensionRegistry \| None` | No | Server-owned Python extension registrations. (default: `None`) |
| `environ` | `Mapping[str, str] \| None` | No | Environment snapshot frozen into local shell execution. (default: `None`) |
| `credentials_snapshot` | `CredentialsSnapshot \| None` | No | Credentials resolved from `environ` for this runtime. (default: `None`) |
| `model_result` | `ModelResult \| None` | No | Workspace model metadata used in the generated prompt. (default: `None`) |
| `profile_overrides` | `dict[str, object] \| None` | No | Session profile fields retained when side questions reconstruct the selected model without a live snapshot. (default: `None`) |

## Returns

`tuple[Pregel[Any, Any, Any, Any], CompositeBackend]`

2-tuple of `(agent_graph, backend)`

- `agent_graph`: Configured LangGraph Pregel instance ready
    for execution
- `composite_backend`: `CompositeBackend` for file operations

---

[View source on GitHub](https://github.com/langchain-ai/deepagents/blob/2069079e09546060f5b52b2cd4f0e3c813e820f3/libs/code/deepagents_code/agent.py#L2524)