Add custom tools to Managed Deep Agents

Custom tools are application code the agent can call for fetching real-time data, querying databases, executing code, and taking actions. Unlike instructions and skills, MDA does not discover them automatically. To load tools from a remote MCP server, see Connect to MCP servers.

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

Put authored tools under tools/, import them into the agent entry, and pass them to the agent definition:

my-agent/
  agent.ts
  tools/
    customer.ts

For the full project layout, see Project structure. To load tools from a remote MCP server without importing them into the agent entry, use an MCP connector instead. MCP connectors are declared under tools/ as well, so the tools/mcp.ts file name is reserved for that declaration.

Add a tool

Use authored tools for business logic, private APIs, database access, and other code that belongs in your agent project.

Define a tool module

tools/customer.ts

import { tool } from "langchain";
import { z } from "zod";

export const lookupCustomer = tool(
  async ({ customerId }) => `Customer ${customerId} is on the enterprise plan.`,
  {
    name: "lookup_customer",
    description: "Look up a customer record by ID.",
    schema: z.object({
      customerId: z.string().describe("Customer ID from the CRM."),
    }),
  },
);

Use clear, unique tool names to avoid collisions. For more about LangChain tool definitions, see Tools.

Attach the tool to the agent

Import the tool into the project-root agent entry and pass it in the tools list:

agent.ts

import { defineDeepAgent } from "managed-deepagents";

import { lookupCustomer } from "./tools/customer";

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

Your imports should work the same way they do in a normal local TypeScript project.

Add human-in-the-loop (Optional)

Pause the agent before sensitive tool calls so a person can approve, edit, or reject them.Set interruptOn in the agent definition, and optionally set permissions to gate tool and filesystem access:

agent.ts

import { defineDeepAgent } from "managed-deepagents";

import { lookupCustomer } from "./tools/customer";

export const agent = defineDeepAgent({
  name: "support-agent",
  model: "openai:gpt-5.5",
  tools: [lookupCustomer],
  interruptOn: {
    lookup_customer: true,
  },
});

The interruptOn field applies the same interrupt behavior as LangChain’s human-in-the-loop middleware.For decision types (approve, edit, reject), conditional interrupts, and permission rules, see the Deep Agents Human-in-the-loop and Permissions guides.To resume a paused run, see Respond to an interrupt.

Use secrets and context

Tools can read deployment secrets from environment variables. Put local values in .env for mda dev; mda deploy forwards non-reserved .env values as hosted deployment secrets. For per-run values such as request metadata or feature flags, use the normal LangChain runtime context patterns for tools. See how to access context from within your tools.

Deployment

mda dev and mda deploy copy project files into the compiled build, including modules under tools/. Tools are not synced to Context Hub; they ship with the agent code.

When to use tools

Concept	Kind	How it reaches the agent
Tools	Application code	Import and pass in the agent definition
MCP connectors	Managed configuration	Declared in the MCP module under `tools/`; no import into the agent entry
Skills	Managed context	Procedures the agent loads when relevant
Instructions	Managed context	Always-on system prompt

For more information, see Project structure.

Respond to an interrupt

When a run hits an interrupt, it pauses and waits for a human response before continuing.

During local development, mda dev runs the agent in LangSmith Studio, which surfaces the interrupt so you can inspect the pending tool call and resume the run.
On a deployed agent, resume the paused run through the LangGraph server API with a resume payload. See Human-in-the-loop using server API.

During public beta, Managed Deep Agents is CLI-first and programmatic invocation is not yet documented. To resume runs programmatically from your own application, contact your LangChain team.

Human-in-the-loop needs durable thread state to pause and resume. The managed runtime owns the checkpointer, so no extra setup is required.

Use tools that require authentication

If a tool requires an API key or OAuth token, use a connection to resolve the credential at runtime. See Manage connections.

Access runtime context

For per-run values such as request metadata or feature flags, use the normal LangChain runtime context patterns for tools. See how to access context from within your tools.

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 capabilities

Build and deploy

Add custom tools to Managed Deep Agents

Add a tool

Use secrets and context

Deployment

When to use tools

Respond to an interrupt

Use tools that require authentication

Access runtime context

​Add a tool

​Use secrets and context

​Deployment

​When to use tools

​Respond to an interrupt

​Use tools that require authentication

​Access runtime context

Add a tool

Use secrets and context

Deployment

When to use tools

Respond to an interrupt

Use tools that require authentication

Access runtime context