Managed Deep Agents에 커스텀 도구 추가하기

관리형 딥 에이전트 프로젝트를 위해 작성한 도구를 정의하는 방법을 알려드릴게요.

커스텀 도구는 에이전트가 실시간 데이터 가져오기, 데이터베이스 조회, 코드 실행, 작업 수행을 위해 호출할 수 있는 애플리케이션 코드입니다. instructions와 skills와 달리 MDA는 이를 자동으로 발견하지 않습니다.

원격 MCP 서버에서 도구를 로드하려면 MCP 서버에 연결하기를 참고하세요.

참고: Managed Deep Agents는 공개 베타 상태이며 LangSmith Cloud의 미국 리전에서만 사용할 수 있어요.

출처: 문서

본문

작성한 도구는 tools/ 아래에 두고, 에이전트 엔트리로 가져온 뒤 에이전트 정의에 전달합니다:

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

전체 프로젝트 레이아웃은 프로젝트 구조를 참고하세요.

에이전트 엔트리로 가져오지 않고 원격 MCP 서버에서 도구를 로드하려면 대신 MCP 커넥터를 사용하세요.

MCP 커넥터도 tools/ 아래에 선언되므로 tools/mcp.ts 파일 이름은 해당 선언을 위해 예약되어 있습니다.

도구 추가하기

작성한 도구는 비즈니스 로직, 비공개 API, 데이터베이스 접근 등 에이전트 프로젝트에 속하는 코드에 사용하세요.

1. 도구 모듈 정의하기

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."),
    }),
  },
);

명확하고 고유한 도구 이름을 사용해 충돌을 피하세요. LangChain 도구 정의에 대한 자세한 내용은 Tools를 참고하세요.

2. 도구를 에이전트에 연결하기

도구를 프로젝트 루트 에이전트 엔트리로 가져와 tools 목록에 전달합니다:

import { defineDeepAgent } from "managed-deepagents";

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

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

import는 일반적인 로컬 TypeScript 프로젝트에서와 동일하게 동작합니다.

3. Human-in-the-loop 추가하기 (선택)

민감한 도구 호출 전에 에이전트를 일시 중지해 사람이 승인·편집·거부할 수 있게 합니다.

에이전트 정의에서 interruptOn을 설정하고, 선택적으로 permissions를 설정해 도구 및 파일시스템 접근을 게이트할 수 있습니다:

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,
  },
});

interruptOn 필드는 LangChain의 human-in-the-loop 미들웨어와 동일한 인터럽트 동작을 적용합니다.

의사결정 유형(승인, 편집, 거부), 조건부 인터럽트, 권한 규칙에 대해서는 Deep Agents의 Human-in-the-loop 및 Permissions 가이드를 참고하세요.

일시 중지된 실행을 재개하려면 인터럽트에 응답하기를 참고하세요.

시크릿과 컨텍스트 사용하기

도구는 환경 변수에서 배포 시크릿을 읽을 수 있습니다. mda dev에서는 로컬 값을 .env에 두세요. mda deploy는 예약되지 않은 .env 값을 호스팅 배포 시크릿으로 전달합니다.

요청 메타데이터나 기능 플래그 같은 실행별 값에는 도구용 일반 LangChain 런타임 컨텍스트 패턴을 사용하세요. 도구 내에서 컨텍스트에 접근하는 방법을 참고하세요.

배포

mda dev와 mda deploy는 tools/ 아래의 모듈을 포함해 프로젝트 파일을 컴파일된 빌드로 복사합니다. 도구는 Context Hub에 동기화되지 않습니다. 에이전트 코드와 함께 배포됩니다.

도구 사용 시점

개념	종류	에이전트에 도달하는 방식
Tools	애플리케이션 코드	에이전트 정의에서 import 후 전달
MCP 커넥터	관리형 구성	`tools/` 아래의 MCP 모듈에 선언, 에이전트 엔트리로 import 아님
Skills	관리형 컨텍스트	관련 시 에이전트가 로드하는 절차
Instructions	관리형 컨텍스트	항상 켜지는 시스템 프롬프트

자세한 내용은 프로젝트 구조를 참고하세요.

인터럽트에 응답하기

실행이 인터럽트에 부딪히면 일시 중지되고, 계속하기 전에 사람의 응답을 기다립니다.

로컬 개발 중에는 mda dev가 LangSmith Studio에서 에이전트를 실행합니다. Studio는 인터럽트를 표시해 보류 중인 도구 호출을 검사하고 실행을 재개할 수 있게 합니다.
배포된 에이전트에서는 resume 페이로드와 함께 LangGraph 서버 API를 통해 일시 중지된 실행을 재개합니다. 서버 API를 이용한 Human-in-the-loop를 참고하세요.

참고: 공개 베타 기간 동안 Managed Deep Agents는 CLI 우선이며 프로그래매틱 호출은 아직 문서화되지 않았습니다. 자체 애플리케이션에서 실행을 프로그래매틱하게 재개하려면 LangChain 팀에 문의하세요.

Human-in-the-loop는 일시 중지·재개를 위해 영구 스레드 상태가 필요합니다. 관리형 런타임이 체크포인터를 소유하므로 추가 설정은 필요 없습니다.

인증이 필요한 도구 사용하기

도구에 API 키나 OAuth 토큰이 필요하면 커넥션을 사용해 런타임에 자격 증명을 해석하세요. 커넥션 관리를 참고하세요.

런타임 컨텍스트 접근하기

요청 메타데이터나 기능 플래그 같은 실행별 값에는 일반 LangChain 런타임 컨텍스트 패턴을 사용하세요. 도구 내에서 컨텍스트에 접근하는 방법을 참고하세요.

더 알아보기

프로젝트 구조 — 전체 프로젝트 레이아웃 안내.