Claude Managed Agents 시작하기

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

핵심 개념

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	A configured container template (packages, network access)
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는 베타 헤더를 자동으로 설정합니다.

동작 방식

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

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

다음 단계

에이전트 정의

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

에이전트 생성

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

set -euo pipefail

agent=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<'EOF'
{
  "name": "Coding Assistant",
  "model": "claude-sonnet-4-6",
  "system": "You are a helpful coding assistant. Write clean, well-documented code.",
  "tools": [
    {"type": "agent_toolset_20260401"}
  ]
}
EOF
)

AGENT_ID=$(jq -er '.id' <<<"$agent")
AGENT_VERSION=$(jq -er '.version' <<<"$agent")

echo "Agent ID: $AGENT_ID, version: $AGENT_VERSION"

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

반환된 agent.id를 저장하세요. 생성하는 모든 세션에서 이를 참조합니다.

환경 생성

환경은 에이전트가 실행되는 컨테이너를 정의합니다.

environment=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<'EOF'
{
  "name": "quickstart-env",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")

echo "Environment ID: $ENVIRONMENT_ID"

반환된 environment.id를 저장하세요. 생성하는 모든 세션에서 이를 참조합니다.

세션 시작

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

session=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "title": "Quickstart session"
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")

echo "Session ID: $SESSION_ID"

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

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

# Send the user message first; the API buffers events until the stream attaches
curl -sS --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- >/dev/null <<'EOF'
{
  "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"
        }
      ]
    }
  ]
}
EOF

# Open the SSE stream and process events as they arrive
while IFS= read -r line; do
  [[ $line == data:* ]] || continue
  json=${line#data: }
  case $(jq -r '.type' <<<"$json") in
    agent.message)
      jq -j '.content[] | select(.type == "text") | .text' <<<"$json"
      ;;
    agent.tool_use)
      printf '\n[Using tool: %s]\n' "$(jq -r '.name' <<<"$json")"
      ;;
    session.status_idle)
      printf '\n\nAgent finished.\n'
      break
      ;;
  esac
done < <(
  curl -sS -N --fail-with-body \
    "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "Accept: text/event-stream"
)

에이전트는 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.