Add identity to Managed Deep Agents

Identity tells Managed Deep Agents who each run is for and how to partition threads, memory, and credentials. It is opt-in: projects without identity.ts or identity.py compile and deploy unchanged. When you add an identity declaration, the CLI wires auth, store scoping, and a frozen runtime.identity envelope into tools and middleware.

Managed Deep Agents is in private beta, available on LangSmith Cloud in the US region only. Join the waitlist to request access.

What identity solves

Without identity, every caller shares the same thread and memory boundary. With identity, Managed Deep Agents answers two questions before the agent runs:

Question	Term	Example
Who is this run for?	Actor	`user_123`, a GitHub login, a guest id
Which customer or org?	Tenant (optional)	`acme`, a Slack workspace, a repo

From those answers, Managed Deep Agents scopes:

Threads — who can open or resume a conversation
Memory — which durable store namespace the run uses
Credentials — whose token downstream calls carry (managed modes or your own resolver)

Identity is fail-closed: missing required actor or tenant values reject the request instead of falling back to shared state.

Add an identity declaration

Create identity.py or identity.ts next to your agent entry and export a named identity. Most projects start from a preset.

from managed_deepagents import define_identity

identity = define_identity.preset("private-assistant")

import { defineIdentity } from "managed-deepagents";

export const identity = defineIdentity.preset("private-assistant");

For the full project layout, see the CLI project file reference. When identity is present, mda generates the custom auth handler, injects it into the compiled LangGraph app, and only then enables reserved identity headers and token verification.

Choose a preset

Presets expand to a full ingress, tenancy, and scoping config. Override any field when you need a different ingress or scope.

Preset	Best for	Threads	Memory	Credentials
`private-assistant`	Personal agents where each user owns their data	`actor`	`actor`	`actor`
`multi-tenant-saas`	One deployment serving many customers	`actor`	`tenant`	`agent`
`shared-bot`	Channel bots (Slack, Discord) with shared threads	`channel`	`actor`	`agent`
`internal-tool`	Internal apps with per-user threads	`actor`	`actor`	`agent`
`service`	Cron/webhook-only agents with shared memory	(unset)	`agent`	`agent`

All presets default to trusted_backend ingress and tenancy: "single", except multi-tenant-saas which sets tenancy: "multi".

Ingress: how Managed Deep Agents learns who is calling

Pick one HTTP ingress mode.

Trusted backend

Your API authenticates the user, then proxies LangGraph requests with a shared ingress secret and reserved identity headers. The browser never sends the secret or raw IdP tokens to Managed Deep Agents. Required headers (case-insensitive):

Header	Required	Purpose
`X-MDA-Ingress-Secret`	Yes	Shared secret from `MDA_INGRESS_SECRET`
`X-MDA-Actor-Id`	Yes	Actor id for this run
`X-MDA-Tenant-Id`	When `tenancy: "multi"`	Tenant id for this run

from managed_deepagents import define_identity

identity = define_identity.preset("internal-tool")

import { defineIdentity } from "managed-deepagents";

export const identity = defineIdentity.preset("internal-tool");

Put MDA_INGRESS_SECRET in .env for mda dev and as a hosted deployment secret for mda deploy. Your production backend should perform OAuth or session auth, then attach the headers above when proxying agent traffic.

Validated token (browser-direct)

The client sends Authorization: Bearer <token>. Managed Deep Agents verifies the token server-side (JWKS, OIDC discovery, opaque introspection, or guest tokens signed by Managed Deep Agents) and maps claims into the identity envelope.

from managed_deepagents import define_identity, providers

identity = define_identity.preset(
    "internal-tool",
    {
        "ingress": {
            "http": {
                "mode": "validated_token",
                "providers": [
                    providers.supabase(project_ref="your-project-ref"),
                    providers.guest(ttl="24h", actor_prefix="guest:"),
                ],
            }
        }
    },
)

import { defineIdentity, providers } from "managed-deepagents";

export const identity = defineIdentity.preset("internal-tool", {
  ingress: {
    http: {
      mode: "validated_token",
      providers: [
        providers.supabase({ projectRef: "your-project-ref" }),
        providers.guest({ ttl: "24h", actorPrefix: "guest:" }),
      ],
    },
  },
});

Built-in provider helpers:

Helper	Verification	Typical claim mapping
`providers.auth0`	JWKS	`sub` → actor, `org_id` → tenant
`providers.clerk`	JWKS	`sub` → actor
`providers.okta`	JWKS	`sub` → actor
`providers.cognito`	JWKS	`sub` → actor
`providers.entra`	JWKS	`oid` → actor
`providers.google`	JWKS	`sub` → actor, `email` → email
`providers.supabase`	JWKS (default) or `/auth/v1/user` introspection	`sub` → actor
`providers.oidc`	OIDC discovery + JWKS	`sub` → actor
`providers.github`	Opaque introspection via `GET /user`	`login` → actor
`providers.guest`	Guest tokens signed by Managed Deep Agents (HS256)	`sub` → actor

In validated_token mode, your frontend signs the user in with the same IdP you configured, reads an access token (or ID token where applicable), and passes it to the LangGraph client as Authorization: Bearer <token>. Do not send refresh tokens or client secrets to the deployment.

Provider	Where to get the token	Docs
Auth0	Access token after login (`getAccessTokenSilently`)	Auth0 SPA SDK
Clerk	Session JWT (`session.getToken()`)	Clerk `getToken()`
Okta	Access token from the Okta Auth JS client	Okta Auth JS
Cognito	ID or access token from Amplify Auth or the hosted UI flow	Amplify Auth
Entra	Access token from `@azure/msal-browser`	MSAL.js
Google	ID token from Google Identity Services	Sign in with Google
Supabase	`session.access_token` from `@supabase/supabase-js`	Supabase JavaScript auth
OIDC	Access token from your IdP’s OIDC client	Your IdP’s OIDC documentation
GitHub	OAuth user access token from your app’s sign-in flow	GitHub OAuth apps
Guest	`token` from `POST /identity/guest`	Claim a guest token

When more than one provider is configured, each entry needs an id. Managed Deep Agents routes JWT providers by token iss and fails closed when the issuer is unknown.

For Supabase, pass projectRef (the subdomain before .supabase.co). Managed Deep Agents derives the JWKS URL. Use introspect: true only for legacy projects that still need /auth/v1/user, and set SUPABASE_ANON_KEY on the deployment.

Guest tokens

Add providers.guest(...) when anonymous visitors should get a short-lived, actor-scoped session without signing in. Managed Deep Agents signs guest tokens with MDA_GUEST_SIGNING_KEY (HS256). Set the key in .env for mda dev and as a hosted deployment secret for mda deploy. Rotate it like any other signing secret. With guest issuance enabled, the deployment exposes a public issuance route:

POST /identity/guest

Claim a guest token

To claim a token, send an empty POST to the deployment base URL with Content-Type: application/json. If the deployment requires a public app key (LANGGRAPH_AUTH_SECRET), also send X-Auth-Key.

curl -X POST "$LANGGRAPH_API_URL/identity/guest" \
  -H "Content-Type: application/json"

On success, the response body contains a signed JWT:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Decode the JWT to read the actor id from sub (for example, guest:01932f4a-... when actor_prefix is guest:) and the expiry from exp. Managed Deep Agents maps sub to runtime.identity.actor.id on subsequent requests.

Use the guest token

Send the token on LangGraph and connector requests the same way you send IdP access tokens:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

const response = await fetch(`${deploymentUrl}/identity/guest`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
});
const { token } = (await response.json()) as { token: string };

const client = new Client({
  apiUrl: deploymentUrl,
  defaultHeaders: { Authorization: `Bearer ${token}` },
});

import httpx
from langgraph_sdk import get_client

response = httpx.post(f"{deployment_url}/identity/guest")
response.raise_for_status()
token = response.json()["token"]

client = get_client(
    url=deployment_url,
    headers={"Authorization": f"Bearer {token}"},
)

For browser apps, proxy guest issuance through your own backend and store the token in an httpOnly cookie. That keeps the same guest actor across reloads until exp and lets you handle rate limits before calling the deployment.

Reclaim a token when the current one is expired or missing. While a token is still valid, reuse it so the guest keeps the same actor id, threads, and memory scope for the token lifetime.

Use `runtime.identity` in tools and middleware

When identity is declared, authored tools and middleware receive a frozen runtime.identity object built from the trusted auth result. Client-supplied spoofable identity keys are stripped from configurable.

from langchain.tools import ToolRuntime, tool


@tool
def whoami(runtime: ToolRuntime) -> str:
    """Return the authenticated actor id for this run."""
    identity = getattr(runtime, "identity", None)
    if not identity:
        return "No authenticated caller on this run."
    return f"Signed in as {identity['actor']['id']}"

import { tool } from "langchain";
import type { ManagedDeepAgentRuntime } from "managed-deepagents";
import { z } from "zod";

export const whoami = tool(
  async (_input, runtime: ManagedDeepAgentRuntime) => {
    const identity = runtime.identity;
    if (!identity) {
      return "No authenticated caller on this run.";
    }
    return `Signed in as ${identity.actor.id}`;
  },
  {
    name: "whoami",
    description: "Return the authenticated actor id for this run.",
    schema: z.object({}),
  },
);

The envelope shape:

runtime.identity = {
  actor: { type: "user" | "service", id: string, email?: string },
  tenant?: { id: string },
  source: {
    provider: "http" | "slack" | "schedule" | "cli" | "studio",
    threadId?: string,
  },
  claims?: Record<string, unknown>, // populated for validated_token ingress
};

Scoping axes

Presets cover the common cases. To customize, set scoping explicitly:

Axis	Values	Meaning
`threads`	`actor`, `channel`, `tenant`	Who can open or resume the conversation
`memory`	`actor`, `tenant`, `agent`, `none`	Durable store namespace prefix
`credentials`	`agent`, `actor`, `none`, `custom`	Whose credentials downstream calls use

tenancy: "single" cannot use "tenant" on any axis. Store access fails closed (403) when required identity segments are missing.

Custom downstream credentials

Set scoping.credentials: "custom" and provide either an in-process resolve function or a hosted token-exchange endpoint. Tools then call runtime.credentials.for(target) to mint per-actor headers. Secrets stay in memory and are never written to thread state or traces. To expose LangSmith capabilities to browsers or other untrusted callers, add a LangSmith connector. It requires identity so capability routes can resolve the caller and prove ownership before calling LangSmith server-side.

Secrets checklist

Secret	When required
`MDA_INGRESS_SECRET`	`trusted_backend` ingress
`MDA_GUEST_SIGNING_KEY`	`providers.guest` issuance or verification
`SUPABASE_ANON_KEY`	Supabase introspection mode (`introspect: true`)
IdP / OAuth secrets	Your own backend or frontend auth flow (never commit them)

Put local values in .env. mda deploy forwards non-reserved .env values as hosted deployment secrets.

Never commit ingress secrets, guest signing keys, or IdP credentials. Do not send MDA_INGRESS_SECRET from the browser — only from a trusted backend proxy.

Test and deploy

Test the project locally with mda dev, then deploy it with mda deploy. Open deployment traces in LangSmith to inspect model calls, tool calls, errors, and latency. Identity misconfiguration usually surfaces as 401 (auth) or 403 (store/thread scope) during local Studio or first authenticated request. Confirm the matching secret is present and that trusted-backend proxies attach the reserved headers.

Next steps

Custom tools

Read runtime.identity from authored tools.

LangSmith connector

Expose constrained LangSmith capabilities to untrusted callers.

How it works

See how compile and deploy wire auth into the runtime.

CLI reference

Look up the identity project file and deploy flags.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​What identity solves

​Add an identity declaration

​Choose a preset

​Ingress: how Managed Deep Agents learns who is calling

​Trusted backend

​Validated token (browser-direct)

​Guest tokens

​Claim a guest token

​Use the guest token

​Use runtime.identity in tools and middleware

​Scoping axes

​Custom downstream credentials

​Secrets checklist

​Test and deploy

​Next steps

Custom tools

LangSmith connector

How it works

CLI reference

What identity solves

Add an identity declaration

Choose a preset

Ingress: how Managed Deep Agents learns who is calling

Trusted backend

Validated token (browser-direct)

Guest tokens

Claim a guest token

Use the guest token

Use `runtime.identity` in tools and middleware

Scoping axes

Custom downstream credentials

Secrets checklist

Test and deploy

Next steps