Managed Deep Agent 정의하기

Managed Deep Agent 정의하기

관리형 딥 에이전트의 모델과 핵심 기능을 구성할 수 있어요.

에이전트 정의는 관리형 딥 에이전트의 모델과 핵심 기능을 선택합니다.

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

에이전트 진입점은 프로젝트 루트에 있습니다:

my-agent/
  agent.ts

agent.tsx도 사용할 수 있어요.

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

에이전트를 정의하려면 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",
});

시스템 프롬프트, 스킬, 메모리, 샌드박스, 아이덴티티, 채널, 스케줄은 에이전트 정의가 아닌 프로젝트 파일로 구성합니다. 프로젝트 구조를 참고하세요.

출처: 문서

본문

파라미터 (Parameters)

파라미터 (Parameter) 동작 (What it does)
name 필수. 에이전트 및 기본 배포 이름을 설정. 문자로 시작하고 문자, 숫자, 밑줄 또는 하이픈만 포함하는 정적 문자열을 전달. 예: "research-assistant".

Managed Deep Agents는 이름을 LangGraph 어시스턴트 ID와 기본 LangSmith 배포 이름으로 사용합니다. 에이전트 정의를 변경하지 않고도 mda deploy --name으로 배포 이름을 재정의할 수 있습니다.
model 에이전트가 사용하는 채팅 모델을 설정. 가장 간단한 옵션은 provider:model 문자열입니다. 모델이 로컬 및 배포에서 작동하도록 공급자의 API 키를 .env에 추가하세요.

코드에서 모델 파라미터를 구성해야 하는 경우 LangChain 채팅 모델 인스턴스를 대신 전달하세요. 모델 옵션과 지원 공급자는 Models를 참고하세요.

LLM Gateway에 연결하려면 LLM Gateway 사용을 참고하세요.
tools 에이전트가 호출할 수 있는 도구를 추가. 에이전트가 애플리케이션 로직이나 외부 서비스를 호출할 수 있도록 tools 배열에 전달하세요.

로컬 모듈에서 도구를 정의하고, 에이전트 진입점으로 가져온 다음 정의에 추가하세요. 커스텀 도구를 참고하세요. 에이전트 진입점으로 가져오지 않고 원격 MCP 서버의 도구를 추가하려면 MCP 커넥터를 사용하세요.
middleware 모델 호출, 도구 호출, 에이전트 수명주기 주변의 동작을 추가. middleware 배열에 전달하세요. 미들웨어는 배열 순서대로 실행됩니다. 커스텀 미들웨어를 참고하세요.
subagents 위임 작업을 위한 특수 에이전트를 정의. 에이전트가 특수 또는 컨텍스트가 많은 작업을 위임해야 하는 경우 서브에이전트 정의를 전달하세요. 각 서브에이전트는 자체 프롬프트, 모델, 도구를 가질 수 있습니다. Subagents를 참고하세요.
permissions 파일시스템 도구에 대한 경로 수준 접근을 제어. 에이전트의 내장 파일시스템 도구가 읽거나 쓸 수 있는 경로를 제어하도록 파일시스템 권한 규칙을 전달하세요. Permissions를 참고하세요.
interruptOn 인간 승인을 위해 선택한 도구 호출 전에 일시 중지. 특정 도구 호출 전에 일시 중지하도록 interruptOn을 설정하면, 사람이 실행 전에 호출을 승인, 편집 또는 거부할 수 있습니다. Human-in-the-loop을 참고하세요.
responseFormat 에이전트가 제약 없는 텍스트 응답 대신 스키마와 일치하는 데이터를 반환해야 할 때 설정. Structured output을 참고하세요.

LLM Gateway 사용하기 (Use LLM Gateway)

LLM Gateway를 사용해 모델 호출에 속도 제한, 폴백 및 기타 정책을 적용할 수 있어요.

게이트웨이 모델 ID 앞에 langsmith:를 붙입니다:

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  name: "my-agent",
  model: "langsmith:moonshotai/kimi-k3",
});

게이트웨이 모델 ID는 공급자와 모델 사이에 슬래시를 사용합니다(langsmith:provider/model-name). 공급자를 직접 호출하는 모델 문자열은 콜론을 사용합니다(provider:model-name).

게이트웨이는 모델 ID로 각 요청을 라우팅합니다. moonshotai/kimi-k3는 LangChain 호스팅 모델이므로 공급자 비밀번호가 필요 없고 게이트웨이 크레딧을 사용합니다. 워크스페이스가 구성한 공급자로 시작하는 모델 ID(예: anthropic/claude-opus-5)는 해당 공급자 비밀번호를 사용하고 자체 공급자 계정으로 청구됩니다.

자세한 내용은 LLM Gateway를 참고하세요.

처음부터 Gateway를 사용하는 프로젝트를 스캐폴딩하려면 초기화 시 --gateway를 전달하세요:

mda init my-agent --gateway

더 알아보기 (Learn more)