컨텍스트 관리

컨텍스트로 간주되는 것

컨텍스트는 특정 턴에서 Claude가 보는 모든 것입니다:

• 시스템 프롬프트
• 메시지 기록
• 도구 정의 및 도구 결과
• 첨부된 파일 및 스킬
• 사고 블록



이는 모든 단일 API 호출의 입력입니다. 들어갈 때도 비용을 지불하고, 나갈 때도 비용을 지불합니다. 그리고 윈도우가 가득 차면 요청이 실패합니다.

따라서 목표는 모든 것을 맞추는 것이 아닙니다. 목표는 올바른 것을 맞추는 것입니다.

Anthropic은 장기 실행 에이전트에서 컨텍스트를 관리하기 위한 네 가지 패턴을 공개합니다. 세 가지는 1급 API 기능이고, 하나는 디자인 패턴입니다.



패턴 1: 적시 컨텍스트

모든 것을 미리 로드하지 마세요. 에이전트가 지금 필요한 것만 로드하고, 요청할 때 도구를 통해 더 많은 것을 가져오게 하세요.

규정 준수 검토 에이전트를 생각해 보세요. 전체 건축 법규집을 시스템 프롬프트에 채워 넣지 않습니다 — 특정 섹션이 필요할 때 lookup_building_code 도구를 호출합니다. 이것이 네 가지 중 디자인 패턴입니다: API에 특별한 것은 없고, 무엇을 언제 로드할지에 대한 의도적인 선택일 뿐입니다.

패턴 2: 서버 측 압축

대화가 길어지면 Anthropic의 서버 측 압축이 이전 턴을 하나의 블록으로 요약합니다. 요청에 context_management 키를 추가하여 옵트인하며, 이 키는 type을 가진 edit를 담습니다:

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=1024,
    context_management={
        "edits": [
            {"type": "compact_20260112"}
        ]
    },
    messages=messages,
)

입력이 트리거 임계값을 넘으면 API가 자동으로 요약합니다. 대화 길이를 직접 추적할 필요가 없습니다.

패턴 3: 프롬프트 캐싱

프롬프트 캐싱을 사용하면 요청의 안정적인 부분 — 시스템 프롬프트, 도구 정의, 긴 문서 — 를 표시하고 호출 간에 재사용하여 비용을 크게 절감할 수 있습니다.

이 계산은 보이는 것보다 더 중요합니다. 시스템 프롬프트가 4,000 토큰이고 시간당 100번 호출한다면, 캐싱은 사용 가능한 청구서와 재무팀의 전화 사이의 차이를 만듭니다.

패턴 4: 메모리 도구

일부 컨텍스트는 세션 간에 유지되어야 합니다: 사용자 선호도, 에이전트의 진행 중인 노트, 지난주에 결정된 내용 등입니다. 이를 위해 권장되는 기본 요소는 메모리 도구입니다.

작동 방식은 다음과 같습니다:

• Claude는 도구 호출을 통해 메모리 디렉터리를 읽고 씁니다.
• 스토리지 백엔드는 클라이언트 측에서 직접 구현합니다 — 파일 시스템, 데이터베이스, 암호화된 저장소 등 원하는 것을 사용할 수 있습니다.
• Anthropic은 작업을 시작하기 전에 메모리 디렉터리를 확인하도록 Claude에게 지시하는 시스템 지침을 자동으로 주입합니다.



패턴 계층화하기

프로덕션 앱에서는 보통 네 가지를 모두 한꺼번에 계층화합니다. 규정 준수 검토 에이전트는 시스템 프롬프트와 도구 정의를 캐싱하고, lookup_building_code를 통해 건축 법규 섹션을 적시에 가져옵니다.

각 패턴은 서로 다른 실패 모드를 처리합니다: 비용, 윈도우 크기, 상태 비유지성. 여러분에게 문제가 되는 것과 일치하는 패턴을 선택하세요.

요약

• 컨텍스트는 한 턴에서 Claude가 보는 모든 것이며, 무료도 무한하지도 않습니다. 윈도우가 가득 차면 요청이 실패합니다.
• 적시 컨텍스트: 지금 필요한 것만 로드하고, 나머지는 도구가 가져오게 하세요. 이것이 네 가지 중 디자인 패턴입니다.
• 서버 측 압축: context_management 키를 추가하면, 입력이 트리거 임계값을 넘을 때 API가 자동으로 이전 턴을 요약합니다.
• 프롬프트 캐싱: 요청의 안정적인 부분을 표시하고 호출 간에 재사용하여 비용을 크게 절감하세요.
• 메모리 도구: Claude는 도구 호출을 통해 메모리 디렉터리를 읽고 씁니다. 스토리지 백엔드를 직접 소유하므로 컨텍스트가 세션 간에 유지됩니다.
• 네 가지 패턴, 하나의 목표. 직접 연결하거나, 기본적으로 캐싱과 압축이 켜져 있는 Claude 관리형 에이전트를 사용하세요.