Migrasi

Claude Managed Agents menggantikan loop agen yang ditulis tangan dengan infrastruktur terkelola. Halaman ini mencakup perubahan apa saat Anda bermigrasi dari loop kustom yang dibangun di Messages API atau dari Claude Agent SDK.

Dari loop agen Messages API

Jika Anda membangun agen dengan memanggil messages.create dalam loop while, menjalankan panggilan alat sendiri, dan menambahkan hasil ke riwayat percakapan, sebagian besar kode itu hilang.

Apa yang Anda berhenti kelola

Perbandingan kode

Sebelum (loop Messages API, disederhanakan):

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,
                        }
                    ],
                }
            )

Sesudah (Claude Managed Agents):

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

Apa yang masih Anda kontrol

• Prompt sistem dan model: Bidang yang sama, sekarang pada definisi agen.
• Alat kustom: Masih dideklarasikan dengan JSON Schema. Eksekusi bergerak dari penanganan inline ke merespons acara agent.custom_tool_use. Lihat Aliran acara sesi.
• Konteks: Anda masih dapat menyuntikkan konteks melalui prompt sistem, sumber daya file, atau keterampilan.

Dari Claude Agent SDK

Jika Anda membangun dengan Claude Agent SDK, Anda sudah bekerja dengan agen, alat, dan sesi sebagai konsep. Perbedaannya adalah di mana mereka berjalan: SDK dijalankan dalam proses yang Anda operasikan, sementara Managed Agents berjalan di infrastruktur Anthropic. Sebagian besar migrasi adalah pemetaan objek konfigurasi SDK ke setara API mereka.

Apa yang berubah

Perbandingan kode

Sebelum (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)

Sesudah (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

Agen dan Lingkungan dibuat sekali dan digunakan kembali di seluruh sesi. Fungsi alat masih berjalan dalam proses Anda; perbedaannya adalah Anda membaca acara agent.custom_tool_use dan mengirim hasil secara eksplisit alih-alih SDK mengirimnya untuk Anda.

Fitur yang bergerak ke klien Anda

Pertukaran untuk Anthropic menjalankan loop agen adalah bahwa beberapa hal yang ditangani SDK secara otomatis menjadi tanggung jawab klien Anda.

Daftar periksa migrasi

1. Buat lingkungan dengan jaringan dan runtime yang dibutuhkan agen Anda.
2. Portkan prompt sistem dan pilihan alat Anda ke definisi agen.
3. Ganti loop Anda dengan sessions.create dan sessions.stream.
4. Untuk file lokal apa pun yang dibaca agen, unggah melalui Files API dan pasang sebagai resources.
5. Untuk penanganan alat kustom apa pun, pindahkan eksekusi ke loop acara Anda sebagai respons terhadap acara agent.custom_tool_use.
6. Verifikasi dengan sesi uji sebelum mengarahkan lalu lintas produksi ke alur baru.

Bermigrasi antara versi model

Ketika model Claude baru dirilis, bermigrasi integrasi Claude Managed Agents biasanya merupakan perubahan satu bidang: perbarui model pada definisi agen Anda dan perubahan berlaku pada sesi berikutnya yang Anda buat.

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --model claude-opus-4-7

Sebagian besar perubahan perilaku tingkat model yang didokumentasikan dalam panduan migrasi Messages API tidak memerlukan tindakan di pihak Anda:

• Perubahan parameter permintaan (default max_tokens, konfigurasi thinking) ditangani oleh runtime Claude Managed Agents. Bidang-bidang ini tidak diekspos pada definisi agen.
• Pengisian pesan asisten tidak ada dalam model sesi berbasis acara, jadi penghapusannya pada model yang lebih baru adalah no-op.
• Penghindaran JSON argumen alat diurai oleh runtime sebelum Anda menerima acara agent.custom_tool_use. Anda melihat data terstruktur, bukan string mentah.

Deskripsi perilaku dalam panduan Messages API (apa yang dilakukan model secara berbeda) masih berlaku. Langkah-langkah migrasi (cara mengubah kode permintaan Anda) tidak.