> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-contex-1789468204-c45d5ed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Define a Managed Deep Agent
> Configure the model and core capabilities of 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](/langsmith/release-stages)** and available on [LangSmith Cloud](/langsmith/cloud) in the US region only.
The agent entry lives at the project root:
```text theme={null}
my-agent/
agent.py
```
For the full project layout, see [Project structure](/langsmith/python/managed-deep-agents-project-structure).
To define the agent, use `define_deep_agent`:
```python OpenAI theme={null}
from managed_deepagents import define_deep_agent
agent = define_deep_agent(
name="research-assistant",
model="openai:gpt-5.5",
)
```
```python Anthropic theme={null}
from managed_deepagents import define_deep_agent
agent = define_deep_agent(
name="research-assistant",
model="anthropic:claude-sonnet-4-6",
)
```
```python Google Gemini theme={null}
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](/langsmith/python/managed-deep-agents-project-structure).
## 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 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 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](/oss/python/deepagents/models).
To connect to LLM Gateway, see [Use LLM Gateway](#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](/langsmith/python/managed-deep-agents-tools). To add tools from remote MCP servers without importing them into the agent entry, use [MCP connectors](/langsmith/python/managed-deep-agents-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](/langsmith/python/managed-deep-agents-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](/oss/python/deepagents/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. See [Permissions](/oss/python/deepagents/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](/langsmith/python/managed-deep-agents-tools#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](/oss/python/langchain/structured-output). |
## Use LLM Gateway
You can use [LLM Gateway](/langsmith/llm-gateway) to apply rate limits, fallbacks, and other policies to model calls.
Prefix the gateway model ID with `langsmith:`:
```python theme={null}
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](/langsmith/llm-gateway-credits). A model ID that starts with a provider your workspace has configured, such as `anthropic/claude-opus-5`, uses that [provider secret](/langsmith/llm-gateway-admin-setup#1-add-provider-secrets) and bills to your own provider account.
For more information, see [LLM Gateway](/langsmith/llm-gateway).
To scaffold a project that uses Gateway from the start, pass `--gateway` when initializing:
```bash theme={null}
mda init my-agent --gateway
```
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-agent-definition.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).