Add identity to Managed Deep Agents

Agents are not anonymous chatbots. As soon as more than one person (or one company) uses a deployment, you need to know: whose conversation is this, and whose data may the agent see or act on? Identity lets one deployment serve thousands of users safely, with no data leakage between callers. Managed Deep Agents answers that question before every run. You declare a small contract once, and the runtime partitions threads, memory, and credentials so callers cannot see or affect each other. Identity is opt-in. Projects without identity.ts or identity.py compile and deploy unchanged. When you add a declaration, mda wires auth, scoping, and a frozen runtime.identity object into tools and middleware. This page assumes you have an existing Managed Deep Agents project and the mda CLI installed. If you are new to Managed Deep Agents, start with the overview and quickstart first.

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

Why identity matters for agents

Without identity, a Managed Deep Agent has one shared boundary for the whole deployment. That is fine for a personal prototype. It breaks as soon as real users show up:

What goes wrong	Example
Shared memory	Alice asks the agent to remember her API preferences. Bob opens a new chat and the agent already “knows” Alice’s details.
Shared threads	Anyone who can hit the deployment can resume or inspect another user’s conversation.
Wrong credentials	The agent calls GitHub or another API with one shared token, so every user acts as the same account, or you have no safe way to act as the signed-in user.

Deep Agents without identity make this a real problem: they keep durable memory, resume long-running threads, and call tools on the user’s behalf. Identity turns “who is calling?” into enforced isolation instead of hoping the prompt or the UI keeps people apart. A key benefit of identity is that downstream tool calls can act as the signed-in user rather than as a shared bot account. For example, with credentials: "actor", the agent calls GitHub as Alice, not as a single bot token shared across all users. For deployments with compliance requirements such as SOC 2, GDPR, or HIPAA, identity scoping provides the data segregation boundaries that auditors expect: each caller’s threads and memory are isolated, and runtime.identity gives you an audit trail of who triggered each run.

Adding identity to a project that previously had none does not delete existing threads or memory. Threads created before identity was enabled remain accessible at the agent scope. New threads are scoped by actor (or tenant) according to your declaration. To migrate old data, export it and re-create threads under the new scoping rules.

Understand three core concepts

Learn these three concepts before you write any identity config:

Idea	Plain meaning	Example
Actor	The person or service this run is for	`user_123`, a GitHub login, a guest id
Tenant (optional)	The customer or org boundary when one deployment serves many orgs	`acme`, a Slack workspace
Ingress	How the runtime learns who is calling for this request	Your backend sends identity headers, or the browser sends a verified login token

A few important clarifications:

Actor is not the agent. It is the caller the run represents.
Tenant is not a LangSmith workspace. Single-tenant agents have no tenant.
Fail closed means the runtime rejects any request that is missing a required actor or tenant. It never falls back to shared memory or threads.

From actor (and optional tenant), Managed Deep Agents derives three outcomes:

Threads: who can open or resume a conversation
Memory: which durable Context Hub slice the run can see
Credentials: whose token the agent uses for downstream tool calls (the signed-in user, or one shared agent token)

Choose a preset

Presets encode the common product shapes so you do not invent scoping rules on day one. Start here, then override only what differs. The preset table uses these scope values:

Value	Meaning
`actor`	Private to the signed-in person (or service actor)
`tenant`	Shared inside one customer org, isolated from other orgs
`channel`	Shared by everyone in the same channel (for example Slack)
`agent`	Shared by the whole deployment
(unset) / `none`	Not scoped on this axis

Credentials is often the first thing teams consider:

actor: downstream calls can act as the signed-in user (for example call GitHub as Alice).
agent: downstream calls use one shared bot or service token for everyone.

Managed Deep Agents ships with five product shapes out of the box, covering the most common deployment patterns. Choose a preset based on your product shape:

Preset	Use it when…	Threads	Memory	Credentials
`private-assistant`	Each person gets a private 1:1 assistant with their own history and memory	`actor`	`actor`	`actor`
`multi-tenant-saas`	One deployment serves many customer orgs; users share org data but not across orgs	`actor`	`tenant`	`agent`
`shared-bot`	A Slack/Discord-style bot where everyone in the channel shares the thread	`channel`	`actor`	`agent`
`internal-tool`	An internal company agent: one org, private per-user threads	`actor`	`actor`	`agent`
`service`	Cron/webhook-only agents with no human caller and shared memory	(unset)	`agent`	`agent`

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

How to choose quickly:

One human per conversation who must not see anyone else’s data → private-assistant
SaaS with customer orgs → multi-tenant-saas
Shared channel bot → shared-bot
Internal company tool → internal-tool
Timer or webhook with no user → service

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 one-line 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");

That expands to this full contract:

from managed_deepagents import define_identity

identity = define_identity(
    ingress={"http": "trusted_backend"},
    tenancy="single",
    scoping={
        "threads": "actor",
        "memory": "actor",
        "credentials": "actor",
    },
)

import { defineIdentity } from "managed-deepagents";

export const identity = defineIdentity({
  ingress: { http: "trusted_backend" },
  tenancy: "single",
  scoping: {
    threads: "actor",
    memory: "actor",
    credentials: "actor",
  },
});

Use the full form when you want every field visible, or when you are assembling a config that does not match a preset. You can also start from a preset and override only the fields that differ. The same define_identity / defineIdentity object serves as both a factory (full form) and a preset selector (.preset() method). 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.

Ingress: identify the caller

Ingress is the mechanism the runtime uses to identify the actor (and tenant) for each request. Choose one HTTP mode: trusted_backend or validated_token.

Trusted backend (recommended default)

Your own API authenticates the user (session, OAuth, or similar), then proxies LangGraph requests with a shared ingress secret and reserved identity headers. The browser never sends the secret or raw identity-provider (IdP) tokens to Managed Deep Agents. This is the default ingress for all presets, and the recommended choice when you already have a backend in front of the agent. For the broader LangGraph auth model, see Add auth to your server. 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

Use a preset that defaults to trusted-backend ingress:

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. In production, your backend authenticates the user, then attaches the identity headers (X-MDA-Ingress-Secret, X-MDA-Actor-Id, and X-MDA-Tenant-Id when applicable) when proxying agent traffic. Example shape for a backend proxy (pseudocode):

// After your app authenticates the user
await fetch(`${deploymentUrl}/threads/${threadId}/runs`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-MDA-Ingress-Secret": process.env.MDA_INGRESS_SECRET!,
    "X-MDA-Actor-Id": authenticatedUser.id,
    // "X-MDA-Tenant-Id": org.id, // only when tenancy is "multi"
  },
  body: JSON.stringify(runBody),
});

Never commit ingress secrets or IdP credentials. Only send MDA_INGRESS_SECRET from a trusted backend proxy, never from the browser.

Validated token (browser-direct)

Use this when the browser talks to the deployment directly and you do not want a proxy that asserts actor headers. The client sends Authorization: Bearer <token>. Managed Deep Agents verifies the token server-side and maps claims (fields inside the token, such as user id) into runtime.identity. Verification can use:

JWKS: public keys your IdP publishes so the runtime can verify signed JWTs
OIDC discovery: standard metadata that points the runtime at those keys
Opaque introspection: call the IdP to ask whether a non-JWT token is still valid
Guest tokens: short-lived tokens signed by Managed Deep Agents for anonymous visitors

Override a preset to enable validated-token ingress. The following example combines Supabase sign-in with optional guest access:

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:" }),
      ],
    },
  },
});

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. When you configure more than one provider, give each entry a unique id. The runtime routes JWT providers by token iss (issuer) and returns 401 when the issuer does not match any configured provider. For provider-specific options and client examples, see Provider setup guides. To let anonymous visitors use the agent with no external identity provider, configure guest tokens as the only provider. Each visitor gets a short-lived, Managed Deep Agents-signed token and a distinct guest actor, so the private-assistant preset still scopes threads and memory per visitor.

from managed_deepagents import define_identity, providers

identity = define_identity.preset(
    "private-assistant",
    {
        "ingress": {
            "http": {
                "mode": "validated_token",
                "providers": [
                    providers.guest(ttl="24h", actor_prefix="guest:"),
                ],
            }
        }
    },
)

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

export const identity = defineIdentity.preset("private-assistant", {
  ingress: {
    http: {
      mode: "validated_token",
      providers: [providers.guest({ ttl: "24h", actorPrefix: "guest:" })],
    },
  },
});

When a guest provider is configured, the deployment exposes a public POST /identity/guest route that mints a guest token. The client calls it once, then sends the returned token as Authorization: Bearer <token> on later requests. The response body is {"token": "<token>"}.

USER_TOKEN=$(curl -s -X POST "$DEPLOYMENT_URL/identity/guest" \
  -H "Content-Type: application/json" | python -c 'import sys, json; print(json.load(sys.stdin)["token"])')

Secrets checklist

Secret	How Managed Deep Agents uses it
`MDA_INGRESS_SECRET`	Shared secret your backend sends in `X-MDA-Ingress-Secret`. The runtime checks it before trusting `X-MDA-Actor-Id` and `X-MDA-Tenant-Id`.
`MDA_GUEST_SIGNING_KEY`	Key used to sign guest tokens at `POST /identity/guest` and to verify them on later requests.

Put local values in .env. mda deploy forwards non-reserved .env values as hosted deployment secrets. Provider-specific secrets (for example Supabase introspection) are listed in Provider setup guides.

Never commit ingress secrets, guest signing keys, or IdP credentials. Only send MDA_INGRESS_SECRET from a trusted backend proxy, never from the browser.

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. The identity object looks like this:

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
};

Annotate the injected runtime parameter as ManagedDeepAgentRuntime so you get typed access to identity (and optional credentials). Use it whenever a tool or middleware hook needs to know who triggered the run, for personalization, audit logs, or branching on verified claims, without trusting anything from the request body.

from langchain.tools import tool
from managed_deepagents import ManagedDeepAgentRuntime


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

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

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 same type works in middleware hooks:

from langchain.agents.middleware import AgentState, before_model
from managed_deepagents import ManagedDeepAgentRuntime


def audit_middleware():
    @before_model
    def audit(state: AgentState, runtime: ManagedDeepAgentRuntime) -> dict | None:
        user = runtime.identity["actor"]["id"] if runtime.identity else "anonymous"
        print(f"[audit] {user} model call with {len(state['messages'])} messages")
        return None

    return audit

import { createMiddleware } from "langchain";
import type { ManagedDeepAgentRuntime } from "managed-deepagents";

export function auditMiddleware() {
  return createMiddleware({
    name: "audit",
    beforeModel: (state, runtime: ManagedDeepAgentRuntime) => {
      const user = runtime.identity?.actor.id ?? "anonymous";
      console.log(
        `[audit] ${user} model call with ${state.messages.length} messages`
      );
      return undefined;
    },
  });
}

Prefer runtime.identity over client-supplied configurable keys for actor or tenant ids. For other per-run values such as feature flags, use normal LangChain runtime context.

Customize scoping

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`	Which Context Hub memory slice is remounted for the run
`credentials`	`agent`, `actor`, `none`, `custom`	Whose credentials downstream calls use

If tenancy is "single", do not set any scoping axis to "tenant", there is no tenant to scope by. If a request is missing the actor or tenant id that scoping needs, Managed Deep Agents rejects it with 403 instead of falling back to shared data. For how memory paths remount under each scope, see Scope memory with identity.

Custom downstream credentials

Use scoping.credentials: "custom" when your application can securely obtain a per-actor credential for a downstream target. Provide a resolve function; tools then call runtime.credentials.for(target) to obtain the headers for that request. Resolved credentials are kept in memory and are never written to thread state or traces.

The token that proves a caller’s identity is not automatically a credential for downstream APIs. For example, a Supabase access token lets Managed Deep Agents identify the caller, but it is not a GitHub API token. Your backend or credential service must hold (and, when needed, refresh) the caller’s separately authorized GitHub credential.

The following shape lets a user sign in through Supabase and open GitHub pull requests as themselves. After the user has separately authorized GitHub, your application stores the GitHub grant keyed by the Supabase user id. getGitHubAccessToken is application code: it looks up and refreshes that grant in your server-side credential store.

identity.ts

import { defineIdentity, providers } from "managed-deepagents";
import { getGitHubAccessToken } from "./github-credentials.js";

export const identity = defineIdentity({
  ingress: {
    http: {
      mode: "validated_token",
      providers: [providers.supabase({ projectRef: "your-project-ref" })],
    },
  },
  tenancy: "single",
  scoping: {
    threads: "actor",
    memory: "actor",
    credentials: "custom",
  },
  credentials: {
    async resolve({ identity, target }) {
      if (target.name !== "github") {
        throw new Error(`No credentials configured for ${target.name}.`);
      }

      const credential = await getGitHubAccessToken(identity.actor.id);
      if (!credential) {
        throw new Error("Connect GitHub before using GitHub tools.");
      }

      return {
        headers: { Authorization: `Bearer ${credential.token}` },
        expiresAt: credential.expiresAt.toISOString(),
      };
    },
  },
});

In a GitHub tool, request the headers with await runtime.credentials.for({ kind: "connection", name: "github", intent: "write" }) and pass them to your GitHub client. 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.

Provider setup guides

These guides cover the built-in providers for validated token ingress. Use one provider, or combine them as in the example in that section.

Guest tokens
Supabase
GitHub

Anonymous visitors get a short-lived, actor-scoped session without signing in. Managed Deep Agents signs guest tokens with MDA_GUEST_SIGNING_KEY (HS256) and maps sub → actor.

Option	Required	Description
`ttl`	No	Token lifetime (for example `"24h"`)
`actorPrefix` / `actor_prefix`	No	Prefix for generated actor ids (for example `"guest:"`)

Guest is usually combined with another IdP, as in the validated token example.Set MDA_GUEST_SIGNING_KEY in .env for mda dev and as a hosted deployment secret for mda deploy.

Claim a guest token

With guest issuance enabled, the deployment exposes POST /identity/guest. Send an empty POST 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:

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

Use the guest token

Send the token the same way you send IdP access tokens:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

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

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.

JWKS by default (asymmetric JWTs). Maps sub → actor. Pass only one of projectRef or url.

Option	Required	Description
`projectRef` / `project_ref`	One of `projectRef` or `url`	Subdomain before `.supabase.co`
`url`	One of `projectRef` or `url`	Project URL or custom auth domain
`introspect`	No	`true` for legacy HS256 projects that need `/auth/v1/user`

Use providers.supabase(...) alone, or combine it with guest as in the validated token example.After sign-in, send session.access_token from @supabase/supabase-js. See also Supabase Auth and JWT signing keys.For legacy introspection, use introspect: true and set SUPABASE_ANON_KEY on the deployment.

Opaque token introspection via GET https://api.github.com/user. Maps login → actor, email → email. providers.github() takes no options.

from managed_deepagents import define_identity, providers

identity = define_identity.preset(
    "internal-tool",
    {
        "ingress": {
            "http": {
                "mode": "validated_token",
                "providers": [providers.github()],
            }
        }
    },
)

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

export const identity = defineIdentity.preset("internal-tool", {
  ingress: {
    http: {
      mode: "validated_token",
      providers: [providers.github()],
    },
  },
});

Complete a GitHub OAuth App sign-in flow, then send the user access token. Do not send OAuth client secrets to the deployment. See also Authorizing OAuth apps and Get the authenticated user.For production, prefer trusted backend ingress: keep the GitHub token on your API, and proxy with X-MDA-Ingress-Secret + X-MDA-Actor-Id (for example the GitHub login).

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 the first authenticated request. Confirm the matching secret is present and that trusted-backend proxies attach the reserved headers.

Next steps

Memory

See how identity remounts per-actor or per-tenant memory.

Custom tools

Read runtime.identity from authored tools.

Evals

Supply identity.json fixtures for Harbor tasks when identity is declared.

Schedules

Run cron agents, including the service preset shape.

LangSmith connector

Expose constrained LangSmith capabilities to untrusted callers.

Channels

Receive Slack Events with shared-bot or Connect-with-Slack linking.

How it works

See how compile and deploy wire auth into the runtime.

CLI reference

Look up project files and identity wiring in mda.

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

Edit this page on GitHub or file an issue.

​Why identity matters for agents

​Understand three core concepts

​Choose a preset

​Add an identity declaration

​Ingress: identify the caller

​Trusted backend (recommended default)

​Validated token (browser-direct)

​Secrets checklist

​Use runtime.identity in tools and middleware

​Customize scoping

​Custom downstream credentials

​Provider setup guides

​Claim a guest token

​Use the guest token

​Test and deploy

​Next steps

Memory

Custom tools

Evals

Schedules

LangSmith connector

Channels

How it works

CLI reference

Why identity matters for agents

Understand three core concepts

Choose a preset

Add an identity declaration

Ingress: identify the caller

Trusted backend (recommended default)

Validated token (browser-direct)

Secrets checklist

Use `runtime.identity` in tools and middleware

Customize scoping

Custom downstream credentials

Provider setup guides

Claim a guest token

Use the guest token

Test and deploy

Next steps