서브에이전트

서브에이전트는 자신만의 컨텍스트와 권한으로 특정 작업을 처리하는 전문 AI입니다. 메인 에이전트가 task 도구로 호출하며, 긴 탐색이나 독립적인 조사를 맡기고 결과만 받아 옵니다.

서브에이전트를 쓰면 다음과 같은 이점이 있습니다.

• 컨텍스트 보존: 탐색·조사 과정이 별도 세션에서 일어나므로 메인 대화의 컨텍스트가 커지지 않습니다.
• 권한 분리: 읽기 전용 에이전트처럼 도구를 제한한 전문 에이전트를 만들 수 있습니다.
• 병렬 작업: 독립적인 작업을 한 번에 여러 서브에이전트에게 맡길 수 있습니다.
• 전문화: 시스템 프롬프트, 모델, 설명을 에이전트별로 다르게 줄 수 있습니다.

note

헬피코드는 에이전트 기능을 자체 구현하지 않고, 번들된 AI 엔진의 기능을 그대로 사용합니다. 이 문서의 에이전트 정의 규칙은 그 엔진의 소스 코드를 기준으로 작성했습니다.

기본 제공 에이전트

에이전트	유형	설명
build	primary (기본)	기본 에이전트. 설정된 권한에 따라 모든 도구를 사용합니다. 사용자에게 질문(question), 계획 모드 진입, 서브에이전트 호출을 할 수 있습니다.
plan	primary	계획 모드. 파일 편집 도구를 모두 막고, 계획 파일만 쓸 수 있습니다. 헬피코드에서는 /plan으로 다음 메시지 한 번에 사용합니다. general 서브에이전트는 호출할 수 없습니다.
general	subagent	복잡한 질문 조사와 여러 단계 작업을 위한 범용 에이전트. 여러 작업 단위를 병렬로 실행할 때 씁니다. todowrite는 막혀 있습니다.
explore	subagent	코드베이스 탐색 전용 에이전트. 파일 패턴 검색, 키워드 검색, 코드 질문 답변에 쓰며, 호출할 때 철저함 수준(quick / medium / very thorough)을 지정합니다. 읽기 전용이며 bash, webfetch, websearch는 사용자 정책에 따라 묻습니다.
compaction	숨김	/compact 요약을 만듭니다. 모든 도구가 막혀 있습니다.
title	숨김	대화 제목을 만듭니다.
summary	숨김	요약을 만듭니다.
reasoning-summary	숨김	원시 추론 대신 보여 줄 짧은 의도 문장을 만듭니다(엘리스 추가).

숨김 에이전트는 직접 선택하거나 호출할 수 없습니다.

서브에이전트가 호출되는 방식

AI가 task 도구를 호출합니다. 사용자는 보통 평소처럼 요청하면 되고, 어떤 서브에이전트를 쓸지는 에이전트의 description을 보고 AI가 선택합니다.

explore 서브에이전트로 결제 모듈의 호출 흐름을 조사한 다음, 결과를 요약해줘

리뷰어 서브에이전트로 내 변경사항을 검토해줘

task 도구의 입력

입력	설명
description	작업의 짧은 설명(3~5 단어). 자식 세션 제목은 "{설명} (@{에이전트} subagent)"가 됩니다.
prompt	서브에이전트가 수행할 작업. 서브에이전트는 이전 대화를 모르므로 상세하게 쓰고, 무엇을 돌려줘야 하는지 명시해야 합니다.
subagent_type	사용할 서브에이전트 이름
task_id	(선택) 이전 작업의 task_id를 넘기면 새로 시작하지 않고 그 서브에이전트의 세션을 이어서 실행합니다.
background	(선택) 백그라운드 실행. 실험 기능으로 기본은 꺼져 있습니다.

동작 규칙은 다음과 같습니다.

• 독립적인 작업은 한 메시지에서 여러 task를 호출해 병렬 실행합니다.
• 서브에이전트의 응답은 사용자에게 직접 보이지 않습니다. 메인 에이전트가 요약해서 전달합니다.
• 이미 알고 있는 파일을 읽거나 특정 심볼을 찾는 일에는 서브에이전트 대신 일반 도구를 쓰도록 안내됩니다.
• 중첩 제한: 기본적으로 서브에이전트는 다시 서브에이전트를 호출할 수 없습니다(subagent_depth 기본값 1). 설정으로 늘릴 수 있습니다.

사용자 정의 서브에이전트

마크다운 파일 하나가 에이전트 하나입니다. 파일 이름이 에이전트 이름이 되고, 본문이 시스템 프롬프트가 됩니다.

파일 위치

범위	위치
프로젝트	<프로젝트>/.opencode/agents/<이름>.md (agent/ 폴더도 인식)
사용자 전역	앱 설정 홈의 opencode/agents/<이름>.md

• 하위 폴더도 읽습니다(agents/team/reviewer.md → team/reviewer).
• 헬피코드는 엔진의 설정 홈을 앱 전용 폴더로 옮겨 쓰므로 전역 위치는 ~/.config/opencode/agents가 아닙니다.

환경	전역 에이전트 폴더
데스크톱	<앱 데이터 폴더>/opencode/config/opencode/agents/
런박스	~/.helpycode/opencode/config/opencode/agents/

note

프로젝트의 .opencode/agents/를 사용할 수 있습니다.

설정 파일의 agent 항목으로도 정의할 수 있습니다. 같은 이름이 있으면 기본 에이전트의 설정에 덮어씌워집니다.

예시

---
description: 변경사항을 읽고 버그와 가독성 문제를 지적하는 코드 리뷰어. 코드를 수정하지 않는다.
mode: subagent
permission:
  edit: deny
  bash:
    "git diff*": allow
    "git log*": allow
    "*": ask
---
당신은 코드 리뷰어입니다. 변경사항을 읽고 다음 순서로 보고하세요.

1. 버그 가능성
2. 보안 문제
3. 가독성과 유지보수성

파일을 수정하지 말고, 발견한 문제를 우선순위 순으로 정리해 주세요.

프런트매터 필드

필드	설명
description	에이전트가 언제 쓰이는지에 대한 설명. 서브에이전트는 AI가 이 설명을 보고 호출 여부를 결정하므로 구체적으로 쓰세요.
mode	subagent(task로만 호출) / primary(메인 에이전트) / all. 새 에이전트의 기본값은 all입니다.
model	provider/model 형식. 생략하면 호출한 세션의 모델을 씁니다.
variant	에이전트의 기본 모델 변형(추론 강도). 에이전트의 model을 지정했을 때만 적용됩니다.
temperature, top_p	생성 파라미터
permission	도구별 allow / ask / deny. 명령·경로 패턴을 지정할 수 있고 나중 규칙이 우선합니다.
steps	최대 반복 횟수. 한도에 도달하면 도구 없이 텍스트로 마무리합니다.
hidden	선택 목록에서 숨김(서브에이전트 전용). 보안 장치는 아닙니다.
color	표시 색(#RRGGBB 또는 테마 색 이름)
disable	true면 같은 이름의 기본 에이전트를 비활성화합니다.
options	모델 호출에 전달할 추가 옵션
tools	더 이상 쓰지 않음. permission을 사용하세요.
maxSteps	더 이상 쓰지 않음. steps를 사용하세요.

알 수 없는 키는 options로 넘겨집니다.

사용 가능한 서브에이전트 목록

AI에게는 현재 에이전트가 호출할 수 있는 서브에이전트(유형이 primary가 아니고 task 권한이 거부되지 않은 것)만 task 도구 설명에 나열됩니다. 따라서 task: { 에이전트이름: "deny" }로 특정 서브에이전트를 목록에서 뺄 수 있습니다.

권한 처리

서브에이전트는 두 겹의 권한을 가집니다.

1. 서브에이전트 자체의 권한

• 기본 정책(수동 수락: 행동하는 작업은 묻고 조회는 허용)이 기반입니다.
• 에이전트 정의의 permission이 그 위에 덧붙습니다. 에이전트 자체 규칙의 deny는 사용자 규칙으로 열 수 없습니다(예: explore는 사용자가 허용해도 편집하지 못합니다).
• 서브에이전트에는 기본으로 todowrite와 task가 거부됩니다. 에이전트 정의에서 해당 도구를 명시하면 쓸 수 있습니다.

2. 호출 시점의 권한

task 호출 자체가 task 권한입니다. 부모 에이전트의 규칙이 task를 ask로 두면 서브에이전트를 부를 때마다 확인하고, deny로 두면 목록에서 빠지거나 호출이 거부됩니다. plan은 general을 deny합니다.

자식 세션이 받는 규칙

서브에이전트가 시작될 때 자식 세션은 부모 세션에서 다음만 물려받습니다.

• 부모의 deny 규칙
• 부모의 external_directory(프로젝트 밖 경로) 규칙

부모 에이전트의 다른 제한은 서브에이전트에게 적용되지 않습니다. 서브에이전트의 능력은 자체 권한이 결정합니다.

헬피코드 화면에서의 권한 요청

항목	동작
요청 표시	서브에이전트가 낸 권한 요청도 입력창 위 같은 권한 패널에 표시됩니다.
순서	메인·모든 자식 세션의 대기 요청을 모아 요청 시각 순으로 정렬하고, 그중 첫 하나만 보여 줍니다.
응답	이번만 허용 / 항상 허용 / 거부는 메인 에이전트와 동일합니다.
"항상 허용"	파일 편집은 루트 대화 단위, 그 외는 프로젝트 단위로 저장되며 서브에이전트가 공유합니다.
자동 수락	AI 판정이 서브에이전트에도 같은 방식으로 적용되고, 판정 기록은 루트 대화 기준이라 서브에이전트가 부모의 결정을 이어받습니다.
자동 수락에서의 task	task를 모두 허용하는 규칙은 자동 수락 진입 시 비활성화됩니다.
중단된 실행	중단한 실행의 대기 요청은 목록에서 제외됩니다.

자세한 권한 동작은 권한을 참고하세요.

서브에이전트가 만든 파일

서브에이전트가 present_files로 보여 준 파일은 메인 대화의 해당 턴 산출물에 합쳐서 표시됩니다. 우측 패널의 대화 내 생성파일 목록과 파일 카드에서 확인하세요. 우측 패널

현재 한계

• 에이전트 선택 화면이 없습니다. 메인 에이전트를 바꾸는 방법은 /plan뿐이고, 사용자 정의 primary 에이전트를 고르는 화면은 없습니다.
• 서브에이전트 전용 진행 화면이 없습니다. task 호출도 다른 도구처럼 "작업 중..." 형태로 표시됩니다.
• @에이전트 멘션 자동 완성은 제공되지 않습니다. 자연어로 요청하세요.
• 번들된 엔진 버전에 따라 필드 이름과 문법이 달라질 수 있습니다. 새 버전에서 에이전트 정의가 동작하지 않으면 업데이트 내용을 확인하세요.

서브에이전트 활용 팁

• description에 "언제 쓰는지"를 적으세요. AI가 호출 시점을 판단하는 유일한 근거입니다. ("코드 리뷰를 요청받았을 때", "DB 마이그레이션을 점검할 때" 등)
• 권한은 최소로 주세요. 리뷰·조사용 에이전트는 edit: deny로 시작하는 것이 안전합니다.
• 결과 형식을 정해 주세요. 서브에이전트의 응답은 메인 에이전트가 읽으므로, 프롬프트에 어떤 형식으로 돌려줄지 적으면 이어지는 작업이 쉬워집니다.
• 큰 일은 병렬로. "서로 독립적인 세 모듈을 각각 서브에이전트로 조사해서 합쳐줘"처럼 요청하면 동시에 진행됩니다.
• 반복해서 쓰는 절차라면 서브에이전트보다 스킬이 가벼울 수 있습니다.

다음 단계

• 권한
• 스킬
• 내장 도구 참조