Add identity to Managed Deep Agents

Agents are not anonymous chat boxes. As soon as more than one person (or one company) uses a deployment, you need a reliable answer to: whose conversation is this, and whose data may the agent see or act on? Identity is how Managed Deep Agents answers that before every run. You declare a small contract once. The runtime then partitions threads, memory, and credentials so callers cannot bleed into 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.

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 make this sharper than a simple chatbot: they keep durable memory, resume long-running threads, and call tools on the user’s behalf. Identity turns “who is calling?” into hard isolation instead of hoping the prompt or the UI keeps people apart.

Three ideas to know first

You only need three ideas before you write any 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 a missing required actor or tenant rejects the request. The runtime never falls back to “everyone’s” 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 downstream tool calls use (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. Before you read the table, these scope values mean:

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 used for that axis

Credentials is the product difference many teams care about first:

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.

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. 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: how Managed Deep Agents learns who is calling

Ingress is only the how: how the runtime learns the actor (and tenant) for this request. Pick one HTTP mode.

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 for presets and the usual path when you already have a backend in front of the agent. 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. Your production backend should authenticate the user, then attach the headers above 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. Do not send MDA_INGRESS_SECRET from the browser—only from a trusted backend proxy.

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 example below 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 more than one provider is configured, each entry needs an id. Managed Deep Agents routes JWT providers by token iss (issuer) and fails closed when the issuer is unknown. For provider-specific options and client examples, see Provider setup guides.

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. Do not send MDA_INGRESS_SECRET from the browser—only from a trusted backend proxy.

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.

Schedules

Run cron agents, including the service preset shape.

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

​Three ideas to know first

​Choose a preset

​Add an identity declaration

​Ingress: how Managed Deep Agents learns who is calling

​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

Schedules

LangSmith connector

How it works

CLI reference

Why identity matters for agents

Three ideas to know first

Choose a preset

Add an identity declaration

Ingress: how Managed Deep Agents learns who is calling

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