빠른 시작

빌드시작하기

Claude Managed Agents 시작하기

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

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

핵심 개념

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	Configuration for where sessions run: an Anthropic-managed cloud container, or a self-hosted sandbox on your own infrastructure
Session	A running agent instance within an environment, performing a specific task and generating outputs
Events	Messages exchanged between your application and the agent (user turns, tool results, status updates)

사전 요구 사항

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-7}' \ --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:
    # Send the user message after the stream opens
    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",
                    },
                ],
            },
        ],
    )

    # Process streaming events
    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 이벤트를 발생시킵니다.

다음 단계

에이전트 정의

재사용 가능한 버전 관리 에이전트 구성 만들기

환경 구성

네트워킹 및 컨테이너 설정 사용자 지정

에이전트 도구

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

이벤트 및 스트리밍

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

Was this page helpful?

빌드시작하기

Claude Managed Agents 시작하기

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

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

핵심 개념

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	Configuration for where sessions run: an Anthropic-managed cloud container, or a self-hosted sandbox on your own infrastructure
Session	A running agent instance within an environment, performing a specific task and generating outputs
Events	Messages exchanged between your application and the agent (user turns, tool results, status updates)

사전 요구 사항

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-7}' \ --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:
    # Send the user message after the stream opens
    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",
                    },
                ],
            },
        ],
    )

    # Process streaming events
    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 이벤트를 발생시킵니다.

다음 단계

에이전트 정의

재사용 가능한 버전 관리 에이전트 구성 만들기

환경 구성

네트워킹 및 컨테이너 설정 사용자 지정

에이전트 도구

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

이벤트 및 스트리밍

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

Was this page helpful?