Loading...
    • 개발자 가이드
    • API 참고자료
    • MCP
    • 리소스
    • 릴리스 노트
    Search...
    ⌘K

    첫 번째 단계

    Claude 소개빠른 시작

    모델 및 가격

    모델 개요모델 선택하기Claude 4.5의 새로운 기능Claude 4.5로 마이그레이션모델 지원 중단가격 정책

    Claude로 빌드하기

    기능 개요Messages API 작업컨텍스트 윈도우프롬프트 작성 모범 사례

    기능

    프롬프트 캐싱컨텍스트 편집확장된 사고스트리밍 메시지배치 처리인용다국어 지원토큰 카운팅임베딩비전PDF 지원Files API검색 결과Google Sheets 애드온

    도구

    개요도구 사용을 구현하는 방법토큰 효율적인 도구 사용세밀한 도구 스트리밍Bash 도구코드 실행 도구컴퓨터 사용 도구텍스트 편집기 도구웹 페치 도구웹 검색 도구메모리 도구

    에이전트 스킬

    개요빠른 시작Skill 작성 모범 사례Skills 사용하기

    Agent SDK

    개요Agent SDK 참조 - TypeScriptPython SDK

    가이드

    스트리밍 입력권한 처리세션 관리Agent SDK 호스팅시스템 프롬프트 수정하기SDK에서의 MCP사용자 정의 도구SDK의 서브에이전트SDK의 슬래시 명령어SDK의 에이전트 스킬비용 및 사용량 추적할 일 목록SDK의 플러그인

    API의 MCP

    MCP 커넥터원격 MCP 서버

    타사 플랫폼의 Claude

    Amazon BedrockVertex AI

    프롬프트 엔지니어링

    개요프롬프트 생성기프롬프트 템플릿 사용하기프롬프트 개선기명확하고 직접적으로예시(멀티샷 프롬프팅) 사용Claude가 생각하도록 하기(CoT)XML 태그 사용Claude에게 역할 부여하기 (시스템 프롬프트)Claude의 응답 미리 채우기복잡한 프롬프트 체이닝긴 컨텍스트 팁확장 사고 팁

    테스트 및 평가

    성공 기준 정의하기테스트 케이스 개발평가 도구 사용하기지연 시간 줄이기

    보안 강화

    환각 현상 줄이기출력 일관성 높이기탈옥 완화handle-streaming-refusals프롬프트 유출 감소Claude의 캐릭터 유지

    관리 및 모니터링

    Admin API 개요사용량 및 비용 APIClaude Code Analytics API
    Console
    가이드

    SDK의 서브에이전트

    Claude Agent SDK에서 서브에이전트 작업하기

    Claude Agent SDK의 서브에이전트는 메인 에이전트에 의해 조율되는 전문화된 AI입니다. 컨텍스트 관리와 병렬화를 위해 서브에이전트를 사용하세요.

    이 가이드는 agents 매개변수를 사용하여 SDK에서 서브에이전트를 정의하고 사용하는 방법을 설명합니다.

    개요

    SDK를 사용할 때 서브에이전트는 두 가지 방법으로 정의할 수 있습니다:

    1. 프로그래밍 방식 - query() 옵션에서 agents 매개변수 사용 (SDK 애플리케이션에 권장)
    2. 파일시스템 기반 - 지정된 디렉토리(.claude/agents/)에 YAML 프론트매터가 있는 마크다운 파일 배치

    이 가이드는 주로 agents 매개변수를 사용하는 프로그래밍 방식에 중점을 두며, 이는 SDK 애플리케이션에 더 통합된 개발 경험을 제공합니다.

    서브에이전트 사용의 이점

    컨텍스트 관리

    서브에이전트는 메인 에이전트와 별도의 컨텍스트를 유지하여 정보 과부하를 방지하고 상호작용을 집중적으로 유지합니다. 이러한 격리는 전문화된 작업이 관련 없는 세부사항으로 메인 대화 컨텍스트를 오염시키지 않도록 보장합니다.

    예시: research-assistant 서브에이전트는 수십 개의 파일과 문서 페이지를 탐색할 수 있으면서도 모든 중간 검색 결과로 메인 대화를 어수선하게 만들지 않고 관련 발견사항만 반환할 수 있습니다.

    병렬화

    여러 서브에이전트가 동시에 실행되어 복잡한 워크플로우를 극적으로 가속화할 수 있습니다.

    예시: 코드 리뷰 중에 style-checker, security-scanner, test-coverage 서브에이전트를 동시에 실행하여 리뷰 시간을 몇 분에서 몇 초로 단축할 수 있습니다.

    전문화된 지시사항과 지식

    각 서브에이전트는 특정 전문 지식, 모범 사례, 제약 조건을 가진 맞춤형 시스템 프롬프트를 가질 수 있습니다.

    예시: database-migration 서브에이전트는 SQL 모범 사례, 롤백 전략, 데이터 무결성 검사에 대한 상세한 지식을 가질 수 있으며, 이는 메인 에이전트의 지시사항에서는 불필요한 노이즈가 될 것입니다.

    도구 제한

    서브에이전트는 특정 도구로 제한되어 의도하지 않은 작업의 위험을 줄일 수 있습니다.

    예시: doc-reviewer 서브에이전트는 Read와 Grep 도구에만 액세스할 수 있어 분석은 할 수 있지만 문서 파일을 실수로 수정하지 않도록 보장할 수 있습니다.

    서브에이전트 생성

    프로그래밍 정의 (권장)

    agents 매개변수를 사용하여 코드에서 직접 서브에이전트를 정의하세요:

    import { query } from '@anthropic-ai/claude-agent-sdk';
    
    const result = query({
      prompt: "인증 모듈의 보안 문제를 검토하세요",
      options: {
        agents: {
          'code-reviewer': {
            description: '전문 코드 리뷰 전문가. 품질, 보안, 유지보수성 리뷰에 사용하세요.',
            prompt: `당신은 보안, 성능, 모범 사례에 전문 지식을 가진 코드 리뷰 전문가입니다.
    
    코드를 리뷰할 때:
    - 보안 취약점 식별
    - 성능 문제 확인
    - 코딩 표준 준수 검증
    - 구체적인 개선사항 제안
    
    피드백은 철저하되 간결하게 제공하세요.`,
            tools: ['Read', 'Grep', 'Glob'],
            model: 'sonnet'
          },
          'test-runner': {
            description: '테스트 스위트를 실행하고 분석합니다. 테스트 실행과 커버리지 분석에 사용하세요.',
            prompt: `당신은 테스트 실행 전문가입니다. 테스트를 실행하고 결과에 대한 명확한 분석을 제공하세요.
    
    다음에 집중하세요:
    - 테스트 명령 실행
    - 테스트 출력 분석
    - 실패한 테스트 식별
    - 실패에 대한 수정 제안`,
            tools: ['Bash', 'Read', 'Grep'],
          }
        }
      }
    });
    
    for await (const message of result) {
      console.log(message);
    }

    AgentDefinition 구성

    필드타입필수설명
    descriptionstring예이 에이전트를 언제 사용할지에 대한 자연어 설명
    promptstring예에이전트의 역할과 행동을 정의하는 시스템 프롬프트
    toolsstring[]아니오허용된 도구 이름 배열. 생략하면 모든 도구를 상속
    model'sonnet' | 'opus' | 'haiku' | 'inherit'아니오이 에이전트의 모델 재정의. 생략하면 메인 모델로 기본값 설정

    파일시스템 기반 정의 (대안)

    특정 디렉토리에 마크다운 파일로 서브에이전트를 정의할 수도 있습니다:

    • 프로젝트 수준: .claude/agents/*.md - 현재 프로젝트에서만 사용 가능
    • 사용자 수준: ~/.claude/agents/*.md - 모든 프로젝트에서 사용 가능

    각 서브에이전트는 YAML 프론트매터가 있는 마크다운 파일입니다:

    ---
    name: code-reviewer
    description: 전문 코드 리뷰 전문가. 품질, 보안, 유지보수성 리뷰에 사용하세요.
    tools: Read, Grep, Glob, Bash
    ---
    
    서브에이전트의 시스템 프롬프트가 여기에 들어갑니다. 이것은 서브에이전트의
    역할, 능력, 문제 해결 접근 방식을 정의합니다.

    참고: 프로그래밍 방식으로 정의된 에이전트(agents 매개변수를 통해)는 같은 이름의 파일시스템 기반 에이전트보다 우선합니다.

    SDK가 서브에이전트를 사용하는 방법

    Claude Agent SDK를 사용할 때 서브에이전트는 프로그래밍 방식으로 정의되거나 파일시스템에서 로드될 수 있습니다. Claude는:

    1. 프로그래밍 에이전트 로드 - 옵션의 agents 매개변수에서
    2. 파일시스템 에이전트 자동 감지 - .claude/agents/ 디렉토리에서 (재정의되지 않은 경우)
    3. 자동으로 호출 - 작업 매칭과 에이전트의 description을 기반으로
    4. 전문화된 프롬프트 사용 및 도구 제한
    5. 별도 컨텍스트 유지 - 각 서브에이전트 호출에 대해

    프로그래밍 방식으로 정의된 에이전트(agents 매개변수를 통해)는 같은 이름의 파일시스템 기반 에이전트보다 우선합니다.

    예시 서브에이전트

    코드 리뷰어, 테스트 러너, 디버거, 보안 감사자를 포함한 서브에이전트의 포괄적인 예시는 메인 서브에이전트 가이드를 참조하세요. 이 가이드에는 효과적인 서브에이전트 생성을 위한 상세한 구성과 모범 사례가 포함되어 있습니다.

    SDK 통합 패턴

    자동 호출

    SDK는 작업 컨텍스트를 기반으로 적절한 서브에이전트를 자동으로 호출합니다. 에이전트의 description 필드가 언제 사용되어야 하는지 명확하게 나타내도록 하세요:

    const result = query({
      prompt: "API 레이어의 데이터베이스 쿼리를 최적화하세요",
      options: {
        agents: {
          'performance-optimizer': {
            description: '코드 변경이 성능에 영향을 줄 수 있을 때 적극적으로 사용하세요. 최적화 작업에는 반드시 사용되어야 합니다.',
            prompt: '당신은 성능 최적화 전문가입니다...',
            tools: ['Read', 'Edit', 'Bash', 'Grep'],
            model: 'sonnet'
          }
        }
      }
    });

    명시적 호출

    사용자는 프롬프트에서 특정 서브에이전트를 요청할 수 있습니다:

    const result = query({
      prompt: "code-reviewer 에이전트를 사용하여 인증 모듈을 확인하세요",
      options: {
        agents: {
          'code-reviewer': {
            description: '전문 코드 리뷰 전문가',
            prompt: '당신은 보안에 중점을 둔 코드 리뷰어입니다...',
            tools: ['Read', 'Grep', 'Glob']
          }
        }
      }
    });

    동적 에이전트 구성

    애플리케이션의 필요에 따라 에이전트를 동적으로 구성할 수 있습니다:

    import { query, type AgentDefinition } from '@anthropic-ai/claude-agent-sdk';
    
    function createSecurityAgent(securityLevel: 'basic' | 'strict'): AgentDefinition {
      return {
        description: '보안 코드 리뷰어',
        prompt: `당신은 ${securityLevel === 'strict' ? '엄격한' : '균형잡힌'} 보안 리뷰어입니다...`,
        tools: ['Read', 'Grep', 'Glob'],
        model: securityLevel === 'strict' ? 'opus' : 'sonnet'
      };
    }
    
    const result = query({
      prompt: "이 PR의 보안 문제를 검토하세요",
      options: {
        agents: {
          'security-reviewer': createSecurityAgent('strict')
        }
      }
    });

    도구 제한

    서브에이전트는 tools 필드를 통해 제한된 도구 액세스를 가질 수 있습니다:

    • 필드 생략 - 에이전트가 사용 가능한 모든 도구를 상속 (기본값)
    • 도구 지정 - 에이전트가 나열된 도구만 사용 가능

    읽기 전용 분석 에이전트의 예시:

    const result = query({
      prompt: "이 코드베이스의 아키텍처를 분석하세요",
      options: {
        agents: {
          'code-analyzer': {
            description: '정적 코드 분석 및 아키텍처 검토',
            prompt: `당신은 코드 아키텍처 분석가입니다. 코드 구조를 분석하고,
    패턴을 식별하며, 변경 없이 개선사항을 제안하세요.`,
            tools: ['Read', 'Grep', 'Glob']  // 쓰기나 실행 권한 없음
          }
        }
      }
    });

    일반적인 도구 조합

    읽기 전용 에이전트 (분석, 검토):

    tools: ['Read', 'Grep', 'Glob']

    테스트 실행 에이전트:

    tools: ['Bash', 'Read', 'Grep']

    코드 수정 에이전트:

    tools: ['Read', 'Edit', 'Write', 'Grep', 'Glob']

    관련 문서

    • 메인 서브에이전트 가이드 - 포괄적인 서브에이전트 문서
    • SDK 개요 - Claude Agent SDK 개요
    • 설정 - 구성 파일 참조
    • 슬래시 명령 - 사용자 정의 명령 생성
    • AgentDefinition 구성
    • SDK가 서브에이전트를 사용하는 방법
    • SDK 통합 패턴
    © 2025 ANTHROPIC PBC

    Products

    • Claude
    • Claude Code
    • Max plan
    • Team plan
    • Enterprise plan
    • Download app
    • Pricing
    • Log in

    Features

    • Claude and Slack
    • Claude in Excel

    Models

    • Opus
    • Sonnet
    • Haiku

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Claude Developer Platform

    • Overview
    • Developer docs
    • Pricing
    • Amazon Bedrock
    • Google Cloud’s Vertex AI
    • Console login

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Help and security

    • Availability
    • Status
    • Support center

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy

    Products

    • Claude
    • Claude Code
    • Max plan
    • Team plan
    • Enterprise plan
    • Download app
    • Pricing
    • Log in

    Features

    • Claude and Slack
    • Claude in Excel

    Models

    • Opus
    • Sonnet
    • Haiku

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Claude Developer Platform

    • Overview
    • Developer docs
    • Pricing
    • Amazon Bedrock
    • Google Cloud’s Vertex AI
    • Console login

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Help and security

    • Availability
    • Status
    • Support center

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    © 2025 ANTHROPIC PBC