Claude Platform Docs
Managed Agents시작하기

Claude Managed Agents 시작하기

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

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

Claude Code

Claude Code가 에이전트를 대신 설정하도록 하세요

/claude-api managed-agents-onboard

핵심 개념

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

시작하기 전에

  1. Claude Console 계정 만들기

    Claude Console 계정에 가입하거나 기존 계정으로 로그인하세요.

  2. 인증 방법 선택하기

    로컬 개발에는 CLI로 로그인하는 것을 권장합니다.

    CLIAPI 키
  1. CLI 설치하기

    brew install anthropics/tap/ant
  2. 로그인하기

    ant auth login

    로그인이 완료되면 SDK와 CLI가 자격 증명을 자동으로 가져옵니다.

SDK 설치

pip install anthropic

첫 번째 세션 만들기

  1. 에이전트 생성

    모델, 시스템 프롬프트, 사용 가능한 도구를 정의하는 에이전트를 생성하세요.

    ant apply coding-assistant.md
    coding-assistant.md
    ---
    name: Coding Assistant
    model: claude-opus-5-5
    tools:
      - type: agent_toolset_20260401
        configs:
          - name: web_search
            enabled: false
          - name: web_fetch
            enabled: false
    ---
    
    You are a helpful coding assistant. Write clean, well-documented code.

    ant apply는 에이전트의 ID를 출력하고 claude-lock.json에 기록합니다. 생성하는 모든 세션에서 이 값을 참조하게 됩니다.

    agent_toolset_20260401 도구 유형은 사전 구축된 에이전트 도구(bash, 파일 작업, 웹 검색 등)를 활성화합니다. 이 가이드의 작업인 짧은 Python 스크립트 작성에는 웹을 사용하지 않으므로, 이 예제에서는 웹 검색과 웹 가져오기를 비활성화합니다. 에이전트에는 필요한 도구만 부여하세요. 전체 목록과 도구별 구성 옵션은 도구를 참조하세요.

  2. 환경 생성

    환경은 에이전트가 실행되는 sandbox(샌드박스)를 정의합니다. 이 환경은 패키지 관리자가 허용된 limited 네트워킹을 사용하므로, 샌드박스에서 실행되는 코드가 공개 패키지 레지스트리 및 코드 호스트에 접근할 수 있습니다. 웹 검색과 웹 가져오기는 샌드박스 외부에서 실행되지만, limited 네트워킹에서는 allowed_hosts 목록이 이들에도 적용됩니다. 이 환경처럼 호스트가 하나도 나열되어 있지 않으면, 이 도구들은 페이지나 검색 결과를 반환하지 않습니다. 직접 만드는 에이전트가 이 도구들을 사용하는 경우, 필요한 호스트를 해당 목록에 추가하세요.

    ant apply environment.yaml
    environment.yaml
    # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
    name: quickstart-env
    config:
      type: cloud
      networking:
        type: limited
        allow_package_managers: true

    ant apply는 환경의 ID도 claude-lock.json에 기록합니다. 하나의 명령으로 에이전트와 환경을 함께 생성하려면 두 파일을 모두 전달하세요: ant apply coding-assistant.md environment.yaml.

  3. 세션 시작

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

    session = client.beta.sessions.create(
        agent=agent.id,
        environment_id=environment.id,
        title="Quickstart session",
    )
    
    print(f"Session ID: {session.id}")
  4. 메시지 전송 및 응답 스트리밍

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

    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:
                        if block.type == "text":
                            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는 다음을 수행합니다:

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

완전한 앱 구축하기

각 빠른 시작은 Claude Managed Agents를 인기 있는 채팅 프레임워크와 결합하여 완전하고 실행 가능한 애플리케이션을 만듭니다. 각 예제에서 프레임워크는 채팅 화면을 렌더링하고, 관리형 세션은 서버 측에서 에이전트 루프를 실행합니다. 세션은 대화 기록을 보관하고, 샌드박스에서 도구를 실행하며, 프런트엔드가 렌더링하는 이벤트를 스트리밍합니다.

Vercel의 Chat SDK로 구축한 브라우저 채팅 속 리서치 분석가입니다. 각 대화는 하나의 영구 세션으로, 실시간 피드에 도구 호출이 표시되는 동안 응답을 스트리밍합니다. Chat SDK 어댑터를 교체하면 동일한 핸들러를 Slack, Teams, Discord 또는 WhatsApp으로 옮길 수 있습니다.

assistant-ui 프리미티브로 구축한 채팅 속 스프레드시트 분석가입니다. 세션이 스레드 목록이 되고, 하나의 리듀서가 세션 이벤트 로그를 메시지와 도구 카드로 변환하며, 각 bash 명령은 실행 전에 인라인 허용/거부 게이트를 렌더링합니다.

CopilotKit 채팅 속 개인 재무 어시스턴트입니다. Claude Managed Agents용 AG-UI 어댑터는 각 채팅 스레드를 관리형 세션에 매핑하고 응답을 토큰 단위로 스트리밍하며, 사용자 정의 도구는 대화 내에 인터랙티브 차트를 인라인으로 렌더링합니다.

다음 단계

재사용 가능하고 버전 관리되는 에이전트 구성을 만드세요

네트워킹 및 샌드박스 설정을 사용자 정의하세요

에이전트에 특정 도구를 활성화하세요

이벤트를 처리하고 실행 중인 에이전트를 조정하세요

반복되는 cron 일정에 따라 에이전트를 실행하세요

문서 코퍼스를 한 번 지식 위키로 정제한 다음, 반복되는 질문에 훨씬 적은 비용으로 답변하세요

이 페이지가 도움이 되었나요?