Claude Managed Agents 설정 3단계 — Agent 생성·도구 할당·Vault 보안 완전 가이드

목차

• 직접 구현 에이전트의 구조적 한계
• Claude Managed Agents 핵심 아키텍처 — Agent와 Session 분리
• Claude Managed Agents 설정 가이드 — 초기 구성 3단계
  • 1단계: 패턴 선택
  • 2단계: 도구 구성
  • 3단계: Environment 생성 → Agent 생성 → Session 생성
• Python SDK로 스트리밍 세션 구현하기
  • Custom Tool 호출 시 idle 상태 처리
• Vault 기반 자격증명 관리와 보안 설정
  • Vault 보안 운영 권장 사항
• Claude Agent SDK와 커스텀 도구 확장
  • Hooks 시스템으로 도구 실행 권한 제어
• 현재 한계점과 프로덕션 적용 시 고려사항
  • 프로덕션 체크리스트
• 설정 구성 전체 흐름 정리와 다음 단계

2026년 1분기 기준, GitHub Trending에서 “AI agent” 태그가 포함된 저장소가 빠르게 늘고 있다. LLM을 단순 챗봇이 아니라 자율 실행 에이전트로 활용하려는 수요가 폭발적으로 늘어난 것이다. Anthropic은 이 흐름에 맞춰 Claude Managed Agents를 베타로 공개했는데, 기존의 단발성 API 호출과 달리 에이전트를 영구 객체로 관리하고 세션 단위로 실행하는 구조를 제공한다. 이 글은 Claude Managed Agents 설정 가이드로서, Agent 생성부터 도구 할당, 보안 설정, 스트리밍 실행까지 초기 구성의 전 과정을 Python 코드 기반으로 정리한다.

모든 엔드포인트에는 managed-agents-2026-04-01 베타 헤더가 필요하다. 아직 GA(General Availability)가 아니므로 API 표면이 변경될 수 있다.

직접 구현 에이전트의 구조적 한계

Managed Agents가 왜 필요한지를 이해하려면, 기존에 LLM 에이전트를 직접 구축할 때 어떤 문제가 발생하는지 살펴볼 필요가 있다.

가장 흔한 패턴은 프롬프트·도구 목록·컨텍스트 관리를 애플리케이션 코드에 하드코딩하는 방식이다. 이 경우 다음과 같은 문제가 반복적으로 나타나는 편이다.

문제 영역	증상	근본 원인
버전 관리	프롬프트 변경 시 실행 중인 세션과 충돌	설정과 런타임이 동일 객체
도구 권한	API 키가 코드에 하드코딩	자격증명 분리 계층 부재
상태 유지	대화 히스토리를 DB에 직접 저장·복원	세션 관리 표준 부재
배포	에이전트 설정 변경마다 전체 재배포	설정-코드 결합도 과다

풀스택 관점에서 보면 프론트엔드의 상태 관리(Redux, Zustand)가 “상태”와 “디스패치”를 분리하는 것처럼, 에이전트에도 “설정”과 “실행”을 분리하는 계층이 필요하다는 결론에 도달하게 된다. Managed Agents는 정확히 이 분리를 API 수준에서 제공하는 것이다.

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

Managed Agents의 가장 중요한 설계 원칙은 Agent(영구적·버전 관리되는 설정 객체)와 Session(런타임 인스턴스)의 분리다. Agent는 POST /v1/agents로 1회 생성하고 agent.id를 저장한 뒤, 매 실행마다 POST /v1/sessions로 Session을 만들어 참조하는 구조를 취한다. 각 업데이트는 새로운 불변(immutable) 버전을 생성하며, 실행 중인 Session은 핀(pin)된 버전을 유지하는 방식이다(Managed Agents 아키텍처 개요).

이 구조가 가져다주는 실질적 이점은 크게 세 가지로 요약된다.

첫째, 무중단 설정 변경이 가능해진다. Agent 설정을 업데이트해도 이미 실행 중인 Session은 이전 버전에 핀되어 있으므로 영향을 받지 않는다. 새 Session부터 최신 버전이 적용되는 셈이다.

둘째, 롤백이 단순해진다. 각 업데이트가 불변 버전을 생성하기 때문에, 문제가 발생하면 이전 버전의 Agent ID를 참조하는 Session을 만들면 그만이다.

셋째, 실행 상태 추적이 명확해진다. Session 단위로 대화 히스토리·도구 호출 기록·상태 변화가 캡슐화되므로, 디버깅 시 특정 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_id는 한 번 생성 후 환경 변수나 설정 파일에 저장해두고 재사용한다. Session은 매 실행(요청·작업 단위)마다 새로 생성하는 것이 원칙이다.

## Claude Managed Agents 설정 가이드 — 초기 구성 3단계

Managed Agents 온보딩은 패턴 선택 → 도구 구성 → 환경·세션 설정의 3단계로 구성된다(Managed Agents 온보딩 절차). 각 단계를 순서대로 정리한다.

1단계: 패턴 선택

Managed Agents는 용도에 따라 네 가지 실행 패턴을 제공한다.

• 이벤트 트리거: 웹훅·GitHub 이벤트 등 외부 신호에 반응하여 실행
• 크론(Cron): 정해진 주기로 반복 실행
• 파이어앤포겟 PR: PR 생성 후 에이전트가 자율적으로 코드 리뷰·수정을 진행
• 리서치+대시보드: 정보 수집 후 결과를 구조화하여 반환

풀스택 개발자 관점에서 가장 자주 사용하게 되는 패턴은 이벤트 트리거와 크론이다. CI/CD 파이프라인에 에이전트를 끼워넣거나, 주기적 코드 품질 점검을 자동화하는 데 적합하기 때문이다.

2단계: 도구 구성

도구는 세 가지 종류로 나뉜다.

도구 유형	설명	설정 방법
agent_toolset_20260401	Anthropic 제공 기본 도구 세트	tools 배열에 type 지정
MCP 도구	외부 MCP 서버 연결	MCP 서버 URL + 자격증명
Custom 도구	직접 정의한 함수	스키마 정의 + 결과 반환 핸들링

기본 도구 세트(agent_toolset_20260401)는 파일 읽기·쓰기, 웹 검색, 코드 실행 등 범용 기능을 포함하며, 별도 설정 없이 type만 지정하면 활성화되는 편이다.

3단계: Environment 생성 → Agent 생성 → Session 생성

실제 코드로 보면 이 3단계가 명확하게 드러난다.

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는 외부 네트워크 접근을 허용하는 옵션인데, 프로덕션에서는 필요한 도메인만 허용 목록에 넣는 것이 보안상 바람직하다.

## Python SDK로 스트리밍 세션 구현하기

Agent와 Session을 생성했으면 실제로 메시지를 보내고 응답을 받아야 한다. Python에서는 pip install anthropic으로 SDK를 설치한 뒤 client.beta.sessions.stream()으로 SSE(Server-Sent Events) 이벤트를 수신한다(Python Managed Agents SDK 가이드).

핵심은 stream-first 패턴이다. 스트림을 먼저 열고, 그 안에서 메시지를 보내는 순서가 필수적이다. 스트림을 열기 전에 메시지를 보내면 이벤트를 놓칠 수 있기 때문이다.

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

이 코드의 흐름을 단계별로 분해하면 다음과 같다.

① 스트림 열기: client.beta.sessions.stream()은 컨텍스트 매니저로 SSE 연결을 유지한다. with 블록을 벗어나면 자동으로 연결이 종료되는 구조이다.

② 메시지 전송: events.send()로 사용자 메시지를 보낸다. 이벤트 타입은 user.message이며, content 배열에 텍스트 블록을 담는다.

③ 이벤트 수신: agent.message 이벤트에서 에이전트의 응답 텍스트를 추출한다. flush=True로 버퍼링 없이 실시간 출력하는 것이 스트리밍의 핵심이다.

④ 종료 감지: session.status_terminated 이벤트가 오면 에이전트가 작업을 완료한 것이므로 루프를 탈출한다.

Custom Tool 호출 시 idle 상태 처리

Custom tool을 사용하는 경우, 에이전트가 도구를 호출하면 Session이 idle 상태로 전환된다. 이때 클라이언트 측에서 도구를 실행하고, user.custom_tool_result 이벤트로 결과를 반환해야 에이전트가 다음 단계로 진행하게 된다. 이 패턴은 Function Calling과 유사하지만, 세션 상태 전이가 명시적이라는 차이가 있다.

[클라이언트] ──stream 열기──▶ [Session]
[클라이언트] ──user.message──▶ [Session: running]
[Session] ──tool_call──▶ [Session: idle]
[클라이언트] ──custom_tool_result──▶ [Session: running]
[Session] ──agent.message──▶ [클라이언트]
[Session] ──terminated──▶ [끝]

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

MCP 서버를 에이전트에 연동할 때 가장 흔한 실수는 인증 정보를 에이전트 설정에 직접 넣는 것이다. Managed Agents는 Vault라는 별도의 자격증명 저장소를 제공하며, Session 생성 시 vault_ids로 참조하는 방식을 사용한다. Anthropic이 OAuth 토큰을 자동 갱신해주므로, 토큰 만료에 따른 장애를 예방할 수 있는 구조다.

# 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 설정을 버전 관리 시스템에 저장하거나 팀원과 공유해도 자격증명이 노출되지 않는 셈이다.

### Vault 보안 운영 권장 사항

Vault를 프로덕션에서 운영할 때 빠뜨리기 쉬운 항목이 두 가지 있다.

자격증명 유형 분리: GitHub 토큰, 데이터베이스 커넥션 문자열, 외부 API 키를 하나의 Vault에 몰아넣기보다 용도별로 Vault를 분리하는 것이 권한 관리에 유리하다. Session 생성 시 vault_ids 배열에 필요한 Vault만 선택적으로 포함하면 최소 권한 원칙을 적용할 수 있게 된다.

토큰 갱신 모니터링: Anthropic이 OAuth 토큰을 자동 갱신해주지만, 갱신 실패 시 알림을 받을 수 있는 체계는 아직 공식 문서에 명시되어 있지 않다. 자체적으로 Session 실행 실패율을 모니터링하여 자격증명 문제를 간접적으로 감지하는 방법이 현실적인 대안이다.

Claude Agent SDK와 커스텀 도구 확장

Managed Agents가 서버 측 에이전트 관리라면, Claude Agent SDK(pip install claude-agent-sdk, Python 3.10+ 필요)는 클라이언트 측에서 도구를 정의하고 에이전트를 제어하는 레이어에 해당한다(Claude Agent SDK Python 저장소). query() 함수로 단순 비동기 질의를, ClaudeSDKClient로 양방향 대화를 지원하는 구조이다.

특히 @tool 데코레이터로 인프로세스 MCP 서버를 만들 수 있다는 점이 풀스택 개발자에게 유용하다. 외부 MCP 서버를 별도 프로세스로 띄울 필요 없이, Python 함수를 바로 도구로 노출하는 방식이기 때문이다.

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]
)

@tool 데코레이터의 인자는 순서대로 도구 이름, 설명, 파라미터 스키마다. 반환값은 MCP 프로토콜의 content 배열 형식을 따르며, 텍스트 블록 외에도 이미지·파일 등 다양한 타입을 지원한다.

Hooks 시스템으로 도구 실행 권한 제어

Agent SDK는 Hooks 시스템을 제공하여 도구 실행을 가로채고 권한을 제어할 수 있다. PreToolUse 훅을 사용하면 특정 도구 호출 전에 검증 로직을 삽입하는 것이 가능해진다. 예를 들어, 파일 쓰기 도구가 특정 디렉토리 외부에 접근하려 하면 차단하는 식의 가드레일을 구현할 수 있다.

이 방식은 Managed Agents의 Vault 보안과 상호 보완적인 관계에 있다. Vault가 “어떤 자격증명에 접근할 수 있는가”를 제어한다면, Hooks는 “어떤 행동을 할 수 있는가”를 제어하는 것이다.

보안 계층	제어 대상	구현 위치
Vault	자격증명 접근 범위	서버(Anthropic)
Hooks(PreToolUse)	도구 실행 허용 여부	클라이언트(SDK)
Environment networking	네트워크 접근 범위	서버(Anthropic)

세 계층을 조합하면 에이전트의 행동 반경을 상당히 정밀하게 제한할 수 있다. 보안 사고는 대부분 단일 계층 의존에서 발생하므로, 다중 방어선을 구성하는 편이 현실적이다. 두 도구의 정확한 관계·차이점은 공식 문서에 명시되어 있지 않으며, 현재까지 파악된 바로는 Managed Agents가 서버 사이드 에이전트 라이프사이클 관리를 담당하고 Agent SDK가 클라이언트 사이드 도구 정의·대화 제어를 담당하는 구조이나, 향후 통합 방향은 불분명하다.

현재 한계점과 프로덕션 적용 시 고려사항

Managed Agents는 아직 베타 단계이며, 프로덕션에 도입하기 전에 몇 가지 한계를 인지해야 한다. 특히 공식 문서에서 확인이 불가한 영역이 존재하므로 솔직하게 정리한다.

요금 체계가 불투명하다. 세션당 비용, 컨테이너 시간 과금 등 구체적인 요금 구조가 공식 문서에 명시되어 있지 않다. 대규모 트래픽을 처리하는 서비스에 에이전트를 투입할 경우, 비용 예측이 어려운 상태이므로 소규모 파일럿부터 시작하는 것이 현실적인 접근이다.

모니터링·알림 가이드가 부재하다. 에이전트의 세션 실패율, 도구 호출 에러율, 응답 지연 등을 추적하는 공식 모니터링 가이드가 존재하지 않는다. 자체적으로 Session 이벤트 로그를 수집하고 Prometheus/Grafana 같은 도구로 대시보드를 구성하는 방법이 필요하게 된다.

공식 문서 진입점이 분산되어 있다. docs.anthropic.com이 code.claude.com과 platform.claude.com으로 분산 리다이렉트되어 단일 진입점이 불명확한 상태다. 특정 API 명세를 찾을 때 여러 도메인을 오가야 하는 경우가 있다.

Agent SDK와의 통합 경로가 불분명하다. 앞서 언급했듯이 Managed Agents(서버 사이드)와 Agent SDK(클라이언트 사이드)의 정확한 관계가 공식 문서에 명시되지 않았다. 두 도구를 함께 사용할 때의 권장 아키텍처나 통합 패턴에 대한 가이드가 필요한 상황인데, 현재로서는 커뮤니티 레벨의 경험에 의존할 수밖에 없다.

프로덕션 체크리스트

현시점에서 Managed Agents를 프로덕션에 적용한다면 최소한 다음 항목을 점검해야 한다.

• Environment의 networking을 unrestricted에서 허용 목록 기반으로 전환
• Vault를 용도별로 분리하고, archive 권한을 가진 API 키를 별도 관리
• Session 이벤트 로그를 외부 로깅 시스템으로 전송하는 파이프라인 구축
• Custom tool의 에러 핸들링 및 타임아웃 설정 (idle 상태가 무한히 지속되지 않도록)
• 베타 API 변경에 대비한 SDK 버전 핀닝 및 변경 로그 구독

설정 구성 전체 흐름 정리와 다음 단계

Claude Managed Agents 설정 가이드의 전체 흐름은 아래 시퀀스를 따른다.

flowchart TD
    A[패턴 선택] --> B[도구 구성]
    B --> C[Environment 생성]
    C --> D[Agent 생성]
    D --> E[Vault 자격증명 저장]
    E --> F[Session 생성 + vault_ids]
    F --> G[stream-first 패턴으로 실행]
    G --> H{Custom tool 호출?}
    H -->|Yes| I[idle → tool_result 반환]
    H -->|No| J[agent.message 수신]
    I --> J
    J --> K[terminated → 종료]

이 흐름에서 Agent 생성은 1회성이고, Session 생성 → 실행 → 종료가 반복되는 구간이라는 점이 설계의 핵심이다. Agent를 수정하면 새 불변 버전이 생성되지만, 기존 Session은 이전 버전에 핀된 채 정상 동작하므로 운영 중 안전하게 설정을 변경할 수 있는 구조인 셈이다.

Managed Agents는 베타 단계의 한계에도 불구하고 에이전트 개발의 방향성을 구체적으로 제시한다. 설정과 런타임의 분리, 자격증명의 Vault 격리, 불변 버전 관리는 에이전트 시스템이 프로덕션 수준으로 성숙하기 위한 전제 조건이다. 단, 요금 체계와 모니터링 인프라가 명확해지기 전까지는 미션 크리티컬한 워크로드보다 내부 도구 자동화, 코드 리뷰 보조, 문서 생성 같은 보조적 영역에 먼저 적용하는 것이 현실적이다.

다음 단계로는 Claude MCP 서버 연동 실전 패턴을 깊이 다루는 것이 자연스럽다. Vault와 MCP를 결합하면 에이전트가 GitHub·Slack·데이터베이스 등 외부 시스템과 안전하게 상호작용하는 구조를 만들 수 있다. 또한 Claude 에이전트 세션 관리 전략 — 장시간 실행 세션의 타임아웃 처리, 세션 간 컨텍스트 공유 방법 등 — 도 프로덕션에서 반드시 다뤄야 할 Claude Managed Agents 설정 가이드의 확장 주제다.

관련 글

• Claude Managed Agents 구축 7단계 — SDK 설치·MCP·비용 최적화 완전 가이드 – Claude Managed Agents를 프로덕션에 투입하기 위한 단계별 가이드. SDK 설치, 에이전트 옵션 설정, 커스텀 도구 구축, …
• Claude Managed Agents API Python SDK 완전 가이드 — 에이전트 생성부터 스트리밍까지 7단계 – Anthropic의 Claude Managed Agents API를 Python SDK로 다루는 전체 흐름을 정리한다. 에이전트 생성, E…
• Claude Code LSP 설정 완전 가이드 — TypeScript·Python 언어 서버 5단계 연동 – Claude Code에서 LSP를 설정하면 코드 컨텍스트 파악 정확도가 올라가고 토큰 소비가 줄어든다. TypeScript와 Python …