Claude Managed Agents 시작하기

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

핵심 개념

사전 요구 사항

• Claude Console 계정
• API 키

CLI 설치

brew install anthropics/tap/ant

VERSION=1.38.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
  x86_64) ARCH=amd64 ;;
  aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

go install github.com/anthropics/anthropic-cli/cmd/ant@latest

export PATH="$PATH:$(go env GOPATH)/bin"

설치를 확인하세요:

ant --version

SDK 설치

pip install anthropic

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

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

첫 번째 세션 만들기

1. 1

   에이전트 생성

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

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   ant apply coding-assistant.md

   coding-assistant.md

   

   ---
   name: Coding Assistant
   model: claude-opus-5-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful coding assistant. Write clean, well-documented code.

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

   agent_toolset_20260401 도구 유형은 사전 구축된 에이전트 도구 전체(bash, 파일 작업, 웹 검색 등)를 활성화합니다. 전체 목록과 도구별 구성 옵션은 도구를 참조하세요.

2. 2

   환경 생성

   환경은 에이전트가 실행되는 샌드박스를 정의합니다.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   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. 3

   세션 시작

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

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   session = client.beta.sessions.create(
       agent=agent.id,
       environment_id=environment.id,
       title="Quickstart session",
   )
   
   print(f"Session ID: {session.id}")

4. 4

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

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

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

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

다음 단계