Claude Sonnet 5로 Claude Managed Agent 만드는 방법

Python 스크립트에서 Claude Code 스타일의 워크플로를 실행해 보고 싶었던 적이 있나요? 모델이 도구, 파일, 스킬, 지침에 접근할 수 있는 관리형 환경에서 작업하도록 말이죠.

Claude Managed Agent는 이러한 워크플로를 위해 설계되었으며, 통제된 환경에서 여러 단계를 거치는 작업을 수행할 수 있는 에이전트를 만들도록 도와줍니다.

이 튜토리얼에서는 Claude Sonnet 5를 사용하는 방법을 보여드립니다. 이는 고급 추론, 코딩, 데이터 분석 작업을 위해 Anthropic이 설계한 최신 모델로, 데이터 점검, 도구 사용, 코드 작성 및 실행, 구조화된 출력 생성 기능을 에이전트에 제공합니다.

Managed Agent를 만들고 환경을 구성한 뒤, CSV 파일을 업로드하고 에이전트에 도구 및 XLSX 스킬 접근 권한을 부여하겠습니다. 

에이전트는 데이터를 분석하고 Python, JSON, Excel 파일을 생성한 후 결과를 검증하고, 완성된 출력을 다운로드할 수 있도록 제공합니다.

Claude가 완전히 처음이라면 먼저 Claude Code 101 코스를 확인하는 것을 권합니다.

Claude Managed Agent란?

Claude Managed Agents는 Anthropic의 관리형 프레임워크로, Claude를 자율 에이전트로 실행할 수 있게 합니다. 

프롬프트 전송, 도구 호출 실행, 결과 저장, 런타임 관리 루프를 직접 작성하는 대신 에이전트를 정의하면 Anthropic이 해당 인프라를 관리합니다. 

이 기능은 작업을 완료하기 전에 모델이 여러 도구를 사용해야 할 수 있는, 더 길고 다단계인 작업에 적합합니다.

Managed Agent는 크게 네 가지 구성 요소로 이루어져 있습니다:

• Agent: 모델, 시스템 프롬프트, 도구, MCP 서버, 스킬을 포함하는 재사용 가능한 구성입니다.
• Environment: 에이전트가 실행되는 위치로, Anthropic의 클라우드 샌드박스 또는 자체 호스팅 샌드박스를 사용할 수 있습니다.
• Session: 특정 작업을 수행하는 에이전트의 실행 인스턴스입니다.
• Events: 세션 실행 중에 교환되는 메시지, 도구 호출, 결과, 상태 업데이트입니다.

1. Claude 에이전트 작업공간 준비 사항

이 튜토리얼을 따라 하려면 컴퓨터에 Python 3.12 이상과 Jupyter Notebook을 설치하세요. Jupyter Notebook에서 Managed Agent를 단계별로 만들고 실행하며 확인하겠습니다.

또한 Anthropic Console 계정이 필요합니다. 

Console에서 새 API 키를 만들고 최소 $5의 API 크레딧을 추가한 후 키를 안전하게 보관하세요. 

Managed Agent는 하나의 세션에서 여러 번 모델과 도구를 호출할 수 있으므로 표준 API 요청보다 비용이 더 들 수 있습니다.

키는 노트북에 직접 추가하거나 GitHub에 커밋하지 말고 ANTHROPIC_API_KEY 환경 변수로 저장하세요.

macOS, Linux, WSL에서는 터미널에서 다음을 실행하세요:

export ANTHROPIC_API_KEY="your-api-key-here"

Windows PowerShell에서는 다음을 사용하세요:

$env:ANTHROPIC_API_KEY="your-api-key-here"

2. Anthropic Python SDK 설정

Managed Agent를 만들기 전에 공식 Anthropic Python SDK를 설치하고 이 노트북에 필요한 모듈을 임포트합니다. 

SDK는 Anthropic 클라이언트를 제공하며, 이를 사용해 에이전트, 환경, 파일, 세션을 생성합니다. 

%pip install -q --upgrade anthropic

다음으로 환경 변수에서 Anthropic API 키를 로드합니다. 

특히 프로젝트를 공유하거나 GitHub에 올릴 계획이라면, 키를 코드에 직접 넣는 것보다 노트북 밖에서 관리하는 편이 더 안전합니다.

import os
from anthropic import Anthropic

api_key = os.environ.get("ANTHROPIC_API_KEY")
assert api_key, "Set ANTHROPIC_API_KEY in your environment or in a local .env file."

현재 Managed Agent는 Anthropic의 베타 API를 통해 접근합니다. managed-agents-2026-04-01 베타 플래그가 이 기능을 활성화하지만, 공식 SDK는 Managed Agent 요청에 필요한 베타 헤더를 자동으로 전송합니다. 

이 플래그는 이후 세션 파일을 나열하고 다운로드할 때 필요하므로 노트북에 유지합니다. 

BETA_FLAG = "managed-agents-2026-04-01"

client = Anthropic(api_key=api_key)

마지막으로, 튜토리얼 동안 생성되는 모든 리소스의 ID를 저장할 딕셔너리를 만듭니다. 

여기에는 에이전트, 환경, 업로드된 파일, 세션이 포함됩니다. 이러한 ID를 저장해 두면 중간 단계가 실패하더라도 마지막에 정리하기가 수월합니다.

created = {"agent": None, "environment": None, "file": None, "session": None}
print("✓ Anthropic client initialized.")

이제 클라이언트가 준비되었습니다. 

3. Managed Agent 생성

Managed Agent는 워크플로를 위한 재사용 가능한 구성입니다. 

생성 시 Claude 모델을 선택하고, 역할과 지침을 정의하는 시스템 프롬프트를 작성하며, 사용할 도구와 스킬을 연결합니다. 

이렇게 만들어 둔 에이전트는 매번 구성을 새로 만들지 않고 여러 세션에서 재사용할 수 있습니다. 

에이전트 이름은 Sonnet 5 Data Analyst로 하고 claude-sonnet-5를 사용하겠습니다. 

시스템 프롬프트는 세심한 데이터 분석가처럼 행동하라고 지시합니다. /workspace에 마운트된 파일을 점검하고, 코드 실행으로 분석하며, 결과를 간결하게 수치로 보고하고, 최종 파일은 /mnt/session/outputs에 저장하도록 합니다.

agent = client.beta.agents.create(
    name="Sonnet 5 Data Analyst",
    model="claude-sonnet-5",
    system=(
        "You are a meticulous data analyst. When asked about data, always read the "
        "file mounted at /workspace, analyse it with the code execution tool, and "
        "report concise, numeric results. Use the XLSX skill for spreadsheet work. "
        "Save final artifacts to /mnt/session/outputs."
    ),
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
    skills=[{"type": "anthropic", "skill_id": "xlsx"}],
)

agent_toolset_20260401는 세션에서 Anthropic의 기본 제공 도구에 접근할 수 있게 하며, xlsx 스킬은 Excel 워크북 생성 및 분석에 대한 작업별 가이드를 제공합니다. 

Anthropic은 PowerPoint, Word, PDF 워크플로용 사전 구축 스킬도 제공합니다.

마지막으로 에이전트 ID를 저장합니다. 

이 ID는 나중에 세션 생성 시 사용하며, 튜토리얼이 끝난 후 정리 단계에서 에이전트를 보관(archive)하는 데도 필요합니다.

created["agent"] = agent.id
print(f"✓ Created agent: {agent.id}")

다음과 유사한 출력이 보여야 합니다:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Anthropic 클라우드 샌드박스 구성

이제 세션 동안 Managed Agent가 실행될 환경을 생성하겠습니다. 

환경은 보안 샌드박스로 작동하며, 에이전트에 별도의 작업공간을 제공하여 마운트된 파일을 읽고, 코드를 작성하고, 명령을 실행할 수 있게 합니다.

제한된 네트워킹이 적용된 Anthropic의 클라우드 환경을 사용하겠습니다. 에이전트는 이후 이 샌드박스를 사용해 업로드된 CSV 파일을 Python으로 분석합니다.

environment = client.beta.environments.create(
    name="code-exec-sandbox",
    config={"type": "cloud", "networking": {"type": "limited"}},
)

created["environment"] = environment.id
print(f"✓ Created environment: {environment.id}")

셀을 실행하면 다음과 유사한 환경 ID가 표시됩니다:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Anthropic Files API로 데이터 업로드

다음으로 에이전트가 분석할 데이터셋을 업로드합니다. 

Managed Agent는 Anthropic의 Files API를 사용해 로컬 파일을 업로드하고, 이 파일을 세션 환경 내부에 마운트할 수 있습니다.

이 가이드에서는 예시로 12행짜리 데이터셋 sales_data.csv를 사용합니다. 

업로드 전에 파일이 존재하는지 확인하고, 예상한 데이터 행 수가 포함되어 있는지 점검합니다.

from pathlib import Path

csv_path = Path("sales_data.csv")
assert csv_path.exists(), f"Missing input file: {csv_path.resolve()}"

row_count = sum(1 for _ in csv_path.open(encoding="utf-8")) - 1
assert row_count == 12, f"Expected 12 data rows, found {row_count}"

그런 다음 파일을 업로드하고, 이후 정리를 위해 해당 ID를 저장합니다.

uploaded = client.beta.files.upload(file=csv_path)

created["file"] = uploaded.id
print(f"✓ Uploaded {csv_path}: {uploaded.id} ({row_count} rows)")

셀을 실행하면 다음과 유사한 출력이 표시됩니다:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. 에이전트 실행 세션 초기화

이제 세션을 생성하겠습니다. 

세션은 특정 작업에 필요한 에이전트, 환경, 리소스를 연결합니다. 여기서는 업로드된 CSV 파일을 /workspace/sales_data.csv로 마운트하여 에이전트가 샌드박스 내부에서 접근할 수 있도록 합니다.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": uploaded.id,
            "mount_path": "/workspace/sales_data.csv",
        },
    ],
)

created["session"] = session.id
print(f"✓ Created session: {session.id}")

다음과 유사한 세션 ID가 표시됩니다:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. 에이전트 응답 스트리밍

이제 작업을 세션에 전송하고, 에이전트가 작업하는 동안의 활동을 스트리밍으로 확인합니다. 

세션을 생성하는 것만으로는 에이전트와 샌드박스가 준비될 뿐이며, 에이전트는 user.message 이벤트를 받은 후에 작업을 시작합니다. 

이벤트 스트림을 통해 에이전트의 메시지, 도구 호출, 최종 세션 상태를 실시간으로 확인할 수 있습니다. 

프롬프트는 에이전트에게 마운트된 CSV 파일을 분석하고, Python 스크립트를 작성 및 실행하며, JSON 요약을 만들고, Excel 보고서를 생성하라고 지시합니다. 

또한 에이전트의 텍스트, 사용한 도구 기록, 세션이 성공적으로 종료되었는지 여부를 수집할 세 변수를 만듭니다.

agent_text_parts = []
tools_used = []
final_status = None

with client.beta.sessions.events.stream(session.id) as stream:
    # Send the user message once the stream is open.
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": (
                            "Use the XLSX skill and analyze /workspace/sales_data.csv. "
                            "Write /mnt/session/outputs/analyze_sales.py, run that Python "
                            "script, and have it create /mnt/session/outputs/summary.json. "
                            "Also create /mnt/session/outputs/sales_report.xlsx with the "
                            "source data, monthly profit, and a summary sheet."
                        ),
                    }
                ],
            }
        ],
    )

    for event in stream:
        etype = getattr(event, "type", None)

        if etype == "agent.message":
            for block in event.content:
                txt = getattr(block, "text", None)
                if txt:
                    print(txt, end="")
                    agent_text_parts.append(txt)

        elif etype == "agent.tool_use":
            name = getattr(event, "name", "<tool>")
            print(f"\n[tool_use] {name}")
            tools_used.append(name)

        elif etype == "session.status_idle":
            final_status = "idle"
            print("\n\n✓ Agent finished; session is idle.")
            break

        elif etype == "session.status_error":
            final_status = "error"
            print("\n✗ Session reported an error.")
            break

print("Tools used:", tools_used)

실행 중에는 read, bash, write, edit 등의 도구 이벤트를 볼 수 있습니다. 

이는 에이전트가 사용 가능한 지침과 파일을 점검하고, 분석 스크립트를 작성해 샌드박스에서 실행하며, 발견한 문제를 수정하고 있음을 보여줍니다.

에이전트가 더 이상 수행할 작업이 없으면 세션은 유휴 상태가 됩니다. 이 예시에서는 session.status_idle이 작업 완료를 나타내므로 스트림 수신을 중지합니다. 

Anthropic은 샌드박스 내 기본 제공 도구의 실행을 관리합니다. 사용자 지정 도구를 사용하는 경우에만 도구 결과를 직접 처리하면 됩니다. 

8. 생성된 파일과 이벤트 기록 가져오기

세션이 완료되면 저장된 이벤트 기록을 확인하고 에이전트가 생성한 파일을 다운로드할 수 있습니다. 

이벤트 기록에는 모델 요청, 도구 호출, 도구 결과, 상태 변경 등 세션의 전체 기록이 포함됩니다.

history = client.beta.sessions.events.list(session.id, order="asc")

print("--- Session event history ---")
for event in history.data:
    print(event.type)

print(f"({len(history.data)} events total)")

다음으로 세션에 첨부된 파일을 나열하고 다운로드 가능 표시가 된 파일을 모두 내려받습니다. 파일은 로컬 outputs 폴더에 저장됩니다.

import os

os.makedirs("outputs", exist_ok=True)

files = client.beta.files.list(scope_id=session.id, betas=[BETA_FLAG])
downloadable = [f for f in files.data if f.downloadable]

print(f"Found {len(downloadable)} downloadable file(s) for this session.")

downloaded_paths = []

for f in downloadable:
    try:
        content = client.beta.files.download(f.id, betas=[BETA_FLAG])
        local_path = os.path.join("outputs", f.filename)

        content.write_to_file(local_path)
        downloaded_paths.append(local_path)

        print(f"  downloaded {f.id} -> {local_path}")
    except Exception as exc:
        print(f"  skip {f.id}: {exc}")

마지막으로 예상한 모든 출력이 성공적으로 다운로드되었는지 확인합니다:

expected_outputs = {"analyze_sales.py", "summary.json", "sales_report.xlsx"}
downloaded_names = {os.path.basename(path) for path in downloaded_paths}

assert expected_outputs <= downloaded_names, (
    f"Missing expected outputs: {sorted(expected_outputs - downloaded_names)}"
)

이제 생성된 Python 스크립트, JSON 요약, Excel 보고서를 로컬 outputs 폴더에서 확인할 수 있습니다.

9. Python, JSON, Excel 출력 분석

에이전트가 작업을 완료하면 생성된 파일이 로컬 outputs/ 디렉터리로 다운로드됩니다. 

이 파일들은 단순히 텍스트 응답을 반환한 것을 넘어, 에이전트가 코드를 작성·실행하고, 구조화된 데이터를 만들며, 독립적으로 검토할 수 있는 스프레드시트 보고서를 생성했음을 보여줍니다.

아래 스크린샷은 생성된 세 가지 산출물을 보여줍니다.

이 파일에는 에이전트가 작성하고 실행한 분석 코드가 담겨 있어, 워크플로를 재현 가능하고 점검하기 쉽게 합니다.

이 파일은 결과를 구조화된 형식으로 저장하며, 대시보드, API 또는 다른 프로그램에서 활용할 수 있습니다.

이 Excel 파일은 매출, 비용, 이익, 마진, 합계, 차트를 포함한 월별 계산을 시각적으로 제공합니다.

sales_data.csv의 12행에 대한 검증된 결과는 다음과 같습니다:

• 총 매출: $32,900
• 총 비용: $14,750
• 총 이익: $18,150
• 월평균 이익: $1,512.50
• 최고의 달: 12월($2,550 이익)
• 최저의 달: 1월($400 이익)

워크북은 하드코딩된 값에만 의존하지 않고 수식 중심으로 구성되어 있습니다. 

실행 중 에이전트는 첨부된 XLSX 스킬 지침을 읽고 워크북을 생성한 뒤, LibreOffice로 재계산하고 수식을 점검했으며, 완료 전에 순환 참조 문제를 수정했습니다.

10. Managed Agent API 리소스 정리

Managed Agent 리소스는 제거할 때까지 남아 있으므로 작업이 완료되면 정리하는 것이 중요합니다. 

특히 실행 중인 세션과 환경은 계속 실행 상태로 두면 비용이 발생할 수 있습니다.

세션은 삭제 전에 유휴 상태여야 합니다. 

마지막 단계에서는 세션, 업로드된 파일, 환경을 삭제하고 에이전트를 보관(archive)합니다. 

정리 작업은 각각 헬퍼 함수로 감싸, 하나의 삭제가 실패하더라도 나머지 리소스 삭제가 중단되지 않도록 합니다.

def safe(label, fn):
    try:
        fn()
        print(f"✓ deleted {label}")
    except Exception as exc:
        print(f"· could not delete {label}: {exc}")

if created["session"]:
    safe("session", lambda: client.beta.sessions.delete(created["session"]))

if created["file"]:
    safe("file", lambda: client.beta.files.delete(created["file"]))

if created["environment"]:
    safe("environment", lambda: client.beta.environments.delete(created["environment"]))

if created["agent"]:
    safe("agent (archived)", lambda: client.beta.agents.archive(created["agent"]))

print("\n🎉 Cleanup complete. The agent is archived; other resources were deleted.")

다음과 유사한 출력이 표시됩니다:

✓ deleted session
✓ deleted file
✓ deleted environment
✓ deleted agent (archived)

🎉 Cleanup complete. The agent is archived; other resources were deleted.

노트북, 샘플 CSV 파일, 설정 안내를 포함한 전체 프로젝트는 GitHub에서 확인할 수 있습니다. 

해당 리포지토리를 클론해 노트북을 다시 실행하면 이 가이드의 결과를 재현할 수 있습니다.

마무리 생각

Claude Managed Agent는 설정과 사용이 쉽다고 느꼈습니다. 

에이전트를 만들고, 필요한 도구와 스킬, 샌드박스를 제공한 다음, 세션을 통해 실행하면 됩니다. 

그다음에는 코드 작성, 파일 생성, 자체 출력 점검, 최종 결과 반환 같은 전체 워크플로를 처리할 수 있습니다.

처음에는 더 유연한 외부 환경을 원해 Modal Sandbox를 사용해 보려 했습니다. 

하지만 이 가이드의 범위를 벗어날 만큼 설정이 복잡해져, 이번 프로젝트는 Anthropic의 관리형 클라우드 샌드박스에 집중하기로 했습니다.

아쉬운 점은 비용이었습니다. 12행짜리 작은 CSV 파일로 이 예시를 두 번 실행했는데, 비용이 약 $0.25 정도 들었습니다. 

대시보드에는 모델 항목으로 비용이 표시되었지만, 상세 내역은 찾을 수 없었습니다. 단순 계산과 스프레드시트 작업치고는, 비용이 더 낮은 오픈소스 대안과 비교해 다소 비싸게 느껴졌습니다.

전반적으로, 이 프로젝트는 Managed Agent의 전체 워크플로를 보여줍니다. 에이전트 생성, CSV 파일 업로드, 관리형 샌드박스에서 Python 실행, JSON과 Excel 보고서 생성, 출력 검증, 파일 다운로드, 사후 리소스 정리까지 모두 다룹니다.