Managed Agents첫 단계

Claude Managed Agents 시작하기

첫 번째 자율 에이전트를 만들어 보세요.

이 가이드는 에이전트 생성, 환경 설정, 세션 시작, 에이전트 응답 스트리밍 과정을 안내합니다.

대화형 안내를 선호하시나요? 최신 버전의 Claude Code에서 /claude-api managed-agents-onboard를 실행하면 단계별 설정 안내와 대화형 질의응답을 이용할 수 있습니다.

핵심 개념

개념	설명
Agent	모델, 시스템 프롬프트, 도구, MCP 서버 및 스킬
Environment	세션이 실행되는 위치에 대한 구성: Anthropic이 관리하는 클라우드 샌드박스 또는 자체 인프라에서 호스팅하는 샌드박스
Session	환경 내에서 실행 중인 에이전트 인스턴스로, 특정 작업을 수행하고 출력을 생성함
Events	애플리케이션과 에이전트 간에 교환되는 메시지(사용자 턴, 도구 결과, 상태 업데이트)

사전 요구 사항

Anthropic Console 계정
API 키

CLI 설치

설치를 확인하세요:

ant --version

SDK 설치

API 키를 환경 변수로 설정하세요:

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

첫 번째 세션 만들기

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

에이전트 생성
모델, 시스템 프롬프트, 사용 가능한 도구를 정의하는 에이전트를 생성하세요.
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
agent_toolset_20260401 도구 타입은 사전 구축된 에이전트 도구 전체 세트(bash, 파일 작업, 웹 검색 등)를 활성화합니다. 전체 목록과 도구별 구성 옵션은 도구를 참조하세요.
반환된 agent.id를 저장하세요. 생성하는 모든 세션에서 이를 참조하게 됩니다.
환경 생성
환경은 에이전트가 실행되는 샌드박스를 정의합니다.
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
반환된 environment.id를 저장하세요. 생성하는 모든 세션에서 이를 참조하게 됩니다.
클라우드 샌드박스 대신 자체 인프라에서 샌드박스를 실행하려면 자체 호스팅 샌드박스를 참조하세요.

세션 시작

에이전트와 환경을 참조하는 세션을 생성하세요.

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

print(f"Session ID: {session.id}")

메시지 전송 및 응답 스트리밍

스트림을 열고 사용자 이벤트를 전송한 다음, 도착하는 이벤트를 처리하세요:

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": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.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[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

에이전트는 Python 스크립트를 작성하고, 샌드박스에서 실행한 다음, 출력 파일이 생성되었는지 확인합니다. 출력은 다음과 유사합니다:

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

작동 방식

사용자 이벤트를 전송하면 Claude Managed Agents는 다음을 수행합니다:

샌드박스 프로비저닝: 환경 구성에 따라 샌드박스가 구축되는 방식이 결정됩니다.
에이전트 루프 실행: Claude가 메시지를 기반으로 사용할 도구를 결정합니다.
도구 실행: 파일 쓰기, bash 명령 및 기타 도구 호출이 샌드박스 내에서 실행됩니다.
이벤트 스트리밍: 에이전트가 작업하는 동안 실시간 업데이트를 받습니다.
유휴 상태 전환: 에이전트는 더 이상 수행할 작업이 없을 때 session.status_idle 이벤트를 내보냅니다.

다음 단계

에이전트 정의

재사용 가능하고 버전 관리되는 에이전트 구성 만들기

환경 구성

네트워킹 및 샌드박스 설정 사용자 지정

에이전트 도구

에이전트에 특정 도구 활성화

세션 이벤트 스트림

이벤트 처리 및 실행 중 에이전트 조정

예약된 배포

반복되는 cron 일정으로 에이전트 실행

Was this page helpful?

핵심 개념

개념	설명
Agent	모델, 시스템 프롬프트, 도구, MCP 서버 및 스킬
Environment	세션이 실행되는 위치에 대한 구성: Anthropic이 관리하는 클라우드 샌드박스 또는 자체 인프라에서 호스팅하는 샌드박스
Session	환경 내에서 실행 중인 에이전트 인스턴스로, 특정 작업을 수행하고 출력을 생성함
Events	애플리케이션과 에이전트 간에 교환되는 메시지(사용자 턴, 도구 결과, 상태 업데이트)

첫 번째 세션 만들기

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

에이전트 생성
모델, 시스템 프롬프트, 사용 가능한 도구를 정의하는 에이전트를 생성하세요.
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
agent_toolset_20260401 도구 타입은 사전 구축된 에이전트 도구 전체 세트(bash, 파일 작업, 웹 검색 등)를 활성화합니다. 전체 목록과 도구별 구성 옵션은 도구를 참조하세요.
반환된 agent.id를 저장하세요. 생성하는 모든 세션에서 이를 참조하게 됩니다.
환경 생성
환경은 에이전트가 실행되는 샌드박스를 정의합니다.
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
반환된 environment.id를 저장하세요. 생성하는 모든 세션에서 이를 참조하게 됩니다.
클라우드 샌드박스 대신 자체 인프라에서 샌드박스를 실행하려면 자체 호스팅 샌드박스를 참조하세요.

세션 시작

에이전트와 환경을 참조하는 세션을 생성하세요.

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

print(f"Session ID: {session.id}")

메시지 전송 및 응답 스트리밍

스트림을 열고 사용자 이벤트를 전송한 다음, 도착하는 이벤트를 처리하세요:

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": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.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[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

에이전트는 Python 스크립트를 작성하고, 샌드박스에서 실행한 다음, 출력 파일이 생성되었는지 확인합니다. 출력은 다음과 유사합니다:

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

작동 방식

사용자 이벤트를 전송하면 Claude Managed Agents는 다음을 수행합니다:

샌드박스 프로비저닝: 환경 구성에 따라 샌드박스가 구축되는 방식이 결정됩니다.

에이전트 루프 실행: Claude가 메시지를 기반으로 사용할 도구를 결정합니다.

도구 실행: 파일 쓰기, bash 명령 및 기타 도구 호출이 샌드박스 내에서 실행됩니다.

이벤트 스트리밍: 에이전트가 작업하는 동안 실시간 업데이트를 받습니다.

유휴 상태 전환: 에이전트는 더 이상 수행할 작업이 없을 때 session.status_idle 이벤트를 내보냅니다.

핵심 개념

사전 요구 사항

CLI 설치

SDK 설치

첫 번째 세션 만들기

작동 방식

다음 단계

핵심 개념

사전 요구 사항

CLI 설치

SDK 설치

첫 번째 세션 만들기

작동 방식

다음 단계

핵심 개념

사전 요구 사항

CLI 설치

SDK 설치

첫 번째 세션 만들기

작동 방식

다음 단계

핵심 개념

사전 요구 사항

CLI 설치

SDK 설치

첫 번째 세션 만들기

작동 방식

다음 단계