Managed Deep Agents quickstart

Create an agent project, test it locally in LangSmith Studio, and deploy it to managed LangSmith infrastructure with the mda CLI. The project folder contains your agent’s model, instructions, and tools. Managed Deep Agents supplies the Deep Agents harness and hosted runtime.

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

Prerequisites

Before you start, make sure you have:

An organization with Managed Deep Agents public beta access.
A LangSmith API key.
Node.js and npm.
An API key for your model provider of choice.

Create and deploy an agent

Install the package

Install managed-deepagents. The package includes the mda CLI.

npm install -g managed-deepagents@dev

Create a project

Create a project and open its directory:

mda init research-assistant
cd research-assistant

The files you edit in this quickstart are:

agent.ts: Defines and exports the agent. See Agent definition.
instructions.md: Contains the prompt that describes how the agent should behave.
.env: Stores API keys for local development and deployment. Do not commit this file.

For all generated files, see Project structure.

Add API keys

Add your LangSmith API key and model provider API key to .env:

.env

LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>

This example uses an OpenAI chat model. If you choose another model provider, add the API key required by that provider instead. mda deploy uses the LangSmith API key to deploy the agent and adds the provider key to the deployment.

Configure the agent

Open agent.ts and set the agent name and model:

agent.ts

import { defineDeepAgent } from "managed-deepagents";

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

The model handles the agent’s language understanding and reasoning. The agent name is also the default deployment name. For model concepts and provider options, see Models.

Edit the instructions

Open instructions.md and describe how the agent should behave:

instructions.md

# Research assistant

You are a careful research assistant. Use internet search to find sources,
keep notes, and return concise answers with citations.

When you deploy, Managed Deep Agents syncs these instructions to LangSmith Context Hub, where you can update them without redeploying the agent.

Add an internet search tool

A tool is a function the agent can call to retrieve data or take an action. Choose your model provider’s server-side search or create a custom LangChain tool with Tavily.

Provider search (recommended)
Tavily (any provider)

OpenAI provides a built-in web search tool that runs server-side, so it does not require another package or API key. Add it directly to the agent:

agent.ts

import { defineDeepAgent } from "managed-deepagents";

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

Add a Tavily API key to .env:

.env

TAVILY_API_KEY=<TAVILY_API_KEY>

Install the Tavily client:

npm install @langchain/tavily

Create a custom internet_search tool:

tools/search.ts

import { TavilySearch } from "@langchain/tavily";
import { tool } from "langchain";
import { z } from "zod";

export const internetSearch = tool(
  async ({ query, maxResults = 5, topic = "general" }) => {
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,
      topic,
    });
    return tavilySearch._call({ query });
  },
  {
    name: "internet_search",
    description: "Search the internet for relevant sources.",
    schema: z.object({
      query: z.string().describe("The search query."),
      maxResults: z.number().optional().default(5),
      topic: z.enum(["general", "news", "finance"]).optional().default("general"),
    }),
  },
);

Import the tool and add it to the agent:

agent.ts

import { defineDeepAgent } from "managed-deepagents";

import { internetSearch } from "./tools/search";

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

For more information, see Custom tools.

Run locally

Install the project dependencies and start the agent:

npm install
mda dev .

mda dev loads the API keys from .env, starts a local Agent Server, and opens the agent in LangSmith Studio. Send messages in Studio to inspect model responses and tool calls. For more information, see Develop locally with LangSmith Studio.

Deploy the agent

Deploy the project:

mda deploy .

Managed Deep Agents packages the project and runs it as a hosted deployment on LangSmith Agent Server. When deployment finishes, the CLI prints the deployment dashboard URL. Open it to view and test the deployed agent.For deployment options and secrets handling, see Deploy a Managed Deep Agent. To inspect the agent’s execution after it runs, use LangSmith observability.

Next steps

Tutorial

Build a scheduled research agent from an empty directory.

Identity

Authenticate callers and provide private threads.

Memory

Persist preferences across threads with Context Hub /memories.

Evals

Author Harbor tasks and compile the managed agent for Harbor.

Custom tools

Add authored LangChain tools from your project source.

Custom middleware

Add built-in or custom middleware around model and tool calls.

Schedules

Run agents on managed cron schedules.

Deploy an agent

Test and deploy Managed Deep Agents with mda.

CLI reference

Review mda init, mda evals, mda dev, and mda deploy.

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

Managed Deep Agents quickstart

Prerequisites

Create and deploy an agent

Next steps

Tutorial

Identity

Memory

Evals

Custom tools

Custom middleware

Schedules

Deploy an agent

CLI reference

​Prerequisites

​Create and deploy an agent

​Next steps

Tutorial

Identity

Memory

Evals

Custom tools

Custom middleware

Schedules

Deploy an agent

CLI reference

Prerequisites

Create and deploy an agent

Next steps