Claude Managed Agents 설정 가이드 — Agent·Session 분리부터 스트리밍까지 5단계

목차

• Claude Managed Agents 아키텍처 — Agent와 Session 분리
  • Agent 설정 객체의 구성 요소
  • Session의 생명주기
• Claude Managed Agents 설정 가이드 — 온보딩 3단계
  • 패턴별 적합 시나리오
• Python에서 SSE 스트리밍 구현 — stream-first 패턴
  • stream-first가 필요한 이유
  • 파일 업로드 처리
• Vault 자격증명 관리와 보안 설정
  • Vault 활용 시 고려사항
• Claude Agent SDK와 Managed Agents 비교
  • 어떤 것을 선택해야 하는가
• 실전 구성 시 주의사항과 트러블슈팅
  • 베타 헤더 누락
  • Custom Tool 호출 시 idle 상태 처리
  • Environment 설정 실수
• 프로덕션 도입 전 체크리스트와 다음 단계

결론부터 말하면, Claude Managed Agents 설정 가이드의 핵심은 Agent(영구 설정 객체)와 Session(런타임 인스턴스)을 분리하는 아키텍처를 이해하는 것이다. Agent를 한 번 생성해 두고 매 실행마다 Session만 새로 만드는 구조이므로, 기존 Messages API처럼 매번 모델·시스템 프롬프트를 반복 전송할 필요가 없다. 이 글에서는 Managed Agents의 아키텍처 구조, 온보딩 절차, Python 스트리밍 구현, 보안 설정, 그리고 Agent SDK와의 비교까지 코드 예제와 함께 정리한다.

Claude Managed Agents 아키텍처 — Agent와 Session 분리

Managed Agents의 설계 철학은 설정과 실행의 완전한 분리에 있다. Agent는 모델 종류, 시스템 프롬프트, 사용할 도구 목록 등을 정의하는 영구적인 설정 객체다. 한 번 POST /v1/agents로 생성하면 agent.id가 발급되고, 이후 이 ID만 참조하면 된다.

Session은 Agent를 기반으로 생성되는 런타임 인스턴스로, 실제 대화가 이루어지는 단위인 셈이다. POST /v1/sessions에 agent.id를 넘기면 새 Session이 시작된다. 각 Agent 업데이트는 새로운 불변(immutable) 버전을 생성하며, 이미 실행 중인 Session은 핀된 버전을 유지하기 때문에 설정 변경이 진행 중인 작업에 영향을 주지 않는다.

# ONE-TIME: Create agent
agent = client.beta.agents.create(
    model="claude-opus-4-7",
    system="You are...",
    tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}]
)
agent_id = agent.id

# EVERY RUN: Create session
session = client.beta.sessions.create(agent=agent_id)

이 패턴의 장점은 명확하다. Agent 설정을 한 곳에서 버전 관리하면서, Session 단위로 실행을 격리할 수 있다. 데이터베이스 마이그레이션 에이전트를 예로 들면, Agent에 DB 스키마 분석 도구와 시스템 프롬프트를 정의해 두고, 마이그레이션 요청마다 새 Session을 생성하는 방식이다. 설정 변경이 필요하면 Agent를 업데이트하되, 기존 Session은 이전 버전으로 계속 실행되므로 중단 없이 롤아웃이 가능해진다.

### Agent 설정 객체의 구성 요소

Agent 생성 시 전달하는 주요 파라미터는 model, system(시스템 프롬프트), tools(도구 배열)이다. tools 배열에는 agent_toolset_20260401(기본 내장 도구), MCP 서버 연동 도구, Custom 도구 세 종류를 조합해 넣을 수 있다. 모든 Managed Agents API 호출에는 managed-agents-2026-04-01 베타 헤더가 필수인 점을 기억해야 한다.

Session의 생명주기

Session은 생성 → 활성(active) → 유휴(idle) → 종료(terminated) 순서로 전이된다. Custom tool 호출이 발생하면 Session은 idle 상태로 전환되고, 클라이언트가 user.custom_tool_result 이벤트로 결과를 반환해야 다시 active로 돌아간다. 이 상태 전이를 이해하지 못하면 스트리밍 구현에서 무한 대기에 빠지는 경우가 있다.

Claude Managed Agents 설정 가이드 — 온보딩 3단계

Managed Agents 온보딩 가이드에 따르면, 온보딩은 크게 3단계로 구성된다.

1단계 — 패턴 선택: 에이전트의 실행 방식을 결정하는 것이다. 이벤트 트리거(웹훅 수신 시 자동 실행), 크론(주기적 실행), 파이어앤포겟 PR(코드 리뷰 후 자동 종료), 리서치+대시보드(데이터 수집 후 결과 보고) 중 하나를 선택한다.

2단계 — 도구 구성: 에이전트가 사용할 도구를 설정하는 단계다. 도구는 세 종류로 나뉜다.

도구 유형	설명	사용 예시
agent_toolset_20260401	Anthropic 기본 내장 도구	파일 읽기/쓰기, 코드 실행
MCP 도구	외부 MCP 서버 연동	GitHub, Slack, DB 접근
Custom 도구	사용자 정의 함수 호출	내부 API 호출, 데이터 변환

3단계 — 환경+세션 설정: Environment를 만들고, Agent를 생성한 뒤, Session을 시작하는 순서로 진행한다.

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

agent = client.beta.agents.create(
    name="my-agent",
    model="claude-opus-4-7",
    tools=[{"type": "agent_toolset_20260401"}],
    system_prompt="..."
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id
)

Environment는 에이전트가 실행되는 인프라 환경을 정의한다. networking 설정에서 unrestricted로 지정하면 외부 네트워크 접근이 가능하고, 제한이 필요한 경우 별도 설정을 적용하는 방식이다. 프로덕션 환경에서는 네트워크 정책을 좁히는 것이 권장되지만, 이에 대한 세부 옵션은 공식 문서에도 명시되어 있지 않다.

### 패턴별 적합 시나리오

이벤트 트리거 패턴은 GitHub 웹훅, Slack 이벤트 등 외부 시스템의 알림에 반응하는 에이전트에 적합하다. 크론 패턴은 매일 로그를 분석하거나 주기적으로 데이터를 수집하는 배치성 작업에 맞는 편이다. 파이어앤포겟 PR 패턴은 PR이 열리면 코드 리뷰를 수행하고 코멘트를 남긴 뒤 자동 종료되는 구조다. 리서치+대시보드 패턴은 여러 소스에서 정보를 수집해 요약 리포트를 생성하는 용도로 쓰인다.

Python에서 SSE 스트리밍 구현 — stream-first 패턴

Managed Agents의 Python 구현에서 가장 중요한 개념은 stream-first 패턴이다. 메시지를 먼저 보내고 응답을 기다리는 일반적인 request-response와 달리, Managed Agents에서는 스트림을 먼저 열고 그 안에서 메시지를 보내야 한다. 이 순서를 뒤집으면 이벤트가 유실될 수 있다.

with client.beta.sessions.stream(session_id=session.id) as stream:
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[{"type": "user.message", "content": [{"type": "text", "text": "Review the auth module"}]}]
    )
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text, end="", flush=True)
        elif event.type == "session.status_terminated":
            break

pip install anthropic으로 SDK를 설치한 뒤 위 코드를 실행하면 SSE(Server-Sent Events) 방식으로 에이전트의 응답을 실시간 수신할 수 있다. client.beta.sessions.stream()이 컨텍스트 매니저로 스트림을 열고, 그 안에서 events.send()로 사용자 메시지를 전송하는 구조다.

이벤트 루프에서 주의할 점은 session.status_terminated 이벤트를 반드시 처리해야 한다는 것이다. 이 이벤트를 무시하면 스트림이 닫히지 않고 프로세스가 영원히 대기하게 된다. Custom tool 호출이 포함된 에이전트라면 idle 상태 감지와 user.custom_tool_result 이벤트 전송 로직도 추가해야 한다.

stream-first가 필요한 이유

일반적인 HTTP request-response 모델에서는 요청을 보내고 응답이 올 때까지 기다린다. 하지만 Managed Agents의 Session은 장시간 실행되는 작업을 수행하기도 하고, 중간에 도구 호출 결과를 주고받아야 하는 양방향 통신이 필요하다. SSE 스트림을 먼저 연결해 두면 에이전트가 생성하는 모든 이벤트(메시지, 도구 호출, 상태 전이)를 누락 없이 수신할 수 있는 셈이다.

### 파일 업로드 처리

에이전트에 파일을 전달해야 하는 경우 Files API를 사용한다. files-api-2025-04-14 베타 헤더가 별도로 필요하며, 업로드된 파일의 ID를 메시지 이벤트에 포함시키는 방식이다. 파일 크기 제한이나 지원 형식에 대한 세부 사항은 공식 문서에도 명시되어 있지 않다.

Vault 자격증명 관리와 보안 설정

MCP 서버를 연동하거나 외부 API에 접근하는 에이전트를 구성할 때, 인증 정보를 에이전트 설정에 직접 포함시키면 보안 위험이 발생한다. Managed Agents는 이 문제를 Vault 시스템으로 해결한다. Vault에 자격증명을 저장하고, Session 생성 시 vault_ids로 참조하는 구조다.

# Vault에 자격증명 저장
vault = client.beta.vaults.create()
cred = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    type="github",
    github_token="ghp_xxxx"
)

# Session에서 vault 참조
session = client.beta.sessions.create(
    agent=agent.id,
    vault_ids=[vault.id]
)

이 방식의 핵심은 Agent 설정 자체에 토큰이나 비밀번호가 포함되지 않는다는 점이다. Agent는 “GitHub 도구를 사용한다”는 것만 알고, 실제 인증 정보는 Session이 Vault를 통해 런타임에 주입받는다. Anthropic이 OAuth 토큰의 자동 갱신도 처리하므로 토큰 만료로 인한 장애를 줄일 수 있다.

### Vault 활용 시 고려사항

Vault에 저장할 수 있는 자격증명 유형으로는 GitHub 토큰이 확인되었으나, 지원하는 전체 유형 목록은 공식 문서에도 명시되어 있지 않다. DB 접속 정보나 AWS 키 같은 범용 자격증명의 경우, Custom 도구와 조합해 별도 인증 흐름을 구성해야 할 수 있다. 요금 체계(세션당 비용, 컨테이너 시간 과금 등)도 현재 공식 문서에서 확인할 수 없는 상태이므로, 프로덕션 도입 전 Anthropic 영업팀에 직접 문의하는 것이 안전하다.

Claude Agent SDK와 Managed Agents 비교

Claude Agent SDK(claude-agent-sdk)와 Managed Agents API는 모두 에이전트를 구축하는 도구지만, Agent SDK Python 리포지토리와 Managed Agents 아키텍처 문서를 비교하면 접근 방식이 다르다.

비교 항목	Managed Agents API	Claude Agent SDK
설치	pip install anthropic	pip install claude-agent-sdk
Python 버전	SDK 기본 요구사항	Python 3.10+
실행 환경	Anthropic 클라우드 (Environment)	로컬 또는 자체 서버
상태 관리	Agent/Session 서버 측 관리	클라이언트 측 직접 관리
도구 정의	API 파라미터로 선언	@tool 데코레이터
MCP 서버	에이전트 설정에 연동	인프로세스 MCP 서버 생성
권한 제어	Vault + 네트워크 정책	Hooks 시스템 (PreToolUse)
버전 관리	자동 불변 버전 생성	수동 관리
양방향 대화	SSE 스트리밍	ClaudeSDKClient
단순 질의	Session 기반	query() 함수

Agent SDK는 로컬 환경에서 에이전트를 직접 실행하는 방식이다. @tool 데코레이터로 도구를 정의하면 인프로세스 MCP 서버가 생성되고, Hooks 시스템의 PreToolUse로 도구 실행 전 권한을 제어할 수 있다.

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

server = create_sdk_mcp_server(
    name="my-tools", version="1.0.0", tools=[greet_user]
)

Managed Agents는 Anthropic 클라우드에서 실행되므로 인프라 관리 부담이 적고, Agent SDK는 자체 서버에서 실행되므로 네트워크 지연이나 데이터 유출 우려 없이 내부 시스템에 접근하기 용이하다. 다만 두 도구의 정확한 관계와 통합 방식에 대해서는 공식 문서에도 명시되어 있지 않다.

어떤 것을 선택해야 하는가

선택 기준은 실행 환경의 위치와 운영 부담 허용 범위로 나뉘는 편이다. Anthropic 클라우드에서 완전 관리형으로 실행하고 싶다면 Managed Agents가 적합하고, 자체 인프라에서 에이전트를 실행하면서 세밀한 제어가 필요하다면 Agent SDK를 쓰는 것이 낫다. 두 접근법 모두 MCP 프로토콜을 지원하므로 도구 정의는 호환될 가능성이 높지만, 현 시점에서 이를 보장하는 공식 문서는 없다.

실전 구성 시 주의사항과 트러블슈팅

Managed Agents를 실제로 설정하다 보면 몇 가지 공통적인 문제 상황에 부딪히게 된다.

베타 헤더 누락

가장 빈번한 실수는 베타 헤더를 빠뜨리는 것이다. Python SDK의 client.beta.* 네임스페이스를 사용하면 헤더가 자동 포함되지만, curl이나 다른 HTTP 클라이언트로 직접 호출할 때는 managed-agents-2026-04-01 헤더를 수동으로 추가해야 한다. 헤더가 없으면 404나 400 에러가 반환되는데, 에러 메시지만으로는 헤더 누락이 원인임을 파악하기 어려운 경우가 있다.

Custom Tool 호출 시 idle 상태 처리

Custom tool이 포함된 에이전트에서 도구 호출이 발생하면 Session이 idle 상태로 전환된다. 이때 클라이언트가 user.custom_tool_result 이벤트로 결과를 반환하지 않으면 Session이 영원히 idle 상태에 머물게 된다. 스트리밍 이벤트 루프에서 idle 상태를 감지하고 적절한 타임아웃을 설정하는 로직이 필수다.

[흐름 정리]
1. 에이전트가 custom tool 호출 → Session idle 전환
2. 클라이언트가 tool 실행 → 결과를 user.custom_tool_result로 전송
3. Session이 active로 복귀 → 에이전트가 결과 기반으로 계속 진행

Environment 설정 실수

Environment의 networking 설정을 unrestricted로 둔 채 프로덕션에 배포하면 에이전트가 의도치 않은 외부 서비스에 접근할 수 있다. 개발 단계에서는 편의를 위해 열어두더라도, 프로덕션 배포 전에는 네트워크 정책을 좁히는 것을 권장한다. 다만 세부 네트워크 정책 옵션은 공식 문서에도 명시되어 있지 않다.

## 프로덕션 도입 전 체크리스트와 다음 단계

Managed Agents를 프로덕션에 도입하기 전 확인 항목은 아래 표를 참조하면 된다.

체크 항목	확인 내용	비고
베타 헤더	모든 호출에 managed-agents-2026-04-01 포함	SDK 사용 시 자동
Vault 설정	자격증명이 Agent 설정에 직접 포함되지 않음	토큰 자동 갱신 확인
archive 방지	프로덕션 Agent에 archive 호출 차단	복원 불가
네트워크 정책	Environment에서 unrestricted 제거	최소 권한 원칙
idle 타임아웃	Custom tool 호출 시 무한 대기 방지	스트리밍 루프에 구현
스트림 순서	stream-first 패턴 준수	이벤트 유실 방지
모니터링	Session 상태 전이 로깅	공식 가이드 부재

모니터링과 알림 설정에 대한 공식 가이드는 현재 존재하지 않으므로, Session 이벤트 스트림에서 상태 전이를 직접 로깅하는 방식으로 구현해야 한다. 요금 체계도 공식적으로 공개되지 않은 상태이므로 비용 예측이 필요하다면 Anthropic에 직접 문의하는 것이 유일한 방법이다.

Managed Agents 설정이 완료되었다면, 다음 단계로 MCP 서버 연동을 고려할 만하다. GitHub, Slack, 데이터베이스 같은 외부 시스템을 MCP 도구로 연결하면 에이전트의 활용 범위가 크게 넓어진다. Claude Agent SDK의 @tool 데코레이터로 로컬 MCP 서버를 구축하는 것도 Managed Agents와 병행할 수 있는 접근법이다. 그리고 에이전트 실행 결과를 입력·출력·도구 호출 단위로 자동 평가하는 Eval 파이프라인 구축도 프로덕션 운영에서는 빠질 수 없는 주제가 된다. Claude Managed Agents 설정 가이드의 기본 구조를 익혔다면, 이런 확장 영역에서 실질적인 차이가 만들어진다.