DEV Community: Syeed Talha

Agent-Scoped Memory in Deep Agents: Sharing Memory Across Conversations

Syeed Talha — Tue, 18 Aug 2026 12:15:47 +0000

In the previous article, we looked at user-scoped memory, where each user gets their own private long-term memory.

But there is another useful pattern:

Agent-scoped memory.

Instead of giving every user a separate memory, we can give one shared memory to an entire agent.

This is useful when the memory represents something about the agent itself rather than about a specific user.

What is agent-scoped memory?

Agent-scoped memory means that all conversations using the same agent can access the same long-term memory.

For example, imagine you build a coding assistant.

The agent has a memory file containing:

Response style:
- Keep responses concise.
- Use code examples where possible.

A user in one conversation tells the agent:

"Remember that I prefer detailed explanations."

The agent saves that preference.

Later, another conversation starts with a completely different thread.

Because the memory belongs to the agent, not the conversation, the second conversation can read the updated memory.

Conceptually:

                    Coding Agent
                         |
                 Shared Agent Memory
                         |
          +--------------+--------------+
          |              |              |
       Thread 1       Thread 2       Thread 3

All three threads can access the same long-term memory.

Why do we need agent-scoped memory?

Without agent-scoped memory, information saved in one conversation may remain limited to that conversation.

For example:

Thread 1
User: Remember that the project uses PostgreSQL.
Agent: Saved.

Thread 2
User: What database does this project use?
Agent: I don't know.

That is not very useful for an agent that should learn information about a project.

With agent-scoped memory:

Thread 1
      |
      v
Agent Memory
      ^
      |
Thread 2

Thread 2 can access what Thread 1 saved.

This is particularly useful for information that should be shared across conversations, such as:

Project instructions
Coding conventions
Team preferences
Agent response style
Shared workflows
Project-specific knowledge

Agent-scoped vs user-scoped memory

This distinction is important.

User-scoped memory

Memory belongs to a particular user.

Agent
 |
 +-- Alice -> Alice's memory
 |
 +-- Bob   -> Bob's memory

For example:

Alice prefers Python.

Bob should not automatically inherit that preference.

Agent-scoped memory

Memory belongs to the agent.

Agent
 |
 +-- Shared memory
       |
       +-- Thread 1
       +-- Thread 2
       +-- Thread 3

For example:

This agent should always provide concise answers.

Every conversation using that agent can use this information.

How does Deep Agents implement it?

The key difference is surprisingly small.

Instead of using the current user's ID as the namespace:

namespace=lambda runtime: (
    runtime.context.user_id,
)

we use a fixed agent ID:

namespace=lambda _runtime: (AGENT_ID,)

For example:

AGENT_ID = "memory-demo-agent"

The resulting store looks conceptually like this:

InMemoryStore
│
└── ("memory-demo-agent",)
    └── /AGENTS.md

Every thread using this agent accesses that same namespace.

The thread ID still matters for conversation state, but it does not create a separate long-term memory namespace.

So:

Thread 1 ─┐
Thread 2 ─┼──> ("memory-demo-agent",) ──> AGENTS.md
Thread 3 ─┘

This is the core idea behind agent-scoped memory.

A simple example

Suppose the agent starts with:

## Response style
- Keep responses concise.
- Use code examples where possible.

Thread 1 tells it:

"Remember that I prefer detailed explanations."

The agent updates AGENTS.md.

Now Thread 2 asks:

"Explain how transformers work."

The agent reads the same memory and can apply the newly saved preference.

Notice something important:

Thread 1 and Thread 2 are different conversations.

They have different thread IDs:

"agent-memory-thread-1"
"agent-memory-thread-2"

But they share:

("memory-demo-agent",)

Therefore, they share the same long-term memory.

When should you use agent-scoped memory?

A simple rule is:

If the memory describes the agent, project, or shared environment, agent-scoped memory may be appropriate.

For example:

Good candidates:

"This project uses PostgreSQL."
"Always use FastAPI for the backend."
"Keep responses concise."
"The project uses Python 3.12."

But be careful with user-specific information.

If Alice says:

"My favorite programming language is Python."

That probably belongs in Alice's user-scoped memory, not the shared agent memory.

Otherwise, Bob could inherit Alice's preference.

One important limitation

The example below uses:

InMemoryStore()

This is useful for learning and testing, but the store is process-local.

If you stop the application and start it again, the memory will be gone.

For a real application, you would normally use a persistent LangGraph/LangSmith store so the agent's long-term memory survives process restarts.

Try it yourself

The following example demonstrates the complete idea.

It creates one agent with shared memory.

Thread 1 saves a new preference:

"I prefer detailed explanations."

Then Thread 2 starts a separate conversation and reads the same agent memory.

Run it with:

uv run agent_scoped_memory.py

Make sure NVIDIA_API_KEY is available in your environment or .env file.

import os

from dotenv import load_dotenv
from langchain_nvidia_ai_endpoints import ChatNVIDIA
from langgraph.store.memory import InMemoryStore
from requests.exceptions import Timeout

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from deepagents.backends.utils import create_file_data


AGENT_ID = "memory-demo-agent"
MEMORY_PATH = "/memories/AGENTS.md"
STORE_MEMORY_PATH = "/AGENTS.md"


def build_model():
    """Create the chat model used by the demo."""
    if not os.getenv("NVIDIA_API_KEY"):
        raise RuntimeError(
            "Set NVIDIA_API_KEY in the environment or a .env file before "
            "running this example."
        )

    model_name = os.getenv(
        "NVIDIA_MODEL",
        "nvidia:nvidia/nemotron-3-ultra-550b-a55b",
    ).removeprefix("nvidia:")

    timeout_seconds = int(os.getenv("NVIDIA_TIMEOUT_SECONDS", "180"))
    max_completion_tokens = int(
        os.getenv("NVIDIA_MAX_COMPLETION_TOKENS", "1024")
    )

    return ChatNVIDIA(
        model=model_name,
        timeout=timeout_seconds,
        max_completion_tokens=max_completion_tokens,
        model_kwargs={"parallel_tool_calls": False},
    )


def seed_memory(store: InMemoryStore) -> None:
    """Create the shared memory file for this agent."""
    store.put(
        (AGENT_ID,),
        STORE_MEMORY_PATH,
        create_file_data(
            """## Response style
- Keep responses concise.
- Use code examples where possible.
"""
        ),
    )


def build_backend(store: InMemoryStore) -> CompositeBackend:
    """Route long-term memory to the namespace shared by this agent."""
    return CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                store=store,
                namespace=lambda _runtime: (AGENT_ID,),
            ),
        },
    )


def build_agent(store: InMemoryStore):
    return create_deep_agent(
        model=build_model(),
        memory=[MEMORY_PATH],
        backend=build_backend(store),
        store=store,
        name=AGENT_ID,
    )


def invoke(agent, thread_id: str, prompt: str) -> str:
    result = agent.invoke(
        {"messages": [{"role": "user", "content": prompt}]},
        config={"configurable": {"thread_id": thread_id}},
    )

    return result["messages"][-1].content


def main() -> None:
    load_dotenv()

    store = InMemoryStore()
    seed_memory(store)
    agent = build_agent(store)

    print("Thread 1: save a new preference")

    try:
        print(
            invoke(
                agent,
                "agent-memory-thread-1",
                "Remember that I prefer detailed explanations. Update "
                f"{MEMORY_PATH} with this preference, then confirm what you saved.",
            )
        )
    except Timeout:
        print(
            "The NVIDIA model timed out. Try "
            "NVIDIA_MODEL=meta/llama-3.2-3b-instruct "
            "or increase NVIDIA_TIMEOUT_SECONDS."
        )

    print("\nThread 2: read the same agent memory")

    try:
        print(
            invoke(
                agent,
                "agent-memory-thread-2",
                "Explain how transformers work. Apply the response preferences "
                f"stored in {MEMORY_PATH}, and begin by naming the preference "
                "you found.",
            )
        )
    except Timeout:
        print(
            "The NVIDIA model timed out. Try "
            "NVIDIA_MODEL=meta/llama-3.2-3b-instruct "
            "or increase NVIDIA_TIMEOUT_SECONDS."
        )


if __name__ == "__main__":
    main()

The key idea

The easiest way to remember the difference is:

User-scoped memory
        ↓
Memory belongs to the USER

Agent-scoped memory
        ↓
Memory belongs to the AGENT

So if you are building a multi-user application, ask yourself:

"Should this information follow the user, or should it be shared by everyone using this agent?"

If it follows the user, use user-scoped memory.

If it belongs to the shared agent or project, agent-scoped memory can be the better choice.

That small namespace decision determines who can see and use the long-term memory.

User-Scoped Memory in Deep Agents: What It Is and Why You Need It

Syeed Talha — Tue, 18 Aug 2026 10:50:59 +0000

Imagine you build one AI agent and 1,000 people use it.

Alice tells the agent:

"I prefer Python examples and concise answers."

Later, Bob asks:

"How do I read a CSV file?"

Bob should not suddenly receive a short Python-focused answer just because Alice used the agent before.

This is exactly the problem user-scoped memory solves.

What is user-scoped memory?

User-scoped memory means giving each user their own separate long-term memory.

The same agent can be shared by many users, but the memory belonging to one user is isolated from everyone else.

For example:

                    One AI Agent
                         |
          +--------------+--------------+
          |              |              |
       Alice            Bob          Charlie
          |              |              |
     Alice's memory  Bob's memory  Charlie's memory

Alice might have:

- Likes concise answers
- Prefers Python

Bob might have:

- Likes detailed explanations
- Prefers TypeScript

When Alice talks to the agent, the agent reads Alice's memory. When Bob talks to it, the agent reads Bob's memory.

Deep Agents implements this using a namespace. The namespace can be based on the user's ID, such as:

namespace=lambda current_runtime: (
    current_runtime.context.user_id,
)

This makes the user's ID the boundary between their memories. LangChain's documentation describes the same concept as user-scoped memory: each user gets an isolated copy of the memory files.

Why do we need it?

Without user-scoped memory, you can accidentally create shared memory.

Suppose your application has:

User A -> Agent -> preferences.md
User B -> Agent -> preferences.md

If both users access the same memory namespace, the agent could potentially read information written by the other user.

That can cause several problems.

1. Preferences can leak between users

Alice says:

"Always give me Python examples."

Bob could later receive Python examples even though he prefers TypeScript.

2. Private information can be exposed

A memory file might contain information about a user's previous interactions, preferences, or other personal context.

If that memory is shared, one user's information could become available to another user.

3. The agent's behavior becomes unpredictable

Imagine 100 users are constantly teaching the same agent different preferences:

User A: Be concise.
User B: Give detailed explanations.
User C: Use Python.
User D: Use TypeScript.

If all of this goes into one shared memory, the agent has no reliable way to know whose preference it should follow.

User-scoped memory vs conversation memory

There is an important distinction.

Short-term memory is generally associated with a conversation/thread. It helps the agent remember what is happening in the current conversation.

Long-term memory survives across conversations.

User-scoped long-term memory adds another layer:

Conversation 1 ─┐
Conversation 2 ─┼──> Alice's long-term memory
Conversation 3 ─┘

So Alice can start a completely new conversation and the agent can still know her saved preferences.

Deep Agents uses memory files for long-term memory and a backend/store to control where those files are stored.

How does Deep Agents implement it?

There are three important pieces in the example.

1. Memory path

MEMORY_PATH = "/memories/preferences.md"

This tells the agent which memory file it should use.

2. User ID

Our application provides:

@dataclass(frozen=True)
class UserContext:
    user_id: str

For example:

user-alice
user-bob

3. Namespace

The important part is:

namespace=lambda current_runtime: (
    current_runtime.context.user_id,
)

This means:

user-alice -> namespace ("user-alice",)
user-bob   -> namespace ("user-bob",)

The same /preferences.md path can therefore exist independently for both users.

Conceptually:

Store
│
├── ("user-alice",)
│   └── /preferences.md
│
└── ("user-bob",)
    └── /preferences.md

The file has the same name, but it belongs to a different namespace.

LangChain recommends user scope when memory should belong to individual users, and specifically notes that user A's preferences should not leak into user B's conversations.

One important security rule

A good default is:

If memory does not need to be shared, make it user-scoped.

Shared memory should be used deliberately. LangChain's documentation also warns that allowing one user to write memory that another user can read can create security problems, including malicious instructions being inserted into shared state.

For shared organizational policies, read-only memory is often more appropriate.

Try it yourself

The following example creates two users:

Alice prefers concise Python answers.
Bob prefers detailed TypeScript answers.

Both use the same agent, but their memories are isolated.

Install the required packages and set your NVIDIA_API_KEY, then save the code as user_scoped_memory.py and run:

uv run user_scoped_memory.py

The example uses NVIDIA's model through ChatNVIDIA, while the memory isolation itself is handled by Deep Agents and InMemoryStore.

"""Runnable user-scoped long-term memory example.

Run with ``uv run user_scoped_memory.py`` after setting ``NVIDIA_API_KEY`` in
the environment or in a ``.env`` file.

Each invocation supplies a user ID through the graph context. The backend uses
that ID as the store namespace, so users can share one agent without sharing
their preference files.
"""

import os
from dataclasses import dataclass

from dotenv import load_dotenv
from langchain_nvidia_ai_endpoints import ChatNVIDIA
from langgraph.store.memory import InMemoryStore
from requests.exceptions import Timeout

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from deepagents.backends.utils import create_file_data


MEMORY_PATH = "/memories/preferences.md"
STORE_MEMORY_PATH = "/preferences.md"


@dataclass(frozen=True)
class UserContext:
    user_id: str


def build_model():
    """Create the chat model used by the demo."""
    if not os.getenv("NVIDIA_API_KEY"):
        raise RuntimeError(
            "Set NVIDIA_API_KEY in the environment or a .env file before "
            "running this example."
        )

    model_name = os.getenv(
        "NVIDIA_MODEL",
        "nvidia:nvidia/nemotron-3-ultra-550b-a55b",
    ).removeprefix("nvidia:")

    timeout_seconds = int(
        os.getenv("NVIDIA_TIMEOUT_SECONDS", "180")
    )

    max_completion_tokens = int(
        os.getenv("NVIDIA_MAX_COMPLETION_TOKENS", "1024")
    )

    return ChatNVIDIA(
        model=model_name,
        timeout=timeout_seconds,
        max_completion_tokens=max_completion_tokens,
        model_kwargs={"parallel_tool_calls": False},
    )


def seed_memory(store: InMemoryStore) -> None:
    """Create an isolated preference file for each demo user."""
    preferences = {
        "user-alice": """## Preferences
- Likes concise bullet points.
- Prefers Python examples.
""",
        "user-bob": """## Preferences
- Likes detailed explanations.
- Prefers TypeScript examples.
""",
    }

    for user_id, content in preferences.items():
        store.put(
            (user_id,),
            STORE_MEMORY_PATH,
            create_file_data(content),
        )


def build_backend(store: InMemoryStore) -> CompositeBackend:
    """Route memory to the namespace belonging to the current user."""
    return CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                store=store,
                namespace=lambda current_runtime: (
                    current_runtime.context.user_id,
                ),
            ),
        },
    )


def build_agent(store: InMemoryStore):
    return create_deep_agent(
        model=build_model(),
        memory=[MEMORY_PATH],
        backend=build_backend(store),
        context_schema=UserContext,
        store=store,
        name="user-scoped-memory-demo",
    )


def invoke_for_user(
    agent,
    user_id: str,
    thread_id: str,
    prompt: str,
) -> str:
    result = agent.invoke(
        {"messages": [{"role": "user", "content": prompt}]},
        config={"configurable": {"thread_id": thread_id}},
        context=UserContext(user_id=user_id),
    )

    return result["messages"][-1].content


def main() -> None:
    load_dotenv()

    store = InMemoryStore()
    seed_memory(store)
    agent = build_agent(store)

    prompt = (
        "How do I read a CSV file? Use only the preferences stored in "
        f"{MEMORY_PATH}. State which language and response style you used."
    )

    print("Alice's isolated memory")

    try:
        print(
            invoke_for_user(
                agent,
                user_id="user-alice",
                thread_id="alice-memory-thread",
                prompt=prompt,
            )
        )
    except Timeout:
        print(
            "The NVIDIA model timed out. The memory store is configured "
            "correctly; try NVIDIA_MODEL=meta/llama-3.2-3b-instruct or "
            "increase NVIDIA_TIMEOUT_SECONDS."
        )

    print("\nBob's isolated memory")

    try:
        print(
            invoke_for_user(
                agent,
                user_id="user-bob",
                thread_id="bob-memory-thread",
                prompt=prompt,
            )
        )
    except Timeout:
        print(
            "The NVIDIA model timed out. The memory store is configured "
            "correctly; try NVIDIA_MODEL=meta/llama-3.2-3b-instruct or "
            "increase NVIDIA_TIMEOUT_SECONDS."
        )


if __name__ == "__main__":
    main()

The key idea to remember

You do not need a separate agent for every user.

You can have:

One Agent
   |
   +-- User ID A -> Memory A
   |
   +-- User ID B -> Memory B
   |
   +-- User ID C -> Memory C

The user ID becomes the memory boundary.

That is the core idea behind user-scoped memory in Deep Agents.

For production applications, InMemoryStore is only suitable for a simple demonstration. Deep Agents' documentation notes that a persistent/platform store should be used when deploying rather than relying on an in-memory store.

For the complete and current implementation details, see LangChain Deep Agents Memory documentation.

Understanding RubricMiddleware in Deep Agents

Syeed Talha — Mon, 17 Aug 2026 11:23:12 +0000

When we build an AI agent, we usually expect it to complete a task and return the result.

The workflow looks simple:

User
  ↓
Agent
  ↓
Output
  ↓
Done

But there is one important question:

How does the agent know whether its output is actually good enough?

This is where RubricMiddleware in Deep Agents becomes useful.

What is a Rubric?

A rubric is simply a set of criteria that defines what a good result should contain.

For example, if we ask an agent to write a research report, our rubric could be:

- Include an introduction
- Discuss existing research
- Include citations
- Identify research gaps
- Provide a clear conclusion

The agent generates the report, and another model checks whether these requirements were satisfied.

How does RubricMiddleware work?

The basic workflow looks like this:

                 ┌─────────────────┐
                 │     Agent       │
                 └────────┬────────┘
                          ↓
                       Output
                          ↓
                 ┌─────────────────┐
                 │  Grader Agent   │
                 │   (LLM Judge)   │
                 └────────┬────────┘
                          ↓
                    Check rubric
                          ↓
              ┌───────────┴───────────┐
              ↓                       ↓
        Everything OK            Something wrong
              ↓                       ↓
         SATISFIED              NEEDS_REVISION
                                      ↓
                                Feedback injected
                                      ↓
                                   Agent
                                      ↓
                                  New output
                                      ↓
                                   Grader

So instead of simply:

Agent → Output → Done

we now have:

Agent → Output → Check → Fix → Check → Done

This is the main idea behind RubricMiddleware.

Worker Agent vs Grader Agent

One important thing to understand is that there are effectively two roles.

1. Agent

The main agent performs the actual task.

For example:

"Research sensor-based tree disease detection and write a report."

The agent searches for information, reads papers, analyzes them, and creates the report.

2. Grader

The grader doesn't primarily perform the original task.

Instead, it asks:

"Does the result satisfy the requirements?"

For example:

Rubric:

✓ Did the report discuss existing research?
✓ Did it include enough papers?
✓ Are claims supported by citations?
✓ Did it identify research gaps?
✓ Is the conclusion clear?

If everything passes:

SATISFIED

If something is missing:

NEEDS_REVISION

The feedback is then sent back to the agent so it can improve the result.

A Simple Example

Imagine asking an agent:

"Write a Python function to check whether a number is prime."

Our rubric could be:

1. Handle numbers smaller than 2.
2. Correctly identify prime numbers.
3. Correctly identify non-prime numbers.
4. Avoid unnecessary iterations.

The agent might initially create a working function, but use an inefficient loop.

The grader checks the rubric:

1. PASS
2. PASS
3. PASS
4. FAIL

So instead of accepting the result, the system sends feedback:

The function works correctly, but the implementation
should avoid checking every number up to n.

The agent revises the code and the grader checks it again.

If everything passes:

PASS
   ↓
SATISFIED
   ↓
Final result

Why is this useful?

Without a rubric, an agent can confidently produce an incomplete or incorrect result.

RubricMiddleware adds a quality-control loop around the agent.

It is especially useful when the task has clear requirements, such as:

Research reports
Coding tasks
Document generation
Data analysis
Structured outputs
Complex multi-step tasks

You can also configure a maximum number of iterations so the agent doesn't keep revising forever.

Rubric vs System Prompt

These two concepts are easy to confuse.

A system prompt tells the agent how it should behave.

You are a senior Python developer.
Write clean and maintainable code.

A rubric defines how the final result should be evaluated.

- Tests must pass
- No hardcoded secrets
- Code must use type hints
- No unnecessary dependencies

In simple terms:

System Prompt
     ↓
How should the agent behave?

Rubric
     ↓
Is the final result good enough?

The Main Idea

The easiest way to remember RubricMiddleware is:

             DO
              ↓
            CHECK
              ↓
        ┌─────┴─────┐
        ↓           ↓
      PASS         FAIL
        ↓           ↓
      DONE         FIX
                    ↓
                  CHECK

It essentially turns an AI agent into a generate → evaluate → revise system.

That is the main idea of RubricMiddleware in Deep Agents.

A runnable code example:

"""A small, runnable introduction to Deep Agents grading rubrics.

This example demonstrates the complete rubric loop from the documentation:

1. The deep agent receives a normal user request and writes an answer.
2. A separate grader model checks that answer against ``RUBRIC``.
3. The grader can call ``run_test_suite`` to collect objective evidence.
4. If a criterion fails, the feedback is sent back to the deep agent.
5. The loop ends when the answer is satisfied or ``max_iterations`` is reached.

The agent is asked to write a ``find_duplicates`` function. The rubric is
passed at invocation time because it describes what must be true for this
particular request. The middleware is configured once and can be reused for
other invocations with different rubrics.

Run this example with:

    uv run rubric_example.py

It requires a provider API key in the environment or in a ``.env`` file. This
project already uses NVIDIA models, so NVIDIA is the default provider. The
NVIDIA endpoint used here supports one tool call per response, so the example
explicitly disables parallel tool calls. You can override the model names with
``DEEP_AGENT_MODEL`` and ``RUBRIC_MODEL``.

Important: ``run_test_suite`` executes generated Python in the current
process. That is useful for learning, but unsafe for untrusted code. In a
real application, run generated code in an isolated sandbox.

Documentation:
https://docs.langchain.com/oss/python/deepagents/rubric
"""

import os
from typing import Any

from dotenv import load_dotenv
from langchain.chat_models import init_chat_model
from langchain.tools import tool
from langgraph.checkpoint.memory import InMemorySaver

from deepagents import RubricMiddleware, create_deep_agent
from deepagents.middleware.rubric import RubricEvaluation


load_dotenv()

AGENT_MODEL = os.getenv(
    "DEEP_AGENT_MODEL",
    "nvidia:meta/llama-3.1-8b-instruct",
)
GRADER_MODEL = os.getenv("RUBRIC_MODEL", AGENT_MODEL)


def initialize_model(model_name: str):
    """Create a model, disabling parallel tools for NVIDIA endpoints."""
    model_kwargs = (
        {"parallel_tool_calls": False}
        if model_name.startswith("nvidia:")
        else None
    )
    return init_chat_model(model_name, model_kwargs=model_kwargs)


@tool
def run_test_suite(code: str) -> dict[str, Any]:
    """Run focused tests against the generated find_duplicates source code."""
    namespace: dict[str, Any] = {"__builtins__": __builtins__}

    try:
        exec(code, namespace)
    except Exception as exc:
        return {
            "ok": False,
            "failures": [f"The generated source could not be executed: {exc}"],
        }

    find_duplicates = namespace.get("find_duplicates")
    if find_duplicates is None or not callable(find_duplicates):
        return {
            "ok": False,
            "failures": ["A callable function named find_duplicates is required"],
        }

    tests = [
        ("basic duplicates", [1, 2, 2, 3, 1], [2, 1]),
        ("empty input", [], []),
        ("no duplicates", [1, 2, 3], []),
        ("unhashable values", [[1], [1], 2], [[1]]),
    ]
    failures: list[str] = []

    for test_name, values, expected in tests:
        try:
            actual = find_duplicates(values)
        except Exception as exc:
            failures.append(f"{test_name}: raised {exc!r}")
            continue

        if actual != expected:
            failures.append(
                f"{test_name}: expected {expected!r}, got {actual!r}"
            )

    return {"ok": not failures, "failures": failures}


def print_evaluation(evaluation: RubricEvaluation) -> None:
    """Display the grader's verdict after each pass through the loop."""
    iteration = evaluation["iteration"] + 1
    print(f"\nGrader pass {iteration}: {evaluation['result']}")
    print(f"Explanation: {evaluation['explanation']}")

    for criterion in evaluation["criteria"]:
        status = "PASS" if criterion["passed"] else "FAIL"
        detail = criterion.get("gap", "")
        suffix = f" - {detail}" if detail else ""
        print(f"  [{status}] {criterion['name']}{suffix}")


def build_agent():
    """Build an agent whose output is checked by an LLM-as-a-judge loop."""
    agent_model = initialize_model(AGENT_MODEL)
    grader_model = initialize_model(GRADER_MODEL)

    rubric_middleware = RubricMiddleware(
        model=grader_model,
        system_prompt=(
            "You are a careful code reviewer. You MUST call run_test_suite on "
            "the final generated source before deciding the verdict. Treat "
            "its ok and failures fields as authoritative evidence for the "
            "test criterion; do not infer that tests pass without running it. "
            "Give specific feedback for every failed criterion."
        ),
        tools=[run_test_suite],
        max_iterations=5,
        on_evaluation=print_evaluation,
    )

    return create_deep_agent(
        model=agent_model,
        system_prompt=(
            "You are a careful Python engineer. Return only readable Python "
            "source code, with a function named find_duplicates. Follow the "
            "user's requirements exactly."
        ),
        middleware=[rubric_middleware],
        checkpointer=InMemorySaver(),
    )


def main() -> None:
    agent = build_agent()

    user_request = (
        "Write a Python function named find_duplicates(values) that returns "
        "every value appearing more than once. Preserve the order in which "
        "duplicates first appear, include each duplicate once, and support "
        "unhashable values such as lists. Return only the Python source code."
    )
    rubric = (
        "- run_test_suite reports ok=True for every test\n"
        "- The function is named find_duplicates and accepts one list argument\n"
        "- Duplicate values appear once and in first-duplicate order\n"
        "- The implementation supports unhashable values such as lists"
    )

    result = agent.invoke(
        {
            "messages": [{"role": "user", "content": user_request}],
            "rubric": rubric,
        },
        config={"configurable": {"thread_id": "rubric-learning-example"}},
    )

    print("\nFinal agent answer")
    print("=" * 60)
    print(result["messages"][-1].content)


if __name__ == "__main__":
    main()

output

Grader pass 1: satisfied
Explanation: The provided code meets all the criteria in the rubric.
  [PASS] run_test_suite reports ok=True for every test
  [PASS] The function is named find_duplicates and accepts one list argument
  [PASS] Duplicate values appear once and in first-duplicate order
  [PASS] The implementation supports unhashable values such as lists

Final agent answer
============================================================
This code defines a function `find_duplicates` that takes an iterable of values as input and returns a list of values that appear more than once in the input. The function uses an `OrderedDict` to keep track of the order in which each value first appears, and a `set` to keep track of the values that have appeared more than once. It iterates over the input values, and for each value, it checks if it has been seen before. If it has, it adds the value to the set of duplicates. Finally, it returns the list of duplicates. The function is written in Python and is saved to a file named `duplicates.py` in the current directory.

For the official implementation details and configuration options, see the Deep Agents Rubric documentation.

How to Run LangChain Deep Agents Skills Safely Inside a Daytona Sandbox

Syeed Talha — Thu, 13 Aug 2026 08:04:46 +0000

Deep Agents skills aren't just prompts. They can ship real code — a script the agent runs, not just reads.

That raises one question: where does that code actually execute?

I built a small arxiv-search skill to answer this. The agent reads instructions, runs a bundled Python script to search arXiv, saves the raw JSON as an artifact, validates it, and summarizes the papers — all while the script itself runs inside an isolated Daytona sandbox instead of your machine.

This post walks through the setup, then gives you the full, runnable code.

The core idea, in one picture

Skills and sandboxes are two different worlds:

The skill store — durable, inspectable, easy to version. Good for storing files.
The sandbox — isolated, disposable, safe to execute untrusted code in. Good for running files.

An agent reading SKILL.md from the store does not mean the sandbox has a copy of search.py. Something has to physically move the file across that boundary before it can run. That "something" is a middleware hook.

StoreBackend (durable)                     Daytona sandbox (disposable)
------------------------                   ----------------------------
/skills/arxiv-search/SKILL.md        ->    /home/daytona/skills/arxiv-search/SKILL.md
/skills/arxiv-search/scripts/search.py ->  /home/daytona/skills/arxiv-search/scripts/search.py

That's the whole architecture. Everything below is just implementation detail.

Folder structure

project-root/
├── sandbox_skill_scripts.py        # agent, store, sandbox, middleware
└── skills/
    └── arxiv-search/
        ├── SKILL.md                 # when + how to use the skill
        └── scripts/
            └── search.py            # the actual arXiv API call

At startup, the agent only sees the skill's name and description (progressive disclosure). It reads the full SKILL.md only once a request matches. It touches search.py only when the instructions tell it to run it.

How a request flows end to end

1. Agent sees "arxiv-search" name + description.
2. User's request matches → agent reads SKILL.md.
3. before_agent middleware uploads SKILL.md + search.py from the store → Daytona.
4. Agent runs search.py inside the sandbox.
5. search.py hits the arXiv API, prints JSON.
6. Agent saves + validates that exact JSON as an artifact.
7. Agent summarizes the papers for the user.
8. after_agent middleware downloads the JSON artifact back out of the sandbox.
9. Sandbox is deleted. Always — even on failure.

Step 9 matters more than it looks. A sandbox is temporary infrastructure; the finally block in the script guarantees cleanup even if the model call blows up.

Why bother with a sandbox at all?

Not just security. It's a predictable execution environment: temp files, dependencies, CLI tools, validation — all without treating your laptop as the agent's workspace. In production, that boundary is what lets you:

keep shared skills read-only,
require review before a skill script changes,
persist artifacts outside an ephemeral sandbox,
inspect a failure without exposing your host filesystem.

Sandboxing doesn't make an unsafe script safe on its own — treat every skill script like application code: review it, restrict its permissions, validate its inputs.

Run it yourself

Set credentials in .env:

DAYTONA_API_KEY=...
NVIDIA_API_KEY=...

Optional:

NVIDIA_MODEL=meta/llama-3.1-8b-instruct
NVIDIA_TIMEOUT_SECONDS=180

Then, from the project root:

uv run python sandbox_skill_scripts.py

It prints the agent's response, previews the JSON artifact copied back from the sandbox, and tears the sandbox down.

The full code

Copy these three files into the structure shown above and you're ready to run.

`skills/arxiv-search/SKILL.md`

---
name: arxiv-search
description: Search the arXiv preprint repository for research papers. Use when the user asks about academic papers, recent research, or scientific literature.
---

# arxiv-search

Search arXiv papers by following these steps:

1. Run `python /home/daytona/skills/arxiv-search/scripts/search.py "<query>" --max-results 3` in the Daytona sandbox.
2. Parse the JSON output and present each paper's title, authors, abstract summary, and link.
3. If the user asks for more detail about a paper, run the script again with a more specific query.

`skills/arxiv-search/scripts/search.py`

import argparse
import json
import sys
import xml.etree.ElementTree as ET
from urllib.parse import urlencode
from urllib.request import Request, urlopen


ATOM = "{http://www.w3.org/2005/Atom}"


def search_arxiv(query: str, max_results: int) -> dict:
    params = urlencode(
        {
            "search_query": f"all:{query}",
            "start": 0,
            "max_results": max_results,
        }
    )
    request = Request(
        f"https://export.arxiv.org/api/query?{params}",
        headers={"User-Agent": "deepagents-sandbox-skill-example/1.0"},
    )

    with urlopen(request, timeout=30) as response:
        root = ET.fromstring(response.read())

    papers = []
    for entry in root.findall(f"{ATOM}entry"):
        authors = [
            author.findtext(f"{ATOM}name", default="")
            for author in entry.findall(f"{ATOM}author")
        ]
        alternate_link = next(
            (
                link.get("href", "")
                for link in entry.findall(f"{ATOM}link")
                if link.get("rel") == "alternate"
            ),
            "",
        )
        papers.append(
            {
                "title": " ".join(
                    (entry.findtext(f"{ATOM}title") or "").split()
                ),
                "authors": authors,
                "abstract": " ".join(
                    (entry.findtext(f"{ATOM}summary") or "").split()
                ),
                "link": alternate_link,
                "published": entry.findtext(f"{ATOM}published", default=""),
            }
        )

    return {"query": query, "results": papers}


def main() -> int:
    parser = argparse.ArgumentParser(description="Search arXiv papers")
    parser.add_argument("query")
    parser.add_argument("--max-results", type=int, default=3)
    args = parser.parse_args()

    if not 1 <= args.max_results <= 10:
        parser.error("--max-results must be between 1 and 10")

    try:
        result = search_arxiv(args.query, args.max_results)
    except Exception as error:
        print(f"arXiv request failed: {error}", file=sys.stderr)
        return 1

    print(json.dumps(result, indent=2, ensure_ascii=True))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

`sandbox_skill_scripts.py`

"""Run a skill script inside an isolated Daytona sandbox.

The skill package lives in the sibling ``skills/arxiv-search/`` directory.
The runner loads that directory into an InMemoryStore. The agent can read the
files through StoreBackend, but the script can execute only after the
middleware uploads both files into the sandbox. The after-agent hook copies
the optional JSON result back into the store.

Prerequisites:
    DAYTONA_API_KEY in .env for the managed sandbox
    NVIDIA_API_KEY in .env for the default model

Run from the repository root:
    uv run python sandbox_skill_scripts.py
"""

import json
import os
from pathlib import Path, PurePosixPath

from daytona import Daytona
from dotenv import load_dotenv
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StoreBackend
from deepagents.backends.utils import create_file_data
from langchain.agents.middleware import AgentMiddleware, ModelResponse
from langchain_core.messages import AIMessage
from langchain_nvidia_ai_endpoints import ChatNVIDIA
from langchain_daytona import DaytonaSandbox
from langgraph.store.memory import InMemoryStore
from requests.exceptions import ReadTimeout


SKILL_NAMESPACE = ("skills", "builtin")
ARTIFACT_NAMESPACE = ("artifacts", "sandbox-skill-demo")
SKILL_ROUTE = "/skills/"
ARTIFACT_PATH = "/outputs/arxiv-results.json"
SANDBOX_WORK_DIR = "/home/daytona"
SANDBOX_SKILLS_DIR = f"{SANDBOX_WORK_DIR}/skills"
SANDBOX_ARTIFACT_PATH = f"{SANDBOX_WORK_DIR}/outputs/arxiv-results.json"
SKILLS_DIR = Path(__file__).resolve().parent / "skills"


def seed_skill_store(
    store: InMemoryStore,
    skills_dir: Path = SKILLS_DIR,
) -> None:
    """Load an on-disk skill directory into the StoreBackend namespace."""
    if not skills_dir.is_dir():
        raise FileNotFoundError(f"Skills directory not found: {skills_dir}")

    for file_path in sorted(
        path
        for path in skills_dir.rglob("*")
        if path.is_file() and "__pycache__" not in path.parts and path.suffix != ".pyc"
    ):
        relative_path = file_path.relative_to(skills_dir).as_posix()
        store.put(
            SKILL_NAMESPACE,
            f"/{relative_path}",
            create_file_data(file_path.read_text(encoding="utf-8")),
        )


def sandbox_path(store_path: str) -> str:
    """Map a StoreBackend key to the matching sandbox skill path."""
    normalized = store_path if store_path.startswith("/") else f"/{store_path}"
    path_parts = PurePosixPath(normalized).parts
    if ".." in path_parts or any(character in normalized for character in "*?"):
        raise ValueError(f"Unsafe skill path: {store_path}")
    return f"{SANDBOX_SKILLS_DIR}{normalized}"


class SandboxSkillSyncMiddleware(AgentMiddleware):
    """Move skill files into the sandbox before execution and results back after."""

    def __init__(self, sandbox_backend: DaytonaSandbox) -> None:
        super().__init__()
        self.sandbox_backend = sandbox_backend

    def before_agent(self, state, runtime):
        files = []
        for item in runtime.store.search(SKILL_NAMESPACE, limit=100):
            content = item.value.get("content")
            encoding = item.value.get("encoding", "utf-8")
            if not isinstance(content, str) or encoding != "utf-8":
                raise ValueError(f"Only UTF-8 text skills are supported: {item.key}")
            files.append((sandbox_path(str(item.key)), content.encode("utf-8")))

        if not files:
            raise RuntimeError("No skill files were found in the skill store")

        responses = self.sandbox_backend.upload_files(files)
        failures = [response for response in responses if response.error]
        if failures:
            details = ", ".join(
                f"{response.path}: {response.error}" for response in failures
            )
            raise RuntimeError(f"Skill upload failed: {details}")
        print(f"Uploaded {len(files)} skill files into the sandbox")
        return None

    def after_agent(self, state, runtime):
        result = self.sandbox_backend.download_files([SANDBOX_ARTIFACT_PATH])[0]
        if result.content is None:
            if result.error == "file_not_found":
                print("No result artifact was created by the agent")
                return None
            raise RuntimeError(f"Artifact download failed: {result.error}")

        runtime.store.put(
            ARTIFACT_NAMESPACE,
            ARTIFACT_PATH,
            create_file_data(result.content.decode("utf-8")),
        )
        print(f"Synced {ARTIFACT_PATH} back into the store")
        return None


class SingleToolCallMiddleware(AgentMiddleware):
    """Keep model history compatible with NVIDIA's single-call tool template."""

    def wrap_model_call(self, request, handler):
        response = handler(request)
        truncated_messages = []

        for message in response.result:
            if not isinstance(message, AIMessage) or len(message.tool_calls) <= 1:
                truncated_messages.append(message)
                continue

            additional_kwargs = dict(message.additional_kwargs)
            raw_tool_calls = additional_kwargs.get("tool_calls")
            if isinstance(raw_tool_calls, list):
                additional_kwargs["tool_calls"] = raw_tool_calls[:1]
            truncated_messages.append(
                message.model_copy(
                    update={
                        "tool_calls": message.tool_calls[:1],
                        "additional_kwargs": additional_kwargs,
                    }
                )
            )

        if truncated_messages == response.result:
            return response
        return ModelResponse(
            result=truncated_messages,
            structured_response=response.structured_response,
        )


def main() -> None:
    load_dotenv()

    model_name = os.getenv(
        "NVIDIA_MODEL",
        "meta/llama-3.1-8b-instruct",
    )
    if model_name.startswith("nvidia:"):
        model_name = model_name.removeprefix("nvidia:")
    timeout_seconds = int(os.getenv("NVIDIA_TIMEOUT_SECONDS", "180"))
    model = ChatNVIDIA(
        model=model_name,
        timeout=timeout_seconds,
        max_completion_tokens=4096,
        model_kwargs={"parallel_tool_calls": False},
    )
    store = InMemoryStore()
    seed_skill_store(store)

    print("Creating Daytona sandbox (this can take a moment)...")
    sandbox = Daytona().create()
    print(f"Created sandbox: {sandbox.id}")
    sandbox_backend = DaytonaSandbox(sandbox=sandbox)
    backend = CompositeBackend(
        default=sandbox_backend,
        routes={
            SKILL_ROUTE: StoreBackend(
                store=store,
                namespace=lambda _runtime: SKILL_NAMESPACE,
            ),
        },
    )

    agent = create_deep_agent(
        model=model,
        backend=backend,
        store=store,
        skills=[SKILL_ROUTE],
        middleware=[
            SandboxSkillSyncMiddleware(sandbox_backend),
            SingleToolCallMiddleware(),
        ],
        system_prompt=(
            "You are a research assistant with an isolated execution sandbox. "
            "Use the arxiv-search skill when the user asks about papers. "
            "Daytona's writable directory is /home/daytona; keep generated "
            "files there and do not write directly under /. "
            "Make at most one tool call per response; wait for its result "
            "before making another tool call."
        ),
    )

    prompt = (
        "Use the arxiv-search skill to find three papers about retrieval augmented "
        "generation. You must read the skill, execute its bundled script inside "
        "the sandbox, and use the script's JSON output. Save that exact JSON to "
        f"{SANDBOX_ARTIFACT_PATH}, then summarize the papers with title, authors, "
        "abstract summary, and link. Do not answer from memory. The artifact must "
        "be valid JSON copied from the script output, not a Python dictionary "
        "repr or fabricated example. Before finishing, run `python -m json.tool "
        f"{SANDBOX_ARTIFACT_PATH}` and fix the file if validation fails."
    )

    try:
        result = agent.invoke(
            {"messages": [{"role": "user", "content": prompt}]},
            config={"configurable": {"thread_id": "sandbox-skill-demo"}},
        )
        print("\nAgent response:\n")
        print(result["messages"][-1].content)

        artifact = store.get(ARTIFACT_NAMESPACE, ARTIFACT_PATH)
        if artifact:
            print("\nStored artifact preview:\n")
            artifact_content = artifact.value["content"]
            try:
                artifact_json = json.loads(artifact_content)
            except json.JSONDecodeError:
                print("Artifact is not valid JSON; raw content preview:\n")
                print(artifact_content[:1000])
            else:
                print(json.dumps(artifact_json, indent=2)[:1000])
    except ReadTimeout as error:
        raise SystemExit(
            f"The NVIDIA model did not respond within {timeout_seconds} seconds. "
            "Try a faster model such as meta/llama-3.2-3b-instruct or increase "
            "NVIDIA_TIMEOUT_SECONDS."
        ) from error
    finally:
        sandbox.delete(wait=True)
        print(f"\nDeleted sandbox: {sandbox.id}")


if __name__ == "__main__":
    main()

What I'd add next

Swap InMemoryStore for a persistent store once skills or artifacts need to survive a restart.
As skills grow past one script, have SKILL.md explicitly list every supporting file it depends on.
Mock the arXiv API response and add real tests for search_arxiv().
Lock down the /skills/ route so agents can read shared skills but never write to them.

The one-sentence takeaway

Store skills where they can be managed, execute them where they can be isolated, and sync only the files that need to cross that boundary.

Once that clicks, sandboxed skills stop feeling like magic — they're just a clean way to give an agent reusable, tested capabilities without turning your machine into its workspace.

References

Understanding the Deep Agents Interpreter with Programmatic Tool Calling

Syeed Talha — Mon, 10 Aug 2026 08:44:46 +0000

Tool calling is an important part of AI agents. It allows a model to search the web, query a database, call an API, or perform another external action.

Normal tool calling works well for simple tasks. But it becomes less efficient when an agent needs to call the same tool many times, process intermediate results, or run several independent operations in parallel.

This is the problem the Deep Agents interpreter solves.

What is the Deep Agents interpreter?

The interpreter gives a Deep Agent a small, in-memory JavaScript environment powered by QuickJS.

Instead of asking the model to manage every tool call separately, the model can write JavaScript that:

Calls approved tools
Runs loops
Handles conditional logic
Retries failed operations
Runs independent calls in parallel
Filters and combines results

Only the final result of that JavaScript execution is returned to the model.

In simple terms, the model decides what work should be done, while JavaScript handles how the repeated work should be organized.

What happens without an interpreter?

Suppose an agent needs to research three topics:

Retrieval
Memory
Evaluation

Without an interpreter, the workflow may look like this:

Model calls the retrieval search tool
→ Model receives the result

Model calls the memory search tool
→ Model receives the result

Model calls the evaluation search tool
→ Model receives the result

Model combines all results
→ Model writes the answer

Every result returns to the model before the next step can be decided.

This creates several problems:

More model turns

The model may need to repeatedly call a tool, read its output, and decide what to do next.

Larger model context

Every intermediate tool result becomes part of the model’s context, even when the result only needs to be filtered or passed to another step.

Unreliable repeated calls

Asking a model to perform the same operation across many items does not guarantee that every item will be processed consistently.

Limited workflow control

A normal batch of tool calls is fixed when the model creates it. The model cannot loop, retry, branch on a result, or feed one result into another call without an additional model turn.

How the interpreter changes the workflow

With an interpreter, the workflow becomes:

Model creates one JavaScript program
→ JavaScript calls all approved tools
→ JavaScript processes and combines the results
→ Model receives one combined result
→ Model writes the final answer

For our three research topics, JavaScript can run all searches at the same time:

const topics = ["retrieval", "memory", "evaluation"];

const results = await Promise.all(
  topics.map((topic) =>
    tools.webSearch({
      query: `${topic} best practices`,
    }),
  ),
);

results.join("\n\n");

Promise.all() runs the independent searches in parallel. The interpreter then combines the results before returning them to the model.

Complete example

The following agent searches for retrieval, memory, and evaluation best practices in parallel.

import os

from dotenv import load_dotenv
from deepagents import create_deep_agent
from langchain.tools import tool
from langchain_nvidia_ai_endpoints import ChatNVIDIA
from langchain_quickjs import CodeInterpreterMiddleware
from tavily import TavilyClient


load_dotenv()


@tool
def web_search(query: str) -> str:
    """Search the web and return a compact text summary of the results."""

    # Create the Tavily search client.
    client = TavilyClient(
        api_key=os.environ["TAVILY_API_KEY"]
    )

    # Search the web and limit the response to three results.
    response = client.search(
        query=query,
        max_results=3,
    )

    # Convert the search results into compact text.
    return "\n".join(
        f"- {item['title']}: {item['content']} ({item['url']})"
        for item in response["results"]
    )


def build_agent():
    """Create an agent with programmatic access to web_search."""

    # Create the language model used by the agent.
    model = ChatNVIDIA(
        model=os.getenv(
            "NVIDIA_MODEL",
            "nvidia/nemotron-3-super-120b-a12b",
        ),
        api_key=os.environ["NVIDIA_API_KEY"],
        temperature=0.0,
        max_completion_tokens=1024,
    )

    # Create the Deep Agent and enable the interpreter.
    return create_deep_agent(
        model=model,
        tools=[web_search],
        middleware=[
            CodeInterpreterMiddleware(
                # Allow JavaScript to call the web_search tool.
                ptc=["web_search"],

                # Disable dynamic subagents for this example.
                subagents=False,
            )
        ],
        system_prompt="""
You are a research assistant demonstrating programmatic tool calling.

For research questions, make exactly one eval tool call. Inside that one call,
write JavaScript that calls tools.webSearch({query}) rather than calling
web_search directly.

When there are several independent topics, use Promise.all to search them
in parallel. Combine the results in JavaScript and return only the combined
research notes before writing a concise answer for the user.

Never issue separate web_search calls or multiple eval calls for the same
request.
""",
    )


if __name__ == "__main__":
    # Build the configured agent.
    agent = build_agent()

    # Send a research request to the agent.
    result = agent.invoke(
        {
            "messages": [
                (
                    "user",
                    "Compare current best practices for retrieval, memory, "
                    "and evaluation in LLM applications. Search each topic "
                    "in parallel with the interpreter, then summarize the "
                    "three most useful practices and include source URLs.",
                )
            ]
        }
    )

    # Print the final response produced by the agent.
    print(result["messages"][-1].content)

How the code works

1. The search tool

The web_search function is a regular Python tool:

@tool
def web_search(query: str) -> str:

It sends the query to Tavily and returns three compact search results.

By itself, the agent can call this tool through normal tool calling. However, we also want the interpreter’s JavaScript code to be able to use it.

2. The interpreter middleware

The interpreter is added through CodeInterpreterMiddleware:

middleware=[
    CodeInterpreterMiddleware(
        ptc=["web_search"],
        subagents=False,
    )
]

This middleware adds an eval tool to the agent. The model uses that tool to execute JavaScript inside QuickJS.

You do not call eval manually in the Python code. The agent decides when to use it based on the request and system prompt.

3. Programmatic Tool Calling

The following option enables Programmatic Tool Calling, or PTC:

ptc=["web_search"]

This is an explicit allowlist. It means the JavaScript interpreter can call web_search, but it cannot automatically access every Python tool or system capability.

Inside JavaScript, Python tool names are converted to camel case:

web_search → tools.webSearch

The tool can therefore be called like this:

const result = await tools.webSearch({
  query: "retrieval best practices",
});

4. The system prompt

The system prompt tells the model to make one eval call and perform the searches inside it.

It also instructs the model to use:

Promise.all(...)

This is important because retrieval, memory, and evaluation are independent topics. There is no reason to wait for one search to finish before starting the next one.

5. The agent request

The user asks the agent to research three topics:

result = agent.invoke(
    {
        "messages": [
            (
                "user",
                "Compare current best practices for retrieval, memory, "
                "and evaluation in LLM applications.",
            )
        ]
    }
)

The agent can respond by generating JavaScript similar to this:

const topics = ["retrieval", "memory", "evaluation"];

const results = await Promise.all(
  topics.map((topic) =>
    tools.webSearch({
      query: `${topic} best practices`,
    }),
  ),
);

results.join("\n\n");

QuickJS executes the JavaScript, calls the Python search tool three times, and combines the results.

The model receives the combined research notes rather than three separate intermediate tool responses.

What the interpreter cannot do by default

The interpreter is an in-memory JavaScript runtime, not a complete operating-system environment.

By default, it cannot directly:

Access the network
Read or write files
Run shell commands
Install packages
Access system resources

Network access in this example comes only from the allowlisted web_search tool.

If you need shell commands, package installation, testing, or filesystem access, a sandbox is the more appropriate option.

When should you use an interpreter?

Use an interpreter when an agent needs to:

Call a tool for many items
Run independent calls in parallel
Retry failed calls
Branch based on tool results
Filter or aggregate structured data
Keep intermediate results out of the model context

For one or two simple tool calls, normal tool calling is usually enough.

Final takeaway

The Deep Agents interpreter moves repetitive orchestration from the model into JavaScript.

Without it, the model must manage more intermediate tool calls and results. With it, the agent can make one eval call, execute a complete workflow, and receive only the combined result.

The main pattern is:

Model
→ One eval call
→ JavaScript orchestration
→ Approved Python tools
→ Combined result
→ Final answer

This is especially useful for research, batch processing, data transformation, and other workflows that involve many related tool calls.

Build a Thread-Scoped AI Data Science Sandbox with Daytona and Deep Agents

Syeed Talha — Mon, 03 Aug 2026 12:14:07 +0000

AI coding agents can write files, install Python packages, run scripts, and create charts. But where should that code run?

Running arbitrary agent-generated code directly on a local laptop or production server can be risky. A sandbox gives an agent an isolated environment where it can use a filesystem and shell commands without directly accessing the host machine.

This article presents a small two-turn data science pipeline using:

Daytona for a remote development sandbox
Deep Agents for an AI agent with filesystem and shell access
LangGraph for conversation memory
NVIDIA NIM as the LLM provider

The objective is not only to train a model. The example demonstrates that:

Python packages installed in the first turn remain available in the second turn.
Files created in the first turn still exist in the second turn.
The agent retains conversation context when the same thread_id is reused.

What the example builds

The program makes two agent calls:

Call	Agent task	Persistence proof
Call 1	Installs Python packages, generates data, trains a model, and saves a chart	Creates `data.csv`, `model.pkl`, and `chart.png`
Call 2	Loads the saved model, predicts a class, and checks the chart	Reads files created during Call 1

Both calls use the same sandbox name:

THREAD_ID = "ds-pipeline-demo-1"
SANDBOX_NAME = f"thread-{THREAD_ID}"

This produces the following sandbox name:

thread-ds-pipeline-demo-1

When Call 2 begins, the program searches for a Daytona sandbox with that name. If one exists, the program reuses it instead of creating a new environment.

Understanding the two types of persistence

It is important to separate conversation state from sandbox state.

State type	Stored by	What it contains	Key used in this example
Conversation memory	LangGraph checkpointer	Earlier messages and agent state	`thread_id`
Execution environment	Daytona sandbox	Files, installed packages, and workspace state	`thread-<thread_id>`

The same thread_id serves two different purposes.

config = {"configurable": {"thread_id": THREAD_ID}}

This gives LangGraph a stable identifier for the conversation.

The sandbox name is then derived from the same value:

SANDBOX_NAME = f"thread-{THREAD_ID}"

This gives Daytona a predictable name for the remote workspace.

A thread_id does not automatically make Daytona reuse a sandbox. The application must implement a mapping strategy. In this example, the mapping is a stable sandbox name.

Architecture

The overall flow looks like this:

User prompt
   |
   v
Deep Agent running in the application
   |
   +-- LangGraph checkpointer
   |      |
   |      +-- Stores conversation state using thread_id
   |
   v
DaytonaSandbox backend
   |
   +-- File operations
   +-- Shell command execution
   |
   v
Remote Daytona sandbox
   |
   +-- /home/daytona/train.py
   +-- /home/daytona/data.csv
   +-- /home/daytona/model.pkl
   +-- /home/daytona/chart.png

The agent runs in the application, while filesystem and shell operations run in the Daytona environment.

Prerequisites

Install the required packages:

pip install daytona langchain-daytona deepagents \
  langchain-nvidia-ai-endpoints python-dotenv

Create a .env file:

DAYTONA_API_KEY=your_daytona_api_key
NVIDIA_API_KEY=your_nvidia_api_key

The .env file and API keys should not be committed to version control.

Step 1: Create shared configuration

Start by loading environment variables and setting up the Daytona client.

from dotenv import load_dotenv
from daytona import Daytona, CreateSandboxFromSnapshotParams
from langchain_daytona import DaytonaSandbox
from langgraph.checkpoint.memory import InMemorySaver
from deepagents import create_deep_agent

load_dotenv()

DAYTONA = Daytona()

# This checkpointer stays alive during this Python process.
CHECKPOINTER = InMemorySaver()

# One ID represents one conversation and one sandbox workspace.
THREAD_ID = "ds-pipeline-demo-1"
SANDBOX_NAME = f"thread-{THREAD_ID}"

# Remove the sandbox after 60 minutes of inactivity.
SANDBOX_TTL_MINUTES = 60

What does `InMemorySaver()` do?

InMemorySaver() stores LangGraph state in memory. Since both agent calls happen inside the same Python script, the second call can access the conversation state created by the first call.

There is an important limitation:

InMemorySaver() is not durable. If the application stops and starts again, the conversation memory is lost.

The Daytona sandbox may still be reusable if it has not expired, because it is found by name. However, a production application should use a persistent LangGraph checkpointer backed by a database or other durable storage service.

Step 2: Find or create a sandbox

This function is the core of the sandbox reuse pattern:

def get_or_create_sandbox(name: str):
    """Reuse a sandbox with this name, or create it if missing."""

    for sb in DAYTONA.list():
        if getattr(sb, "name", None) == name:
            print(
                f"Reusing existing sandbox: "
                f"{name} (id={sb.id}, state={sb.state})"
            )

            # Start it again if it is stopped or paused.
            if str(sb.state).lower() not in ("running", "started"):
                sb.start()

            return sb

    print(
        f"Creating new sandbox: {name} "
        f"(ttl={SANDBOX_TTL_MINUTES}min)..."
    )

    sb = DAYTONA.create(
        CreateSandboxFromSnapshotParams(
            name=name,
            language="python",
            ttl_minutes=SANDBOX_TTL_MINUTES,
        )
    )

    print(f"Created sandbox: {name} (id={sb.id})")
    return sb

Here is what happens in different situations:

Situation	Result
No sandbox with the target name exists	A new sandbox is created
A matching sandbox exists and is running	It is reused immediately
A matching sandbox exists but is stopped	It is started and reused
The sandbox expired because of TTL	A new sandbox is created

Files and installed packages exist inside the Daytona sandbox, not in the LangGraph checkpointer.

That is why Call 2 can load the model:

Call 1 writes /home/daytona/model.pkl
                 |
                 v
The same Daytona sandbox is reused
                 |
                 v
Call 2 reads /home/daytona/model.pkl

Step 3: Give the agent access to the sandbox

Next, the Daytona sandbox is wrapped in a Deep Agents backend.

def build_agent(sandbox):
    """Create an AI agent connected to one Daytona sandbox."""

    backend = DaytonaSandbox(sandbox=sandbox)

    return create_deep_agent(
        model="nvidia:nvidia/nemotron-3-ultra-550b-a55b",
        backend=backend,
        checkpointer=CHECKPOINTER,
        system_prompt=(
            "You are a data-science coding assistant with sandbox access. "
            "Use the filesystem and execute tools to install packages, "
            "write scripts, run them, and inspect outputs. "
            "Always verify files exist before reporting success.\n\n"
            "The writable working directory is /home/daytona. "
            "Use absolute paths under /home/daytona/ for file operations. "
            "When executing commands, first run: cd /home/daytona"
        ),
    )

The sandbox backend gives the agent tools for tasks such as:

Writing files
Reading files
Editing files
Listing directories
Searching files
Running shell commands

These tools allow the agent to install packages, create Python scripts, run them, and inspect generated artifacts.

Why `/home/daytona` matters

The system prompt directs the agent to work only inside:

/home/daytona

This convention keeps generated files in one writable and predictable location.

For example:

/home/daytona/train.py
/home/daytona/data.csv
/home/daytona/model.pkl
/home/daytona/chart.png

Using absolute paths also reduces the chance of files being written to an unexpected location or to a protected root-level directory.

Step 4: Run the training turn

For the first call, the agent receives instructions to install dependencies, create a training script, execute it, and verify the outputs.

call1_prompt = (
    "Do the following in the sandbox, step by step:\n"
    "1. Install: pandas matplotlib scikit-learn (use pip).\n"
    "2. Write a Python script `train.py` that:\n"
    "   - generates a small synthetic classification dataset,\n"
    "   - saves the data to `data.csv`,\n"
    "   - trains a sklearn LogisticRegression model,\n"
    "   - saves the trained model to `model.pkl`,\n"
    "   - creates and saves a scatter plot as `chart.png`.\n"
    "3. Run `train.py` and verify `model.pkl` and `chart.png` exist.\n"
    "4. Report what you did and the file sizes."
)

Inside the sandbox, the workflow is similar to:

cd /home/daytona
pip install pandas matplotlib scikit-learn
python train.py
ls -lh model.pkl chart.png

After the first call, the Daytona workspace should contain:

/home/daytona/
├── train.py
├── data.csv
├── model.pkl
└── chart.png

Step 5: Reuse the sandbox in the second call

Before the second call, the same lookup function runs again:

sandbox = get_or_create_sandbox(SANDBOX_NAME)
agent = build_agent(sandbox)

Since SANDBOX_NAME is unchanged, the program finds and reuses the existing environment.

The next prompt uses artifacts from the earlier turn:

call2_prompt = (
    "Using the artifacts from the previous turn in the sandbox:\n"
    "1. Load `model.pkl` and run a prediction on this new row:\n"
    "   feature_1 = 0.5, feature_2 = -1.2\n"
    "   Print the predicted class.\n"
    "2. Confirm `chart.png` is still present and report its size and "
    "the list of files in the working directory.\n"
    "This proves the installed packages and files survived between turns."
)

A successful second call demonstrates that:

scikit-learn is still installed
model.pkl still exists
chart.png still exists

This is the practical value of a thread-scoped sandbox.

Streaming tool activity

The run_turn() function streams the agent’s actions while work is in progress:

for chunk in agent.stream(
    {"messages": [{"role": "user", "content": prompt}]},
    config=config,
    stream_mode="updates",
):
    ...

This makes the workflow observable:

[agent] -> execute({"command": "cd /home/daytona && pip install ..."})
[tools] <- execute: Successfully installed ...
[agent] -> write_file({"path": "/home/daytona/train.py", ...})
[agent] -> execute({"command": "cd /home/daytona && python train.py"})
[tools] <- execute: Model saved successfully

Streaming is useful for code-running agents because it shows:

Which commands were executed
Which files were written
Whether a command failed
Whether the agent verified the final files

Step 6: Clean up the sandbox

The example uses a finally block to stop the sandbox after the script ends:

finally:
    try:
        sb = DAYTONA.get(SANDBOX_NAME)
        sb.stop()
        print(f"Stopped sandbox: {SANDBOX_NAME} (id={sb.id})")
    except Exception as exc:
        print(f"Could not stop sandbox {SANDBOX_NAME}: {exc}")

This matters because sandboxes consume remote compute resources.

The example also configures:

ttl_minutes=60

The TTL is a backup cleanup mechanism. If the application crashes or the session does not return, the sandbox can be removed after it remains idle for the configured period.

In this demo, the explicit stop() runs after Call 2, so the TTL mainly serves as a fallback.

Security considerations

A sandbox provides isolation between agent-generated code and the local machine or primary application server.

However, a sandbox does not solve every security issue automatically.

Risk	Why it still matters
Prompt injection	Untrusted input could convince an agent to run unwanted commands inside the sandbox
Network access	If outbound networking is allowed, the agent may send data elsewhere
Secrets in prompts	Sensitive information passed to the agent could be written into sandbox files
Resource usage	An agent may install large packages, create large files, or run expensive commands

Practical safety rules include:

Keep API keys outside the sandbox when possible.
Avoid placing sensitive production data into the sandbox unless necessary.
Use short sandbox TTL values.
Use unique and difficult-to-guess thread IDs in multi-user systems.
Validate user-provided file paths and commands.
Apply runtime, storage, package, and network restrictions where available.
Clean up environments when tasks finish.

Full code

"""
Thread-scoped Daytona Sandbox: multi-turn data science pipeline.

Demonstrates sandbox + conversation reuse across two calls with the
same `thread_id`:

  Call 1: install pandas/matplotlib/scikit-learn, generate a CSV, train a
          small model, save `model.pkl` + `chart.png`.
  Call 2: load the saved model and predict on a new row; re-display the
          chart. Proves both the installed packages and the files
          survived between turns.

How reuse works:
  - The sandbox is named `thread-<thread_id>`. On Call 2 we list existing
    sandboxes and find it by name -> reuse it (files + installed packages
    are still there). If not found, we create it.
  - A LangGraph checkpointer keyed by the same `thread_id` keeps the
    conversation memory across the two invocations.
  - `ttl_minutes` auto-deletes the sandbox after idle time so you don't
    pay forever if you never come back.

Prereqs (already in pyproject.toml):
    pip install daytona langchain-daytona deepagents langchain-nvidia-ai-endpoints

Env (already in .env):
    DAYTONA_API_KEY     - for Daytona()
    NVIDIA_API_KEY      - for the LLM

Run:
    python daytona_thread_scoped.py
"""

from dotenv import load_dotenv
from daytona import Daytona, CreateSandboxFromSnapshotParams
from langchain_daytona import DaytonaSandbox
from langgraph.checkpoint.memory import InMemorySaver

from deepagents import create_deep_agent

# Load DAYTONA_API_KEY / NVIDIA_API_KEY from .env
load_dotenv()

DAYTONA = Daytona()

# A single checkpointer kept alive for the whole script so both calls
# share conversation memory keyed by thread_id.
CHECKPOINTER = InMemorySaver()

# The conversation/sandbox key. Same value on both calls => reuse.
THREAD_ID = "ds-pipeline-demo-1"
SANDBOX_NAME = f"thread-{THREAD_ID}"
SANDBOX_TTL_MINUTES = 60  # auto-delete after 1h idle


def get_or_create_sandbox(name: str):
    """Find an existing Daytona sandbox by name, or create a new one.

    Returns the (running) Sandbox. Reusing the same name across turns is
    what makes files and installed packages persist between calls.
    """
    for sb in DAYTONA.list():
        if getattr(sb, "name", None) == name:
            print(f"Reusing existing sandbox: {name} (id={sb.id}, state={sb.state})")
            # Make sure it's running (it may have been stopped/paused).
            if str(sb.state).lower() not in ("running", "started"):
                sb.start()
            return sb

    print(f"Creating new sandbox: {name} (ttl={SANDBOX_TTL_MINUTES}min)...")
    sb = DAYTONA.create(
        CreateSandboxFromSnapshotParams(
            name=name,
            language="python",
            ttl_minutes=SANDBOX_TTL_MINUTES,
        )
    )
    print(f"Created sandbox: {name} (id={sb.id})")
    return sb


def build_agent(sandbox):
    """Build a Deep Agent bound to the given sandbox backend."""
    backend = DaytonaSandbox(sandbox=sandbox)
    return create_deep_agent(
        model="nvidia:nvidia/nemotron-3-ultra-550b-a55b",
        backend=backend,
        checkpointer=CHECKPOINTER,
        system_prompt=(
            "You are a data-science coding assistant with sandbox access. "
            "Use the provided filesystem and execute tools to install "
            "packages, write scripts, run them, and read outputs. "
            "Always verify results (e.g. check that a file exists) before "
            "reporting success. Keep shell commands short.\n\n"
            "IMPORTANT -- working directory:\n"
            "- The sandbox's writable working directory is `/home/daytona`. "
            "The filesystem root `/` is NOT writable.\n"
            "- When using write_file / read_file / edit_file, ALWAYS pass "
            "absolute paths under `/home/daytona/` "
            "(e.g. `/home/daytona/train.py`, NOT `train.py` or `/train.py`).\n"
            "- When using the execute tool, first `cd /home/daytona` so that "
            "relative paths in shell commands also land there.\n"
            "- Keep all created files (scripts, data.csv, model.pkl, "
            "chart.png) under `/home/daytona/`."
        ),
    )


def run_turn(agent, config, label: str, prompt: str) -> str:
    """Invoke the agent for one turn, streaming tool calls and results."""
    print("\n" + "=" * 72)
    print(f"{label}")
    print("=" * 72)
    print(f"USER: {prompt}\n")

    final_text = ""
    for chunk in agent.stream(
        {"messages": [{"role": "user", "content": prompt}]},
        config=config,
        stream_mode="updates",
    ):
        for node_name, update in chunk.items():
            if not update:
                continue
            for msg in update.get("messages", []):
                if msg.type == "ai" and getattr(msg, "tool_calls", None):
                    for call in msg.tool_calls:
                        name = call.get("name")
                        args = call.get("args", {})
                        summary = str(args)
                        if len(summary) > 200:
                            summary = summary[:200] + "..."
                        print(f"[{node_name}] -> {name}({summary})")
                elif msg.type == "tool":
                    content = str(msg.content)
                    if len(content) > 300:
                        content = content[:300] + "..."
                    print(f"[{node_name}] <- {msg.name}: {content}")
                elif msg.type == "ai" and not getattr(msg, "tool_calls", None):
                    final_text = msg.content
                    print(f"[{node_name}] AI: {final_text}\n")
    return final_text


def main():
    config = {"configurable": {"thread_id": THREAD_ID}}

    # --- Call 1: create sandbox + run the data-science pipeline -------
    sandbox = get_or_create_sandbox(SANDBOX_NAME)
    agent = build_agent(sandbox)

    call1_prompt = (
        "Do the following in the sandbox, step by step:\n"
        "1. Install: pandas matplotlib scikit-learn (use pip).\n"
        "2. Write a Python script `train.py` that:\n"
        "   - generates a small synthetic classification dataset (e.g. "
        "make_classification, ~200 rows, 2 numeric features),\n"
        "   - saves the data to `data.csv`,\n"
        "   - trains a sklearn LogisticRegression model,\n"
        "   - saves the trained model to `model.pkl` using joblib/pickle,\n"
        "   - plots the two features colored by class and saves it as "
        "`chart.png` (do not call plt.show).\n"
        "3. Run `train.py` and verify `model.pkl` and `chart.png` exist.\n"
        "4. Report what you did and the file sizes."
    )
    run_turn(agent, config, "CALL 1: train + save artifacts", call1_prompt)

    # --- Call 2: reuse sandbox + memory; prove files survived ---------
    # Same thread_id => same checkpointer memory AND same sandbox.
    sandbox = get_or_create_sandbox(SANDBOX_NAME)
    agent = build_agent(sandbox)  # rebuild bound to the (reused) sandbox

    call2_prompt = (
        "Using the artifacts from the previous turn in the sandbox:\n"
        "1. Load `model.pkl` and run a prediction on this new row:\n"
        "   feature_1 = 0.5, feature_2 = -1.2\n"
        "   Print the predicted class.\n"
        "2. Confirm `chart.png` is still present and report its size and "
        "the list of files in the working directory.\n"
        "This proves the installed packages and files survived between turns."
    )
    run_turn(agent, config, "CALL 2: load model + reuse files", call2_prompt)


if __name__ == "__main__":
    try:
        main()
    finally:
        # Clean up the sandbox so it doesn't keep running / billing.
        # (ttl_minutes would also clean it up, but we stop it now to be safe.)
        try:
            sb = DAYTONA.get(SANDBOX_NAME)
            sb.stop()
            print(f"\nStopped sandbox: {SANDBOX_NAME} (id={sb.id})")
        except Exception as exc:
            print(f"\nCould not stop sandbox {SANDBOX_NAME}: {exc}")

Final takeaway

A thread-scoped sandbox gives each AI conversation its own isolated workspace.

In this example:

THREAD_ID identifies the conversation.
thread-<THREAD_ID> identifies the Daytona sandbox.
Call 1 installs packages and creates artifacts.
Call 2 finds the same sandbox and reuses its packages and files.
LangGraph memory preserves conversational context during the script.
Daytona TTL and explicit cleanup help control resource usage.

This pattern can be used for more than a small machine-learning example:

AI coding assistants
Data analysis agents
File-processing workflows
Report and chart generation
Automated testing environments
Per-user development workspaces

Conversation state and execution state are separate, but a shared thread identifier can connect them in a clean and reliable way.

Deep Agents Filesystem Permissions: A Beginner-Friendly Guide with 3 Python Examples

Syeed Talha — Tue, 28 Jul 2026 10:20:55 +0000

An AI agent that can read and write files is only as safe as the boundaries you put around it. A coding agent might need full access to a project folder, but it should never be able to open .env, read a shared credentials file, or overwrite a policy document it was only supposed to consult.

Deep Agents solves this with FilesystemPermission rules: small, declarative statements that say which paths an agent's built-in filesystem tools can touch, and how.

This guide builds three examples, each adding one new idea:

A workspace agent — confined to a project folder, blocked from a secret file inside it.
A memory + approval agent — can read shared knowledge but not edit it, and must pause for a human's OK before writing anything sensitive.
A parent/subagent pair — a coding agent that can edit files, and an auditor subagent that can only read them.

Each example is a complete, runnable script. If you want to follow along, you'll need deepagents installed and a chat model configured — the full scripts (linked at the end) include that setup so you can just run them.

Requirements

Permission rules need deepagents>=0.5.2. If you want to use mode="interrupt" (Example 2), you need deepagents>=0.6.8. If your examples don't behave as described below, check your installed version first.

How a Permission Rule Works

A rule has three parts:

FilesystemPermission(
    operations=["read", "write"],
    paths=["/workspace/**"],
    mode="allow",
)

operations — which kind of filesystem call the rule watches:

"read" covers ls, read_file, glob, grep
"write" covers write_file, edit_file, delete

paths — glob patterns matched against the agent's virtual filesystem, not necessarily your real disk layout (more on that below). ** matches any depth (/workspace/** matches /workspace/app.py and /workspace/sub/dir/file.txt). You can also use {a,b} to match alternatives, e.g. /workspace/{src,tests}/**.

mode — what happens when a call matches:

"allow" — let it through
"deny" — reject it
"interrupt" — pause the whole agent graph and wait for a human to approve, edit, or reject the call

Three rules govern how a list of FilesystemPermission objects behaves, and all three matter more than any single rule on its own:

Rules are checked top to bottom. The first one that matches wins. Rules below it are never consulted for that call.
If nothing matches, the call is allowed. This is the part beginners trip on — permissions are opt-out, not opt-in. If you want a closed policy, you must end your list with a catch-all deny rule on /**.
Permissions only govern the built-in filesystem tools (ls, read_file, glob, grep, write_file, edit_file, delete). They do not restrict custom tools, MCP tools, or a sandbox backend's execute tool — that's a separate concern, covered at the end of this guide.

With that model in place, the examples below should read less like magic incantations and more like straightforward consequences of these three rules.

Example 1: A Secure Workspace Agent

Goal: the agent can freely read and edit files in /workspace, except a .env file sitting inside it.

The script maps a real folder to the agent's virtual root using FilesystemBackend(root_dir=..., virtual_mode=True). Concretely, if root_dir is secure_workspace_data/, then the real file secure_workspace_data/workspace/app.py appears to the agent simply as /workspace/app.py. The agent never sees your actual disk paths — only the virtual ones you've exposed.

import os
from pathlib import Path

from dotenv import load_dotenv
from langchain.chat_models import init_chat_model
from deepagents import FilesystemPermission, create_deep_agent
from deepagents.backends import FilesystemBackend

load_dotenv()

ROOT = Path(__file__).parent / "secure_workspace_data"
WORKSPACE = ROOT / "workspace"
WORKSPACE.mkdir(parents=True, exist_ok=True)
(WORKSPACE / "app.py").write_text("print('demo application')\n", encoding="utf-8")
(WORKSPACE / ".env").write_text("DEMO_SECRET=do-not-read\n", encoding="utf-8")

model = init_chat_model("nvidia:meta/llama-3.1-70b-instruct")
backend = FilesystemBackend(root_dir=ROOT, virtual_mode=True)

permissions = [
    # Rule 1: the exception. Checked first, so it wins before the broad allow below.
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/.env", "/workspace/secrets/**"],
        mode="deny",
    ),
    # Rule 2: the general case. Everything else in the workspace is fair game.
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/**"],
        mode="allow",
    ),
    # Rule 3: the catch-all. Anything outside /workspace is blocked by default.
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

agent = create_deep_agent(model=model, backend=backend, permissions=permissions)
result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Read /workspace/.env.",
            }
        ]
    }
)
print(result["messages"][-1].content)


result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Read /workspace/app.py.",
            }
        ]
    }
)
print(result["messages"][-1].content)

this will generate output something like:

I cannot read or list the contents of /workspace or /workspace/.env due to a permission error.
The file `/workspace/app.py` contains only one line of code: `print('demo application')`.

Now lets see why the order matters here: /workspace/.env matches both Rule 1 and Rule 2. Because Rule 1 is checked first, .env is denied before Rule 2's broad allow ever gets a chance to apply. Swap the two, and the allow rule would win instead — the deny rule would still exist in your code, but it would never fire, because a match was already found above it.

Agent action	Result	Which rule decided it
Read/edit `/workspace/app.py`	Allowed	Rule 2
Read/edit `/workspace/.env`	Denied	Rule 1
Read `/anything-else.txt`	Denied	Rule 3 (nothing else matched)

Example 2: Read-Only Memory, with Approval for Sensitive Writes

Goal: the agent can read a shared policy document but never edit it, and any write under /secrets pauses for a human to approve.

This introduces mode="interrupt", which behaves differently from allow/deny: instead of resolving the tool call immediately, it freezes the agent's execution graph at that point and returns control to your application. Your application decides what happens next — approve the call as-is, edit its arguments, or reject it — and then resumes the same run.

Because the graph has to be paused and later resumed, it needs somewhere to store its state in between. That's what the checkpointer and thread_id are for: without a checkpointer, there's no state to resume from, so mode="interrupt" requires one.

"""Example 2: read-only memory and human approval for sensitive writes."""

import os
from pathlib import Path

from dotenv import load_dotenv
from langchain.chat_models import init_chat_model
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command
from deepagents import FilesystemPermission, create_deep_agent
from deepagents.backends import FilesystemBackend

load_dotenv()

if not os.environ.get("NVIDIA_API_KEY", "").startswith("nvapi-"):
    raise RuntimeError(
        "Set NVIDIA_API_KEY to a valid NVIDIA API key (starting with 'nvapi-') "
        "in your environment or a .env file before running this example."
    )

ROOT = Path(__file__).parent / "approval_memory_data"
# Prepare separate demo locations so each permission rule has a real path to
# test: normal work, shared memory, and sensitive secrets.
for directory in ("workspace", "memories", "secrets"):
    (ROOT / directory).mkdir(parents=True, exist_ok=True)
(ROOT / "workspace" / "report.md").write_text("# Draft report\n", encoding="utf-8")
(ROOT / "memories" / "company-policy.md").write_text(
    "Never commit credentials to source control.\n", encoding="utf-8"
)

# This creates the following demo structure on disk. The secrets directory is
# intentionally empty; the agent will request approval before writing there.
# approval_memory_data/
# |-- workspace/
# |   `-- report.md
# |-- memories/
# |   `-- company-policy.md
# `-- secrets/

# This model supports one tool call per response, so disable parallel tool
# calls when the agent has several filesystem operations to perform.
model = init_chat_model(
    "nvidia:meta/llama-3.1-70b-instruct",
    model_kwargs={"parallel_tool_calls": False},
)
# Agent path /memories/company-policy.md maps to ROOT/memories/company-policy.md.
backend = FilesystemBackend(root_dir=ROOT, virtual_mode=True)
# An interrupt pauses the graph; the checkpointer stores its state while a
# human decides whether the pending filesystem operation should continue.
checkpointer = InMemorySaver()

permissions = [
    # Memory is readable but cannot be changed by the agent.
    FilesystemPermission(
        operations=["write"],
        paths=["/memories/**", "/policies/**"],
        mode="deny",
    ),
    # Reading policy is allowed separately from writing it.
    FilesystemPermission(
        operations=["read"],
        paths=["/memories/**", "/policies/**"],
        mode="allow",
    ),
    # The graph pauses here and must be resumed with a human decision.
    FilesystemPermission(
        operations=["write"],
        paths=["/secrets/**"],
        mode="interrupt",
    ),
    # Normal workspace changes do not require approval.
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=permissions,
    checkpointer=checkpointer,
)

config = {"configurable": {"thread_id": "approval-memory-demo"}}
result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "Read /memories/company-policy.md, then write a short note to "
                    "/secrets/review.txt saying that the policy was reviewed. "
                    "The secret write requires human approval."
                ),
            }
        ]
    },
    config=config,
)

while True:
    interrupts = result.get("__interrupt__", ())
    if not interrupts:
        print(result["messages"][-1].content)
        break

    # Filesystem permission interrupts use the same action_requests structure
    # as other LangGraph human-in-the-loop tool interrupts.
    interrupt_value = interrupts[0].value
    action_requests = interrupt_value["action_requests"]
    decisions = []

    for action in action_requests:
        print("\nApproval required")
        print(f"Tool: {action['name']}")
        print(f"Arguments: {action['args']}")

        while True:
            decision = input("Approve this operation? [a]pprove/[r]eject: ").strip().lower()
            if decision in {"a", "approve"}:
                decisions.append({"type": "approve"})
                break
            if decision in {"r", "reject"}:
                decisions.append(
                    {
                        "type": "reject",
                        "message": "The user rejected this filesystem operation. Do not retry it.",
                    }
                )
                break
            print("Please enter 'a' to approve or 'r' to reject.")

    # Resume with the same config so InMemorySaver can restore this thread.
    result = agent.invoke(Command(resume={"decisions": decisions}), config=config)

A couple of details that are easy to miss:

deny and interrupt mean different things. deny is for actions that should never happen, full stop. interrupt is for actions that are legitimate but need a person in the loop before they happen. Mixing them up either blocks something you actually wanted to allow-with-review, or lets something through that should have been reviewed.
Deleting a directory is all-or-nothing. If you use delete on a folder, permissions are checked against every file inside it; if even one of them is denied, the whole delete is refused rather than partially completing.
Interrupt patterns should have a concrete leading path segment — something like /secrets/**, not a wildcard-first pattern like /**/secrets. Bulk operations (ls, glob, grep, or delete on a directory) will trigger the interrupt any time their search could touch the pattern, so an unanchored pattern tends to interrupt far more often than intended.

Example 3: A Parent Agent and a Read-Only Auditor Subagent

Goal: a parent agent can edit code inside a project. It delegates review work to an auditor subagent that must never write anything, only read.

This example uses a CompositeBackend instead of a plain FilesystemBackend. A composite backend lets you route different virtual path prefixes to different underlying storage — here, everything under /workspace/ is mapped to a real project folder on disk, while anything else falls back to StateBackend() (in-memory, scratch state that isn't persisted to disk).

import os
from pathlib import Path

from dotenv import load_dotenv
from langchain.chat_models import init_chat_model
from deepagents import FilesystemPermission, create_deep_agent
from deepagents.backends import CompositeBackend, FilesystemBackend, StateBackend

load_dotenv()

ROOT = Path(__file__).parent / "multi_agent_data"
PROJECT = ROOT / "project"
(PROJECT / "src").mkdir(parents=True, exist_ok=True)
(PROJECT / "src" / "app.py").write_text(
    "def greet(name):\n    return f'Hello, {name}'\n", encoding="utf-8"
)

model = init_chat_model("nvidia:meta/llama-3.1-70b-instruct")
backend = CompositeBackend(
    default=StateBackend(),
    routes={
        "/workspace/": FilesystemBackend(
            root_dir=PROJECT,
            virtual_mode=True,
        ),
    },
)

parent_permissions = [
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

auditor_permissions = [
    # Nothing this subagent does can write anywhere.
    FilesystemPermission(
        operations=["write"],
        paths=["/**"],
        mode="deny",
    ),
    # It may only read inside the project workspace.
    FilesystemPermission(
        operations=["read"],
        paths=["/workspace/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read"],
        paths=["/**"],
        mode="deny",
    ),
]

agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=parent_permissions,
    subagents=[
        {
            "name": "auditor",
            "description": "Reviews workspace code but must never edit it.",
            "system_prompt": "Review code and report issues. Never modify files.",
            "permissions": auditor_permissions,
        }
    ],
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Ask the auditor to inspect /workspace/src/app.py.",
            }
        ]
    },
    config={"configurable": {"thread_id": "multi-agent-auditor-demo"}},
)
print(result["messages"][-1].content)

The single most important thing to understand here: permissions on a subagent spec replaces the parent's rules, it does not add to them. A subagent doesn't inherit a stricter version of its parent's policy by default — if you give it permissions at all, that list is now the entire policy for that subagent, evaluated in isolation.

That's exactly why auditor_permissions is a complete three-rule list on its own — deny all writes, allow reads inside /workspace, deny all other reads — rather than just the single write-deny rule. Remember rule #2 from earlier: unmatched calls are allowed by default. If the auditor only had the write-deny rule, it would correctly be blocked from writing, but it would also be free to read absolutely anything, since nothing would deny it.

One more thing worth knowing if you reach for CompositeBackend with a sandbox: if the backend's default route is a sandbox (one that can execute arbitrary shell commands), every permission path you declare must be scoped under one of the composite's named route prefixes — you can't write a permission like /** or /workspace/** that reaches into the sandbox's default route, and doing so raises NotImplementedError. This example avoids that because its default is StateBackend(), not a sandbox — but it's the first thing to check if you swap in a sandbox default and your permissions suddenly stop working.

A Security Boundary, Not a Complete Sandbox

It's worth restating plainly: FilesystemPermission rules only govern Deep Agents' own built-in filesystem tools. They say nothing about:

Custom tools you write yourself
MCP tools connected to the agent
A sandbox backend's ability to run shell commands via execute

If your agent can run shell commands, filesystem permission globs cannot contain that — a shell command can read or write anything the process itself has access to, permission rules or not. That's a separate problem, solved with an actual sandboxed execution environment, not with path patterns.

Practical Checklist

Start from a small allow-list, e.g. /workspace/**, rather than trying to enumerate everything to deny.
Put specific deny rules (a secret file, a policy folder) before the broad allow rule that would otherwise match them.
End a closed policy with a catch-all deny on /** — remember, no match means allowed.
Reach for interrupt (with a checkpointer) when a human should sign off on an action, and deny when an action should never happen at all.
Give every subagent that needs different access from its parent a complete permission list — its rules replace the parent's, they don't extend them.
If you use a CompositeBackend with a sandbox as the default route, scope every permission path to a named route prefix.

The full runnable versions are available in this project as secure_workspace_agent.py, approval_memory_agent.py, and multi_agent_auditor.py.

For the current API reference and additional examples, see the Deep Agents permissions documentation.

Deep Agents LocalShellBackend Tutorial Real Files and Host Shell Execution

Syeed Talha — Mon, 27 Jul 2026 09:02:21 +0000

AI agents become much more useful when they can do more than generate text.

For example, an agent can:

Create a Python file.
Save it to your real local filesystem.
Run that file using a shell command.
Read the file again in a later interaction.
Let another agent thread access the same project folder.

Deep Agents provides LocalShellBackend for this kind of trusted local-development workflow.

It gives an agent access to:

Real files and folders under a configured working directory
File tools such as ls, read_file, and write_file
An execute tool for running commands through your computer’s shell

⚠️ Security Warning

LocalShellBackend executes commands directly on the machine running your Python script.

It is not a sandbox.

This means an agent may be able to:

Run shell commands with your user permissions
Read accessible files, including secrets and credentials
Modify or delete files
Install packages
Start processes
Consume CPU, memory, or disk space
Access files outside the configured workspace through shell commands

Use it only in a trusted local development environment. Do not expose it through a public website, API, chatbot, shared machine, or multi-user system. LangChain strongly recommends human approval for operations and a real sandbox for production or untrusted workloads. (reference.langchain.com)

What This Script Demonstrates

Step	What happens in your code
1	The agent creates `/scripts/hello.py`.
2	The file is physically written to `./shell_workspace/scripts/hello.py`.
3	The agent runs `python scripts/hello.py` through the host shell.
4	The same thread reads the file again.
5	A different thread can still find, read, and run the same file.

Key idea

                         LocalShellBackend
                                │
             ┌──────────────────┴──────────────────┐
             │                                     │
             ▼                                     ▼
   Real files on local disk              Shell commands on host
   ./shell_workspace/                    python, ls, dir, pwd, etc.
             │                                     │
             └──────────────────┬──────────────────┘
                                │
                                ▼
                        Your local computer

The file is not stored only in agent memory or LangGraph state. It is an ordinary operating-system file in your project directory.

Before You Begin

1. Install dependencies

pip install deepagents langchain langchain-nvidia-ai-endpoints python-dotenv

2. Create a `.env` file

Create a file named .env beside your Python script:

NVIDIA_API_KEY=your_nvidia_api_key_here

3. Add private files and generated folders to `.gitignore`

.env
shell_workspace/

💡 Do not place credentials, SSH keys, database files, or private configuration files inside shell_workspace. A local-shell agent may be able to read accessible files.

Complete Code

"""
Demonstrates Deep Agents' LocalShellBackend (real files + shell on host).

What you will observe:
1. The agent writes real files to disk under a root_dir.
2. The agent can execute shell commands directly on your machine.
3. Files persist across threads because they are real OS files.

SECURITY NOTE:
LocalShellBackend runs shell commands directly on the host and is not
sandboxed. Use only in local development environments that you trust.
"""

import os

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend
from dotenv import load_dotenv
from langchain_nvidia_ai_endpoints import ChatNVIDIA


# Load NVIDIA_API_KEY from the local .env file.
load_dotenv()


# Create the NVIDIA chat model used by the Deep Agent.
model = ChatNVIDIA(
    model="nvidia/nemotron-3-super-120b-a12b",
    nvidia_api_key=os.getenv("NVIDIA_API_KEY"),
    max_completion_tokens=1500,
)


# ---------------------------------------------------------
# LocalShellBackend — real disk files + host shell execution
# ---------------------------------------------------------
# Files are saved under ./shell_workspace/.
#
# With virtual_mode=True:
#   /scripts/hello.py
#
# maps to:
#   ./shell_workspace/scripts/hello.py
#
# IMPORTANT:
# virtual_mode=True affects file-tool paths, but it does NOT sandbox
# shell commands executed through the execute tool.
agent = create_deep_agent(
    model=model,
    backend=LocalShellBackend(
        root_dir="./shell_workspace",
        virtual_mode=True,
    ),
)


def run(thread_id: str, prompt: str):
    """Send one prompt to the agent and print its final response."""

    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": prompt,
                }
            ]
        },
        config={
            "configurable": {
                "thread_id": thread_id,
            }
        },
    )

    print("\n" + "=" * 70)
    print(f"THREAD: {thread_id}")
    print("=" * 70)
    print(result["messages"][-1].content)


# ---------------------------------------------------------
# Turn 1 — create a real Python file and execute it
# ---------------------------------------------------------
run(
    "shell-thread-1",
    """
Use the write_file tool to create:

Path: /scripts/hello.py

Content:
for i in range(20):
    print("Hello from LocalShellBackend!")

After writing:
1. Use ls to confirm /scripts/hello.py exists.
2. Use the execute tool to run: python scripts/hello.py
3. Report the exact output of the command.
""",
)


# ---------------------------------------------------------
# Turn 2 — same thread reads the file and inspects workspace
# ---------------------------------------------------------
run(
    "shell-thread-1",
    """
Use read_file to read /scripts/hello.py.

Then use the execute tool to run a command that prints the current
working directory and lists the contents of the scripts directory.

If you are on Windows, use:
cd && dir scripts

If you are on macOS or Linux, use:
pwd && ls -la scripts
""",
)


# ---------------------------------------------------------
# Turn 3 — a different thread can still access the same file
# ---------------------------------------------------------
run(
    "shell-thread-2",
    """
Use ls to inspect the filesystem.

Can you find /scripts/hello.py?

Read it and run it with the execute tool.

Report:
1. The file contents
2. The command output
""",
)


# ---------------------------------------------------------
# Confirm where the generated file exists on your computer
# ---------------------------------------------------------
print("\n" + "=" * 70)
print("Files written to: ./shell_workspace/")
print("Windows commands:")
print("  dir shell_workspace\\scripts\\")
print("  type shell_workspace\\scripts\\hello.py")
print()
print("macOS/Linux commands:")
print("  ls -la shell_workspace/scripts/")
print("  cat shell_workspace/scripts/hello.py")
print("=" * 70)

How `LocalShellBackend` Works

LocalShellBackend is a filesystem backend with host shell execution added.

Filesystem access
    │
    ├── ls
    ├── read_file
    ├── write_file
    ├── edit_file
    ├── glob
    └── grep
    │
    ▼
LocalShellBackend
    │
    └── execute

The execute tool runs shell commands on the computer where your script is running. Its working directory is set to the configured root_dir, which in this example is:

./shell_workspace

Commands are executed through the system shell, and LocalShellBackend does not isolate those commands from the rest of the host machine. (docs.langchain.com)

Step 1: The Agent Creates a Real Python File

In the first prompt, the agent is asked to create:

/scripts/hello.py

Because your backend is configured with:

LocalShellBackend(
    root_dir="./shell_workspace",
    virtual_mode=True,
)

the virtual agent path:

/scripts/hello.py

maps to the real local path:

./shell_workspace/scripts/hello.py

The resulting project structure becomes:

your-project/
├── local_shell_demo.py
├── .env
└── shell_workspace/
    └── scripts/
        └── hello.py

The generated Python file contains:

for i in range(20):
    print("Hello from LocalShellBackend!")

Step 2: The Agent Executes the File

Your first prompt instructs the agent to run:

python scripts/hello.py

Because the shell working directory is ./shell_workspace, the relative command path resolves to:

./shell_workspace/scripts/hello.py

Expected output:

Hello from LocalShellBackend!
Hello from LocalShellBackend!
Hello from LocalShellBackend!
...

The message should appear 20 times.

⚠️ The exact wording of the agent’s final explanation may vary because an LLM chooses its own tool calls and response text. However, the generated hello.py file should print the message 20 times if the command succeeds.

Step 3: The Same Thread Reads the File Again

The second call uses the same thread ID:

"shell-thread-1"

The agent is instructed to:

Read /scripts/hello.py
Print the current directory
List the scripts folder

For Windows, the requested command is:

cd && dir scripts

For macOS or Linux, the requested command is:

pwd && ls -la scripts

This verifies that the shell command is running with ./shell_workspace as its working directory.

Step 4: A Different Thread Sees the Same File

The third call uses a new thread ID:

"shell-thread-2"

Even though this is a different thread, it can still access:

/scripts/hello.py

Why?

Because the file is stored on your real filesystem:

shell-thread-1
      │
      │ writes
      ▼
shell_workspace/scripts/hello.py
      ▲
      │ reads and runs
      │
shell-thread-2

The thread_id can distinguish agent execution or conversation state, but it does not isolate files saved through LocalShellBackend.

Storage type	Shared across threads?	Reason
`StateBackend`	Usually no	Files are stored in thread-associated agent state.
`FilesystemBackend`	Yes	Files are stored on local disk.
`LocalShellBackend`	Yes	It uses real local filesystem storage plus shell execution.

StateBackend is intended for thread-scoped ephemeral files, whereas filesystem-based backends operate on persistent local files. (docs.langchain.com)

Understanding `virtual_mode=True`

Your code uses:

virtual_mode=True

This allows the agent to use clean virtual paths:

/scripts/hello.py

instead of machine-specific paths such as:

C:\Users\YourName\project\shell_workspace\scripts\hello.py

or:

/home/yourname/project/shell_workspace/scripts/hello.py

For filesystem tools, virtual mode treats root_dir as the virtual root and blocks filesystem-tool traversal patterns such as .. and ~.

However, this is critical:

virtual_mode=True does not sandbox shell commands.

An execute command can still potentially access paths outside ./shell_workspace, because host shell execution is unrestricted. (reference.langchain.com)

⚠️ Common Mistakes to Avoid

1. Assuming `root_dir` makes shell commands safe

This is not a security boundary:

LocalShellBackend(
    root_dir="./shell_workspace",
    virtual_mode=True,
)

It organizes file operations under the workspace, but shell commands can still access other host locations.

2. Exposing this agent to public users

Do not attach this backend directly to:

Public web applications
REST APIs
Telegram, Discord, or Slack bots
Shared servers
Multi-user SaaS products
User-submitted prompt workflows

Untrusted prompts can influence an agent to run unsafe commands.

3. Keeping secrets inside the workspace

Avoid this structure:

shell_workspace/
├── .env
├── credentials.json
├── private_key.pem
└── scripts/

Keep API keys and credentials outside the agent-accessible workspace whenever possible.

4. Assuming `python` works on every computer

Your code asks the agent to run:

python scripts/hello.py

This may fail on some machines:

Environment	Possible command
Windows	`python scripts/hello.py`
macOS/Linux	`python3 scripts/hello.py`
Virtual environment	Path to that environment’s Python interpreter

If python is unavailable in the shell, update the prompt to use:

python3 scripts/hello.py

A more portable advanced approach is to pass sys.executable into the prompt so the agent uses the exact Python interpreter that launched your script.

Optional Improvement: Add Execution Limits

Your current code uses the default shell execution settings. According to the current backend reference, the default timeout is 120 seconds and the default captured-output limit is 100,000 bytes. (docs.langchain.com)

For safer local experimentation, you can update the backend configuration:

agent = create_deep_agent(
    model=model,
    backend=LocalShellBackend(
        root_dir="./shell_workspace",
        virtual_mode=True,
        timeout=20,
        max_output_bytes=20_000,
    ),
)

Setting	Purpose
`timeout=20`	Stops commands that run longer than 20 seconds.
`max_output_bytes=20_000`	Prevents extremely large command output from being captured.

These settings reduce accidental resource usage, but they do not turn LocalShellBackend into a sandbox.

Final Takeaway

Your script demonstrates this workflow:

Agent writes code
      ↓
Code is saved on real disk
      ↓
Agent executes code on your host machine
      ↓
Agent reads and inspects files later
      ↓
Another thread accesses the same real files

✅ Use this pattern for

Trusted local coding experiments
Personal development tools
Internal developer workflows
Controlled CI environments with careful secret handling

❌ Do not use this pattern for

Public APIs
Production web applications
Shared servers
Multi-tenant applications
Untrusted users or user-provided code

For a project that needs isolated code execution, use a proper sandbox, container, or VM-based backend rather than LocalShellBackend. (reference.langchain.com)

Understanding FilesystemBackend in LangChain's Deep Agents

Syeed Talha — Fri, 24 Jul 2026 09:46:30 +0000

In a previous example, we used StateBackend, where files belonged to a specific LangGraph conversation thread.

This time, we are using something different:

FilesystemBackend lets a Deep Agent read and write real files on your machine.

That means if the agent creates a Markdown file, Python file, or project folder, it remains on your disk even after the script finishes.

This is useful for local coding assistants, document-generation tools, and development workflows. But because the agent can modify real files, it must be used carefully.

What This Example Demonstrates

The code shows four important behaviors:

The agent writes files to a real folder on disk.
Those files remain after the Python program stops.
thread_id does not isolate files when using local disk storage.
CompositeBackend can keep temporary agent artifacts separate from your real project files.

Here is the high-level comparison:

StateBackend
────────────
Thread A → temporary files for Thread A
Thread B → separate temporary files for Thread B

FilesystemBackend
─────────────────
Thread A ─┐
          ├── same real folder on your computer
Thread B ─┘

With FilesystemBackend, files are not stored inside LangGraph state. They are regular operating-system files under a configured directory. (docs.langchain.com)

The Full Example

"""
Demonstrates Deep Agents' FilesystemBackend (real files on disk).

What you will observe:
1. The agent writes real files to disk under a root_dir.
2. Files persist after the Python process ends — inspect them.
3. Thread isolation does NOT apply (files are real OS files).
4. CompositeBackend keeps internal agent artifacts out of your project.
"""

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, FilesystemBackend, StateBackend
from langchain.chat_models import init_chat_model
from dotenv import load_dotenv

load_dotenv()

model = init_chat_model(
    "openrouter:nvidia/nemotron-3-super-120b-a12b",
    max_tokens=4096,
)


# ---------------------------------------------------------
# 1. FilesystemBackend (standalone) — writes under a root_dir
# ---------------------------------------------------------
# Files go to real disk under ./agent_workspace/ on your machine.
agent = create_deep_agent(
    model=model,
    backend=FilesystemBackend(
        root_dir="./agent_workspace",
        virtual_mode=True,
    ),
)


def run(thread_id: str, prompt: str):
    result = agent.invoke(
        {"messages": [{"role": "user", "content": prompt}]},
        config={"configurable": {"thread_id": thread_id}},
    )
    print("\n" + "=" * 70)
    print(f"THREAD: {thread_id}")
    print("=" * 70)
    print(result["messages"][-1].content)


# ---------------------------------------------------------
# Turn 1 — write a real file
# ---------------------------------------------------------
run(
    "demo-thread-1",
    """
Use the write_file tool to create a file:

Path: /notes/todo.md

Content:
# To-do
- Buy groceries
- Finish the project
- Review pull requests

After writing:
1. Use ls to confirm it exists.
2. Tell me the absolute OS path where this file was written.
""",
)


# ---------------------------------------------------------
# Turn 2 — same thread reads it back
# ---------------------------------------------------------
run(
    "demo-thread-1",
    """
Use read_file to read /notes/todo.md.
Then list the three to-do items.
""",
)


# ---------------------------------------------------------
# Turn 3 — different thread ALSO sees the file
# ---------------------------------------------------------
# Unlike StateBackend, files are real OS files — they are NOT
# isolated by thread_id. Any thread can read any file.
run(
    "demo-thread-2",
    """
Use ls to inspect the filesystem.
Can you find /notes/todo.md? Read it and report its contents.
""",
)

print("\n" + "=" * 70)
print("Files written to: ./agent_workspace/ -- check with:")
print("  dir agent_workspace\\notes\\")
print("  type agent_workspace\\notes\\todo.md")
print("=" * 70)


# ---------------------------------------------------------
# 2. CompositeBackend (recommended for real projects)
# ---------------------------------------------------------
# Internal agent artifacts (large tool results, conversation
# history) go to ephemeral StateBackend. Only files under
# /workspace/ hit real disk.
print("\n" + "=" * 70)
print("COMPOSITE BACKEND (recommended pattern)")
print("=" * 70)

agent2 = create_deep_agent(
    model=model,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/workspace/": FilesystemBackend(
                root_dir="./my_project",
                virtual_mode=True,
            ),
        },
    ),
)

result = agent2.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "Write a file at path /workspace/src/hello.py "
                    "with content: print('hello from FilesystemBackend'). "
                    "Then confirm it exists via ls."
                ),
            }
        ]
    },
    config={"configurable": {"thread_id": "composite-demo"}},
)
print(result["messages"][-1].content)
print("\nFile written to: ./my_project/src/hello.py")

Before You Run the Code

Install the required packages:

pip install deepagents langchain langgraph python-dotenv

You also need your model provider credentials configured. Since this example uses OpenRouter, place your API key in a .env file:

OPENROUTER_API_KEY=your_api_key_here

The call to load_dotenv() loads environment variables from that file:

from dotenv import load_dotenv

load_dotenv()

Do not commit .env files containing real API keys to GitHub.

The Important Difference: Real Disk vs Agent State

Before studying the code, understand this difference.

Feature	`StateBackend`	`FilesystemBackend`
Where files live	LangGraph state	Your computer’s filesystem
Survives script restart	No, with `InMemorySaver`	Yes
Isolated by `thread_id`	Yes	No
Good for	Temporary agent artifacts	Local projects and durable output
Risk level	Lower	Higher
Can affect real project files	No	Yes

FilesystemBackend reads and writes directly to the local filesystem. It is intended for controlled local development or carefully configured CI/CD workflows—not directly exposed web applications or multi-user APIs. (reference.langchain.com)

Step 1: Creating the Model

model = init_chat_model(
    "openrouter:nvidia/nemotron-3-super-120b-a12b",
    max_tokens=4096,
)

This creates the language model used by the Deep Agent.

The max_tokens=4096 argument limits the size of generated responses. This is practical when using paid APIs because it helps control token usage and cost.

You can use another supported model later. The storage behavior explained in this article comes from the backend configuration, not from the model itself.

Step 2: Creating a `FilesystemBackend`

Here is the most important part of the first agent:

agent = create_deep_agent(
    model=model,
    backend=FilesystemBackend(
        root_dir="./agent_workspace",
        virtual_mode=True,
    ),
)

This tells the agent:

Use the agent_workspace folder as the location for real file operations.

When the agent receives this virtual path:

/notes/todo.md

it maps to a real path similar to this:

your-project-folder/
└── agent_workspace/
    └── notes/
        └── todo.md

The exact full path depends on where you run your Python script.

For example, if your project is located at:

C:\Users\Talha\deep-agents-demo

the final file could be:

C:\Users\Talha\deep-agents-demo\agent_workspace\notes\todo.md

On macOS or Linux, it could look like:

/home/talha/deep-agents-demo/agent_workspace/notes/todo.md

Why Use `virtual_mode=True`?

virtual_mode=True

This is an important safety setting.

It lets the agent use clean virtual paths such as:

/notes/todo.md

while mapping them underneath the configured root_dir.

It also blocks common path-escape attempts such as:

../../some-other-folder/file.txt

or:

~/secret-file.txt

However, this is not full sandboxing. It provides path-based restrictions, but it does not isolate the Python process like a container or remote sandbox would. The official Deep Agents documentation recommends using virtual_mode=True together with a configured root directory. (reference.langchain.com)

A Small Improvement: Use an Absolute `root_dir`

For beginner projects, this works:

root_dir="./agent_workspace"

But using an absolute path makes your code more predictable, especially if you run the script from different directories.

Here is a slightly safer version:

from pathlib import Path

workspace_dir = Path("./agent_workspace").resolve()

agent = create_deep_agent(
    model=model,
    backend=FilesystemBackend(
        root_dir=workspace_dir,
        virtual_mode=True,
    ),
)

Now workspace_dir becomes a complete OS path automatically.

For example:

C:\Users\Talha\deep-agents-demo\agent_workspace

or:

/home/talha/deep-agents-demo/agent_workspace

Step 3: The `run()` Helper Function

The helper function invokes the agent:

def run(thread_id: str, prompt: str):
    result = agent.invoke(
        {"messages": [{"role": "user", "content": prompt}]},
        config={"configurable": {"thread_id": thread_id}},
    )

The thread_id is still passed to LangGraph:

config={"configurable": {"thread_id": thread_id}}

But with FilesystemBackend, the file itself does not belong to the thread.

This is a crucial distinction:

thread_id controls conversation/checkpoint state
root_dir controls real file location

The thread can affect conversation memory, but a file written to disk is visible to anything that has permission to access that disk location.

Turn 1: Writing a Real Markdown File

The first prompt asks the agent to create:

/notes/todo.md

with this content:

# To-do
- Buy groceries
- Finish the project
- Review pull requests

Because the backend root directory is:

./agent_workspace

the actual file becomes:

./agent_workspace/notes/todo.md

The agent should then call ls to confirm that the file exists.

Conceptually, the filesystem now looks like this:

agent_workspace/
└── notes/
    └── todo.md

Unlike StateBackend, this file is not temporary agent state. It is a real file created on your computer.

Turn 2: Reading the File Again

The second call uses the same thread:

run(
    "demo-thread-1",
    ...
)

The agent reads:

/notes/todo.md

and should report:

Buy groceries
Finish the project
Review pull requests

At this point, it may look similar to the StateBackend example. But the reason the file is available is different.

With StateBackend, the same thread ID matters because files are stored in thread state.

With FilesystemBackend, the file is available because it physically exists in:

./agent_workspace/notes/todo.md

The agent could read it even after restarting the Python script, as long as the file is still on disk.

Turn 3: A Different Thread Can Read the Same File

Now notice this call:

run(
    "demo-thread-2",
    ...
)

The code uses a different thread ID:

demo-thread-2

But the agent can still find and read:

/notes/todo.md

Why?

Because both threads point to the same real directory:

./agent_workspace

Here is the flow:

Thread: demo-thread-1
        │
        │ writes
        ▼
agent_workspace/notes/todo.md
        ▲
        │ reads
        │
Thread: demo-thread-2

This means thread_id is not a filesystem security boundary when using FilesystemBackend.

If two agents use the same FilesystemBackend root directory, they can access the same files—subject to operating-system permissions and the backend configuration.

Verifying the File Yourself

Your code prints these Windows commands:

dir agent_workspace\notes\
type agent_workspace\notes\todo.md

Run them in Command Prompt:

dir agent_workspace\notes\
type agent_workspace\notes\todo.md

Expected output:

# To-do
- Buy groceries
- Finish the project
- Review pull requests

For PowerShell, you can use:

Get-ChildItem .\agent_workspace\notes\
Get-Content .\agent_workspace\notes\todo.md

For macOS or Linux:

ls agent_workspace/notes/
cat agent_workspace/notes/todo.md

This is a helpful test because it proves that the file exists independently of the agent and the Python process.

Why `CompositeBackend` Is Better for Real Projects

The second part of the code introduces this:

CompositeBackend(
    default=StateBackend(),
    routes={
        "/workspace/": FilesystemBackend(
            root_dir="./my_project",
            virtual_mode=True,
        ),
    },
)

This is a hybrid approach.

It says:

Use StateBackend for most agent files.
Use real disk only for paths beginning with /workspace/.

Here is the routing idea:

Agent path                         Backend used
────────────────────────────────────────────────────
/workspace/src/hello.py            FilesystemBackend
/tmp/tool-output.txt               StateBackend
/internal/agent-notes.md           StateBackend

And visually:

                         CompositeBackend
                                │
                 ┌──────────────┴──────────────┐
                 │                             │
      /workspace/... paths               All other paths
                 │                             │
                 ▼                             ▼
      FilesystemBackend                  StateBackend
       ./my_project/                  temporary state

CompositeBackend routes file operations by path prefix. A matching route sends the operation to that backend; paths that do not match a route use the default backend. (reference.langchain.com)

Understanding the `/workspace/` Route

This configuration:

routes={
    "/workspace/": FilesystemBackend(
        root_dir="./my_project",
        virtual_mode=True,
    ),
},

means that this agent path:

/workspace/src/hello.py

will become a real file at:

./my_project/src/hello.py

The agent prompt says:

"Write a file at path /workspace/src/hello.py "
"with content: print('hello from FilesystemBackend'). "
"Then confirm it exists via ls."

After the agent finishes, your project folder should contain:

my_project/
└── src/
    └── hello.py

The contents of hello.py should be:

print("hello from FilesystemBackend")

Why Keep Internal Files in `StateBackend`?

Deep Agents can create temporary artifacts while working, such as:

Large tool results
Intermediate research notes
Planning files
Conversation-related artifacts
Temporary generated content

You may not want these files to appear in your actual source-code project.

That is why this pattern is useful:

default=StateBackend()

Only explicit project output goes to disk:

/workspace/...

Everything else remains temporary and isolated in agent state.

This creates a cleaner project directory and reduces the chance that internal agent artifacts are mixed with your application files.

`FilesystemBackend` vs `CompositeBackend`

Question	Standalone `FilesystemBackend`	`CompositeBackend`
Where do files go?	One real disk folder	Different locations based on path
Are all agent files written to disk?	Usually yes	Only selected routes
Can temporary artifacts stay ephemeral?	No, not by default	Yes
Best for	Small local experiments	Real development workflows
Project-folder cleanliness	Can become messy	Easier to control
Configuration complexity	Simple	Slightly more advanced

For a quick experiment, use FilesystemBackend.

For a project where you want the agent to create real source files but keep its internal work temporary, use CompositeBackend.

Important Safety Warning

FilesystemBackend is powerful because it gives an AI agent access to real files.

That also makes it risky.

The official documentation warns that agents using this backend may be able to read accessible secrets such as .env files, API keys, or credentials, and that file changes are permanent. It is intended for controlled local development and carefully managed CI/CD environments—not public web servers, multi-tenant apps, or untrusted user input. (reference.langchain.com)

Avoid These Mistakes

1. Do not point the agent at your entire computer

Avoid this:

FilesystemBackend(
    root_dir="C:/",
    virtual_mode=True,
)

Or on macOS/Linux:

FilesystemBackend(
    root_dir="/",
    virtual_mode=True,
)

Instead, create a dedicated workspace:

FilesystemBackend(
    root_dir="./agent_workspace",
    virtual_mode=True,
)

2. Do not expose secrets inside the workspace

Avoid placing files like these inside the folder available to the agent:

.env
credentials.json
private_key.pem
config.production.json

A safer project structure might look like:

my-app/
├── .env                    # Keep outside agent workspace
├── app/
├── agent_workspace/        # Agent can access this
└── run_agent.py

3. Do not use it directly in a public API

If users can send prompts to an agent through a website, avoid giving that agent direct access to your host machine’s filesystem.

For production systems, prefer:

StateBackend for temporary per-thread files
StoreBackend for durable managed storage
A sandbox backend for isolated execution environments

Deep Agents specifically recommends safer state, store, or sandbox alternatives for web servers and HTTP APIs. (reference.langchain.com)

4. Do not treat `thread_id` as access control

This is unsafe thinking:

“My files are secure because each user has a different thread_id.”

That is true for StateBackend, but not for a shared FilesystemBackend.

If different users, agents, or processes share the same disk folder, they may see the same files.

Use proper authentication, authorization, per-user directories, and operating-system permissions in real applications.

A Recommended Project Structure

For experimenting safely, use a layout like this:

deepagents-filesystem-demo/
│
├── .env
├── filesystem_demo.py
│
├── agent_workspace/
│   └── notes/
│       └── todo.md
│
└── my_project/
    └── src/
        └── hello.py

You can also add these generated folders to .gitignore:

# Agent-generated workspace files
agent_workspace/

# Add this only if you do not want generated project files in Git
# my_project/

# Never commit environment secrets
.env

Final Takeaway

FilesystemBackend allows a Deep Agent to work with files that truly exist on your machine.

The core idea is:

StateBackend
→ files are temporary and tied to a LangGraph thread

FilesystemBackend
→ files are real, persistent, and shared through the operating system

For simple local experiments:

FilesystemBackend(
    root_dir="./agent_workspace",
    virtual_mode=True,
)

For more organized real-world projects:

CompositeBackend(
    default=StateBackend(),
    routes={
        "/workspace/": FilesystemBackend(
            root_dir="./my_project",
            virtual_mode=True,
        )
    }
)

This hybrid approach gives you the best of both worlds:

real project files where you want them;
temporary agent artifacts kept out of your project folder.

Understanding StateBackend in LangChain's Deep Agents

Syeed Talha — Fri, 24 Jul 2026 09:08:40 +0000

When building an AI agent, you may want it to create a file in one conversation turn and use that same file later.

For example:

Turn 1: The agent writes study notes.
Turn 2: The agent reads those notes and answers questions about them.
Turn 3: A different user/session should not be able to access those notes.

This is exactly what Deep Agents’ StateBackend is designed for.

In this tutorial, we will walk through a small Python example that demonstrates how StateBackend, LangGraph checkpoints, and thread_id work together.

What You Will Learn

By the end of this article, you will understand:

What StateBackend is.
Why a LangGraph checkpointer is needed.
How thread_id separates one agent session from another.
Why the same thread can access a file in later turns.
Why another thread cannot see that file.
Why InMemorySaver is useful for testing but not production.

The Main Idea

Think of a thread_id as a unique conversation workspace.

Each workspace can have:

Conversation history
Agent state
Files created through StateBackend

Here is the concept visually:

                    ┌──────────────────────────────┐
                    │      InMemorySaver            │
                    │   (stores LangGraph state)    │
                    └──────────────┬───────────────┘
                                   │
             ┌─────────────────────┴─────────────────────┐
             │                                           │
             ▼                                           ▼
┌───────────────────────────┐              ┌───────────────────────────┐
│ thread_id:                │              │ thread_id:                │
│ talha-learning-thread     │              │ another-user-thread       │
│                           │              │                           │
│ StateBackend files:       │              │ StateBackend files:       │
│ /learning/python_notes.md │              │ (empty)                   │
└───────────────────────────┘              └───────────────────────────┘

The important rule is:

Files written with StateBackend belong to the current LangGraph thread.

So, when the same thread_id is used again, the agent can access its previous files. When a different thread_id is used, it receives a separate state and cannot access files from the first thread.

Deep Agents documents StateBackend as a thread-scoped backend: files are stored in agent state, persist across turns through checkpoints, and are not shared between threads. (docs.langchain.com)

The Complete Example

Here is the code:

"""
Demonstrates Deep Agents' StateBackend.

What you will observe:
1. Turn 1 writes a file.
2. Turn 2 reads that same file using the SAME thread_id.
3. Turn 3 uses a DIFFERENT thread_id and cannot see the file.
"""

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from langgraph.checkpoint.memory import InMemorySaver
from langchain.chat_models import init_chat_model

from dotenv import load_dotenv

load_dotenv()


# ---------------------------------------------------------
# 1. Create an in-memory checkpointer
# ---------------------------------------------------------
# The checkpointer saves LangGraph state between agent calls.
#
# InMemorySaver is useful for local experiments.
# Its data disappears when this Python program stops.
checkpointer = InMemorySaver()


# ---------------------------------------------------------
# 2. Create the model with a max_tokens cap
# ---------------------------------------------------------
# This prevents the model response from using too many tokens.
model = init_chat_model(
    "openrouter:nvidia/nemotron-3-super-120b-a12b",
    max_tokens=4096,
)


# ---------------------------------------------------------
# 3. Create the agent with StateBackend
# ---------------------------------------------------------
# StateBackend is the default Deep Agents backend,
# but we specify it explicitly for learning purposes.
agent = create_deep_agent(
    model=model,
    backend=StateBackend(),
    checkpointer=checkpointer,
)


def run_agent(thread_id: str, prompt: str):
    """
    Run one agent turn for a specific conversation thread.

    StateBackend files are separated by thread_id.
    """

    config = {
        "configurable": {
            "thread_id": thread_id,
        }
    }

    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": prompt,
                }
            ]
        },
        config=config,
    )

    print("\n" + "=" * 70)
    print(f"THREAD ID: {thread_id}")
    print("=" * 70)
    print(result["messages"][-1].content)

    return result


# =========================================================
# TURN 1: Write a file into StateBackend
# =========================================================
run_agent(
    thread_id="talha-learning-thread",
    prompt="""
Use the write_file tool to create this file:

Path: /learning/python_notes.md

Content:
# Python StateBackend Notes

- StateBackend behaves like a temporary filesystem.
- Files belong to a LangGraph thread.
- The same thread can access files in later turns.

After writing the file:
1. Use ls to confirm the file exists.
2. Reply with a short confirmation.
""",
)


# =========================================================
# TURN 2: Read the file from the SAME thread
# =========================================================
run_agent(
    thread_id="talha-learning-thread",
    prompt="""
Use read_file to read /learning/python_notes.md.

Then answer these questions:
1. What is the first bullet point?
2. Why can you read this file now?

Do not recreate or rewrite the file.
""",
)


# =========================================================
# TURN 3: Try to access the file from a DIFFERENT thread
# =========================================================
run_agent(
    thread_id="another-user-thread",
    prompt="""
Use ls to inspect the filesystem.

Can you find /learning/python_notes.md?
Explain why or why not. Do not create any files.
""",
)

Understanding the Three Important Pieces

This example has three main building blocks:

Component	Purpose
`StateBackend()`	Gives the agent a virtual, thread-scoped file workspace.
`InMemorySaver()`	Saves the agent’s LangGraph state between calls while the Python process is running.
`thread_id`	Identifies the conversation/session whose state should be loaded.

In short:

thread_id tells LangGraph which saved state to load
            ↓
checkpointer loads that state
            ↓
StateBackend makes that thread's files available to the agent

LangGraph uses thread_id as the primary key for saving and retrieving checkpoints. Without a thread ID, a checkpointer cannot reliably load state from a previous invocation. (reference.langchain.com)

Step 1: Creating the Checkpointer

checkpointer = InMemorySaver()

A checkpointer is responsible for preserving the agent’s state between calls.

Without a checkpointer, this sequence would not work reliably:

Call 1 → agent writes a file
Call 2 → agent starts with no saved state

With a checkpointer:

Call 1 → agent writes a file → state is saved
Call 2 → saved state is loaded → file is available

InMemorySaver stores checkpoints in Python memory. It is useful for debugging, tutorials, and local experiments, but its contents disappear when the process ends. LangGraph recommends using a durable checkpointer, such as a database-backed option, for production use. (reference.langchain.com)

Step 2: Creating the Model

model = init_chat_model(
    "openrouter:nvidia/nemotron-3-super-120b-a12b",
    max_tokens=4096,
)

This code initializes an LLM through OpenRouter.

The max_tokens=4096 setting limits the maximum response size. This is useful because model providers may allow very large output limits by default, which can increase cost or exceed account limits.

You can replace this model with another supported chat model if needed. The StateBackend behavior does not depend on the specific model provider.

Step 3: Creating a Deep Agent with `StateBackend`

agent = create_deep_agent(
    model=model,
    backend=StateBackend(),
    checkpointer=checkpointer,
)

This is where the agent receives:

A language model
A backend for file operations
A checkpointer for preserving state

StateBackend is already the default backend in Deep Agents, so this would also work:

agent = create_deep_agent(
    model=model,
    checkpointer=checkpointer,
)

However, explicitly writing backend=StateBackend() is a good teaching choice because it makes the storage behavior visible.

Step 4: Why `run_agent()` Matters

The helper function accepts two values:

def run_agent(thread_id: str, prompt: str):

thread_id: identifies the session
prompt: tells the agent what to do

The most important part is the LangGraph configuration:

config = {
    "configurable": {
        "thread_id": thread_id,
    }
}

Every time you call the agent, this configuration tells LangGraph:

Load and continue the state associated with this thread.

Then the agent runs:

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": prompt,
            }
        ]
    },
    config=config,
)

The config object is what connects one call to the state from an earlier call.

Turn 1: Writing a File

The first call uses this thread ID:

thread_id="talha-learning-thread"

The prompt tells the agent to create:

/learning/python_notes.md

with this content:

# Python StateBackend Notes

- StateBackend behaves like a temporary filesystem.
- Files belong to a LangGraph thread.
- The same thread can access files in later turns.

The agent should use its file tool to write the file, then use ls to verify that it exists.

Conceptually, the result is:

Thread: talha-learning-thread

/
└── learning/
    └── python_notes.md

At the end of the turn, LangGraph saves the thread’s updated state through InMemorySaver.

Turn 2: Reading the Same File

The second call uses the same thread ID:

thread_id="talha-learning-thread"

This is the reason the agent can read the file created in Turn 1.

Turn 1
  thread_id = talha-learning-thread
  file created
          ↓
  state saved by InMemorySaver
          ↓
Turn 2
  thread_id = talha-learning-thread
  same state loaded
  file is available

The agent is asked to read:

/learning/python_notes.md

It should then answer:

What is the first bullet point?

StateBackend behaves like a temporary filesystem.
Why can you read this file now?

Because the same thread_id was used, so LangGraph restored the previously saved state for that thread.

This is not the same as writing to your computer’s actual disk. The file is stored in the agent’s state, not automatically in a local folder on your machine. StateBackend is intended for thread-scoped agent files, while FilesystemBackend is the option that accesses real files under a configured local directory. (docs.langchain.com)

Turn 3: Using a Different Thread

The third call changes the ID:

thread_id="another-user-thread"

This creates or loads a completely separate state.

Thread A: talha-learning-thread
├── /learning/python_notes.md
└── conversation history from Turns 1 and 2

Thread B: another-user-thread
├── no files from Thread A
└── separate conversation state

When the agent runs ls in the second thread, it should not find:

/learning/python_notes.md

Why?

Because StateBackend files are tied to a specific LangGraph thread. The second thread has its own state and cannot access Thread A’s files. This thread-level separation is a core behavior of StateBackend. (docs.langchain.com)

Expected Outcome

Your exact wording may differ because an LLM generates the final response, but the behavior should look like this:

Turn	Thread ID	Expected Result
Turn 1	`talha-learning-thread`	The file is created and appears in `ls`.
Turn 2	`talha-learning-thread`	The agent reads the file and answers from its contents.
Turn 3	`another-user-thread`	The file is not found because this is a separate thread.

The key observation is simple:

Same thread_id      → same state → file is visible
Different thread_id → different state → file is not visible

`StateBackend` vs Local Files

A common beginner mistake is assuming StateBackend writes files to your laptop.

It does not.

Here is the difference:

Feature	`StateBackend`	`FilesystemBackend`
Storage location	LangGraph agent state	Your real local filesystem
Scope	Current thread	Configured local directory
Persists across turns	Yes, with a checkpointer	Yes, because files are on disk
Persists after Python program exits	Not with `InMemorySaver`	Usually yes
Best use case	Agent scratch files and intermediate work	Controlled local development workflows
Safety	Does not directly expose your whole disk	Requires careful security controls

For temporary agent work, StateBackend is often a safer and simpler choice. If an agent needs true cross-thread durable storage, Deep Agents provides StoreBackend; if it needs real local files, FilesystemBackend can be used carefully. (docs.langchain.com)

Important Limitation: `InMemorySaver` Is Temporary

This line is convenient:

checkpointer = InMemorySaver()

But it has one important limitation:

Python script stops
        ↓
InMemorySaver data is lost
        ↓
Saved thread state and StateBackend files are gone

So if you run the script today, stop it, and run it again tomorrow, the previous file will not exist anymore.

For production applications, you would normally use a persistent checkpointer backed by a database or managed service.

Common Mistakes to Avoid

1. Changing the `thread_id` accidentally

This will create a separate workspace:

run_agent(
    thread_id="new-thread",
    prompt="Read /learning/python_notes.md",
)

Even though the file was created earlier, it will not be visible because the thread is different.

2. Expecting files after restarting the program

With InMemorySaver, this will not work:

Run script → create file
Stop script
Run script again → try to read file

The in-memory data was removed when the Python process stopped.

3. Treating `thread_id` as authentication

A thread_id is a state identifier, not a complete security system.

In a real multi-user application:

Authenticate the user.
Authorize access on the server.
Generate non-guessable thread IDs.
Associate each thread with its owner.
Do not allow users to submit arbitrary thread IDs without validation.

Thread isolation is useful, but it should be part of a larger access-control design.

4. Assuming the agent will always follow instructions perfectly

The agent is driven by an LLM, so responses may vary slightly between runs.

For example, the agent may phrase its confirmation differently. However, the central behavior should remain the same:

It writes the file in Turn 1.
It reads it in Turn 2 using the same thread.
It cannot access it from the different thread in Turn 3.

When Should You Use `StateBackend`?

Use StateBackend when your agent needs short-term, thread-specific files such as:

Research notes
Intermediate summaries
Generated Markdown documents
Large tool outputs
Temporary plans
Multi-step task artifacts
Files shared between an agent and its subagents in the same workflow

A practical example:

Turn 1: Agent researches a topic and saves findings to /research/notes.md
Turn 2: Agent reads notes and writes a blog post
Turn 3: Agent reads the blog post and creates a social-media summary

As long as all turns use the same thread_id, the agent can continue using those files.

Final Takeaway

StateBackend gives a Deep Agent a virtual filesystem that belongs to its current LangGraph thread.

The behavior in this example can be summarized in one sentence:

A file written by an agent remains available in later turns only when the same thread_id and saved LangGraph state are used.

StateBackend + Checkpointer + Same thread_id
                    =
Files available across agent turns

For local learning and experimentation, InMemorySaver is a great starting point. When you move to production, replace it with persistent storage and add proper user authentication and thread ownership checks.

Understanding Interpreters in LangChain Deep Agents

Syeed Talha — Thu, 23 Jul 2026 10:39:24 +0000

If you've built even a basic agent, you know the rhythm. Model wants to do something, it calls a tool, the result comes back, the model reads it and decides what's next. Every single one of those round trips goes through the model, and every result lands in the conversation history whether the model needed to see the raw data or not.

That's fine for one or two tool calls. It gets clunky fast once the agent needs to loop over ten items, combine a few results, retry something that failed, or do plain computation like sorting a list. Doing that one call at a time is slow, and it stuffs the model's context with numbers and text nobody actually needed to read.

This is the problem interpreters in Deep Agents are meant to fix.

What an interpreter actually is

An interpreter gives the agent a small programmable workspace, a bit like a scratchpad, where it can write and run real JavaScript. Under the hood this runs on QuickJS, a lightweight JS engine embedded directly in the same Python process. Nothing gets written to disk, no separate process gets spawned. The code lives in memory, runs in memory, and only the final result comes back to the model.

That last detail is the whole point. Instead of the model calling a tool, waiting, reading the result, deciding on the next step, and repeating that a few times, it writes one piece of code that does the looping, sorting, and combining by itself. The model only sees the answer.

One way to keep it straight: a sandbox lets an agent touch the outside world, running shell commands, editing real files. An interpreter lets an agent work inside its own reasoning, keeping the messy intermediate steps out of the context window entirely.

How the flow actually changes

It helps to see the two approaches side by side, step by step, for something as simple as checking three scores and finding the winner.

Without an interpreter, one tool call at a time:

Model calls get_score("alpha")
Result comes back, gets added to the conversation
Model calls get_score("beta")
Result comes back, added again
Model calls get_score("gamma")
Result comes back, added again
Model reads all three, does the comparison itself, writes the answer

That's seven steps, three of which are pure round trips through the model just to fetch numbers it isn't going to reason about deeply, it's just going to compare them.

With an interpreter:

Model calls eval once, with a short script
Inside that script, all three get_score calls happen, along with the sort and the subtraction
Only the final sentence comes back out of eval
Model reads that sentence and replies

Same task, one tool call from the model's point of view instead of three, and none of the raw scores ever touch the conversation history. The looping and comparing happen where they belong, in code, not in the model's head.

Adding one to an agent

Getting an interpreter attached to an agent takes very little setup. Install the package, then add the middleware when you create the agent.

pip install deepagents langchain-quickjs

from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="openai:gpt-5.4",
    middleware=[CodeInterpreterMiddleware()],
)

That single line of middleware adds one new tool called eval to the agent. You never call it yourself, the model calls it when it decides writing code is the better way to handle whatever you asked for.

Letting the interpreter use your tools

On its own, an interpreter can do math, sort arrays, and reshape data that's already in front of it, but nothing else. Most real agents need to reach outside for that, checking a database or hitting an API. This is what programmatic tool calling, PTC for short, is for.

PTC lets you pick specific tools the interpreter is allowed to call directly from its code, instead of only through the model. Here's a small working example.

from langchain.tools import tool
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

from dotenv import load_dotenv
load_dotenv()

@tool
def get_score(team: str) -> str:
    """Get the score for a team."""
    scores = {"alpha": 42, "beta": 78, "gamma": 55}
    return str(scores.get(team.lower(), 0))

agent = create_deep_agent(
    model="openrouter:nvidia/nemotron-3-super-120b-a12b",
    tools=[get_score],
    middleware=[
        CodeInterpreterMiddleware(ptc=["get_score"])
    ],
    system_prompt=(
        "Use the eval tool to write JavaScript. "
        "Call tools.getScore({team}) with await when you need a score."
    ),
)

result = agent.invoke(
    {"messages": [("user",
        "Check scores for alpha, beta, and gamma. "
        "Tell me the winner and the margin."
    )]},
    config={"configurable": {"thread_id": "demo-1"}},
)

for m in result["messages"]:
    if m.type == "ai" and m.content:
        print(m.content)

A couple of details worth pointing out. ptc=["get_score"] is an allowlist, it tells the interpreter exactly which tools it's permitted to touch from JavaScript and nothing beyond that. Once a tool is on the list, its name gets converted to camel case automatically for use in code, so get_score in Python becomes tools.getScore in JavaScript.

What actually happens when you run this

Walking through it in order helps make the invisible part visible:

The user message goes to the model.
The model decides this needs code, not three separate tool calls, and calls eval with a script.
Inside that script, tools.getScore runs three times, once per team, all inside the sandboxed JS environment.
The script sorts the results and builds a sentence naming the winner and the margin.
That sentence is the only thing eval returns.
The model receives that single string and turns it into a reply.

The generated script looks something like this:

const teams = ["alpha", "beta", "gamma"];
const scores = await Promise.all(
  teams.map(async t => ({
    team: t,
    score: parseInt(await tools.getScore({ team: t }))
  }))
);
scores.sort((a, b) => b.score - a.score);
`${scores[0].team} wins by ${scores[0].score - scores[1].score}`;

All three lookups, the sort, and the subtraction happen inside that one call. None of it shows up in the conversation history, only the final sentence does.

A checklist before you wire this into your own agent

If you're trying this for the first time, a few things are worth checking before you assume something's broken:

Confirm the tool you want to expose is passed both to tools=[...] on the agent and listed in ptc=[...] on the middleware. Missing either one means the interpreter won't see it.
Remember the camelCase conversion. If your Python tool is get_user_orders, the interpreter expects tools.getUserOrders, not the snake_case version.
Mention the tool names in your system prompt, in camelCase, the way the example does. The model doesn't automatically know it should reach for eval instead of calling the tool directly.
If a script fails, check whether the tool call inside it was awaited. Tool calls from PTC are asynchronous, forgetting await is the most common reason results come back as pending promises instead of values.
Keep the scripts small and single-purpose at first. It's easier to debug a ten-line script that does one job than a fifty-line one that tries to do everything.

Why bother with this at all

The benefit is obvious once you picture the alternative. Without an interpreter, checking three scores and comparing them takes three tool calls, each needing its own round trip through the model before the next step can start. With the interpreter, it's one call to eval, with three calls tucked away inside the code it runs. Fewer round trips, less clutter in the context window, and the model spends its attention on the actual answer instead of bookkeeping.

This matters more as the task grows. Looping over fifty records, running several searches at once, retrying a failed call, keeping a running total across many steps, these are all awkward to do one tool call at a time but completely natural as a short program.

A common misunderstanding worth clearing up

It's easy to assume that because the interpreter runs code, it must also be able to save files, generate images, or produce something like a PDF. It can't, and that's intentional. By default an interpreter has no filesystem access and no network access. It's a sandboxed space for computation and for calling a short, explicit list of tools, nothing more. If a task needs to produce a real file someone can open, that's a job for a sandbox backend, a separate part of the Deep Agents toolkit built specifically for touching real files or running real commands.

The one line summary

An interpreter is a private scratchpad the model can write code into. It lets an agent think in loops, conditions, and function calls instead of one slow tool call at a time, and it keeps the intermediate mess out of the conversation so only the answer that matters comes back to you.

Understanding Middleware in Deep Agents (With Runnable Examples)

Syeed Talha — Wed, 22 Jul 2026 12:49:29 +0000

If you've built even a simple AI agent, you've probably noticed that the "agent loop" itself is deceptively simple: the model gets a message, decides whether to call a tool, gets the result back, and repeats until it has an answer. But real-world agents need a lot more than that bare loop to actually work well.

What happens when a conversation gets so long it blows past the model's context window? What if a tool call gets interrupted halfway through and leaves your message history in a broken state? What if you want the agent to keep a running todo list of what it's working on, or delegate parts of a task to a specialized sub-agent, or read and write files as part of its job?

You could bolt all of this onto your agent manually. Or, if you're using Deep Agents, you get most of it for free through something called middleware.

This post walks through what middleware actually is, why Deep Agents ships with a default stack of it, and how each piece behaves, with runnable code for each one so you can see it working instead of just reading about it.

So What Is Middleware, Really?

If you've done any web development, the term "middleware" probably already rings a bell. It's the same idea here.

Middleware is code that sits around the core agent loop and gets a chance to run before or after certain things happen, like before a tool call executes, after the model responds, or right before messages are sent to the model. Instead of writing all of this logic directly inside your agent, you attach separate, independent pieces of middleware that each handle one specific concern.

This matters for two reasons:

You don't have to build common behaviors from scratch. Things like managing a todo list, summarizing long conversations, or handling file access are problems almost every non-trivial agent runs into. Deep Agents ships default middleware for these so you don't reinvent them every time.
You can customize behavior without touching the agent's core logic. Need a custom summarization strategy? Want to pause and ask for human approval before certain tool calls run? You add or swap out middleware, and the rest of the agent stays untouched.

Think of it like a pipeline. A request comes in, passes through a stack of middleware (each one doing its own small job), reaches the model, and the response passes back out through that same stack on the way out.

Why Deep Agents Comes With Middleware Already Built In

When you call create_deep_agent, you're not getting a bare-bones agent loop. You're getting an agent that already knows how to track tasks, manage files, spin up sub-agents, keep conversations within context limits, and recover gracefully from interrupted tool calls, all because of a default middleware stack that's assembled for you automatically.

Here's the order that stack runs in, from first to last:

TodoListMiddleware — tracks and manages todo lists for organizing the agent's work
SkillsMiddleware — only enabled when you pass skills; injects skill metadata before filesystem tools run
FilesystemMiddleware — handles reading, writing, editing, searching, and navigating files/directories, including permission enforcement
SubAgentMiddleware — spawns and coordinates sub-agents for delegated tasks
AsyncSubAgentMiddleware — supports asynchronous sub-agents for non-blocking delegated work
MemoryMiddleware — loads persistent instructions or memory, often from files such as AGENTS.md, into the agent context
HumanInTheLoopMiddleware — pauses selected tool calls so a human can approve, edit, or reject an action before it runs
Custom Class-Based Middleware — creates reusable middleware by extending AgentMiddleware and implementing lifecycle hooks
Prebuilt_retry_middleware - automatically retries failed tool calls for temporary errors, using configurable retry limits and delays.

After that, there's room for your own custom middleware, followed by a "tail" of provider-specific extras: things like prompt caching for Anthropic or Bedrock models, memory injection, excluded-tool filtering, and human-in-the-loop approval steps.

The important thing to understand up front is that order matters. Each middleware runs at a specific point for a reason, for example, PatchToolCallsMiddleware needs to run before prompt caching so the cached message prefix actually matches what gets sent to the model. We'll come back to details like this as we go through each piece.

What We'll Cover

Rather than explain all of this in the abstract, the rest of this post goes through each middleware one at a time with a runnable example, so you can actually see:

What it does in practice
When it kicks in (always, or only under certain conditions)
What breaks or gets harder without it

By the end, you should have a clear mental model of what's happening under the hood every time you call create_deep_agent, and enough understanding to start adding your own custom middleware or overriding the defaults when you need something different.

Let's start with the first one in the stack: TodoListMiddleware.

1. TodoListMiddleware

"""
Example: TodoListMiddleware
"""

import os
import sys

sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

from dotenv import load_dotenv
load_dotenv()

from langchain.tools import tool
from langchain_nvidia_ai_endpoints import ChatNVIDIA
from deepagents import create_deep_agent


@tool
def get_weather(city: str) -> str:
    """Get the current weather in a city."""
    return f"The weather in {city} is sunny, 24C."


@tool
def get_time(city: str) -> str:
    """Get the current time in a city."""
    return f"The current time in {city} is 12:00 PM."


@tool
def get_population(city: str) -> str:
    """Get the approximate population of a city."""
    return f"The population of {city} is approximately 14 million."


# Build the model directly so we can control the timeout
model = ChatNVIDIA(
    model="nvidia/nemotron-3-super-120b-a12b",
    api_key=os.environ["NVIDIA_API_KEY"],
)

agent = create_deep_agent(
    model=model,
    tools=[get_weather, get_time, get_population],
    system_prompt="You are a helpful assistant. For multi-step requests, "
                  "plan your steps using the todo list before executing them.",
)

result = agent.invoke(
    {
        "messages": [
            (
                "user",
                "I need a full briefing on Tokyo: check the weather, the "
                "current time, and the population. Plan this out first, "
                "then give me a summary.",
            )
        ]
    },
    config={"configurable": {"thread_id": "todo-example-1"}},
)

for m in result["messages"]:
    if m.type == "ai":
        if m.tool_calls:
            for call in m.tool_calls:
                print(f"[Tool Call] {call['name']} -> {call['args']}")
        if m.content:
            print(f"AI: {m.content}")
    elif m.type == "tool":
        print(f"[Tool Result - {m.name}]: {m.content}")

if "todos" in result:
    print("\nFinal todo list state:")
    for todo in result["todos"]:
        print(f"  - {todo}")

2. SkillsMiddleware

"""
Example: SkillsMiddleware

The SkillsMiddleware is added to the default stack automatically when you pass
`skills=` to `create_deep_agent`. It loads each skill's `name` and `description`
from the YAML frontmatter of `SKILL.md` into the system prompt at startup, and
gives the agent a `read_file` tool so it can pull the full instructions in
progressive disclosure when a task matches a skill.

This example uses `FilesystemBackend` so skills are loaded from disk relative
to a project root. Two sample skills live under `middleware-examples/skills/`:

  - code-review: reviews code for bugs, security, performance, and style.
  - git-commit:  writes conventional commit messages from a diff or summary.

Run from the project root with:
    uv run middleware-examples/02_skills_middleware.py
"""

import os
import sys
from pathlib import Path

sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

from dotenv import load_dotenv

load_dotenv()

from langchain_nvidia_ai_endpoints import ChatNVIDIA

from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend

ROOT = Path(__file__).resolve().parent.parent
SKILLS_DIR = ROOT / "middleware-examples" / "skills"

backend = FilesystemBackend(root_dir=str(ROOT))

llm = ChatNVIDIA(
    model="nvidia/nemotron-3-super-120b-a12b",
    timeout=120,
)

agent = create_deep_agent(
    model=llm,
    backend=backend,
    skills=[str(SKILLS_DIR)],
    system_prompt=(
        "You are a helpful assistant. When a user request matches one of your "
        "available skills, read the skill's SKILL.md and follow its instructions."
    ),
)

result = agent.invoke(
    {
        "messages": [
            (
                "user",
                "Please turn this diff into a commit message:\n"
                "+ added 5 req/sec rate limiting to /login\n"
                "+ added unit tests for the limiter\n"
                "- removed the in-memory counter fallback",
            ),
            (
                "user",
                "review the below code:\n"
                "def add(a, b):\n"
                "    return a.tO_string() + b",
            ),
        ]
    },
    config={"configurable": {"thread_id": "skills-example-1"}},
)

print("\n=== Skill state ===")
for m in result["messages"]:
    if m.type == "ai" and m.content:
        print(f"\nAI: {m.content}")

3. FilesystemMiddleware

"""
Example: FilesystemMiddleware

The FilesystemMiddleware handles file system operations such as reading,
writing, and navigating directories. When you pass permissions, filesystem
permissions enforcement is included.

This example shows basic filesystem operations without custom permissions.

Run with: python middleware-examples/03_filesystem_middleware.py
"""

import os
import sys
from pathlib import Path

sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

from dotenv import load_dotenv

load_dotenv()

from langchain_nvidia_ai_endpoints import ChatNVIDIA

from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend

# FIX: this was `.parent.parent`, which resolves to one directory *above*
# your project (this file lives at <ROOT>/middleware-examples/<this file>,
# so a single .parent already gets you back to <ROOT>). The extra .parent
# silently wrote poem.txt outside the folder you were checking.
ROOT = Path(__file__).resolve().parent

# FIX: virtual_mode=True still resolves relative paths under root_dir (same
# as before) but also blocks path traversal ('..', '~') and absolute paths
# escaping root_dir. virtual_mode=False gives the agent no real guardrails.
backend = FilesystemBackend(root_dir=str(ROOT), virtual_mode=True)

llm = ChatNVIDIA(
    model="nvidia/nemotron-3-super-120b-a12b",
    timeout=120,
)

agent = create_deep_agent(
    model=llm,
    backend=backend,
    system_prompt=(
        "You are a helpful assistant. Use the filesystem to save and "
        "read files as needed."
    ),
)

result = agent.invoke(
    {
        "messages": [
            (
                "user",
                "Write a short poem to a file called 'poem.txt'.",
            )
        ]
    },
    config={"configurable": {"thread_id": "fs-example-1"}},
)

# DEBUG: log every message, including tool calls and tool results, not just
# AI text. This is what would have made the original bug obvious immediately
# — you'd have seen a write_file call and a WriteResult path, just not in
# the folder you expected.
for m in result["messages"]:
    if m.type == "ai":
        if getattr(m, "tool_calls", None):
            for tc in m.tool_calls:
                print(f"TOOL CALL: {tc['name']}({tc['args']})")
        if m.content:
            print(f"AI: {m.content}")
    elif m.type == "tool":
        print(f"TOOL RESULT [{m.name}]: {m.content}")

# Sanity check: prove where the file actually landed.
expected_path = ROOT / "poem.txt"
if expected_path.exists():
    print(f"\n✅ poem.txt created at: {expected_path}")
else:
    print(f"\n⚠️  poem.txt not found at expected path: {expected_path}")

4. SubAgentMiddleware

"""
Example: SubAgentMiddleware

The SubAgentMiddleware spawns and coordinates subagents for delegating
tasks to specialized agents. Only the parent agent exposes the task tool
that creates subagents.

This example creates a subagent for research. The parent agent delegates
research to the subagent via the task tool.

Run with: python middleware-examples/04_subagent_middleware.py
"""

import os
import sys

sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

from dotenv import load_dotenv

load_dotenv()

from langchain_nvidia_ai_endpoints import ChatNVIDIA

from deepagents import create_deep_agent, SubAgent

llm = ChatNVIDIA(
    model="nvidia/nemotron-3-super-120b-a12b",
    timeout=120,
    model_kwargs={"chat_template_kwargs": {"enable_thinking": False}},
)

research_subagent = SubAgent(
    name="research",
    description="Researches a topic and returns findings.",
    model=llm,
    system_prompt="You are a research assistant. Find answers concisely.",
)

writer_subagent = SubAgent(
    name="writer",
    description="Writes content, reports, or summaries based on research findings.",
    model=llm,
    system_prompt="You are a skilled writer. Produce clear, well-structured content.",
)

reviewer_subagent = SubAgent(
    name="reviewer",
    description="Reviews content for quality, accuracy, and completeness.",
    model=llm,
    system_prompt="You are a meticulous reviewer. Check for errors and suggest improvements.",
)

agent = create_deep_agent(
    model=llm,
    subagents=[research_subagent, writer_subagent, reviewer_subagent],
    system_prompt=(
        "You are a helpful assistant. Delegate tasks to subagents using the "
        "task tool. Use 'research' for finding information, 'writer' for "
        "creating content, and 'reviewer' for quality checks."
    ),
)

result = agent.invoke(
    {
        "messages": [
            (
                "user",
                "Research the history of Python, write a short summary, then review it.",
            )
        ]
    },
    config={"configurable": {"thread_id": "subagent-example-1"}},
)

for m in result["messages"]:
    if m.type == "ai" and m.content:
        print(f"AI: {m.content}")

5. AsyncSubAgentMiddleware

"""
Example: Async execution with SubAgentMiddleware

SubAgentMiddleware spawns and coordinates subagents for delegating tasks.
Use `ainvoke` for async execution with regular SubAgent instances.

AsyncSubAgent is for connecting to remote Agent Protocol servers
(graph_id + url required) — not for local async execution.
See: https://docs.langchain.com/oss/python/deepagents/subagents#async-subagents

This example runs a research subagent via ainvoke.

Run with: python middleware-examples/07_async_subagent_middleware.py
"""

import os
import sys
import asyncio

sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

from dotenv import load_dotenv

load_dotenv()

from deepagents import create_deep_agent, SubAgent


async def main():
    research_subagent = SubAgent(
        name="researcher",
        description="Researches a topic and returns findings.",
        model="nvidia:meta/llama-3.1-8b-instruct",
        system_prompt="You are a research assistant. Find answers concisely.",
    )

    agent = create_deep_agent(
        model="nvidia:meta/llama-3.1-8b-instruct",
        subagents=[research_subagent],
        system_prompt=(
            "You are a helpful assistant. Delegate research to the "
            "'researcher' subagent using the task tool."
        ),
    )

    result = await agent.ainvoke(
        {"messages": [("user", "Research what's the capital of France.")]},
        config={"configurable": {"thread_id": "async-subagent-example-1"}},
    )

    for m in result["messages"]:
        if m.type == "ai" and m.content:
            print(f"AI: {m.content}")


asyncio.run(main())

06_memory_middleware.py

6.1. Create this file at your project root

Your expected project layout:

Deep Agent/
├── AGENTS.md
└── middleware-examples/
    └──memory_middleware.py

Create AGENTS.md:

# Agent Memory

## User Preferences
- The user's name is Talha.
- The user prefers Python examples.
- The user lives in California, USA.

## Response Style
- Use clear, concise explanations.
- Use headings and code comments where helpful.

6.2. Use this code: `memory_middleware.py`

"""
Example: MemoryMiddleware

MemoryMiddleware loads one or more AGENTS.md files and injects their
contents into the agent's system prompt.

You do not need to manually create MemoryMiddleware. Passing memory=[...]
to create_deep_agent() adds it automatically.

Expected project structure:

Deep Agent/
├── AGENTS.md
└── middleware-examples/
    └──memory_middleware.py

Run with:
    uv run 08_memory_middleware.py
"""

import sys
from pathlib import Path

from dotenv import load_dotenv

from langchain_nvidia_ai_endpoints import ChatNVIDIA

from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend

# Make UTF-8 output work correctly in Windows terminals.
sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

load_dotenv()

# The script is inside:
#   Deep Agent/middleware-examples/08_memory_middleware.py
#
# Therefore ROOT becomes:
#   Deep Agent/
ROOT = Path(__file__).resolve().parent.parent

# This is the real local file that stores the memory.
memory_file = ROOT / "AGENTS.md"

# Fail early with a clear error if the required memory file does not exist.
if not memory_file.exists():
    raise FileNotFoundError(
        f"Memory file was not found:\n{memory_file}\n\n"
        "Create AGENTS.md in your project root first."
    )

# FilesystemBackend lets the agent read/write real files under ROOT.
# virtual_mode=True makes virtual paths such as /AGENTS.md map safely to:
# ROOT / AGENTS.md
backend = FilesystemBackend(
    root_dir=str(ROOT),
    virtual_mode=True,
)

llm = ChatNVIDIA(
    model="nvidia/nemotron-3-super-120b-a12b",
    timeout=120,
    model_kwargs={
        "chat_template_kwargs": {
            "enable_thinking": False,
        }
    },
)

agent = create_deep_agent(
    model=llm,
    backend=backend,
    system_prompt=(
        "You are a helpful assistant. "
        "Use the loaded memory as reference for user preferences."
    ),
    # This automatically enables MemoryMiddleware.
    # The path is virtual and relative to FilesystemBackend's root.
    memory=["/AGENTS.md"],
)

print(f"📂 Project root: {ROOT}")
print(f"🧠 Memory file:  {memory_file}\n")

result = agent.invoke(
    {
        "messages": [
            (
                "user",
                (
                    "Based only on your loaded memory, tell me my name, "
                    "preferred programming language, and city."
                ),
            )
        ]
    },
    config={
        "configurable": {
            "thread_id": "memory-example-1",
        }
    },
)

# Print the final AI message.
last_message = result["messages"][-1]

if last_message.type == "ai" and last_message.content:
    print("AI response:")
    print(last_message.content)
else:
    print("No normal AI response was returned.")
    print(last_message)

7. HumanInTheLoopMiddleware

"""
Example: HumanInTheLoopMiddleware

HumanInTheLoopMiddleware pauses an agent before selected tool calls.
The human reviewer can approve or reject the requested action.

This example pauses before the get_weather tool runs, then asks for
approval in the terminal.

Run with:
    uv run 09_human_in_the_loop_middleware.py
"""

import sys

from dotenv import load_dotenv
from langchain.tools import tool
from langgraph.checkpoint.memory import MemorySaver
from langgraph.types import Command

from deepagents import create_deep_agent

# Make Unicode output work properly in Windows terminals.
sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

load_dotenv()


@tool
def get_weather(city: str) -> str:
    """Get the weather for a city.

    This is a demo tool, so it returns fixed data rather than real weather.
    """
    return f"The weather in {city} is sunny and 25°C."


# REQUIRED for Human-in-the-Loop:
# It stores agent state while execution is paused.
checkpointer = MemorySaver()

agent = create_deep_agent(
    model="nvidia:meta/llama-3.1-8b-instruct",
    tools=[get_weather],
    interrupt_on={
        # Limit the reviewer to approve or reject.
        # "edit" is not useful for this small demonstration.
        "get_weather": {
            "allowed_decisions": ["approve", "reject"],
        },
    },
    checkpointer=checkpointer,
    system_prompt=(
        "You are a helpful assistant. "
        "Use the get_weather tool when the user asks about weather."
    ),
)

# This config MUST be reused when resuming the paused run.
config = {
    "configurable": {
        "thread_id": "hitl-example-1",
    }
}

# Step 1: Start the agent.
result = agent.invoke(
    {
        "messages": [
            ("user", "What is the weather in London?"),
        ],
    },
    config=config,
    version="v2",
)

# Step 2: Check whether the middleware paused execution.
if result.interrupts:
    interrupt_value = result.interrupts[0].value

    # The agent may request approval for one or more tool calls.
    action_requests = interrupt_value["action_requests"]
    review_configs = interrupt_value["review_configs"]

    # Map each tool name to its allowed review decisions.
    review_config_by_tool = {
        item["action_name"]: item
        for item in review_configs
    }

    print("\n⚠️ Human approval required.\n")

    decisions = []

    # A decision is required for every pending action, in the same order.
    for action in action_requests:
        tool_name = action["name"]
        tool_args = action["args"]
        allowed = review_config_by_tool[tool_name]["allowed_decisions"]

        print(f"Tool requested: {tool_name}")
        print(f"Arguments:      {tool_args}")
        print(f"Allowed:        {', '.join(allowed)}")

        while True:
            choice = input("\nApprove this tool call? [y/n]: ").strip().lower()

            if choice in ("y", "yes"):
                decisions.append({"type": "approve"})
                break

            if choice in ("n", "no"):
                decisions.append(
                    {
                        "type": "reject",
                        "message": (
                            "The human reviewer rejected the weather lookup. "
                            "Do not call get_weather again unless the user asks."
                        ),
                    }
                )
                break

            print("Please enter y or n.")

    # Step 3: Resume the same paused agent execution.
    result = agent.invoke(
        Command(resume={"decisions": decisions}),
        config=config,  # Must be the SAME thread_id/config.
        version="v2",
    )

# Step 4: Print the final agent response.
if result.interrupts:
    print("\n⚠️ The agent paused again; additional review is required.")
else:
    final_message = result.value["messages"][-1]

    print("\n Final AI response:")
    print(final_message.content)

8.Custom Class-Based Middleware

"""
Example: Custom Middleware using AgentMiddleware class

Demonstrates creating custom middleware by subclassing AgentMiddleware.
This approach is preferred when you need to track state safely using
graph state instead of mutating instance attributes.

Key rule: Do NOT mutate attributes after initialization (self.x = ...).
Use graph state (state["key"]) instead to avoid race conditions.

Run with: python middleware-examples/12_custom_middleware_class_based.py
"""

import os
import sys

sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

from dotenv import load_dotenv

load_dotenv()

from langchain.agents.middleware import AgentMiddleware
from langchain.tools import tool
from deepagents import create_deep_agent


class TurnCounterMiddleware(AgentMiddleware):
    """Counts turns using graph state instead of instance mutation."""

    def __init__(self):
        pass

    def before_agent(self, state, runtime):
        turns = state.get("turns", 0) + 1
        print(f"[Middleware] Turn #{turns}")
        return {"turns": turns}  # update graph state — safe under concurrency


@tool
def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is sunny."


agent = create_deep_agent(
    model="nvidia:meta/llama-3.1-8b-instruct",
    tools=[get_weather],
    middleware=[TurnCounterMiddleware()],
    system_prompt="You are a helpful assistant.",
)

result = agent.invoke(
    {"messages": [("user", "What's the weather in Paris?")]},
    config={"configurable": {"thread_id": "custom-class-example-1"}},
)

for m in result["messages"]:
    if m.type == "ai" and m.content:
        print(f"Final AI: {m.content}")

9. Prebuilt_retry_middleware

"""
Example: Prebuilt ToolRetryMiddleware

ToolRetryMiddleware retries failed tool calls automatically.

This example uses a deterministic tool:
- Call 1: raises ConnectionError
- Call 2: raises ConnectionError
- Call 3: succeeds

This makes retry behavior visible and reliable.

Run with:
    uv run 16_prebuilt_retry_middleware.py
"""

import sys

from dotenv import load_dotenv
from langchain.agents.middleware import ToolRetryMiddleware
from langchain.tools import tool

from deepagents import create_deep_agent

# Ensure UTF-8 output works in Windows terminals.
sys.stdout.reconfigure(encoding="utf-8")
sys.stderr.reconfigure(encoding="utf-8")

load_dotenv()

# Mutable state for this small learning demonstration.
# In production, do not usually store retry state in a global variable.
tool_call_count = 0


@tool
def unreliable_tool() -> str:
    """Simulate a temporary network service that fails twice, then succeeds."""
    global tool_call_count

    tool_call_count += 1

    print(f"🔧 unreliable_tool executed: attempt #{tool_call_count}")

    # Fail predictably on attempts 1 and 2.
    if tool_call_count <= 2:
        raise ConnectionError(
            f"Temporary network failure on attempt #{tool_call_count}"
        )

    # Succeed on attempt 3.
    return "✅ Success! The external service responded on attempt #3."


# Retry only transient network failures from this specific tool.
retry_middleware = ToolRetryMiddleware(
    max_retries=3,
    tools=["unreliable_tool"],
    retry_on=(ConnectionError,),
    on_failure="continue",

    # Keep the demo fast.
    initial_delay=0.1,
    backoff_factor=1.0,
    max_delay=0.1,
    jitter=False,
)

agent = create_deep_agent(
    model="nvidia:meta/llama-3.1-8b-instruct",
    tools=[unreliable_tool],
    middleware=[retry_middleware],
    system_prompt=(
        "You are a helpful assistant. "
        "When the user asks to run unreliable_tool, you MUST call the "
        "unreliable_tool tool exactly once. Do not answer without calling it."
    ),
)

result = agent.invoke(
    {
        "messages": [
            (
                "user",
                "Run unreliable_tool and tell me its final result.",
            )
        ]
    },
    config={
        "configurable": {
            "thread_id": "retry-example-1",
        }
    },
)

print("\n" + "=" * 60)
print("📊 Retry demonstration result")
print("=" * 60)

print(f"\nTotal physical tool executions: {tool_call_count}")

# Print messages, including tool messages/results.
for message in result["messages"]:
    print(f"\nType: {message.type}")
    print(f"Content: {message.content}")

DEV Community: Syeed Talha

Agent-Scoped Memory in Deep Agents: Sharing Memory Across Conversations

What is agent-scoped memory?

Why do we need agent-scoped memory?

Agent-scoped vs user-scoped memory

User-scoped memory

Agent-scoped memory

How does Deep Agents implement it?

A simple example

When should you use agent-scoped memory?

One important limitation

Try it yourself

The key idea

User-Scoped Memory in Deep Agents: What It Is and Why You Need It

What is user-scoped memory?

Why do we need it?

1. Preferences can leak between users

2. Private information can be exposed

3. The agent's behavior becomes unpredictable

User-scoped memory vs conversation memory

How does Deep Agents implement it?

1. Memory path

2. User ID

3. Namespace

One important security rule

Try it yourself

The key idea to remember

Understanding RubricMiddleware in Deep Agents

What is a Rubric?

How does RubricMiddleware work?

Worker Agent vs Grader Agent

1. Agent

2. Grader

A Simple Example

Why is this useful?

Rubric vs System Prompt

The Main Idea

A runnable code example:

output

How to Run LangChain Deep Agents Skills Safely Inside a Daytona Sandbox

The core idea, in one picture

Folder structure

How a request flows end to end

Why bother with a sandbox at all?

Run it yourself

The full code

skills/arxiv-search/SKILL.md

skills/arxiv-search/scripts/search.py

sandbox_skill_scripts.py

What I'd add next

The one-sentence takeaway

Understanding the Deep Agents Interpreter with Programmatic Tool Calling

What is the Deep Agents interpreter?

What happens without an interpreter?

How the interpreter changes the workflow

Complete example

How the code works

1. The search tool

2. The interpreter middleware

3. Programmatic Tool Calling

4. The system prompt

5. The agent request

What the interpreter cannot do by default

When should you use an interpreter?

Final takeaway

Build a Thread-Scoped AI Data Science Sandbox with Daytona and Deep Agents

What the example builds

Understanding the two types of persistence

Architecture

Prerequisites

Step 1: Create shared configuration

What does InMemorySaver() do?

Step 2: Find or create a sandbox

Step 3: Give the agent access to the sandbox

Why /home/daytona matters

Step 4: Run the training turn

Step 5: Reuse the sandbox in the second call

Streaming tool activity

Step 6: Clean up the sandbox

Security considerations

`skills/arxiv-search/SKILL.md`

`skills/arxiv-search/scripts/search.py`

`sandbox_skill_scripts.py`

What does `InMemorySaver()` do?

Why `/home/daytona` matters

2. Create a `.env` file

3. Add private files and generated folders to `.gitignore`

How `LocalShellBackend` Works

Understanding `virtual_mode=True`

1. Assuming `root_dir` makes shell commands safe

4. Assuming `python` works on every computer

Step 2: Creating a `FilesystemBackend`

Why Use `virtual_mode=True`?

A Small Improvement: Use an Absolute `root_dir`

Step 3: The `run()` Helper Function

Why `CompositeBackend` Is Better for Real Projects

Understanding the `/workspace/` Route

Why Keep Internal Files in `StateBackend`?

`FilesystemBackend` vs `CompositeBackend`

4. Do not treat `thread_id` as access control

Step 3: Creating a Deep Agent with `StateBackend`

Step 4: Why `run_agent()` Matters