관리형 딥 에이전트 빠른 시작

mda CLI로 첫 번째 관리형 딥 에이전트(Manged Deep Agent)를 만들고 배포해요.

첫 번째 관리형 딥 에이전트를 만들고 배포하세요: 프로젝트를 스캐폴딩하고, 모델과 지시문을 구성하고, 검색을 추가하고, LangSmith Studio에서 테스트하고, mda CLI로 배포하세요. 관리형 딥 에이전트는 Deep Agents harness와 호스팅 런타임을 제공해요.

이 빠른 시작 후에 튜토리얼은 같은 프로젝트에 내구성 있는 메모리와 일일 스케줄을 추가해요.

관리형 딥 에이전트는 **공개 베타**이며 US 리전의 LangSmith Cloud에서만 사용할 수 있어요.

출처: 문서

본문

사전 요구 사항

진행하려면 다음이 필요해요:

Python 및 uv.
선택한 모델 프로바이더의 API 키.

`managed-deep-agents` 스킬 추가하기

managed-deep-agents 스킬은 mda CLI로 관리형 딥 에이전트를 빌드, 테스트, 배포하는 과정을 코딩 에이전트에 안내해요. 현재 프로젝트에 추가하려면 다음을 실행하세요:

npx skills add langchain-ai/langchain-skills --skill managed-deep-agents --yes

또는 이 프롬프트를 코딩 에이전트에 붙여넣으세요:

빠른 시작으로 관리형 딥 에이전트 빌드하기

이 작업 디렉터리에서 관리형 딥 에이전트 빠른 시작을 따라 관리형 딥 에이전트를 만들고 배포하세요.

1단계: 가이드 읽기

CLI 명령, 프로젝트 구조 및 배포 단계의 진실의 원천으로 https://docs.langchain.com/langsmith/managed-deep-agents-quickstart.md를 가져와 따르세요. 이 프로젝트와 일치하는 Python 또는 TypeScript 경로를 선호하세요.

2단계: 스킬 설치

managed-deep-agents 스킬이 아직 없다면 설치하세요:
npx skills add langchain-ai/langchain-skills --skill managed-deep-agents --yes
사용 가능할 때 나머지 워크플로에서 그 스킬을 사용하세요.

3단계: 사전 요구 사항 및 시크릿

사용자가 LangSmith 접근 권한과 필요한 모델 또는 검색 자격 증명이 있는지 확인하세요. 필요한 API 키가 없으면 셸이나 .env 파일에 설정하도록 요청한 다음 기다리세요. 시크릿을 임의로 만들거나 하드코딩하거나 커밋하지 마세요.

4단계: 스캐폴딩, 구성, 테스트 및 배포

빠른 시작 단계를 순서대로 따르세요: mda로 프로젝트 초기화, 모델과 지시문 구성, 페이지에 표시된 대로 검색 추가, LangSmith Studio에서 테스트, mda CLI로 배포. 대시보드 작업이나 자격 증명을 사용자만 LangSmith UI에서 완료할 수 있을 때 중지하고 물어보세요.

규칙

빠른 시작에 범위를 두세요. 가이드가 요구하지 않으면 관련 없는 제품을 추가하거나 생성된 프로젝트 구조를 다시 쓰지 마세요.

커스텀 배포 경로를 임의로 만드는 대신 mda CLI와 managed-deep-agents 스킬을 선호하세요.

시크릿, 요금제 계층 제한 또는 UI 전용 단계가 명확하지 않을 때는 추측보다 물어보세요.

에이전트 만들고 배포하기

프로젝트 설정하기: 프로젝트를 만들고 디렉터리를 여세요:
```
uvx --from managed-deepagents mda init research-assistant
cd research-assistant
```
이제 에이전트를 위한 모든 스캐폴딩이 갖춰졌어요.
키 추가하기: 모델 프로바이더 API 키를 .env에 추가하세요:
```
OPENAI_API_KEY=<OPENAI_API_KEY>
# ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
# GOOGLE_API_KEY=<GOOGLE_API_KEY>
```
이 빠른 시작은 기본적으로 OpenAI를 사용해요. 다음 단계에서 Google이나 Anthropic을 선택한다면 해당 프로바이더의 API 키를 대신 설정하세요. mda deploy는 프로바이더 키를 배포에 추가해요. 다른 채팅 프로바이더도 사용할 수 있어요.

.env 파일을 버전 관리에 커밋하지 마세요. 시크릿이 포함되어 있어요.
LangSmith 설정하기: 관리형 딥 에이전트는 LangSmith에서 실행돼요. LangSmith API 키는 mda dev로 로컬 개발을 인증하고, mda deploy로 에이전트를 배포하며, LangSmith Studio에서 에이전트를 열어 대화하고 트레이스를 검사할 수 있게 해줘요.

아직 계정이 없다면 LangSmith 가입을 하세요.

LangSmith API 키를 만들려면 Settings를 열고 API Keys로 이동한 다음 Create API Key를 클릭하세요. 자세한 내용은 계정 및 API 키 만들기를 참고하세요.

LangSmith API 키를 .env에 추가하세요:
```
LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
```
지시문 편집하기: instructions.md를 열고 에이전트가 어떻게 동작해야 하는지 설명하세요:
```
# Research assistant

You are a careful research assistant. Use internet search to find sources,
keep notes, and return concise answers with citations.
```
배포하면 관리형 딥 에이전트는 이 지시문을 LangSmith Context Hub에 동기화하며, 에이전트를 재배포하지 않고도 업데이트할 수 있어요.

모델과 검색 구성하기: 이제 모델과 내장 웹 검색 도구를 설정하세요. Google, OpenAI, Anthropic은 추가 패키지나 API 키 없이 서버 측 검색을 제공해요. 모델과 일치하는 프로바이더 도구 dict를 전달하세요:

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

Google:

from managed_deepagents import define_deep_agent

# Google's built-in search — no extra install or API key needed
agent = define_deep_agent(
    name="research-assistant",
    model="google_genai:gemini-3.6-flash",
    tools=[{"google_search": {}}],
)

Anthropic:

from managed_deepagents import define_deep_agent

# Anthropic's built-in web search — no extra install or API key needed
agent = define_deep_agent(
    name="research-assistant",
    model="anthropic:claude-sonnet-4-6",
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
)

에이전트 이름은 기본 배포 이름이기도 해요. 모델 개념과 프로바이더 옵션은 Models를 참고하세요.

다른 프로바이더를 사용하시나요?

대신 Tavily 검색 도구를 사용할 수 있어요. Tavily API 키를 .env에 추가하세요:

TAVILY_API_KEY=<TAVILY_API_KEY>

Tavily 클라이언트를 설치하세요:

uv add tavily-python

커스텀 internet_search 도구를 만드세요:

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

도구를 가져와 에이전트에 추가하세요:

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],
)

더 작성된 도구는 커스텀 도구를 참고하세요.

로컬 실행하기: 프로젝트 의존성을 설치하고 에이전트를 시작하세요:
```
uv sync
uv run mda dev
```
mda dev는 .env에서 API 키를 로드하고, 로컬 Agent Server를 시작하며, LangSmith Studio에서 에이전트를 열어요.

Studio에서 다음을 보내세요:
```
What were the main announcements from the latest LangChain release?
```
에이전트가 웹 검색 도구를 호출한 다음 출처를 인용하는 간결한 답변을 반환하는 것을 볼 수 있어야 해요. 검색이 트레이스에 나타나지 않으면 프로바이더 도구 dict가 agent.py 또는 agent.ts에 설정한 모델과 일치하는지 확인하세요.

자세한 내용은 LangSmith Studio로 로컬 개발을 참고하세요.
에이전트 배포하기: 다음을 실행해 프로젝트를 배포하세요:
```
uv run mda deploy
```
관리형 딥 에이전트는 프로젝트를 패키징하고 LangSmith Agent Server에서 호스팅 배포로 실행해요. 배포가 끝나면 CLI가 배포 대시보드 URL을 출력해요.

그 URL을 여세요. 배포가 준비 상태로 보여야 해요. 이전 단계와 동일한 리서치 질문을 보내고 호스팅 에이전트가 검색 도구 호출로 답변을 반환하는지 확인하세요. 배포 옵션 및 시크릿 처리는 관리형 딥 에이전트 배포를 참고하세요. 에이전트가 실행된 후 실행을 검사하려면 LangSmith 옵저버빌리티를 사용하세요.

다음 단계

튜토리얼 - : 커스텀 Tavily 검색 도구, 내구성 있는 메모리 및 일일 스케줄 추가.
커스텀 도구 - : 프로젝트에서 작성한 LangChain 도구 추가.
연결 - : 에이전트로 또는 호출자로 외부 서비스와 인증.

관리형 딥 에이전트 빠른 시작