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.

The agent entry lives at the project root:

my-agent/
  agent.py

For the full project layout, see Project structure. To define the 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",
)

Configure the system prompt, skills, memory, sandbox, identity, channels, and schedules through their project files rather than the agent definition. See Project structure. define_deep_agent does not compile an agent. It returns a definition, and the managed runtime compiles it with create_deep_agent at deploy time. The parameters below are the create_deep_agent surface without the ones the runtime owns. See Relationship to Deep Agents.

Parameters

Parameter	What it does
`name=`	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 agent’s graph ID and the default LangSmith deployment name, and clients pass it as `assistant_id` when they call the deployment. You can override the deployment name with `mda deploy --name` without changing the agent definition.
`model=`	Set 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. Pass a LangChain chat model instance instead when you need to configure model parameters in code. For model options and supported providers, see Models. To connect to LLM Gateway, see Use LLM Gateway.
`tools=`	Adds tools the agent can call. Pass tools in the `tools` list so the agent can 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=`	Adds behavior around model calls, tool calls, and the agent lifecycle. Pass middleware in the `middleware` list. Middleware runs in list order. See Custom middleware.
`subagents=`	Defines specialized agents for delegated tasks. Pass subagent definitions when the agent should delegate specialized or context-heavy work. Each subagent can have its own prompt, model, and tools. See Subagents.
`permissions=`	Controls path-level access for filesystem tools. Pass filesystem permission rules to control which paths the agent’s built-in filesystem tools can read or write. Cleared when the project declares a sandbox, because a permission rule disables the sandbox `execute` tool. See Permissions.
`interrupt_on=`	Pauses before selected tool calls for human approval. Set `interrupt_on` to pause before selected tool calls, so a person can approve, edit, or reject the call before it runs. See Human-in-the-loop.
`response_format=`	Set when the agent must return data that matches a schema instead of an unconstrained text response. See Structured output.

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. To scaffold a project that uses Gateway from the start, pass --gateway when initializing:

mda init my-agent --gateway

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Agent capabilities

Build and deploy

Parameters

Use LLM Gateway

​Parameters

​Use LLM Gateway

Parameters

Use LLM Gateway