Deep Agents Code에서 서브에이전트 쓰기

한 에이전트에게 모든 일을 시키다 보면 "이건 이쪽 전문가에게 맡기면 되겠다" 싶은 작업이 생겨요. Deep Agents Code에서는 커스텀 동기(synchronous) 서브에이전트를 마크다운 파일로 정의해 둘 수 있어요. 각 서브에이전트는 AGENTS.md 파일 하나로 깔끔하게 정의되고, 프론트매터(frontmatter)에 이름과 설명을 적는 방식이에요. 여기서 서브에이전트를 어떤 형식으로 정의하고 어떻게 활용하는지 살펴볼게요.

출처: 공식문서

서브에이전트 정의하기

커스텀 동기 서브에이전트를 마크다운 파일로 정의하면, Deep Agents Code가 전문화된 작업을 그 서브에이전트에게 위임할 수 있어요.

비동기 서브에이전트는 현재 Deep Agents Code에서 최종 사용자가 쓸 수 없어요.

각 서브에이전트는 자기 폴더 안에 AGENTS.md 파일로 존재해요:

.deepagents/agents/{subagent-name}/AGENTS.md   # Project-level
~/.deepagents/{agent}/agents/{subagent-name}/AGENTS.md  # User-level

같은 이름의 프로젝트 서브에이전트는 사용자 서브에이전트를 덮어써요 (precedence rules 참고).

부모 대화 이어가기

내장 general-purpose 서브에이전트는 부모 에이전트의 대화와 시스템 프롬프트를 상속받아요. 이 맥락 덕분에, 부모 대화에서 이미 확립된 조사, 결정, 기타 세부 내용을 반복하지 않고도 위임된 작업을 이어갈 수 있어요.

내장 general-purpose 서브에이전트를 격리 모드로 실행하려면 셸 또는 전역 ~/.deepagents/.env에 다음 변수를 설정해요:

export DEEPAGENTS_CODE_FORKED_SUBAGENTS=false

프론트매터에는 name과 description이 필요해요 (SubAgent dictionary spec과 동일). 마크다운 본문은 서브에이전트의 system_prompt이 돼요. 기본 스펙에 더해, AGENTS.md 파일은 선택적 model 프론트매터 필드를 지원해서 이 서브에이전트의 메인 에이전트 모델을 덮어쓸 수 있어요. provider:model-name 형식을 써요 (예: anthropic:claude-opus-4-8, openai:gpt-5.5). 생략하면 메인 에이전트의 모델을 상속해요.

다른 SubAgent 필드(tools, middleware, interrupt_on, skills)는 현재 AGENTS.md 프론트매터로 설정할 수 없어요 — 이렇게 정의한 커스텀 서브에이전트는 메인 에이전트의 도구를 상속받아요. 완전한 제어가 필요하면 SDK를 직접 쓰세요.

파일 형식

서브에이전트 AGENTS.md 파일은 YAML 프론트매터 뒤에 마크다운 본문이 이어지는 구조예요:

---
name: researcher
description: Research topics on the web before writing content
model: anthropic:claude-haiku-4-5-20251001
---

You are a research assistant with access to web search.

## Your Process
1. Search for relevant information
2. Summarize findings clearly

동적 서브에이전트 (Dynamic subagents)

dcode는 코드 인터프리터가 활성화된 상태로 제공돼서, 동적 서브에이전트가 기본으로 동작해요.

동적 서브에이전트를 트리거하려면 "워크플로우"를 요청하면 돼요. 에이전트는 스스로 작업을 하거나 네이티브 task 도구로 팬아웃을 관리하는 대신, 내장 task() 전역을 호출하는 오케스트레이션 스크립트를 작성해 코드 인터프리터에서 실행해요. 예: "src/ 폴더의 모든 파일을 SQL 인젝션에 대해 리뷰하는 워크플로우를 실행해줘."

서브에이전트가 생성되면 dcode는 그들을 동적 서브에이전트 패널에서 dispatch 단계별로 묶어 실시간으로 보여줘요.

선택한 코딩 에이전트에서도 동적 서브에이전트를 ACP를 통해 사용할 수 있어요 (예: Zed).

예시: 비용 효율적인 서브에이전트

간단한 위임 작업에는 더 저렴하고 빠른 모델을 쓰면서, 메인 에이전트는 더 강력한 모델에 두는 방식이에요:

---
name: general-purpose
description: General-purpose agent for research and multi-step tasks
model: anthropic:claude-haiku-4-5-20251001
---

You are a general-purpose assistant. Complete the task efficiently and return a concise summary.

이렇게 하면 내장 general-purpose 서브에이전트를 덮어써서, 모든 위임 작업이 더 저렴한 모델로 라우팅돼요. 자세한 내용은 Override the general-purpose subagent 문서를 참고하세요.

더 알아보기 (Learn more)

Subagents — 서브에이전트 개념과 사전 기반(dictionary-based) 정의법을 다루는 문서.
Dynamic subagents — 워크플로우로 동적 서브에이전트를 펼치는 방법.
Configuration — 서브에이전트 우선순위 규칙과 설정.