Migrazione

Prima	Dopo
Mantieni l'array della cronologia della conversazione e lo trasmetti ad ogni turno.	La sessione memorizza la cronologia lato server. Invia eventi, ricevi eventi.
Analizzi `stop_reason: "tool_use"`, esegui lo strumento e torni indietro con un messaggio `tool_result`.	Gli strumenti precostruiti si eseguono automaticamente all'interno del contenitore. Gestisci solo gli strumenti personalizzati tramite gli eventi .

Prima	Dopo
Mantieni l'array della cronologia della conversazione e lo trasmetti ad ogni turno.	La sessione memorizza la cronologia lato server. Invia eventi, ricevi eventi.
Analizzi `stop_reason: "tool_use"`, esegui lo strumento e torni indietro con un messaggio `tool_result`.	Gli strumenti precostruiti si eseguono automaticamente all'interno del contenitore. Gestisci solo gli strumenti personalizzati tramite gli eventi .

agent.custom_tool_use

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

agent=$(
  curl --fail-with-body -sS "https://api.anthropic.com/v1/agents?beta=true" \
    -H "x-api-key: ${ANTHROPIC_API_KEY}" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    --json '{
      "name": "Task Runner",
      "model": "claude-sonnet-4-6",
      "tools": [{"type": "agent_toolset_20260401"}]
    }'
)
agent_id=$(jq -r '.id' <<< "${agent}")

session_id=$(
  curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions?beta=true" \
    -H "x-api-key: ${ANTHROPIC_API_KEY}" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    --json "$(jq -n --argjson a "${agent}" --arg env "${environment_id}" \
      '{agent: {type: "agent", id: $a.id, version: $a.version}, environment_id: $env}')" \
  | jq -r '.id'
)

# Open the SSE stream in the background, then send the user message.
stream_log=$(mktemp)
curl --fail-with-body -sS -N \
  "https://api.anthropic.com/v1/sessions/${session_id}/stream?beta=true" \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  > "${stream_log}" &
stream_pid=$!

curl --fail-with-body -sS \
  "https://api.anthropic.com/v1/sessions/${session_id}/events?beta=true" \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  --json "$(jq -n --arg text "${task}" \
    '{events: [{type: "user.message", content: [{type: "text", text: $text}]}]}')" \
  > /dev/null

# Read events until the session goes idle.
while IFS= read -r line; do
  [[ ${line} == data:* ]] || continue
  event_type=$(jq -r '.type // empty' 2>/dev/null <<< "${line#data: }" || true)
  [[ ${event_type} == "session.status_idle" ]] && break
done < <(tail -f -n +1 "${stream_log}")

kill "${stream_pid}" 2>/dev/null || true

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)` costruito per ogni esecuzione	`client.beta.agents.create(...)` una volta; l'Agente è persistito e versionato lato server. Vedi Configurazione dell'agente.
`async with ClaudeSDKClient(...)` o `query(...)`	`client.beta.sessions.create(...)` quindi invia e ricevi eventi.
Funzioni decorate con `@tool` inviate automaticamente dall'SDK	Dichiara come `{"type": "custom", ...}` sull'Agente; il tuo client gestisce gli eventi `agent.custom_tool_use` e risponde con `user.custom_tool_result`. Vedi Strumenti.
Gli strumenti incorporati vengono eseguiti nel tuo processo rispetto al tuo filesystem	`{"type": "agent_toolset_20260401"}` esegue gli stessi strumenti all'interno del contenitore della sessione rispetto a `/workspace`.
`cwd`, `add_dirs` puntano a percorsi locali	Carica o monta file come risorse della sessione.
`system_prompt` e la gerarchia `CLAUDE.md`	Una singola stringa `system` sull'Agente. Ogni aggiornamento produce una nuova versione lato server; fissa le sessioni a una versione specifica per promuovere o eseguire il rollback senza un deploy. Vedi Configurazione dell'agente.
`mcp_servers` configurati e autenticati in un unico posto	Dichiara i server sull'Agente; fornisci le credenziali tramite un Vault sulla Sessione.
`permission_mode`, `can_use_tool`	Per-strumento `permission_policy`; rispondi agli eventi `user.tool_confirmation` per gli strumenti `always_ask`.

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-sonnet-4-6",
    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)

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="weather-agent",
    model="claude-sonnet-4-6",
    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

Funzionalità SDK	Approccio Managed Agents
Modalità di pianificazione	Esegui prima una sessione di sola pianificazione, quindi una seconda sessione per eseguire.
Stili di output, comandi slash	Applica nel tuo client prima di inviare `user.message` o dopo aver ricevuto `agent.message`.
Hook `PreToolUse` / `PostToolUse`	Il tuo client vede già ogni evento `agent.custom_tool_use` prima di rispondere; metti la logica lì. Per gli strumenti incorporati, usa `permission_policy: always_ask`.
`max_turns`	Conta i turni lato client.

curl -sS --fail-with-body "https://api.anthropic.com/v1/agents/$AGENT_ID?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  --json "$(jq -n --argjson version "$AGENT_VERSION" '{version: $version, model: "claude-sonnet-4-6"}')"

Migrazione

Da un ciclo agente dell'API Messages

Cosa smetti di gestire

Migrazione

Da un ciclo agente dell'API Messages

Cosa smetti di gestire

Confronto del codice

Cosa controlli ancora

Da Claude Agent SDK

Cosa cambia

Confronto del codice

Funzionalità che passano al tuo client

Elenco di controllo della migrazione

Migrazione tra versioni di modello