Add identity to Managed Deep Agents

Identity authenticates callers to a Managed Deep Agents deployment. When you declare identity, Managed Deep Agents gives each caller private threads and exposes the verified caller to tools and middleware.

Managed Deep Agents is in public beta and available on LangSmith Cloud in the US region only.

Add identity

Create identity.py or identity.ts at the project root and export a named identity declaration:

from managed_deepagents import define_identity

identity = define_identity()

import { defineIdentity } from "managed-deepagents";

export const identity = defineIdentity();

This declaration uses backend authentication, the default. The only configurable identity option is auth, which controls how Managed Deep Agents authenticates callers. Managed Deep Agents supplies the remaining identity behavior:

Threads: Each thread belongs to the authenticated caller. Requests cannot select another caller’s thread owner.
Runtime identity: Tools and middleware receive the verified caller through runtime.identity.

Identity does not configure durable memory or downstream connections. Do not pass scope, credentials, connect, or memory options to defineIdentity(...) or define_identity(...).

Adding identity to an existing deployment does not add owner metadata to existing threads. Plan and test a migration before relying on identity-based access for those threads.

Choose how callers authenticate

The auth option supports two patterns:

Backend authentication: Your backend authenticates the caller and sends trusted identity headers. This is the default.
Validated-token authentication: The caller sends an identity-provider token that Managed Deep Agents verifies.

Use backend authentication

Use backend authentication when your application server already authenticates users through a session, OAuth flow, or another mechanism. Your server proxies requests to the deployment with these headers:

Header	Purpose
`X-MDA-Ingress-Secret`	Shared secret that must match the deployment’s `MDA_INGRESS_SECRET`.
`X-MDA-User-Id`	Stable identifier for the authenticated caller.

The argument-free declaration selects this mode. You can also set it explicitly:

from managed_deepagents import define_identity

identity = define_identity(auth="backend")

import { defineIdentity } from "managed-deepagents";

export const identity = defineIdentity({ auth: "backend" });

After your backend authenticates the caller, forward the request with the reserved headers:

await fetch(`${deploymentUrl}/threads/${threadId}/runs`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-MDA-Ingress-Secret": process.env.MDA_INGRESS_SECRET!,
    "X-MDA-User-Id": authenticatedUser.id,
  },
  body: JSON.stringify(runBody),
});

Set MDA_INGRESS_SECRET as a hosted deployment secret. mda dev configures local identity automatically, so local Studio requests do not require these headers.

Send MDA_INGRESS_SECRET only from a trusted backend. Do not expose it in browser code or commit it to source control.

Backend authentication accepts only the caller id from the public identity headers. It does not accept groups, email, organization, or arbitrary claims from the client.

Use validated-token authentication

Use validated-token authentication when a browser or another client calls the deployment directly. The client sends:

Authorization: Bearer <token>

Managed Deep Agents verifies the token and maps its claims to the caller identity. As a first party example, use auth.supabase(...) to authenticate callers with Supabase.

Authenticate with Supabase

Configure Supabase with a project reference or project URL:

from managed_deepagents import auth, define_identity

identity = define_identity(
    auth=auth.supabase(project_ref="your-project-ref"),
)

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

export const identity = defineIdentity({
  auth: auth.supabase({ projectRef: "your-project-ref" }),
});

After signing in with Supabase Auth, send the user’s access token in the Authorization header. By default, Managed Deep Agents verifies JWTs against Supabase JWKS. Pass url for a custom auth domain.

Use `runtime.identity`

Tools and middleware receive a frozen identity object built from the trusted authentication result. Client-supplied identity keys in the normal configurable payload are not trusted. The identity contains:

user: The caller’s id, kind, and optional email.
groups: Optional group memberships mapped from a validated token.
source: The run’s ingress provider and optional source thread id.
claims: Optional verified token claims.

Use ManagedDeepAgentRuntime for typed access:

from langchain.tools import tool
from managed_deepagents import ManagedDeepAgentRuntime


@tool
def whoami(runtime: ManagedDeepAgentRuntime) -> str:
    """Return the authenticated user id for this run."""
    identity = runtime.identity
    if not identity:
        return "No authenticated caller on this run."
    return f"Signed in as {identity['user']['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.user.id}`;
  },
  {
    name: "whoami",
    description: "Return the authenticated user id for this run.",
    schema: z.object({}),
  },
);

In Python, read the optional source thread as runtime.identity["source"]["thread_id"]. In TypeScript, read it as runtime.identity.source.threadId. Use verified identity for personalization, audit records, and authorization decisions. Do not trust a user id supplied in a tool argument or request body.

Understand identity boundaries

Identity provides a fixed user boundary rather than configurable scope axes:

Threads are always per caller.
Validated-token groups and claims are available for authorization logic, but they do not change thread ownership.
Durable memory is configured in memory.py or memory.ts and is shared across the deployment.

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. Authentication failures return 401. Attempts to access another caller’s thread return 403. For backend authentication, confirm that the deployment has MDA_INGRESS_SECRET and that your proxy sends both reserved headers.

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

Edit this page on GitHub or file an issue.

​Add identity

​Choose how callers authenticate

​Use backend authentication

​Use validated-token authentication

​Authenticate with Supabase

​Use runtime.identity

​Understand identity boundaries

​Test and deploy

Add identity

Choose how callers authenticate

Use backend authentication

Use validated-token authentication

Authenticate with Supabase

Use `runtime.identity`

Understand identity boundaries

Test and deploy