Claude Platform Docs
Managed AgentsLangkah pertama

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 pemanggilan alat sendiri, dan menambahkan hasilnya ke riwayat percakapan, sebagian besar kode tersebut akan hilang.

Apa yang tidak perlu Anda kelola lagi

SebelumSesudah
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 kembali ke loop 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 memancarkan 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, kini berada 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, kini diatur sekali pada entri web_search dan web_fetch dalam array configs milik 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, sumber daya file, atau skills.

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 semuanya 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 SDKManaged Agents
ClaudeAgentOptions(...) dibuat per eksekusiclient.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 berdekorator @tool yang didispatch secara otomatis oleh SDKDeklarasikan 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 sistem file Anda{"type": "agent_toolset_20260401"} menjalankan alat yang sama di dalam sandbox sesi terhadap /workspace.
cwd, add_dirs menunjuk ke path lokalUnggah atau mount file sebagai sumber daya sesi.
system_prompt dan hierarki CLAUDE.mdSatu string system pada Agent. Setiap pembaruan yang mengubah agen menghasilkan versi baru di sisi server; sematkan sesi ke versi tertentu untuk mempromosikan atau melakukan rollback tanpa deploy. Lihat Penyiapan agen.
mcp_servers dikonfigurasi dan diautentikasi di satu tempatDeklarasikan server pada Agent; sediakan kredensial melalui Vault pada Session.
permission_mode, can_use_toolpermission_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 berbagai 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 mendispatchnya untuk Anda.

Fitur yang berpindah ke klien Anda

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

Fitur SDKPendekatan Managed Agents
Mode planJalankan sesi khusus perencanaan terlebih dahulu, lalu sesi kedua untuk menjalankan rencana tersebut.
Gaya output, slash commandTerapkan di klien Anda sebelum mengirim user.message atau setelah menerima agent.message.
Hook PreToolUse / PostToolUseKlien Anda sudah melihat setiap event agent.custom_tool_use sebelum merespons; letakkan logikanya di sana. Untuk alat bawaan, gunakan permission_policy: always_ask.
max_turnsHitung giliran di sisi klien.

Daftar periksa migrasi

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

Migrasi antar versi model

Ketika model Claude baru dirilis, migrasi integrasi Claude Managed Agents biasanya hanya berupa 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 pihak 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 pun.
  • Escaping JSON argumen alat diurai 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 migrasinya (cara mengubah kode permintaan Anda) tidak berlaku.

Was this page helpful?