WaveSpeedAI
← 블로그

Claude Managed Agents 퀵스타트 가이드 2026

Claude Managed Agents 퀵스타트 가이드: 베타 헤더 설정, 첫 번째 세션, 도구 호출, 스트리밍 이벤트 — 주요 코드 패턴 및 비용 체크포인트 포함.

By Dora 5 min read
Claude Managed Agents 퀵스타트 가이드 2026

Managed Agents 세션을 처음 실행하려 했을 때, 첫 번째 curl에서 바로 400 오류가 났습니다. 에이전트 생성에서가 아니었습니다. 환경 설정에서도 아니었습니다. 스트림 엔드포인트에서였습니다. 생성 요청의 헤더를 복사해 붙여넣었는데 — anthropic-beta: managed-agents-2026-04-01 — 스트리밍 API가 이를 거부했습니다. 알고 보니 당시 문서의 스트리밍 엔드포인트가 다른 베타 헤더를 참조하고 있었던 것입니다. 그걸로 40분을 낭비했습니다.

오늘 Managed Agents 세션을 처음부터 끝까지 실행해보려 한다면, 이것이 제가 실제로 걸어온 길입니다. 안녕하세요, Dora입니다! 베타 헤더부터 시작합니다. 실패의 절반이 거기서 비롯되기 때문입니다. 그다음 에이전트, 환경, 세션, 스트림 순서입니다. 마지막으로 비용 확인 포인트가 있는데, 디버깅하는 동안에도 세션 런타임은 계속 올라가기 때문입니다.

시작하기 전에

Managed Agents 접근 권한이 있는 Anthropic API 키가 필요합니다. 현재 대기자 명단은 없으며 기존 키라면 공개 베타에서 모두 사용할 수 있습니다.

베타 헤더는 필수입니다. 모든 Managed Agents 엔드포인트에는 anthropic-beta: managed-agents-2026-04-01이 필요합니다. Anthropic의 Managed Agents 개요에 따르면 SDK가 이를 자동으로 설정합니다. raw curl을 사용하는 경우 모든 요청에 직접 추가해야 합니다. 이것이 커뮤니티 보고서에서 제가 본 400 오류의 가장 흔한 원인입니다.

공식 SDK(Python용 anthropic, TypeScript용 @anthropic-ai/sdk)를 사용한다면 베타 에이전트 지원을 포함하는 버전인지 확인하세요. 오래된 버전에는 client.beta.agents 또는 client.beta.sessions가 없을 수 있습니다.

모델 선택도 중요합니다. Opus 4.7은 장기적인 에이전트 추론에 더 뛰어납니다. Sonnet 4.6은 토큰당 비용이 저렴하고 빠릅니다. 빠른 시작 실행에는 Sonnet 4.6으로 충분합니다. 실제 작업이 디버깅, 계획 수립, 또는 긴 도구 체인이라면 Opus 4.7이 그 가격 값을 합니다.

1단계 — 에이전트 정의하기

Managed Agents에서 에이전트는 프로세스가 아닌 설정 객체입니다. 이름, 모델, 시스템 프롬프트, 도구 접근 권한을 한 번 정의하면 여러 세션에서 재사용할 수 있습니다.

공식 퀵스타트의 최소 실행 가능한 정의:

python

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding agent.",
    tools=[{"type": "agent_toolset_20260401"}],
)

agent_toolset_20260401 도구 타입은 전체 내장 도구셋을 활성화합니다 — bash, 파일 읽기/쓰기, 웹 검색, 웹 페치, 코드 실행. 나중에 범위를 좁힐 수 있습니다. 첫 실행에서는 에이전트가 실제로 무엇을 선택하는지 볼 수 있도록 넓게 설정해두세요.

agent.id를 저장하세요. 모든 세션이 이를 참조합니다.

2단계 — 환경 생성하기

환경은 샌드박스 컨테이너를 정의합니다. 대부분의 첫 실행의 경우:

python

env = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

env.id를 저장하세요. 에이전트가 자체 파일시스템만 접근한다면 "networking": {"type": "limited"}가 더 안전하며, SRE 인시던트 대응 쿡북에 잘 문서화되어 있습니다.

3단계 — 세션 시작하기

세션은 에이전트를 환경과 연결합니다. 세션을 생성한다고 작업이 시작되지는 않습니다. 단지 프로비저닝할 뿐입니다. 사용자 이벤트를 전송할 때 작업이 시작됩니다.

python

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
    title="Quickstart session",
)

이 패턴 — 생성 후 이벤트로 구동 — 은 세션 레퍼런스의 상태 머신 모델이 의미 있어지는 부분입니다. 세션은 지속됩니다. 나중에 더 많은 이벤트를 보낼 수 있습니다. 파일시스템은 턴 사이에도 유지됩니다.

4단계 — 이벤트 스트리밍하기

스트림을 열고, 사용자 메시지를 보내고, session.status_idle까지 이벤트를 읽습니다:

python

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text",
                         "text": "Generate first 20 Fibonacci numbers, save to fib.txt"}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[tool: {event.name}]")
            case "session.status_idle":
                break

이벤트 이름은 {도메인}.{액션} 형식을 따릅니다. 전체 스키마는 이벤트 및 스트리밍 문서에 있습니다. processed_at 필드가 중요합니다: null이면 이벤트가 큐에 있는 것이며 아직 실행되지 않은 상태입니다. 첫 실행 때 이걸 놓쳐서 도구가 조용히 실패하고 있다고 착각했습니다.

비용 확인 포인트

Managed Agents는 두 가지를 청구합니다: 표준 토큰 요금과 활성 런타임의 세션-시간당 $0.08. 공식 가격 페이지에 따르면 런타임은 밀리초 단위로 누적되지만 — 상태가 running일 때만 해당됩니다. 유휴 시간과 종료된 세션은 청구되지 않습니다.

실제로 이것이 의미하는 바:

  • 디버깅하는 동안 닫는 것을 잊은 세션: 여전히 누적 중입니다(실행 중인 경우).
  • 웹 검색: 1,000회당 $10, 별도 청구됩니다. 리서치 에이전트는 이를 빠르게 소진합니다.
  • 하루 작업을 마치기 전에 콘솔 추적에서 활성 세션을 확인하세요. 콘솔 레이아웃이 계속 바뀌고 있으므로 현재 UI 경로는 직접 확인하세요.

자주 발생하는 오류

베타 헤더 누락 또는 오류. 400 오류, 지원되지 않는 엔드포인트에 대한 메시지가 함께 나타납니다. 해결책: 모든 직접 HTTP 호출에 managed-agents-2026-04-01이 있는지 확인하세요. SDK를 사용 중인데도 이 오류가 발생한다면 SDK를 업그레이드하세요.

속도 제한. 생성 엔드포인트는 분당 60회, 읽기 엔드포인트는 분당 600회로 제한됩니다. 조직 티어 제한도 추가로 적용됩니다. 429 오류는 지터와 함께 백오프하라는 의미이지, 즉시 재시도하라는 뜻이 아닙니다.

조용한 도구 루프. 에이전트가 계속 도구를 호출하지만 최종 메시지를 생성하지 않습니다. 세션 추적을 확인하세요 — 보통 응답이 다시 전송되지 않은 처리되지 않은 requires_action 때문입니다.

FAQ

Q1: Managed Agents에서 멀티 에이전트 조율을 어떻게 활성화하나요?

멀티 에이전트(메모리 및 결과와 함께)는 아직 리서치 프리뷰 기능입니다. Claude 콘솔을 통해 별도로 접근 권한을 요청해야 합니다. 조율 패턴 — 오케스트레이터가 호출 가능한 에이전트에 위임하는 방식 — 은 멀티에이전트 세션에 문서화되어 있지만, 조직의 프리뷰 플래그가 활성화될 때까지 사용할 수 없습니다.

Q2: 세션 중 에이전트가 호출한 도구를 검사할 수 있나요?

네. 프로그래밍 방식 접근에는 client.beta.sessions.events.list(session.id)를 사용하거나, 이벤트별 토큰과 타임스탬프가 있는 시간순 타임라인을 위해 콘솔의 추적 뷰를 사용하세요.

Q3: 공식 Managed Agents 쿡북은 어디에 있나요?

튜토리얼은 Claude 쿡북 사이트에 있습니다 — iterate-fix-failing-tests 노트북이 첫 번째로 읽기 좋습니다. operate-in-production 노트북은 hello-world 단계를 넘어서면 볼트, MCP, 웹훅을 다룹니다.

Q4: 세션 런타임 비용 없이 테스트할 방법이 있나요?

Managed Agents 전용 무료 티어는 없습니다. 표준 API 무료 크레딧이 적용됩니다. 개발 중에는 세션을 짧게 유지하고 작업을 멈출 때 닫으세요. 유휴 세션은 청구되지 않지만, 실행 중인 세션은 청구됩니다 — “실행 중”에는 조용히 루프를 도는 에이전트도 포함됩니다.

Q5: 장기 실행 Managed Agents 작업에 가장 좋은 모델은 무엇인가요?

“장기 실행”이 무엇을 의미하는지에 달려 있습니다. 도구를 많이 사용하는 다중 시간 추론의 경우 Opus 4.7. 고볼륨의 단순한 루프의 경우 프롬프트 캐싱이 적용된 Sonnet 4.6이 비용을 크게 절감합니다. 아직 2시간 이상의 세션에서 Opus 4.7을 테스트 중입니다. 제 데이터는 거기서 끝납니다. 더 많은 내용이 나올 예정입니다.

두 시간이 지난 후 컴팩션이 어떻게 동작하는지 아직 검증 중입니다. 직접 실행해보세요 — 제가 말할 수 있는 것보다 더 많은 것을 알 수 있을 겁니다.

이전 게시물:

공유