Managed Deep Agents CLI 참조

mda 명령, 프로젝트 파일, 배포 동작에 대한 참조예요.

mda CLI는 코드 우선 Managed Deep Agents를 컴파일하고 배포합니다.

이는 managed-deepagents npm 패키지에 포함되어 있습니다.

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

가장 빠른 엔드투엔드 경로는 퀵스타트를 참고하세요. 워크플로우 안내는 아이덴티티, 메모리, 평가, 커스텀 도구, 연결, 커스텀 미들웨어, 샌드박스, 채널, 스케줄, 에이전트 배포를 참고하세요.

출처: 문서

본문

설치 (Install)

mda init은 managed-deepagents를 프로젝트 의존성으로 선언하므로 프로젝트에서 mda 바이너리를 실행하세요.

npx managed-deepagents init my-agent
cd my-agent
npm install
npx mda --version

pnpm dlx managed-deepagents init my-agent
cd my-agent
pnpm install
pnpm exec mda --version

bunx managed-deepagents init my-agent
cd my-agent
bun install
bunx mda --version

패키지는 에이전트, 아이덴티티, 스케줄, 샌드박스 작성 API를 제공합니다.

인증 (Authentication)

mda deploy는 다음 순서로 API 키를 읽습니다:

LANGGRAPH_HOST_API_KEY
LANGSMITH_API_KEY
LANGCHAIN_API_KEY

CLI는 먼저 프로젝트 .env 파일에서 해당 값을 읽은 다음 프로세스 환경에서 읽습니다. 대화형 터미널에서 키가 없으면 mda deploy는 LangSmith API 키를 요청하고 프로젝트 .env 파일에 저장합니다.

LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>

조직 범위 키로 배포하려면 LANGSMITH_WORKSPACE_ID를 설정하거나 mda deploy에 --workspace-id를 전달하세요.

LangSmith API 키가 배포를 인증합니다. 에이전트의 모델 공급자도 런타임에 자격증명이 필요합니다. 공급자 키를 .env에 설정하거나, 셸에서 내보내거나, LangSmith 워크스페이스 비밀로 구성하세요. 예를 들어 openai:gpt-5.5는 OPENAI_API_KEY가 필요합니다.

mda deploy는 OPENAI_API_KEY, MCP 토큰, 커스텀 도구 자격증명 같은 예약되지 않은 .env 항목을 호스팅 배포 비밀로 전달합니다. LANGSMITH_API_KEY, LANGGRAPH_HOST_API_KEY, LANGCHAIN_API_KEY, LANGSMITH_WORKSPACE_ID를 포함한 예약된 플랫폼 변수는 CLI 인증과 배포 라우팅에 사용되지만 사용자 관리 배포 비밀로 업로드되지는 않습니다.

명령 개요 (Command overview)

명령 (Command)	용도 (Use)
`mda --help`	CLI 도움말 표시.
`mda --version`	설치된 CLI 버전 표시.
`mda init <name>`	TypeScript Managed Deep Agents 프로젝트 스캐폴딩.
`mda build [path]`	배포 없이 프로젝트를 관리형 LangGraph 앱으로 컴파일.
`mda evals …`	Harbor 워크스페이스를 초기화하고 코딩 에이전트에서 평가 작성을 계속.
`mda dev [path]`	프로젝트를 컴파일하고 로컬 LangGraph 개발 서버에서 실행.
`mda connections …`	도구와 MCP 커넥터의 인증 관리.
`mda deploy [path]`	Compile, sync Context Hub context, upload, and deploy to LangSmith.
`mda channels init slack`	현재 프로젝트에 Slack 채널 선언 추가.
`mda logs [path]`	배포된 에이전트의 Agent Server 로그를 테일링.
`mda delete [path]` / `mda destroy [path]`	배포된 에이전트와 생성한 LangSmith 리소스 삭제.

프로젝트 초기화하기 (Initialize projects)

mda init을 사용해 새 프로젝트 디렉터리를 만듭니다:

npx managed-deepagents init my-agent

pnpm dlx managed-deepagents init my-agent

bunx managed-deepagents init my-agent

인자 또는 플래그 (Argument or flag)	용도 (Use)
`name`	필수 프로젝트 디렉터리 이름. 대상이 이미 있으면 명령이 실패.
`--instructions TEXT`	`instructions.md`에 쓸 시스템 프롬프트.
`--instructions-file PATH`	`instructions.md`의 시스템 프롬프트를 파일에서 읽거나 `-`로 설정하면 stdin에서 읽음.
`--identity`	사용자 소유 스레드로 관리형 인증 추가.
`--memory agent\|none`	선택적으로 루트 메모리 선언 작성. 생략하면 메모리 파일이 생성되지 않고 영구 메모리가 꺼짐.
`--model SPEC`	에이전트가 실행할 모델, `provider:model` 형식.
`--no-sandbox`	관리형 샌드박스 선언을 제외.
`--channel slack`	Slack 채널 선언으로 에이전트를 초기화. 반복 가능; `--channels`는 별칭.

새 프로젝트에 Slack을 포함하려면:

npx managed-deepagents init my-agent --channel slack

pnpm dlx managed-deepagents init my-agent --channel slack

bunx managed-deepagents init my-agent --channel slack

스캐폴드 언어는 현재 디렉터리가 아닌 실행하는 패키지에서 결정됩니다: npm 패키지는 항상 TypeScript 프로젝트를 씁니다. npm에서 설치된 CLI는 Python 프로젝트를 거부합니다.

스캐폴드는 다음을 만듭니다:

파일 (File)	설명 (Description)
`agent.ts`	`defineDeepAgent(...)`에서 이름이 `agent`인 내보내기.
`instructions.md`	관리형 시스템 프롬프트.
`package.json`	최소한의 언어별 매니페스트.
`README.md`	로컬 프로젝트 지침.
`.env`	배포 인증 및 런타임 비밀. 실제 비밀을 커밋하지 마세요.
`.gitignore`	`.env`, `.env.*`, `.mda/`, 의존성 캐시를 무시.

평가 작업은 옵트인이며 mda init이 만들지 않습니다. 프로젝트 루트에서 mda evals init -i를 실행해 Harbor 워크스페이스를 초기화하고 eval-engineering 스킬로 코딩 에이전트에서 계속하세요.

Slack 채널 초기화하기 (Initialize a Slack channel)

기존 매니지드 딥 에이전트 프로젝트 루트에서 다음 명령을 실행합니다:

npx mda channels init slack

pnpm exec mda channels init slack

bunx mda channels init slack

이 명령은 channels/ 디렉터리에 Slack 채널 선언을 만듭니다. 다음 mda deploy가 에이전트가 Slack에 나타나는 데 필요한 리소스를 설정합니다. 전체 워크플로우는 Managed Deep Agent를 Slack에 연결을 참고하세요.

프로젝트 빌드하기 (Build projects)

mda build를 사용해 배포하지 않고 프로젝트를 관리형 LangGraph 앱으로 컴파일합니다:

npx mda build

pnpm exec mda build

bunx mda build

인자 또는 플래그 (Argument or flag)	용도 (Use)
`path`	프로젝트 디렉터리. 기본값은 현재 디렉터리.
`--out OUT`	컴파일된 앱의 출력 디렉터리. 기본값은 `<path>/.mda/build`. 빌드 전에 디렉터리가 비워지므로 존재하지 않거나 비어 있거나 이전 빌드가 작성한 디렉터리여야 함.

프로젝트 평가하기 (Evaluate projects)

mda evals init을 사용해 Harbor 워크스페이스를 초기화합니다. 대화형 핸드오프로 코딩 에이전트와 eval-engineering 스킬을 사용해 완전한 작업을 개발하세요.

npx mda evals init -i

pnpm exec mda evals init -i

bunx mda evals init -i

명령 또는 플래그 (Command or flag)	용도 (Use)
`mda evals init`	누락된 `evals/harbor-job.json`을 만들고 `.mda/evals/` 아래에 Harbor 어댑터와 런타임 설정을 생성. 프로젝트 루트에서 이 명령을 실행.
`-i`, `--interactive`	감지된 코딩 에이전트를 eval-engineering 프롬프트로 시작하거나 다른 에이전트의 프롬프트를 복사.

핸드오프는 코딩 에이전트에게 eval-engineering 스킬을 설치하고, 관리형 에이전트를 검사하고, evals/<task>/ 아래에 완전한 Harbor 작업을 쓰도록 요청합니다. 또한 MDA 작업 플러그인과 LangSmith 플러그인을 로드하는 고정 Harbor 명령도 포함합니다.

mda evals compile은 Harbor 작업 플러그인이 사용하는 내부 명령입니다. Harbor 작업이 시작될 때 플러그인이 이를 실행하므로 별도로 평가 아티팩트를 컴파일하지 않습니다.

워크플로우 안내는 평가를 참고하세요.

로컬 개발 (Develop locally)

mda dev를 사용해 프로젝트를 컴파일하고 로컬 LangGraph 개발 서버를 실행합니다:

npx mda dev

pnpm exec mda dev

bunx mda dev

인자 또는 플래그 (Argument or flag)	용도 (Use)
`path`	프로젝트 디렉터리. 기본값은 현재 디렉터리.
`--port PORT`	LangGraph 개발 서버에 포트 포워딩.
`--hostname HOSTNAME`	LangGraph 개발 서버에 호스트 포워딩.
`--no-browser`	개발 서버가 시작할 때 브라우저에서 Studio를 열지 못하게 함.
`--no-reload`	개발 서버의 핫 리로드 비활성화.

mda dev는 .mda/build로 컴파일한 다음 해당 디렉터리에서 언어별 LangGraph 개발 서버를 시작합니다:

프로젝트 언어 (Project language)	개발 서버 명령 (Dev server command)
TypeScript	`npx --yes @langchain/langgraph-cli dev`

샌드박스가 구성되면 mda dev는 구성된 공급자를 시도합니다. 공급자 자격증명을 사용할 수 없거나 공급자 생성이 실패하면 로컬 임시 디렉터리 샌드박스로 폴백하고 선택한 경로를 출력합니다.

로컬 개발의 경우 mda dev는 프로젝트 .env 파일을 .mda/build/.env로 단계 배치하여 LangGraph가 모델 공급자 키와 기타 런타임 자격증명을 로드할 수 있게 합니다.

연결 관리하기 (Manage connections)

연결은 관리형 딥 에이전트를 외부 서비스에 연결합니다. 자격증명은 LangSmith 워크스페이스에 있으므로 재배포 없이 교체할 수 있고, 사용자 소유 연결은 에이전트를 호출한 사람의 자격증명을 해석합니다. 도구와 MCP 커넥터는 런타임에 connections.get(...)으로 연결을 해석합니다.

연결은 세 가지 모드 중 하나로 만듭니다: 불투명 시크릿(고정 API 키), 일반 OAuth(카탈로그의 BYOT 앱 또는 커스텀 엔드포인트), MCP OAuth(MCP 서버 URL에서 발견 및 등록). mda connections를 사용해 현재 워크스페이스에서 이러한 자격증명을 관리하세요.

명령 (Command)	용도 (Use)
`mda connections catalog`	사전 구성된 OAuth 설정이 있는 서비스 나열.
`mda connections create <slug>`	불투명 시크릿, 일반 OAuth 또는 MCP OAuth 연결 생성.
`mda connections list`	워크스페이스의 연결 메타데이터 나열.
`mda connections get <slug>`	하나의 연결 메타데이터 표시.
`mda connections delete <slug>`	연결과 저장된 자료 삭제.

mda connections create의 첫 번째 인자는 slug이며, 이는 연결 이름이자 코드가 connections.get(...)에 전달하는 이름입니다. 공급자 이름은 --oauth로 갑니다.

OAuth 카탈로그는 공급자의 OAuth 설정을 찾는 수고를 덜어줍니다. 목록에 있는 서비스를 --oauth에 전달하면 CLI가 인가 URL, 토큰 URL, 토큰 엔드포인트 인증 메서드, 인가 파라미터, 기본 스코프를 제공하므로 클라이언트 ID와 클라이언트 시크릿만 제공하면 됩니다. 카탈로그가 사용할 수 있는 공급자를 제한하지는 않습니다: 그 외의 것은 --authorize-url과 --token-url을 전달하세요. 카탈로그 이름은 github, google, linear, slack, atlassian, notion-api를 포함합니다:

npx mda connections catalog

pnpm exec mda connections catalog

bunx mda connections catalog

커스텀 Tavily 도구용 에이전트 소유 API 키를 만듭니다:

npx mda connections create organization-tavily --secret-from-env TAVILY_API_KEY

pnpm exec mda connections create organization-tavily --secret-from-env TAVILY_API_KEY

bunx mda connections create organization-tavily --secret-from-env TAVILY_API_KEY

다음 플래그가 연결 생성을 제어합니다:

플래그 (Flag)	용도 (Use)
`--project PATH`	프로젝트 디렉터리 설정. 기본값은 현재 디렉터리.
`--workspace-id WORKSPACE_ID`	`LANGSMITH_WORKSPACE_ID` 재정의.
`--secret-from-env VAR`	셸 또는 프로젝트 `.env`에서 고정 값 또는 OAuth 클라이언트 시크릿 읽기.
`--secret-from-file PATH`	파일에서 고정 값 또는 OAuth 클라이언트 시크릿 읽기.
`--oauth SERVICE`	`mda connections catalog`에서 서비스의 사전 구성된 설정 사용.
`--client-id CLIENT_ID`	OAuth 클라이언트 ID 설정.
`--auth-method METHOD`	토큰 엔드포인트 메서드를 `client_secret_basic`, `client_secret_post` 또는 `none`으로 설정.
`--scope SCOPE`	공급자의 기본 스코프를 교체. 스코프마다 반복.
`--allowed-scope SCOPE`	인가 흐름이 요청할 수 있는 최대 스코프 설정. 스코프마다 반복.
`--authorization-param KEY=VALUE`	OAuth 인가 쿼리 파라미터 추가. 파라미터마다 반복.
`--authorize-url URL`	커스텀 OAuth 인가 엔드포인트 설정. `--token-url` 필요.
`--token-url URL`	커스텀 OAuth 토큰 엔드포인트 설정. `--authorize-url` 필요.
`--mcp URL`	MCP 서버 URL에서 OAuth를 발견해 MCP OAuth 연결 생성.
`--authorize`	배포된 에이전트가 사용하는 계정에 로그인하여 에이전트 소유 OAuth 그랜트 저장. OAuth 플래그와 프로젝트 디렉터리 필요.

값 플래그와 --oauth 엔드포인트가 없으면 mda connections create <slug>는 해당 slug가 프로젝트의 사용자 소유 MCP 연결 정확히 하나와 일치할 때 MCP OAuth를 유추합니다.

catalog, list 또는 get에서 --json을 사용해 머신 판독 가능 출력을 얻고, delete에서 --yes를 사용해 확인 프롬프트를 건너뜁니다.

자격증명 소유자, 생성 모드, 호출자 아이덴티티, 런타임 예시는 연결 관리를 참고하세요.

프로젝트 배포하기 (Deploy projects)

mda deploy를 사용해 프로젝트를 컴파일하고 LangSmith에 배포합니다:

npx mda deploy

pnpm exec mda deploy

bunx mda deploy

인자 또는 플래그 (Argument or flag)	용도 (Use)
`path`	프로젝트 디렉터리. 기본값은 현재 디렉터리.
`--name NAME`	배포 이름. 기본값은 `defineDeepAgent`의 에이전트 `name`.
`--deployment-type dev\|prod`	배포를 만들 때 배포 유형. 기본값은 `dev`.
`--workspace-id WORKSPACE_ID`	배포할 워크스페이스 ID. `LANGSMITH_WORKSPACE_ID` 재정의.
`--context-strategy overwrite\|keep-hub`	마지막 동기화 이후 Hub에서 `instructions.md` 또는 `skills/`가 변경되었을 때 Context Hub 충돌 해결. 비대화형 셸에서 필수. Context Hub 참고.
`--no-wait`	원격 빌드를 트리거하고 배포 완료를 폴링하지 않고 종료.

배포는 다음 단계를 실행합니다:

프로젝트 디렉터리를 검증하고 에이전트 진입점 파일을 로드.
LangSmith API 키와 선택적 워크스페이스 ID를 해석.
예약되지 않은 .env 값을 호스팅 배포 비밀로 수집.
모델 공급자 API 키가 .env, 셸 환경 또는 LangSmith 워크스페이스 비밀에 있는지 확인.
배포 소유 컨텍스트를 Context Hub에 동기화.
프로젝트를 .mda/build로 컴파일하고 선택적 schedules/ 및 channels/ 선언을 추출.
이름으로 LangSmith 호스팅 배포를 만들거나 찾음.
빌드를 아카이브하고 업로드하고 원격 빌드를 트리거.
--no-wait가 설정되지 않으면 개정이 DEPLOYED에 도달할 때까지 폴링.
--no-wait가 설정되지 않으면 스케줄의 관리형 LangSmith cron 작업 조정.
선언된 Slack 채널 프로비저닝. Slack 인가 또는 워크스페이스 승인이 필요하면 작업을 표시하고 완료한 후 계속.

Slack 채널이 있는 프로젝트는 Slack 프로비저닝에 배포된 Agent Server URL이 필요하므로 --no-wait를 사용할 수 없습니다. 전체 워크플로우는 Managed Deep Agent를 Slack에 연결을 참고하세요.

성공 시 CLI는 LangSmith 배포 대시보드 URL을 출력합니다. 비밀 라우팅과 배포 팁은 에이전트 배포를 참고하세요.

배포 로그 읽기 (Read deployment logs)

mda logs를 사용해 배포된 에이전트의 Agent Server 로그를 테일링합니다:

npx mda logs

pnpm exec mda logs

bunx mda logs

인자 또는 플래그 (Argument or flag)	용도 (Use)
`path`	프로젝트 디렉터리. 기본값은 현재 디렉터리.
`--name NAME`	배포 이름. 기본값은 프로젝트의 에이전트 `name`.
`--lines LINES`	가져올 최근 로그 줄 수. 기본값은 `1000`.
`--level LEVEL`	주어진 심각도 이상의 항목만 표시: `debug`, `info`, `warning`, `error`, 또는 `critical`.
`--follow`	새 로그를 계속 스트리밍. 대화형 터미널의 기본값.
`--no-follow`	최근 로그를 출력하고 종료. 출력이 파이프될 때의 기본값.
`--workspace-id WORKSPACE_ID`	읽을 워크스페이스 ID. `LANGSMITH_WORKSPACE_ID` 재정의.

배포 삭제하기 (Delete deployments)

mda delete를 사용해 배포된 Managed Deep Agent와 생성한 LangSmith 리소스를 삭제합니다. mda destroy는 별칭입니다.

npx mda delete

pnpm exec mda delete

bunx mda delete

인자 또는 플래그 (Argument or flag)	용도 (Use)
`path`	프로젝트 디렉터리. 기본값은 현재 디렉터리.
`--name NAME`	배포 이름. 기본값은 `defineDeepAgent`의 에이전트 `name`.
`--workspace-id WORKSPACE_ID`	배포가 있는 워크스페이스 ID. `LANGSMITH_WORKSPACE_ID` 재정의.
`--yes`	확인을 묻지 않고 삭제.

문제 해결 (Troubleshooting)

증상 (Symptom)	원인 및 해결책 (Cause and fix)
`project root ... is not a directory`	`mda dev` 또는 `mda deploy`에 디렉터리 경로를 전달.
`no agent entry file found`	프로젝트 루트에 `agent.ts` 또는 `agent.tsx` 추가.
`No LangSmith API key found`	`LANGSMITH_API_KEY` 설정 또는 프로젝트 `.env`에 추가.
배포가 401 또는 403으로 실패	API 키가 배포 접근 권한이 있는 워크스페이스에 속하는지 확인. 가격 요금제 참고.
배포가 모델 공급자 API 키 누락 보고	`.env`에 `OPENAI_API_KEY` 같은 공급자 키 추가, 셸에서 내보내기, 또는 LangSmith 워크스페이스 비밀로 구성.
배포가 Context Hub 충돌 보고	마지막 동기화 이후 Context Hub에서 `instructions.md` 또는 `skills/`가 변경되었거나 동기화 중 저장소가 변경됨. 대화형 터미널에서 덮어쓰기 프롬프트에 답변. 비대화형 셸에서 `--context-strategy overwrite` 또는 `--context-strategy keep-hub`로 재실행. Context Hub 참고.
빌드가 200 MB 초과	배포 전에 생성된 아티팩트나 큰 파일을 프로젝트에서 제거.
배포가 `BUILD_FAILED` 또는 `DEPLOY_FAILED`에 도달	LangSmith에서 출력된 배포 URL을 열고 개정 로그 검사.

더 알아보기 (Learn more)

이 문서들을 사용하기 — MCP를 통해 Claude, VSCode 등에 연결하여 실시간 답변을 받아 보세요.
GitHub에서 이 페이지 편집 또는 이슈 등록