마이그레이션

Claude Managed Agents는 수동으로 작성한 에이전트 루프를 관리형 인프라로 대체합니다. 이 페이지에서는 Messages API에서 구축한 사용자 정의 루프 또는 Claude Agent SDK에서 마이그레이션할 때 변경되는 사항을 다룹니다.

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

Messages API 에이전트 루프에서

while 루프에서 messages.create를 호출하고, 도구 호출을 직접 실행하고, 결과를 대화 기록에 추가하여 에이전트를 구축한 경우, 대부분의 코드가 제거됩니다.

더 이상 관리하지 않는 것

이전	이후
대화 기록 배열을 유지하고 매 턴마다 다시 전달합니다.	세션이 서버 측에 기록을 저장합니다. 이벤트를 보내고 이벤트를 받습니다.
`stop_reason: "tool_use"`를 파싱하고, 도구를 실행하고, `tool_result` 메시지로 루프를 돌립니다.	사전 구축된 도구가 컨테이너 내에서 자동으로 실행됩니다. `agent.custom_tool_use` 이벤트를 통해서만 사용자 정의 도구를 처리합니다.
에이전트 생성 코드를 실행하기 위한 자체 샌드박스를 프로비저닝합니다.	세션 컨테이너가 코드 실행, 파일 작업 및 bash를 처리합니다.
루프가 완료되는 시점을 결정합니다.	세션이 에이전트가 더 이상 할 일이 없을 때 `session.status_idle`을 내보냅니다.

코드 비교

이전 (Messages API 루프, 간소화됨):

이후 (Claude Managed Agents):

여전히 제어하는 것

시스템 프롬프트 및 모델: 동일한 필드이며, 이제 에이전트 정의에 있습니다.
사용자 정의 도구: 여전히 JSON Schema로 선언됩니다. 실행은 인라인 처리에서 agent.custom_tool_use 이벤트에 응답하는 것으로 이동합니다. 세션 이벤트 스트림을 참조하세요.
컨텍스트: 시스템 프롬프트, 파일 리소스 또는 스킬을 통해 컨텍스트를 주입할 수 있습니다.

Claude Agent SDK에서

Claude Agent SDK로 구축한 경우, 이미 에이전트, 도구 및 세션을 개념으로 작업하고 있습니다. 차이점은 실행 위치입니다. SDK는 사용자가 운영하는 프로세스에서 실행되고, Managed Agents는 Anthropic의 인프라에서 실행됩니다. 대부분의 마이그레이션은 SDK 구성 객체를 API 측 동등물에 매핑하는 것입니다.

변경 사항

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)` 실행당 구성됨	`client.beta.agents.create(...)` 한 번; 에이전트는 서버 측에서 지속되고 버전이 관리됩니다. 에이전트 설정을 참조하세요.
`async with ClaudeSDKClient(...)` 또는 `query(...)`	`client.beta.sessions.create(...)` 그 다음 이벤트를 보내고 받습니다.
`@tool` 데코레이터 함수는 SDK에서 자동으로 디스패치됨	에이전트에서 `{"type": "custom", ...}`으로 선언; 클라이언트는 `agent.custom_tool_use` 이벤트를 처리하고 `user.custom_tool_result`로 응답합니다. 도구를 참조하세요.
기본 제공 도구는 파일 시스템에 대해 프로세스에서 실행됨	`{"type": "agent_toolset_20260401"}`은 세션 컨테이너 내에서 `/workspace`에 대해 동일한 도구를 실행합니다.

코드 비교

이전 (Agent SDK):

from claude_agent_sdk import (
    ClaudeAgentOptions,
    ClaudeSDKClient,
    create_sdk_mcp_server,
    tool,
)


@tool("get_weather", "Get the current weather for a city.", {"city": str})
async def get_weather(args: dict) -> dict:
    return {"content": [{"type": "text", "text": f"{args['city']}: 18°C, clear"}]}


options = ClaudeAgentOptions(
    model="claude-opus-4-7",
    system_prompt="You are a concise weather assistant.",
    mcp_servers={
        "weather": create_sdk_mcp_server("weather", "1.0", tools=[get_weather])
    },
)

async with ClaudeSDKClient(options=options) as agent:
    await agent.query("What's the weather in Tokyo?")
    async for msg in agent.receive_response():
        print(msg)

이후 (Managed Agents):

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="weather-agent",
    model="claude-opus-4-7",
    system="You are a concise weather assistant.",
    tools=[
        {
            "type": "custom",
            "name": "get_weather",
            "description": "Get the current weather for a city.",
            "input_schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
)
environment = client.beta.environments.create(
    name="weather-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
)


def get_weather(city: str) -> str:
    return f"{city}: 18°C, clear"


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": "What's the weather in Tokyo?"}],
            }
        ],
    )
    for ev in stream:
        if ev.type == "agent.message":
            print("".join(b.text for b in ev.content))
        elif ev.type == "agent.custom_tool_use":
            result = get_weather(**ev.input)
            client.beta.sessions.events.send(
                session.id,
                events=[
                    {
                        "type": "user.custom_tool_result",
                        "custom_tool_use_id": ev.id,
                        "content": [{"type": "text", "text": result}],
                    }
                ],
            )
        elif ev.type == "session.status_idle" and ev.stop_reason.type == "end_turn":
            break

에이전트와 환경은 한 번 생성되고 세션 전체에서 재사용됩니다. 도구 함수는 여전히 프로세스에서 실행됩니다. 차이점은 agent.custom_tool_use 이벤트를 읽고 SDK가 디스패치하는 대신 명시적으로 결과를 보낸다는 것입니다.

클라이언트로 이동하는 기능

Anthropic이 에이전트 루프를 실행하는 대신, SDK가 자동으로 처리하던 몇 가지 사항이 클라이언트의 책임이 됩니다.

SDK 기능	Managed Agents 접근 방식
계획 모드	먼저 계획 전용 세션을 실행한 다음 두 번째 세션을 실행하여 실행합니다.
출력 스타일, 슬래시 명령	`user.message`를 보내기 전에 또는 `agent.message`를 받은 후 클라이언트에 적용합니다.
`PreToolUse` / `PostToolUse` 훅	클라이언트는 이미 응답하기 전에 모든 `agent.custom_tool_use` 이벤트를 봅니다. 로직을 거기에 넣으세요. 기본 제공 도구의 경우 `permission_policy: always_ask`를 사용합니다.
`max_turns`	클라이언트 측에서 턴을 계산합니다.

마이그레이션 체크리스트

환경 생성 - 에이전트가 필요로 하는 네트워킹 및 런타임 포함.
시스템 프롬프트 및 도구 선택을 에이전트 정의로 포팅합니다.
루프를 sessions.create 및 sessions.stream으로 바꿉니다.
에이전트가 읽는 로컬 파일의 경우 Files API를 통해 업로드하고 resources로 마운트합니다.
사용자 정의 도구 핸들러의 경우 실행을 agent.custom_tool_use 이벤트에 대한 응답으로 이벤트 루프로 이동합니다.
프로덕션 트래픽을 새 흐름으로 지정하기 전에 테스트 세션으로 확인합니다.

모델 버전 간 마이그레이션

새로운 Claude 모델이 출시되면, Claude Managed Agents 통합을 마이그레이션하는 것은 일반적으로 한 필드 변경입니다. 에이전트 정의에서 model을 업데이트하면 다음에 생성하는 세션에서 변경 사항이 적용됩니다.

Messages API 마이그레이션 가이드에 문서화된 대부분의 모델 수준 동작 변경 사항은 사용자 측에서 조치가 필요하지 않습니다.

요청 매개변수 변경 (max_tokens 기본값, thinking 구성)은 Claude Managed Agents 런타임에서 처리됩니다. 이러한 필드는 에이전트 정의에 노출되지 않습니다.
어시스턴트 메시지 사전 채우기는 이벤트 기반 세션 모델에 존재하지 않으므로, 최신 모델에서 제거되는 것은 작동하지 않습니다.
도구 인수 JSON 이스케이프는 agent.custom_tool_use 이벤트를 받기 전에 런타임에서 파싱됩니다. 원시 문자열이 아닌 구조화된 데이터를 봅니다.

Messages API 가이드의 동작 설명(모델이 다르게 수행하는 작업)은 여전히 적용됩니다. 마이그레이션 단계(요청 코드를 변경하는 방법)는 적용되지 않습니다.

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=messages,
        tools=tools,
    )
    messages.append({"role": "assistant", "content": response.content})
    if response.stop_reason == "end_turn":
        break
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            messages.append(
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "tool_result",
                            "tool_use_id": block.id,
                            "content": result,
                        }
                    ],
                }
            )

agent = client.beta.agents.create(
    name="Task Runner",
    model="claude-opus-4-7",
    tools=[{"type": "agent_toolset_20260401"}],
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.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": task}]}],
    )
    for event in stream:
        if event.type == "session.status_idle":
            break