Migrasi

Pindahkan agen yang sudah ada yang dibangun di atas Messages API atau Claude Agent SDK ke Claude Managed Agents.

Claude Managed Agents menggantikan loop agen yang Anda tulis sendiri dengan infrastruktur terkelola. Halaman ini membahas apa yang berubah ketika Anda bermigrasi dari loop kustom yang dibangun di atas 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 hasilnya ke riwayat percakapan, sebagian besar kode tersebut tidak lagi diperlukan.

Apa yang tidak lagi Anda kelola

Sebelum	Sesudah
Anda memelihara array riwayat percakapan dan mengirimkannya kembali pada setiap giliran.	Sesi menyimpan riwayat di sisi server. Kirim event, terima event.
Anda mengiterasi blok konten `tool_use`, menjalankan setiap alat, dan mengulang kembali dengan pesan `tool_result`.	Alat bawaan berjalan di dalam sandbox secara otomatis. Anda hanya menangani alat kustom melalui event `agent.custom_tool_use`.
Anda menyediakan sandbox sendiri untuk menjalankan kode yang dihasilkan agen.	Sandbox sesi menangani eksekusi kode, operasi file, dan bash.
Anda memutuskan kapan loop selesai.	Sesi mengeluarkan `session.status_idle` ketika agen tidak memiliki hal lain untuk dilakukan.

Perbandingan kode

Sebelum (loop Messages API, disederhanakan):

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

Prompt sistem dan model: Field yang sama, sekarang pada definisi agen.
Alat kustom: Masih dideklarasikan dengan JSON Schema. Eksekusi berpindah dari penanganan inline menjadi merespons event agent.custom_tool_use. Lihat Aliran event sesi.
Pengaturan web search dan web fetch: Field allowed_domains, blocked_domains, max_content_tokens, dan user_location yang sama, sekarang diatur sekali pada entri web_search dan web_fetch dari array configs toolset agen, bukan pada setiap permintaan. Field max_uses, citations, dan cache_control tidak tersedia. Lihat Membatasi domain web search dan web fetch.
Konteks: Anda masih dapat menyuntikkan konteks melalui prompt sistem, resource file, atau skill.

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 berjalan dalam proses yang Anda operasikan, sedangkan Managed Agents berjalan di infrastruktur Anthropic. Sebagian besar migrasi adalah memetakan objek konfigurasi SDK ke padanannya di sisi API.

Apa yang berubah

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)` dibuat per eksekusi	`client.beta.agents.create(...)` sekali; Agent disimpan dan diberi versi di sisi server. Lihat Penyiapan agen.
`async with ClaudeSDKClient(...)` atau `query(...)`	`client.beta.sessions.create(...)` lalu kirim dan terima event.
Fungsi dengan dekorator `@tool` yang di-dispatch secara otomatis oleh SDK	Deklarasikan sebagai `{"type": "custom", ...}` pada Agent; klien Anda menangani event `agent.custom_tool_use` dan membalas dengan `user.custom_tool_result`. Lihat Alat.
Alat bawaan berjalan dalam proses Anda terhadap filesystem Anda	`{"type": "agent_toolset_20260401"}` menjalankan alat yang sama di dalam sandbox sesi terhadap `/workspace`.
`cwd`, `add_dirs` menunjuk ke path lokal	Unggah atau mount file sebagai resource sesi.
`system_prompt` dan hierarki `CLAUDE.md`	Satu string `system` pada Agent. Setiap pembaruan yang mengubah agen menghasilkan versi baru di sisi server; pin sesi ke versi tertentu untuk mempromosikan atau melakukan rollback tanpa deploy. Lihat Penyiapan agen.
`mcp_servers` dikonfigurasi dan diautentikasi di satu tempat	Deklarasikan server pada Agent; sediakan kredensial melalui Vault pada Session.
`permission_mode`, `can_use_tool`	`permission_policy` per alat; kirim event `user.tool_confirmation` untuk alat `always_ask`.

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

Agent dan Environment dibuat sekali dan digunakan kembali di seluruh sesi. Fungsi alat masih berjalan dalam proses Anda; perbedaannya adalah Anda membaca event agent.custom_tool_use dan mengirim hasilnya secara eksplisit, bukan SDK yang melakukan dispatch untuk Anda.

Fitur yang berpindah ke klien Anda

Konsekuensi dari Anthropic yang menjalankan loop agen adalah beberapa hal yang sebelumnya ditangani SDK secara otomatis menjadi tanggung jawab klien Anda.

Fitur SDK	Pendekatan Managed Agents
Plan mode	Jalankan sesi khusus perencanaan terlebih dahulu, lalu sesi kedua untuk menjalankan rencana tersebut.
Output style, slash command	Terapkan di klien Anda sebelum mengirim `user.message` atau setelah menerima `agent.message`.
Hook `PreToolUse` / `PostToolUse`	Klien Anda sudah melihat setiap event `agent.custom_tool_use` sebelum merespons; letakkan logikanya di sana. Untuk alat bawaan, gunakan `permission_policy: always_ask`.
`max_turns`	Hitung giliran di sisi klien.

Daftar periksa migrasi

Buat environment dengan jaringan dan runtime yang dibutuhkan agen Anda.
Pindahkan prompt sistem dan pemilihan alat Anda ke definisi agen.
Ganti loop Anda dengan sessions.create dan sessions.events.stream.
Untuk file lokal apa pun yang dibaca agen, unggah melalui Files API dan mount sebagai resources.
Untuk handler alat kustom apa pun, pindahkan eksekusi ke dalam event loop Anda sebagai respons terhadap event agent.custom_tool_use.
Verifikasi dengan sesi uji sebelum mengarahkan trafik produksi ke alur baru.

Migrasi antar versi model

Ketika model Claude baru dirilis, migrasi integrasi Claude Managed Agents biasanya hanya perubahan satu field: perbarui model pada definisi agen Anda dan perubahan tersebut berlaku pada sesi berikutnya yang Anda buat.

ant beta:agents update --agent-id "$AGENT_ID" < agent.yaml

agent.yaml

name: Task Runner
model: claude-opus-5
system: You are a task automation agent. Complete the task you are given end to end.
tools:
  - type: agent_toolset_20260401

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

Perubahan parameter permintaan (default max_tokens, konfigurasi thinking) ditangani oleh runtime Claude Managed Agents. Field ini tidak diekspos pada definisi agen.
Prefilling pesan asisten tidak ada dalam model sesi berbasis event, sehingga penghapusannya pada model yang lebih baru tidak berdampak apa-apa.
Escaping JSON argumen alat di-parse oleh runtime sebelum Anda menerima event agent.custom_tool_use. Anda melihat data terstruktur, bukan string mentah.

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

Was this page helpful?

Managed AgentsLangkah pertama

Migrasi

Pindahkan agen yang sudah ada yang dibangun di atas Messages API atau Claude Agent SDK ke Claude Managed Agents.

Dari loop agen Messages API

Apa yang tidak lagi Anda kelola

Sebelum	Sesudah
Anda memelihara array riwayat percakapan dan mengirimkannya kembali pada setiap giliran.	Sesi menyimpan riwayat di sisi server. Kirim event, terima event.
Anda mengiterasi blok konten `tool_use`, menjalankan setiap alat, dan mengulang kembali dengan pesan `tool_result`.	Alat bawaan berjalan di dalam sandbox secara otomatis. Anda hanya menangani alat kustom melalui event `agent.custom_tool_use`.
Anda menyediakan sandbox sendiri untuk menjalankan kode yang dihasilkan agen.	Sandbox sesi menangani eksekusi kode, operasi file, dan bash.
Anda memutuskan kapan loop selesai.	Sesi mengeluarkan `session.status_idle` ketika agen tidak memiliki hal lain untuk dilakukan.

Perbandingan kode

Sebelum (loop Messages API, disederhanakan):

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

Prompt sistem dan model: Field yang sama, sekarang pada definisi agen.
Alat kustom: Masih dideklarasikan dengan JSON Schema. Eksekusi berpindah dari penanganan inline menjadi merespons event agent.custom_tool_use. Lihat Aliran event sesi.
Pengaturan web search dan web fetch: Field allowed_domains, blocked_domains, max_content_tokens, dan user_location yang sama, sekarang diatur sekali pada entri web_search dan web_fetch dari array configs toolset agen, bukan pada setiap permintaan. Field max_uses, citations, dan cache_control tidak tersedia. Lihat Membatasi domain web search dan web fetch.
Konteks: Anda masih dapat menyuntikkan konteks melalui prompt sistem, resource file, atau skill.

Dari Claude Agent SDK

Apa yang berubah

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)` dibuat per eksekusi	`client.beta.agents.create(...)` sekali; Agent disimpan dan diberi versi di sisi server. Lihat Penyiapan agen.
`async with ClaudeSDKClient(...)` atau `query(...)`	`client.beta.sessions.create(...)` lalu kirim dan terima event.
Fungsi dengan dekorator `@tool` yang di-dispatch secara otomatis oleh SDK	Deklarasikan sebagai `{"type": "custom", ...}` pada Agent; klien Anda menangani event `agent.custom_tool_use` dan membalas dengan `user.custom_tool_result`. Lihat Alat.
Alat bawaan berjalan dalam proses Anda terhadap filesystem Anda	`{"type": "agent_toolset_20260401"}` menjalankan alat yang sama di dalam sandbox sesi terhadap `/workspace`.
`cwd`, `add_dirs` menunjuk ke path lokal	Unggah atau mount file sebagai resource sesi.
`system_prompt` dan hierarki `CLAUDE.md`	Satu string `system` pada Agent. Setiap pembaruan yang mengubah agen menghasilkan versi baru di sisi server; pin sesi ke versi tertentu untuk mempromosikan atau melakukan rollback tanpa deploy. Lihat Penyiapan agen.
`mcp_servers` dikonfigurasi dan diautentikasi di satu tempat	Deklarasikan server pada Agent; sediakan kredensial melalui Vault pada Session.
`permission_mode`, `can_use_tool`	`permission_policy` per alat; kirim event `user.tool_confirmation` untuk alat `always_ask`.

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

Fitur yang berpindah ke klien Anda

Konsekuensi dari Anthropic yang menjalankan loop agen adalah beberapa hal yang sebelumnya ditangani SDK secara otomatis menjadi tanggung jawab klien Anda.

Fitur SDK	Pendekatan Managed Agents
Plan mode	Jalankan sesi khusus perencanaan terlebih dahulu, lalu sesi kedua untuk menjalankan rencana tersebut.
Output style, slash command	Terapkan di klien Anda sebelum mengirim `user.message` atau setelah menerima `agent.message`.
Hook `PreToolUse` / `PostToolUse`	Klien Anda sudah melihat setiap event `agent.custom_tool_use` sebelum merespons; letakkan logikanya di sana. Untuk alat bawaan, gunakan `permission_policy: always_ask`.
`max_turns`	Hitung giliran di sisi klien.

Daftar periksa migrasi

Buat environment dengan jaringan dan runtime yang dibutuhkan agen Anda.
Pindahkan prompt sistem dan pemilihan alat Anda ke definisi agen.
Ganti loop Anda dengan sessions.create dan sessions.events.stream.
Untuk file lokal apa pun yang dibaca agen, unggah melalui Files API dan mount sebagai resources.
Untuk handler alat kustom apa pun, pindahkan eksekusi ke dalam event loop Anda sebagai respons terhadap event agent.custom_tool_use.
Verifikasi dengan sesi uji sebelum mengarahkan trafik produksi ke alur baru.

Migrasi antar versi model

ant beta:agents update --agent-id "$AGENT_ID" < agent.yaml

agent.yaml

name: Task Runner
model: claude-opus-5
system: You are a task automation agent. Complete the task you are given end to end.
tools:
  - type: agent_toolset_20260401

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

Perubahan parameter permintaan (default max_tokens, konfigurasi thinking) ditangani oleh runtime Claude Managed Agents. Field ini tidak diekspos pada definisi agen.
Prefilling pesan asisten tidak ada dalam model sesi berbasis event, sehingga penghapusannya pada model yang lebih baru tidak berdampak apa-apa.
Escaping JSON argumen alat di-parse oleh runtime sebelum Anda menerima event agent.custom_tool_use. Anda melihat data terstruktur, bukan string mentah.

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

Was this page helpful?

Dari loop agen Messages API

Apa yang tidak lagi Anda kelola

Perbandingan kode

Apa yang masih Anda kendalikan

Dari Claude Agent SDK

Apa yang berubah

Perbandingan kode

Fitur yang berpindah ke klien Anda

Daftar periksa migrasi

Migrasi antar versi model

Dari loop agen Messages API

Apa yang tidak lagi Anda kelola

Perbandingan kode

Apa yang masih Anda kendalikan

Dari Claude Agent SDK

Apa yang berubah

Perbandingan kode

Fitur yang berpindah ke klien Anda

Daftar periksa migrasi

Migrasi antar versi model

Dari loop agen Messages API

Apa yang tidak lagi Anda kelola

Perbandingan kode

Apa yang masih Anda kendalikan

Dari Claude Agent SDK

Apa yang berubah

Perbandingan kode

Fitur yang berpindah ke klien Anda

Daftar periksa migrasi

Migrasi antar versi model

Dari loop agen Messages API

Apa yang tidak lagi Anda kelola

Perbandingan kode

Apa yang masih Anda kendalikan

Dari Claude Agent SDK

Apa yang berubah

Perbandingan kode

Fitur yang berpindah ke klien Anda

Daftar periksa migrasi

Migrasi antar versi model