Migrazione

Claude Managed Agents sostituisce il tuo ciclo agente scritto manualmente con un'infrastruttura gestita. Questa pagina copre i cambiamenti quando esegui la migrazione da un ciclo personalizzato creato su Messages API o da Claude Agent SDK.

Da un ciclo agente Messages API

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

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

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

Cosa controlli ancora

• Prompt di sistema e modello: Stessi campi, ora sulla definizione dell'agente.
• Strumenti personalizzati: Ancora dichiarati con JSON Schema. L'esecuzione passa dalla gestione inline alla risposta agli eventi agent.custom_tool_use. Vedi Flusso di eventi della sessione.
• Contesto: Puoi ancora iniettare il contesto tramite il prompt di sistema, risorse file, o competenze.

Da Claude Agent SDK

Se hai creato con 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, mentre Managed Agents viene eseguito nell'infrastruttura di Anthropic. La maggior parte della migrazione è 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-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)

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

L'Agente e l'Ambiente vengono creati una 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 che l'SDK lo invii per te.

Funzionalità che passano al tuo client

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

Elenco di controllo della migrazione

1. Crea un ambiente con la rete e i runtime di cui il tuo agente ha bisogno.
2. Trasferisci il tuo prompt di sistema e la selezione degli strumenti a una definizione di agente.
3. Sostituisci il tuo ciclo con sessions.create e sessions.stream.
4. Per qualsiasi file locale che l'agente legge, caricalo tramite Files API e montalo come resources.
5. Per qualsiasi gestore 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 di modello

Quando viene rilasciato un nuovo modello Claude, la migrazione di un'integrazione Claude Managed Agents è in genere una modifica a un campo: aggiorna model sulla tua definizione di agente e il cambiamento avrà effetto sulla prossima sessione che crei.

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

La maggior parte dei cambiamenti di comportamento a livello di modello documentati nella guida alla migrazione di Messages API non richiedono azioni da parte tua:

• Modifiche ai parametri di richiesta (impostazioni predefinite di max_tokens, configurazione di thinking) sono gestite dal runtime di Claude Managed Agents. Questi campi non sono esposti sulla definizione dell'agente.
• Prefilling dei messaggi dell'assistente non esiste nel modello di sessione basato su eventi, quindi la sua rimozione nei modelli più recenti è un no-op.
• Escaping JSON degli argomenti dello strumento viene analizzato dal runtime prima di ricevere gli eventi agent.custom_tool_use. Vedi dati strutturati, non stringhe grezze.

Le descrizioni del comportamento nella guida di Messages API (cosa fa il modello diversamente) si applicano ancora. I passaggi di migrazione (come modificare il codice della tua richiesta) no.