Managed Deep Agents quickstart

Create and deploy your first Managed Deep Agent with the mda CLI.

Create and deploy your first Managed Deep Agent: scaffold a project, configure the model and instructions, add search, test in LangSmith Studio, and deploy with the mda CLI. Managed Deep Agents supplies the Deep Agents harness and hosted runtime.

After this quickstart, the tutorial adds durable memory and a daily schedule on the same project.

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

Prerequisites

To follow along, you need:

• Python and uv.

• An API key for your model provider of choice.

Create and deploy an agent

1. Set up the project

   Install managed-deepagents, create a project, and open its directory:

   uv tool install managed-deepagents
   mda init research-assistant
   cd research-assistant
   

   You now have all the scaffolding for your agent.

2. Add your keys

   Add your model provider API key to .env:

   .env

   OPENAI_API_KEY=<OPENAI_API_KEY>
   # ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
   # GOOGLE_API_KEY=<GOOGLE_API_KEY>
   

   This quickstart uses OpenAI by default. If you choose Google or Anthropic in the next step, set that provider’s API key instead. mda deploy adds the provider key to the deployment. You can also use any other chat provider.

   Do not commit the .env file into version control. It contains secrets.

3. Set up LangSmith

   Managed Deep Agents runs on LangSmith. Your LangSmith API key authenticates local development with mda dev, deploys the agent with mda deploy, and opens the agent in LangSmith Studio so you can chat with it and inspect traces.

   Sign up for LangSmith if you do not already have an account.

   To create a LangSmith API key, open Settings, go to API Keys, and click Create API Key. For more details, see Create an account and API key.

   Add your LangSmith API key to .env:

   .env

   LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
   
4. 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.

5. Configure your model and search

   Now set the model and a built-in web search tool. Google, OpenAI, and Anthropic offer server-side search with no extra package or API key. Pass the provider tool dict that matches your model:

   Open agent.py:

   OpenAI

   from managed_deepagents import define_deep_agent
   
   # OpenAI's built-in web search — no extra install or API key needed
   agent = define_deep_agent(
       name="research-assistant",
       model="openai:gpt-5.5",
       tools=[{"type": "web_search"}],
   )
   

   The agent name is also the default deployment name. For model concepts and provider options, see Models.

   Using another provider?

   You can use a Tavily search tool instead. Add a Tavily API key to .env:

   .env

   TAVILY_API_KEY=<TAVILY_API_KEY>
   

   Install the Tavily client:

   uv add tavily-python
   

   Create a custom internet_search tool:

   tools/search.py

   import os
   from typing import Literal
   
   from langchain.tools import tool
   from tavily import TavilyClient
   
   
   tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
   
   
   @tool
   def internet_search(
       query: str,
       max_results: int = 5,
       topic: Literal["general", "news", "finance"] = "general",
   ) -> dict:
       """Search the internet for relevant sources."""
       return tavily_client.search(
           query,
           max_results=max_results,
           topic=topic,
       )
   

   Import the tool and add it to the agent:

   agent.py

   from managed_deepagents import define_deep_agent
   
   from tools.search import internet_search
   
   agent = define_deep_agent(
       name="research-assistant",
       model="openai:gpt-5.5",
       tools=[internet_search],
   )
   

   For more authored tools, see Custom tools.

6. Run locally

   Install the project dependencies and start the agent:

   uv sync
   mda dev .
   

   mda dev loads the API keys from .env, starts a local Agent Server, and opens the agent in LangSmith Studio.

   In Studio, send:

   What were the main announcements from the latest LangChain release?
   

   You should see the agent call the web search tool, then return a concise answer that cites sources. If search never appears in the trace, confirm the provider tool dict matches the model you set in agent.py or agent.ts.

   For more information, see Develop locally with LangSmith Studio.

7. Deploy the agent

   Deploy the project by running:

   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 that URL. You should see the deployment in a ready state. Send the same research question from the previous step and confirm the hosted agent returns an answer with a search tool call. 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

Add a custom Tavily search tool, durable memory, and a daily schedule.

Custom tools

Add authored LangChain tools from your project.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.