릴리스 노트마이그레이션 가이드

마이그레이션

Messages API 또는 Claude Agent SDK로 구축된 기존 에이전트를 Claude Managed Agents로 이전합니다.

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

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

Messages API 에이전트 루프에서 마이그레이션

while 루프에서 messages.create를 호출하고, 도구 호출을 직접 실행하고, 결과를 대화 기록에 추가하는 방식으로 에이전트를 구축했다면, 해당 코드의 대부분이 사라집니다.

더 이상 관리하지 않아도 되는 것

이전	이후
대화 기록 배열을 유지하고 매 턴마다 다시 전달합니다.	세션이 서버 측에 기록을 저장합니다. 이벤트를 보내고 이벤트를 받습니다.
`tool_use` 콘텐츠 블록을 반복하고, 각 도구를 실행하고, `tool_result` 메시지로 다시 루프를 돕니다.	사전 구축된 도구가 샌드박스 내에서 자동으로 실행됩니다. `agent.custom_tool_use` 이벤트를 통해 커스텀 도구만 처리하면 됩니다.
에이전트가 생성한 코드를 실행하기 위해 자체 샌드박스를 프로비저닝합니다.	세션 샌드박스가 코드 실행, 파일 작업 및 bash를 처리합니다.
루프가 언제 완료되는지 직접 결정합니다.	에이전트가 더 이상 할 일이 없을 때 세션이 `session.status_idle`을 내보냅니다.

코드 비교

이전 (Messages API 루프, 단순화됨):

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        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,
                        }
                    ],
                }
            )

이후 (Claude Managed Agents):

agent = client.beta.agents.create(
    name="Task Runner",
    model="claude-opus-4-8",
    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

여전히 제어할 수 있는 것

시스템 프롬프트 및 모델: 동일한 필드이며, 이제 에이전트 정의에 있습니다.
커스텀 도구: 여전히 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(...)`를 한 번 호출합니다. Agent는 서버 측에 저장되고 버전 관리됩니다. 에이전트 설정을 참조하세요.
`async with ClaudeSDKClient(...)` 또는 `query(...)`	`client.beta.sessions.create(...)`를 호출한 다음 이벤트를 보내고 받습니다.
SDK가 자동으로 디스패치하는 `@tool` 데코레이터 함수	Agent에서 `{"type": "custom", ...}`으로 선언합니다. 클라이언트가 `agent.custom_tool_use` 이벤트를 처리하고 `user.custom_tool_result`로 응답합니다. 도구를 참조하세요.
내장 도구가 사용자의 프로세스에서 사용자의 파일 시스템을 대상으로 실행됨	`{"type": "agent_toolset_20260401"}`이 세션 샌드박스 내에서 `/workspace`를 대상으로 동일한 도구를 실행합니다.
`cwd`, `add_dirs`가 로컬 경로를 가리킴	파일을 세션 리소스로 업로드하거나 마운트합니다.
`system_prompt` 및 `CLAUDE.md` 계층 구조	Agent의 단일 `system` 문자열입니다. 각 업데이트는 새로운 서버 측 버전을 생성합니다. 배포 없이 승격하거나 롤백하려면 세션을 특정 버전에 고정하세요. 에이전트 설정을 참조하세요.
한 곳에서 구성되고 인증되는 `mcp_servers`	Agent에서 서버를 선언하고, Session의 Vault를 통해 자격 증명을 제공합니다.
`permission_mode`, `can_use_tool`	도구별 `permission_policy`를 사용합니다. `always_ask` 도구에 대해 `user.tool_confirmation` 이벤트를 보냅니다.

코드 비교

이전 (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-8",
    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-8",
    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(block.text for block in ev.content if block.type == "text"))
        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
            and ev.stop_reason.type == "end_turn"
        ):
            break

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

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

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

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