Going to production ↗

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent.ts:agent"
  },
  "env": ".env"
}

const authClient = new Client();

// Inside your agent's tool:
const authResult = await authClient.authenticate({
  provider: "github",
  scopes: ["repo", "read:org"],
  userId: config.configurable.langgraph_auth_user_id,
});
// Use authResult.token for GitHub API calls on the user's behalf

    import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";

    const agent = createDeepAgent({
      backend: (rt) => new CompositeBackend(
        new StateBackend(rt),
        {
          "/memories/": new StoreBackend(rt, {
            namespace: (ctx) => [ctx.runtime.context.userId],
          }),
        },
      ),
      systemPrompt: `You have persistent memory at /memories/.

      Read /memories/instructions.txt at the start of each conversation for
      accumulated knowledge and preferences. When you learn something that
      should persist, update that file.`,
    });

    export { agent };
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Assistant"></span>
Namespace by `assistant_id`. Memory is shared across all users of the same assistant, so any user can read or update it. Use this for shared instructions or knowledge that applies to everyone using a given assistant (e.g., "always reply in formal tone").

```typescript
    import { getConfig } from "@langchain/langgraph";
    import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";

    const agent = createDeepAgent({
      backend: (rt) => new CompositeBackend(
        new StateBackend(rt),
        {
          "/memories/": new StoreBackend(rt, {
            namespace: (ctx) => {
              const config = getConfig();
              return [config.metadata.assistantId];
            },
          }),
        },
      ),
    });

    export { agent };
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Global"></span>
Namespace by `org_id`. Memory is shared across all users and all assistants. Typically used for organization-wide policies (compliance rules, brand guidelines) that should be read-only for the agent. Write access should be restricted to application code to prevent prompt injection.

```typescript
    import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";

    const agent = createDeepAgent({
      backend: (rt) => new CompositeBackend(
        new StateBackend(rt),
        {
          "/memories/": new StoreBackend(rt, {
            namespace: (ctx) => [ctx.runtime.context.orgId],
          }),
        },
      ),
    });

    export { agent };
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

You can also read and write to the store from your application code using the [Store API](/langsmith/custom-store). See [accessing memories from external code](/oss/javascript/deepagents/memory#accessing-memories-from-external-code) for examples.

For the full namespace factory API, see [namespace factories](/oss/javascript/deepagents/backends#namespace-factories). For memory patterns like self-improving instructions and knowledge bases, see [long-term memory](/oss/javascript/deepagents/memory).

## Execution environment

Locally, agents can read and write files on disk and run shell commands directly. In production, you need to think about isolation and persistence. The right setup depends on whether your agent needs to execute code:

* **Filesystem backends** are enough if your agent only reads and writes files. Choose a backend that matches your persistence needs: ephemeral scratch space, persistent storage, or a mix of both.
* **Sandboxes** add an isolated container with an `execute` tool for running shell commands. Use a sandbox if your agent needs to run code, install packages, or do anything beyond file I/O.

### Filesystem

Choose a backend based on what needs to persist:

* [StateBackend](https://reference.langchain.com/javascript/deepagents/backends/StateBackend) (default): ephemeral scratch space, scoped to a single conversation. Checkpointed at every step, so avoid writing large files.
* [StoreBackend](https://reference.langchain.com/javascript/deepagents/backends/StoreBackend): persistent storage that survives across conversations. Scope with a [namespace factory](/oss/javascript/deepagents/backends#namespace-factories).
* [CompositeBackend](https://reference.langchain.com/javascript/deepagents/backends/CompositeBackend): mix both. Ephemeral scratch space by default with persistent routes for specific paths like `/memories/`.

For the full list of backends and how to build custom ones, see [backends](/oss/javascript/deepagents/backends).

<span class="callout-start" data-callout-type="warning"></span>
  `FilesystemBackend` and `LocalShellBackend` access the host directly. Don't use them in deployed agents.
<span class="callout-end"></span>

### Sandboxes

If your agent needs to run code (not just read and write files), use a [sandbox](/oss/javascript/deepagents/sandboxes). Sandboxes provide both a filesystem and an `execute` tool for running shell commands, all inside an isolated container. This isolation also protects your host: if the agent's code exhausts memory or crashes, only the sandbox is affected. Your server keeps running.

#### Lifecycle

The key decision is how long a sandbox lives. Does each conversation get a fresh one, or do conversations share a persistent environment?

| Scope                | Sandbox ID stored on                      | Lifecycle                                 | Example use case                                                     |
| -------------------- | ----------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------- |
| **Thread-scoped**    | [Thread](/langsmith/use-threads) metadata | Fresh per conversation, cleaned up on TTL | A data analysis bot where each conversation starts clean             |
| **Assistant-scoped** | [Assistant](/langsmith/assistants) config | Shared across all conversations           | A coding assistant that maintains a cloned repo across conversations |

<span class="callout-start" data-callout-type="note"></span>
  The examples below use an async [graph factory](/langsmith/graph-rebuild) instead of a static graph because the sandbox needs the `thread_id` or `assistant_id` from the runtime config to look up or create the correct sandbox. A graph factory receives the config on each run, so it can resolve the sandbox before building the agent. The factory is async because sandbox creation is an I/O-bound operation that requires runtime information like `thread_id` or `assistant_id` that is only available at invocation time.
<span class="callout-end"></span>

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Thread-scoped (most common)"></span>
Each conversation gets its own sandbox. The [graph factory](/langsmith/graph-rebuild) reads `thread_id` from the config, so each [thread](/langsmith/use-threads) automatically gets its own isolated environment. The provider's label-based lookup handles deduplication across runs. Cleaned up when the sandbox [TTL](/langsmith/configure-ttl) expires.

```typescript
    import { Daytona } from "@daytonaio/sdk";
    import { DaytonaSandbox } from "@langchain/daytona";
    import { createDeepAgent } from "deepagents";
    import type { RunnableConfig } from "@langchain/core/runnables";

    const client = new Daytona();

    export async function agent(config: RunnableConfig) {
      const threadId = config.configurable!.thread_id;
      let sandbox;
      try {
        sandbox = await client.findOne({ labels: { thread_id: threadId } });
      } catch {
        sandbox = await client.create({
          labels: { thread_id: threadId },
          autoDeleteInterval: 3600, // TTL: clean up when idle
        });
      }
      return createDeepAgent({ backend: await DaytonaSandbox.fromId(sandbox.id) });
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Assistant-scoped"></span>
All conversations share one sandbox. The [graph factory](/langsmith/graph-rebuild) reads the [assistant](/langsmith/assistants) ID from config metadata, so every thread on the same assistant returns to the same environment. Files, installed packages, and cloned repositories persist across conversations.

```typescript
    import { Daytona } from "@daytonaio/sdk";
    import { DaytonaSandbox } from "@langchain/daytona";
    import { createDeepAgent } from "deepagents";
    import type { RunnableConfig } from "@langchain/core/runnables";

    const client = new Daytona();

    export async function agent(config: RunnableConfig) {
      const assistantId = config.metadata!.assistant_id;
      let sandbox;
      try {
        sandbox = await client.findOne({ labels: { assistant_id: assistantId } });
      } catch {
        sandbox = await client.create({ labels: { assistant_id: assistantId } });
      }
      return createDeepAgent({ backend: await DaytonaSandbox.fromId(sandbox.id) });
    }
    ```

<span class="callout-start" data-callout-type="warning"></span>
  Assistant-scoped sandboxes accumulate files, installed packages, and other in-sandbox state over time. Configure a TTL with your sandbox provider, use snapshots to reset periodically, or implement cleanup logic to prevent the sandbox's disk and memory from growing unbounded.
<span class="callout-end"></span>
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

Because the `agent` variable is an async function (not a compiled graph), the server treats it as a [graph factory](/langsmith/graph-rebuild) and calls it on each run, injecting the config. The factory looks up or creates the sandbox via the provider's label-based search and returns a fresh agent graph wired to that sandbox.

Once deployed with `langgraph deploy`, invoke the agent from your application code using the SDK. The client-side code is the same regardless of scope. The scoping is handled entirely in the agent factory above, but the behavior differs:

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Thread-scoped"></span>
Each thread gets its own sandbox. Follow-up messages within the same thread reuse the same sandbox, but a new thread always starts fresh with no leftover files or installed packages from previous conversations.

```typescript
    import { Client } from "@langchain/langgraph-sdk";

    const client = new Client({ apiUrl: "<DEPLOYMENT_URL>", apiKey: "<LANGSMITH_API_KEY>" });

    // Conversation 1: install pandas and analyze data
    const thread1 = await client.threads.create();
    for await (const chunk of client.runs.stream(
      thread1.thread_id,
      "agent",
      { input: { messages: [{ role: "human", content: "Install pandas and analyze sales_data.csv" }] } },
    )) {
      console.log(chunk.data);
    }

    // Follow-up in the same conversation — pandas is still installed
    for await (const chunk of client.runs.stream(
      thread1.thread_id,
      "agent",
      { input: { messages: [{ role: "human", content: "Now plot the results" }] } },
    )) {
      console.log(chunk.data);
    }

    // Conversation 2: fresh sandbox — pandas is NOT installed, no files from conversation 1
    const thread2 = await client.threads.create();
    for await (const chunk of client.runs.stream(
      thread2.thread_id,
      "agent",
      { input: { messages: [{ role: "human", content: "What packages are installed?" }] } },
    )) {
      console.log(chunk.data);
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Assistant-scoped"></span>
All threads share one sandbox. This is useful when the sandbox has state that's expensive to recreate, such as a cloned repo, installed dependencies, or build artifacts. Any conversation on the same assistant picks up where the last one left off without repeating setup.

```typescript
    import { Client } from "@langchain/langgraph-sdk";

    const client = new Client({ apiUrl: "<DEPLOYMENT_URL>", apiKey: "<LANGSMITH_API_KEY>" });

    // Conversation 1: clone and set up the project
    const thread1 = await client.threads.create();
    for await (const chunk of client.runs.stream(
      thread1.thread_id,
      "agent",
      { input: { messages: [{ role: "human", content: "Clone https://github.com/org/repo and install dependencies" }] } },
    )) {
      console.log(chunk.data);
    }

    // Conversation 2: repo and dependencies are still there
    const thread2 = await client.threads.create();
    for await (const chunk of client.runs.stream(
      thread2.thread_id,
      "agent",
      { input: { messages: [{ role: "human", content: "Run the test suite and fix any failures" }] } },
    )) {
      console.log(chunk.data);
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

#### File transfers

Sandboxes are isolated containers, so your application code can't directly access files inside them. Use `upload_files()` and `download_files()` to move data across the sandbox boundary:

* **Seed the sandbox before the agent runs**: upload user files, [skill](/oss/javascript/deepagents/skills) scripts, configuration, or [persistent memories](/oss/javascript/deepagents/memory) so the agent has what it needs from the start
* **Retrieve results after the agent finishes**: download generated artifacts (reports, plots, exports) and sync updated memories back for future conversations

For provider-specific file transfer examples, see [working with files](/oss/javascript/deepagents/sandboxes#working-with-files). For provider setup, security, and lifecycle patterns, see the full [sandboxes guide](/oss/javascript/deepagents/sandboxes).

<Accordion title="Example: syncing skills and memories with custom middleware">
  [Skill](/oss/javascript/deepagents/skills) scripts that the agent needs to execute must be uploaded into the sandbox before the agent runs. You may also want to sync [memories](/oss/javascript/deepagents/memory) so the agent can read and update them inside the container. Use [custom middleware](/oss/javascript/langchain/middleware/custom) with `before_agent` and `after_agent` hooks to move files across the sandbox boundary:

  ```typescript
  import { createMiddleware } from "langchain";
  import { createDeepAgent, CompositeBackend, StoreBackend } from "deepagents";
  import { DaytonaSandbox } from "@langchain/daytona";

  function safeFilename(key: string): string {
    const name = key.split("/").pop()!;
    if (name.includes("..") || /[*?]/.test(name)) {
      throw new Error(`Invalid key: ${key}`);
    }
    return name;
  }

  const createSandboxSyncMiddleware = (backend: CompositeBackend) => {
    return createMiddleware({
      name: "SandboxSyncMiddleware",
      beforeAgent: async (state, runtime) => {
        // Upload skill scripts and memories into the sandbox
        const userId = runtime.context.userId;
        const store = runtime.store;
        const encoder = new TextEncoder();
        const files: [string, Uint8Array][] = [];
        for (const item of await store.search(["skills", userId])) {
          const name = safeFilename(item.key);
          files.push([`/skills/${name}`, encoder.encode(item.value.content)]);
        }
        for (const item of await store.search(["memories", userId])) {
          const name = safeFilename(item.key);
          files.push([`/memories/${name}`, encoder.encode(item.value.content)]);
        }
        if (files.length > 0) {
          await backend.uploadFiles(files);
        }
      },
      afterAgent: async (state, runtime) => {
        // Sync updated memories back to the store
        const userId = runtime.context.userId;
        const store = runtime.store;
        const items = await store.search(["memories", userId]);
        const results = await backend.downloadFiles(
          items.map((item) => `/memories/${item.key}`),
        );
        const decoder = new TextDecoder();
        for (const result of results) {
          if (result.content) {
            await store.put(
              ["memories", userId],
              result.path.split("/").pop()!,
              { content: decoder.decode(result.content) },
            );
          }
        }
      },
    });
  };

  const backend = new CompositeBackend(
    await DaytonaSandbox.fromId(sandbox.id),
    {
      "/skills/": new StoreBackend(rt, {
        namespace: (ctx) => ["skills", ctx.runtime.context.userId],
      }),
      "/memories/": new StoreBackend(rt, {
        namespace: (ctx) => ["memories", ctx.runtime.context.userId],
      }),
    },
  );

  const agent = createDeepAgent({
    backend,
    middleware: [createSandboxSyncMiddleware(backend)],
  });

  export { agent };

{
  "proxy_config": {
    "rules": [
      {
        "name": "openai-api",
        "match_hosts": ["api.openai.com"],
        "inject_headers": {
          "Authorization": "Bearer ${OPENAI_API_KEY}"
        }
      },
      {
        "name": "anthropic-api",
        "match_hosts": ["api.anthropic.com"],
        "inject_headers": {
          "x-api-key": "${ANTHROPIC_API_KEY}"
        }
      }
    ]
  }
}

const agent = createAgent({
  model: "claude-sonnet-4-6",
  middleware: [
    modelCallLimitMiddleware({ runLimit: 50 }),
    toolCallLimitMiddleware({ runLimit: 200 }),
  ],
});

const agent = createAgent({
  model: "claude-sonnet-4-6",
  middleware: [
    // Retry model calls on rate limits, timeouts, and 5xx errors
    modelRetryMiddleware({ maxRetries: 3, backoffFactor: 2.0, initialDelayMs: 1000 }),
    // If the primary model is fully down, fall back to an alternative
    modelFallbackMiddleware("gpt-4.1"),
    // Retry specific tools that hit external APIs (not all tools)
    toolRetryMiddleware({
      maxRetries: 2,
      tools: ["search", "fetch_url"],
      retryOn: [TimeoutError, TypeError],
    }),
  ],
});

const agent = createAgent({
  model: "claude-sonnet-4-6",
  middleware: [
    piiMiddleware("email", { strategy: "redact", applyToInput: true }),
    piiMiddleware("credit_card", { strategy: "mask", applyToInput: true }),
  ],
});

function App() {
  const stream = useStream<typeof agent>({
    apiUrl: "https://your-deployment.langsmith.dev",
    assistantId: "agent",
    reconnectOnMount: true,    // Resume stream after page refresh or navigation
    fetchStateHistory: true,   // Load full thread history on mount
  });
}

stream.submit(
  { messages: [{ type: "human", content: text }] },
  {
    streamSubgraphs: true,
    config: { recursionLimit: 10000 },
  },
);