Build a custom frontend for a Managed Deep Agent

A custom frontend is any application you write that calls a deployment directly instead of reaching the agent through a channel or LangSmith 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. A frontend talks to the same threads, runs, and streaming endpoints that every Agent Server client uses.

Managed Deep Agents is in public beta on LangSmith Cloud.

Choose an identity provider

Every request to a deployment names a caller, and the frontend supplies that name. Which identity provider 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.
Your own server, which already authenticates the user	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 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 works before you configure a provider, because the local server supplies a test user.

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 serves the same routes at the URL the CLI prints. Assistant ID. Clients pass the agent’s name from the agent definition. Managed Deep Agents also uses that name as the graph ID:

agent.ts

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  name: "research-assistant",
  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 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:

useAuthHeaders.ts

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());
    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:

Chat.tsx

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. The same frontend patterns work against a Managed Deep Agents deployment. See tool-call rendering, generative UI, human-in-the-loop approval, queued submissions, and durable rejoin.

Handle authorization interrupts

When the agent needs a user-owned connection 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.

Get started

Agent capabilities

Build and deploy

Build a custom frontend for a Managed Deep Agent

Choose an identity provider

Connect to the deployment

Build a web frontend

Handle authorization interrupts

See also

​Choose an identity provider

​Connect to the deployment

​Build a web frontend

​Handle authorization interrupts

​See also

Choose an identity provider

Connect to the deployment

Build a web frontend

Handle authorization interrupts

See also