> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a custom frontend for a Managed Deep Agent

> Call a Managed Deep Agents deployment from your own browser or server application instead of reaching the agent through a channel or LangSmith Studio.

A custom frontend is any application you write that calls a deployment directly instead of reaching the agent through a [channel](/langsmith/javascript/managed-deep-agents-channels.md) or [LangSmith Studio](/langsmith/javascript/managed-deep-agents-local-development.md#start-local-studio). Use one when the agent belongs inside a product surface you control, such as a support console, an internal dashboard, or a customer-facing chat page.

Managed Deep Agents deployments run on [LangSmith Agent Server](/langsmith/agent-server-overview.md). A frontend talks to the same threads, runs, and streaming endpoints that every Agent Server client uses.

> [!NOTE]
>
> Managed Deep Agents is in **public [beta](/langsmith/release-stages.md)** on [LangSmith Cloud](/langsmith/cloud.md).

## Choose an identity provider

Every request to a deployment names a caller, and the frontend supplies that name. Which [identity provider](/langsmith/javascript/managed-deep-agents-identity.md) fits depends on where the frontend code runs, not on the language it is written in.

| Where the frontend calls the deployment from | Identity provider |
| - | - |
| The user's browser | An external auth provider. The browser sends an access token and the deployment verifies it. See [Supabase](/langsmith/javascript/managed-deep-agents-identity.md#configure-identity-with-supabase). |
| Your own server, which already authenticates the user | [Your own backend](/langsmith/javascript/managed-deep-agents-identity.md#configure-identity-with-your-own-backend). Your server asserts the user ID behind a shared ingress secret. |
| Your own server, with no end-user accounts of its own | The [LangSmith API key](/langsmith/javascript/managed-deep-agents-identity.md#configure-identity-with-a-langsmith-api-key) default. The key itself is the caller. |

Either server row fits a server-rendered application in any language. Streamlit, Gradio, and Dash run their code on the server, as do a Next.js route handler and an Express proxy. A frontend pointed at [`mda dev`](/langsmith/javascript/managed-deep-agents-local-development#understand-local-behavior) works before you configure a provider, because the local server supplies a test user.

> [!WARNING]
>
> A LangSmith API key reaches every resource in the workspace, not only this deployment, so it must never ship in browser JavaScript. Use an external auth provider when the browser calls the deployment directly, and backend identity when your own server calls it on the user's behalf.

## Connect to the deployment

A frontend needs two values.

**Deployment API URL.** `mda deploy` prints the LangSmith deployment dashboard URL, not the API URL. Open that dashboard, then copy the **API URL** from the deployment details view. The local server started by [`mda dev`](/langsmith/javascript/managed-deep-agents-local-development) serves the same routes at the URL the CLI prints.

**Assistant ID.** Clients pass the agent's `name` from the [agent definition](/langsmith/javascript/managed-deep-agents-agent-definition.md#parameters). Managed Deep Agents also uses that name as the graph ID:

```ts agent.ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  name: "research-assistant", // [!code highlight]
  model: "openai:gpt-5.5",
});
```

Clients address an agent named `research-assistant` with that same string. Renaming the agent changes the value clients send, so treat the name as part of the deployment's public interface.

## Build a web frontend

The [LangChain frontend SDKs](/oss/javascript/langchain/frontend/overview.md) connect a browser application to an Agent Server deployment. `useStream` exposes messages, tool calls, interrupts, and thread state as reactive values:

| Framework | Package | Entry point |
| - | - | - |
| React | `@langchain/react` | `useStream` |
| Vue | `@langchain/vue` | `useStream` |
| Svelte | `@langchain/svelte` | `useStream` |
| Angular | `@langchain/angular` | `injectStream` |

The frontend runs in the browser, so these examples are TypeScript even when the agent is written in Python.

Under an external auth provider, the browser sends the access token from the signed-in session. That token rotates, so re-read it whenever the session changes rather than capturing it once at mount:

```ts useAuthHeaders.ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { useEffect, useState } from "react";

import { supabase } from "./supabase";

export function useAuthHeaders() {
  const [headers, setHeaders] = useState<Record<string, string>>();

  useEffect(() => {
    const refresh = async () => {
      const { data } = await supabase.auth.getSession();
      const token = data.session?.access_token;
      setHeaders(token ? { Authorization: `Bearer ${token}` } : undefined);
    };

    void refresh();
    const { data } = supabase.auth.onAuthStateChange(() => void refresh()); // [!code highlight]
    return () => data.subscription.unsubscribe();
  }, []);

  return headers;
}
```

The highlighted subscription fires on sign-in, sign-out, and token refresh. Without it the hook holds the token captured at mount, and requests start failing with 401 once that token expires.

Point the stream at the deployment API URL, the agent name, and those headers:

```tsx Chat.tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { useStream } from "@langchain/react";
import { useState } from "react";

import { useAuthHeaders } from "./useAuthHeaders";

export function Chat() {
  const [input, setInput] = useState("");
  const headers = useAuthHeaders();
  const stream = useStream({
    apiUrl: import.meta.env.VITE_DEPLOYMENT_API_URL,
    assistantId: "research-assistant",
    defaultHeaders: headers,
  });

  return (
    <main>
      {stream.messages.map((message) => (
        <p key={message.id}>{message.text}</p>
      ))}

      <form
        onSubmit={(event) => {
          event.preventDefault();
          stream.submit({ messages: [{ type: "human", content: input }] });
          setInput("");
        }}
      >
        <input value={input} onChange={(event) => setInput(event.target.value)} />
        <button type="submit" disabled={stream.isLoading}>
          Send
        </button>
      </form>
    </main>
  );
}
```

Under backend identity the browser never reaches the deployment. Point `apiUrl` at your own server and forward the Agent Server routes from there, stamping `x-mda-ingress-secret` and the user ID your auth layer resolved on each upstream request. For the headers and the shared secret, see [Configure identity with your own backend](/langsmith/javascript/managed-deep-agents-identity.md#configure-identity-with-your-own-backend).

The same frontend patterns work against a Managed Deep Agents deployment. See [tool-call rendering](/oss/javascript/langchain/frontend/tool-calling.md), [generative UI](/oss/javascript/langchain/frontend/generative-ui-overview.md), [human-in-the-loop approval](/oss/javascript/langchain/frontend/human-in-the-loop.md), [queued submissions](/oss/javascript/langchain/frontend/message-queues.md), and [durable rejoin](/oss/javascript/langchain/frontend/join-rejoin.md).

### Handle authorization interrupts

When the agent needs a [user-owned connection](/langsmith/javascript/managed-deep-agents-connections.md) the caller has not granted, the run pauses and `stream.interrupt` carries a credential gate payload. A browser frontend renders the consent links and resumes with `stream.respond`. For the payload shape and a worked example, see [Handle the authorization interrupt](/langsmith/javascript/managed-deep-agents-connections.md#handle-the-authorization-interrupt).

## See also

* [Identity](/langsmith/javascript/managed-deep-agents-identity.md): configure how callers authenticate to the deployment.
* [Frontend overview](/oss/javascript/langchain/frontend/overview.md): message rendering, tool calls, interrupts, and generative UI patterns.
* [Connections](/langsmith/javascript/managed-deep-agents-connections.md): handle the credential authorization interrupt in your UI.
* [MCP endpoint](/langsmith/javascript/managed-deep-agents-mcp-endpoint.md): expose the agent to MCP clients instead of calling the API.
* [Channels](/langsmith/javascript/managed-deep-agents-channels.md): reach the agent from Slack or your own HTTP service.

***

[Connect these docs](/use-these-docs.md) to your agent of choice via MCP for real-time answers.

[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-custom-frontend.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).