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.py

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    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.

Build a Python frontend

Streamlit, Gradio, and Dash render on the server, so no credential reaches the browser and the API-key default works without extra setup. All three use the same LangGraph SDK client, so the connection code below applies to any of them. Install the SDK alongside your application framework:

uv add langgraph-sdk streamlit

Create a client, then stream a run against a thread:

from langgraph_sdk import get_sync_client

client = get_sync_client(
    url=DEPLOYMENT_API_URL,
    api_key=LANGSMITH_API_KEY,
)

thread = client.threads.create()

for chunk in client.runs.stream(
    thread["thread_id"],
    "research-assistant",
    input={"messages": [{"role": "user", "content": "Summarize this week's incidents."}]},
    stream_mode="messages",
):
    ...

Three details govern how that loop behaves:

api_key: Sets the x-api-key header. Passing headers={"x-api-key": ...} instead raises ValueError: Cannot set reserved header 'x-api-key'.
Environment fallback: When api_key is omitted, the client tries LANGGRAPH_API_KEY, then LANGSMITH_API_KEY, then LANGCHAIN_API_KEY. For Supabase or backend identity, pass api_key=None explicitly and put the token in headers. Otherwise a stray environment variable attaches a second credential.
messages/partial: Carries the whole message so far, not a delta. Replace the rendered text on each event rather than appending, or the output repeats itself.

Stream into a Streamlit chat

This application keeps one thread per browser session and rewrites the assistant bubble as each event arrives:

app.py

import os

import streamlit as st
from langgraph_sdk import get_sync_client

ASSISTANT_ID = "research-assistant"


@st.cache_resource
def get_agent_client():
    return get_sync_client(
        url=os.environ["DEPLOYMENT_API_URL"],
        api_key=os.environ["LANGSMITH_API_KEY"],
    )


def text_of(message):
    return "".join(
        block.get("text", "")
        for block in message.get("content", [])
        if block.get("type") == "text"
    )


client = get_agent_client()

if "thread_id" not in st.session_state:
    st.session_state.thread_id = client.threads.create()["thread_id"]
    st.session_state.history = []

for role, text in st.session_state.history:
    st.chat_message(role).markdown(text)

if prompt := st.chat_input("Message the agent"):
    st.session_state.history.append(("user", prompt))
    st.chat_message("user").markdown(prompt)

    with st.chat_message("assistant"):
        placeholder = st.empty()
        answer = ""
        for chunk in client.runs.stream(
            st.session_state.thread_id,
            ASSISTANT_ID,
            input={"messages": [{"role": "user", "content": prompt}]},
            stream_mode="messages",
        ):
            if chunk.event != "messages/partial":
                continue
            for message in chunk.data:
                if message.get("type") == "ai":
                    answer = text_of(message)
                    placeholder.markdown(answer)

    st.session_state.history.append(("assistant", answer))

The highlighted line replaces the bubble contents on every event. Appending there produces duplicated text, because each event repeats the message from the beginning. text_of reads content blocks rather than a plain string. Agent messages arrive as a list of typed blocks, so a frontend that expects message["content"] to be text renders nothing. The web SDKs deserialize each event into a message object that exposes a text accessor, which is why the React example above reads message.text. The LangGraph SDK yields plain dictionaries, so a Python frontend extracts the text itself. Gradio and Dash use the same client and the same loop. Substitute their streaming primitive for the Streamlit placeholder: a generator function for gr.ChatInterface, or a dcc.Interval callback for Dash.

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

Build a Python frontend

Stream into a Streamlit chat

See also

​Choose an identity provider

​Connect to the deployment

​Build a web frontend

​Handle authorization interrupts

​Build a Python frontend

​Stream into a Streamlit chat

​See also

Choose an identity provider

Connect to the deployment

Build a web frontend

Handle authorization interrupts

Build a Python frontend

Stream into a Streamlit chat

See also