컨텐츠로 건너뛰기
쇼케이스 생태계 소스 코드 문서

에이전트

에이전트는 특정 작업 및 워크플로우를 위해 구성할 수 있는 전문 AI 어시스턴트입니다. 커스텀 프롬프트, 모델 및 도구 액세스를 갖춘 집중된 도구를 만들 수 있습니다.

유형

OpenCode에는 기본 에이전트와 서브 에이전트, 두 가지 유형의 에이전트가 있습니다.

기본 에이전트

기본 에이전트는 직접 대화하는 주요 어시스턴트입니다. Tab 키 또는 구성된 switch_agent 단축키를 사용하여 전환할 수 있습니다.

OpenCode에는 두 개의 기본 제공 기본 에이전트가 제공됩니다: Build와 Plan.

서브 에이전트

서브 에이전트는 기본 에이전트가 특정 작업을 위해 호출할 수 있는 전문 어시스턴트입니다. 메시지에서 @ 언급하여 수동으로 호출할 수도 있습니다.

OpenCode에는 세 개의 기본 제공 서브 에이전트가 제공됩니다: General, Explore, Scout.

기본 제공

OpenCode에는 두 개의 기본 제공 기본 에이전트와 세 개의 기본 제공 서브 에이전트가 제공됩니다.

Build 사용

모드: primary

Build는 개발 작업을 위해 모든 도구가 활성화된 기본 기본 에이전트입니다.

Plan 사용

모드: primary

분석 및 계획 전용으로 설계된 제한된 에이전트입니다. 기본적으로 file edits 및 bash는 ask로 설정됩니다. 수정 없이 코드를 분석하는 데 유용합니다.

General 사용

모드: subagent

복잡한 질문을 연구하고 다단계 작업을 실행하는 범용 에이전트입니다. 병렬 작업을 위한 전체 도구 액세스를 보유합니다.

Explore 사용

모드: subagent

코드베이스를 탐색하기 위한 빠르고 읽기 전용 에이전트입니다. 파일을 빠르게 찾거나, 코드를 검색하거나, 코드베이스에 대한 질문에 답변하는 데 사용하세요.

Scout 사용

모드: subagent

외부 문서 및 종속성 연구를 위한 읽기 전용 에이전트입니다. 라이브러리 소스를 검사하거나 로컬 코드를 업스트림 구현과 교차 참조하는 데 사용하세요.

Compaction 사용

모드: primary | 숨김

긴 컨텍스트를 더 작은 요약으로 압축하는 시스템 에이전트입니다. 필요할 때 자동으로 실행됩니다.

Title 사용

모드: primary | 숨김

짧은 세션 제목을 생성하는 시스템 에이전트입니다. 자동으로 실행됩니다.

Summary 사용

모드: primary | 숨김

세션 요약을 생성하는 시스템 에이전트입니다. 자동으로 실행됩니다.

사용법

  1. 기본 에이전트의 경우 세션 중에 Tab 키를 사용하여 전환합니다.
  2. 서브 에이전트는 다음 방법으로 호출할 수 있습니다:
    • 기본 에이전트가 해당 설명에 따라 자동으로 호출
    • @ 언급으로 수동 호출: @general help me search for this function
  3. 세션 간 탐색: 서브 에이전트가 자식 세션을 생성할 때:
    • session_child_first (기본: Leader+Down) 첫 번째 자식 입력
    • session_child_cycle (기본: Right) 다음 자식 순환
    • session_parent (기본: Up) 부모로 반환

구성

에이전트는 두 가지 방법으로 구성할 수 있습니다:

JSON

opencode.json에서 에이전트를 구성합니다:

{
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Markdown

마크다운 파일을 사용하여 에이전트를 정의합니다:

  • 전역: ~/.config/opencode/agents/
  • 프로젝트별: .opencode/agents/
---
description: 코드 품질 검토
mode: subagent
permission:
  edit: deny
  bash: deny
---

보안, 성능 및 유지보수성에 중점을 두고 코드를 검토합니다.

옵션

설명

필수 - 에이전트가 수행하는 작업에 대한 간단한 설명입니다.

Temperature

temperature로 무작위성을 제어합니다:

  • 0.0-0.2: 매우 집중적, 코드 분석에 이상적
  • 0.3-0.5: 균형 잡힌, 일반 개발에 적합
  • 0.6-1.0: 더 창의적, 브레인스토밍에 유용

Max Steps

강제 텍스트 응답 전 최대 에이전트 반복 횟수를 제어합니다.

{
  "agent": {
    "quick-thinker": {
      "steps": 5
    }
  }
}

비활성화

에이전트를 비활성화하려면 disable: true로 설정합니다.

프롬프트

커스텀 시스템 프롬프트 파일 지정:

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

모델

이 에이전트의 모델을 재정의합니다:

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

권한

에이전트가 수행할 수 있는 작업을 관리하도록 권한을 구성합니다:

  • "ask" — 실행 전 승인 요청
  • "allow" — 승인 없이 허용
  • "deny" — 도구 비활성화

사용 가능한 권한 키: read, edit, glob, grep, list, bash, task, external_directory, todowrite, webfetch, websearch, lsp, skill, question, doom_loop

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

모드

에이전트의 모드 제어: primary, subagent, 또는 all.

숨김

hidden: true로 @ 자동완성 메뉴에서 서브 에이전트를 숨깁니다. 프로그래밍 방식으로만 호출되는 내부 에이전트에 유용합니다.

작업 권한

Task 도구를 통해 에이전트가 호출할 수 있는 서브 에이전트를 제어합니다:

{
  "agent": {
    "orchestrator": {
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

색상

color로 에이전트의 시각적 모양을 사용자 지정합니다 (hex 또는 테마 색상: primary, secondary, accent, success, warning, error, info).

Top P

무작위성 제어를 위한 temperature 대안 (0.0에서 1.0).

추가

다른 모든 옵션은 모델별 기능을 위해 provider에 직접 전달됩니다.

에이전트 생성

다음으로 새 에이전트를 생성합니다:

opencode agent create

이 대화형 명령은:

  1. 저장 위치 질문 (전역 또는 프로젝트)
  2. 에이전트 설명 질문
  3. 시스템 프롬프트 및 식별자 생성
  4. 권한 선택 허용
  5. 마크다운 파일 생성

예시

문서 에이전트

---
description: 프로젝트 문서 작성 및 유지
mode: subagent
permission:
  bash: deny
---

기술 작가로서 명확하고 포괄적인 문서를 작성합니다.

보안 감사자

---
description: 보안 감사를 수행하고 취약점 식별
mode: subagent
permission:
  edit: deny
---

보안 전문가로서 입력 검증 취약점, 인증 결함, 데이터 노출 위험을 찾습니다.