Claude Platform Docs
Managed AgentsPrimi passi

Migrazione

Sposta un agente esistente costruito sulla Messages API o sul Claude Agent SDK verso Claude Managed Agents.

Claude Managed Agents sostituisce il tuo ciclo dell'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 dell'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 scompare.

Cosa smetti di gestire

PrimaDopo
Mantieni l'array della cronologia della conversazione e lo ripassi a ogni turno.La sessione memorizza la cronologia lato server. Invia eventi, ricevi eventi.
Iteri sui blocchi di contenuto tool_use, esegui ogni strumento e torni nel ciclo con messaggi tool_result.Gli strumenti predefiniti vengono eseguiti automaticamente all'interno della sandbox. Gestisci solo gli strumenti personalizzati tramite gli eventi agent.custom_tool_use.
Predisponi la tua sandbox per eseguire il codice generato dall'agente.La sandbox della sessione gestisce l'esecuzione del codice, le operazioni sui file e bash.
Decidi tu quando il ciclo è terminato.La sessione emette session.status_idle quando l'agente non ha più nulla da fare.

Confronto del codice

Prima (ciclo Messages API, semplificato):

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

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

Cosa controlli ancora

  • Prompt di sistema e modello: Gli 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.
  • Impostazioni di web search e web fetch: Gli stessi campi allowed_domains, blocked_domains, max_content_tokens e user_location, ora impostati una sola volta nelle voci web_search e web_fetch dell'array configs del toolset dell'agente invece che in ogni richiesta. I campi max_uses, citations e cache_control non sono disponibili. Consulta Limitare i domini di web search e web fetch.
  • Contesto: Puoi ancora iniettare contesto tramite il prompt di sistema, le risorse file o le skill.

Dal Claude Agent SDK

Se hai costruito 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

Agent SDKManaged Agents
ClaudeAgentOptions(...) costruito a ogni esecuzioneclient.beta.agents.create(...) una sola volta; l'Agent viene persistito e versionato lato server. Consulta Configurazione dell'agente.
async with ClaudeSDKClient(...) oppure query(...)client.beta.sessions.create(...) poi invia e ricevi eventi.
Funzioni decorate con @tool smistate automaticamente dall'SDKDichiarale come {"type": "custom", ...} sull'Agent; il tuo client gestisce gli eventi agent.custom_tool_use e risponde con user.custom_tool_result. Consulta Strumenti.
Gli strumenti integrati vengono eseguiti nel tuo processo sul tuo filesystem{"type": "agent_toolset_20260401"} esegue gli stessi strumenti all'interno della sandbox della sessione su /workspace.
cwd, add_dirs puntano a percorsi localiCarica o monta file come risorse della sessione.
system_prompt e la gerarchia CLAUDE.mdUna singola stringa system sull'Agent. Ogni aggiornamento che modifica l'agente produce una nuova versione lato server; vincola le sessioni a una versione specifica per promuovere o ripristinare senza un deploy. Consulta Configurazione dell'agente.
mcp_servers configurati e autenticati in un unico postoDichiara i server sull'Agent; fornisci le credenziali tramite un Vault sulla Session.
permission_mode, can_use_toolpermission_policy per singolo strumento; invia eventi user.tool_confirmation per gli strumenti always_ask.

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

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

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 smisti per te.

Funzionalità che passano al tuo client

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

Funzionalità dell'SDKApproccio in Managed Agents
Modalità pianoEsegui prima una sessione di sola pianificazione, poi una seconda sessione per eseguire il piano.
Stili di output, comandi slashApplicali nel tuo client prima di inviare user.message o dopo aver ricevuto agent.message.
Hook PreToolUse / PostToolUseIl tuo client vede già ogni evento agent.custom_tool_use prima di rispondere; inserisci lì la logica. Per gli strumenti integrati, usa permission_policy: always_ask.
max_turnsConta i turni lato client.

Checklist di migrazione

  1. Crea un ambiente con la rete 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 verso il nuovo flusso.

Migrazione tra versioni del modello

Quando viene rilasciato un nuovo modello Claude, migrare un'integrazione Claude Managed Agents è in genere una modifica di un solo campo: aggiorna model nella tua definizione dell'agente e la modifica ha effetto dalla prossima sessione che crei.

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

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:

  • Le modifiche ai parametri di 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 diversamente il modello) si applicano ancora. I passaggi di migrazione (come modificare il codice delle tue richieste) no.

Was this page helpful?