Define a Managed Deep Agent

The agent definition selects the model and core capabilities of a Managed Deep Agent.

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

Project structure

The agent entry lives at the project root:

my-agent/
  agent.py

Export the agent definition as a named agent.

Define an agent

Use define_deep_agent:

from managed_deepagents import define_deep_agent

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

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    name="research-assistant",
    model="anthropic:claude-sonnet-4-6",
)

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    name="research-assistant",
    model="google_genai:gemini-3.6-flash",
)

Parameter	What it does
`name=`	Sets the agent and default deployment name
`model=`	Selects the chat model
`tools=`	Adds tools the agent can call
`middleware=`	Adds behavior around model calls, tool calls, and the agent lifecycle
`subagents=`	Defines specialized agents for delegated tasks
`permissions=`	Controls path-level access for filesystem tools
`interrupt_on=`	Pauses before selected tool calls for human approval
`response_format=`	Defines a structured output schema

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". Managed Deep Agents 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. Add the provider’s API key to .env so the model works locally and in the deployment.

from managed_deepagents import define_deep_agent

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

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    name="research-assistant",
    model="anthropic:claude-sonnet-4-6",
)

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    name="research-assistant",
    model="google_genai:gemini-3.6-flash",
)

Pass a LangChain chat model instance instead when you need to configure model parameters in code. For model options and supported providers, see Models.

Use LLM Gateway

You can use LLM Gateway to apply rate limits, fallbacks, and other policies to model calls. Prefix the gateway model ID with langsmith::

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    name="my-agent",
    model="langsmith:moonshotai/kimi-k3",
)

Gateway model IDs use a slash between provider and model (langsmith:provider/model-name). Model strings that call a provider directly use a colon (provider:model-name).

The gateway routes each request by model ID. moonshotai/kimi-k3 is a LangChain-hosted model, so it requires no provider secret and draws on Gateway Credits. A model ID that starts with a provider your workspace has configured, such as anthropic/claude-opus-5, uses that provider secret and bills to your own provider account. For more information, see LLM Gateway.

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. To add tools from remote MCP servers without importing them into the agent entry, use MCP connectors.

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

Get started

Agent definition

Build and deploy

Project structure

Define an agent

Name

Model

Use LLM Gateway

Tools

Middleware

Subagents

Permissions

Human-in-the-loop

Structured output

​Project structure

​Define an agent

​Name

​Model

​Use LLM Gateway

​Tools

​Middleware

​Subagents

​Permissions

​Human-in-the-loop

​Structured output

Project structure

Define an agent

Name

Model

Use LLM Gateway

Tools

Middleware

Subagents

Permissions

Human-in-the-loop

Structured output