Define a Managed Deep Agent - Docs by LangChain

The agent definition selects the model and core capabilities of a Managed Deep Agent. Export it as a named agent from agent.py, agent.ts, or agent.tsx at the project root.

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

Define an agent

Use define_deep_agent in Python or defineDeepAgent in TypeScript:

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    name="research-assistant",
    model="openai:gpt-5.5",
)

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  name: "research-assistant",
  model: "openai:gpt-5.5",
});

Name

name is required. Pass a static string that starts with a letter and contains only letters, numbers, underscores, or hyphens, such as "research-assistant". MDA uses the name as the LangGraph assistant ID and the default LangSmith deployment name. You can override the deployment name with mda deploy --name without changing the agent definition.

Model

Set model to the chat model the agent uses. The simplest option is a provider:model string, such as "openai:gpt-5.5". Add the provider’s API key to .env so the model works locally and in the deployment. Pass a LangChain chat model instance instead when you need to configure model parameters in code. For model options and supported providers, see Models.

Tools

Pass tools in the tools list to let the agent call application logic or external services. Define tools in local modules, import them into the agent entry, and add them to the definition. See Custom tools.

Middleware

Pass middleware in the middleware list to add behavior around model calls, tool calls, and the agent lifecycle. Middleware runs in list order. See Custom middleware.

Subagents

Pass subagent definitions in subagents when the agent should delegate specialized or context-heavy work. Each subagent can have its own prompt, model, and tools. See Subagents.

Permissions

Pass filesystem permission rules in permissions to control which paths the agent’s built-in filesystem tools can read or write. See Permissions.

Human-in-the-loop

Set interrupt_on in Python or interruptOn in TypeScript to pause before selected tool calls. Use this for actions that require a person to approve, edit, or reject the call before it runs. See Human-in-the-loop.

Structured output

Set response_format in Python or responseFormat in TypeScript when the agent must return data that matches a schema instead of an unconstrained text response. See Structured output. Configure the system prompt, skills, memory, sandbox, identity, channels, and schedules through their project files rather than the agent definition. See Project structure.

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

Edit this page on GitHub or file an issue.

​Define an agent

​Name

​Model

​Tools

​Middleware

​Subagents

​Permissions

​Human-in-the-loop

​Structured output

Define an agent

Name

Model

Tools

Middleware

Subagents

Permissions

Human-in-the-loop

Structured output