Migrazione

Claude Managed Agents sostituisce il tuo ciclo agente scritto a mano con un'infrastruttura gestita. Questa pagina descrive cosa cambia quando migri da un ciclo personalizzato costruito sulla Messages API o dal Claude Agent SDK.



Da un ciclo agente basato sulla Messages API

Se hai costruito un agente chiamando messages.create in un ciclo while, eseguendo tu stesso le chiamate agli strumenti e aggiungendo i risultati alla cronologia della conversazione, la maggior parte di quel codice non è più necessaria.



Cosa smetti di gestire



Confronto del codice

Prima (ciclo Messages API, semplificato):

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

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



Cosa continui a controllare

• Prompt di sistema e modello: stessi campi, ora nella definizione dell'agente.
• Strumenti personalizzati: ancora dichiarati con JSON Schema. L'esecuzione passa dalla gestione inline alla risposta agli eventi agent.custom_tool_use. Consulta Flusso di eventi della sessione.
• Contesto: puoi ancora iniettare contesto tramite il prompt di sistema, le risorse file o le skill.



Dal Claude Agent SDK

Se hai sviluppato con il Claude Agent SDK, stai già lavorando con agenti, strumenti e sessioni come concetti. La differenza è dove vengono eseguiti: l'SDK viene eseguito in un processo che gestisci tu, mentre Managed Agents viene eseguito nell'infrastruttura di Anthropic. La maggior parte della migrazione consiste nel mappare gli oggetti di configurazione dell'SDK ai loro equivalenti lato API.



Cosa cambia



Confronto del codice

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

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

L'Agent e l'Environment vengono creati una sola volta e riutilizzati tra le sessioni. La funzione dello strumento viene ancora eseguita nel tuo processo; la differenza è che leggi l'evento agent.custom_tool_use e invii il risultato esplicitamente invece di lasciare che l'SDK lo invii per te.



Funzionalità che passano al tuo client

Il compromesso per far eseguire ad Anthropic il ciclo agente è che alcune cose che l'SDK gestiva automaticamente diventano responsabilità del tuo client.



Checklist di migrazione

1. Crea un environment con il networking e i runtime di cui il tuo agente ha bisogno.
2. Porta il tuo prompt di sistema e la selezione degli strumenti in una definizione dell'agente.
3. Sostituisci il tuo ciclo con sessions.create e sessions.events.stream.
4. Per tutti i file locali che l'agente legge, caricali tramite la Files API e montali come resources.
5. Per tutti i gestori di strumenti personalizzati, sposta l'esecuzione nel tuo ciclo di eventi come risposte agli eventi agent.custom_tool_use.
6. Verifica con una sessione di test prima di indirizzare il traffico di produzione al nuovo flusso.



Migrazione tra versioni del modello

Quando viene rilasciato un nuovo modello Claude, la migrazione di un'integrazione Claude Managed Agents è tipicamente una modifica di un solo campo: aggiorna model nella tua definizione dell'agente e la modifica avrà effetto sulla prossima sessione che crei.

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

La maggior parte delle modifiche di comportamento a livello di modello documentate nella guida alla migrazione della Messages API non richiede alcuna azione da parte tua:

• Modifiche ai parametri della richiesta (valori predefiniti di max_tokens, configurazione di thinking) sono gestite dal runtime di Claude Managed Agents. Questi campi non sono esposti nella definizione dell'agente.
• Il prefilling dei messaggi dell'assistente non esiste nel modello di sessione basato su eventi, quindi la sua rimozione nei modelli più recenti non ha alcun effetto.
• L'escaping JSON degli argomenti degli strumenti viene analizzato dal runtime prima che tu riceva gli eventi agent.custom_tool_use. Vedi dati strutturati, non stringhe grezze.

Le descrizioni del comportamento nella guida della Messages API (cosa fa di diverso il modello) sono ancora valide. I passaggi di migrazione (come modificare il codice della richiesta) no.