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

Export the agent definition as a named agent. You can also use agent.tsx.

Define an agent

Use defineDeepAgent:

import { defineDeepAgent } from "managed-deepagents";

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

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  name: "research-assistant",
  model: "anthropic:claude-sonnet-4-6",
});

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  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
`interruptOn`	Pauses before selected tool calls for human approval
`responseFormat`	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". 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. Add the provider’s API key to .env so the model works locally and in the deployment.

import { defineDeepAgent } from "managed-deepagents";

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

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  name: "research-assistant",
  model: "anthropic:claude-sonnet-4-6",
});

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  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.

Using LangSmith Gateway

You can use LangSmith Gateway to control rate limits, fallbacks, and more. In order to use, you should:

Use the ChatOpenAI model directly
Set a base url of https://gateway.smith.langchain.com/v1
Set an environment variable of LANGSMITH_GATEWAY_API_KEY to be your LangSmith API key.

This should look like (illustrative):

import { defineDeepAgent } from "managed-deepagents";
import { ChatOpenAI } from "@langchain/openai";

const apiKey =
  process.env.LANGSMITH_GATEWAY_API_KEY ?? "missing-langsmith-gateway-api-key";
const baseURL = "https://gateway.smith.langchain.com/v1";

export const agent = defineDeepAgent({
  name: "my-agent",
  model: new ChatOpenAI({
    model: "moonshotai/Kimi-K3",
    apiKey,
    configuration: { baseURL },
  }),
});

The model slug should be provider/model-name when using Gateway. When NOT using Gateway, it is normally provider:model-name

In order to scaffold your project to use Gateway from the start, you can pass a --gateway flag when initializing your agent:

mda init my-agent --gateway

Tools

Pass tools in the tools array 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 array to add behavior around model calls, tool calls, and the agent lifecycle. Middleware runs in array 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 interruptOn 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 responseFormat 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

Using LangSmith Gateway

Tools

Middleware

Subagents

Permissions

Human-in-the-loop

Structured output

​Project structure

​Define an agent

​Name

​Model

​Using LangSmith Gateway

​Tools

​Middleware

​Subagents

​Permissions

​Human-in-the-loop

​Structured output

Project structure

Define an agent

Name

Model

Using LangSmith Gateway

Tools

Middleware

Subagents

Permissions

Human-in-the-loop

Structured output