Migration

Claude Managed Agents remplace votre boucle d'agent écrite à la main par une infrastructure gérée. Cette page couvre les changements lorsque vous migrez à partir d'une boucle personnalisée construite sur l'API Messages ou à partir du Claude Agent SDK.

À partir d'une boucle d'agent API Messages

Si vous avez construit un agent en appelant messages.create dans une boucle while, en exécutant vous-même les appels d'outils et en ajoutant les résultats à l'historique de conversation, la plupart de ce code disparaît.

Ce que vous arrêtez de gérer

Comparaison de code

Avant (boucle API Messages, simplifiée) :

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

Après (Claude Managed Agents) :

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

Ce que vous contrôlez toujours

• Invite système et modèle : Mêmes champs, maintenant sur la définition de l'agent.
• Outils personnalisés : Toujours déclarés avec JSON Schema. L'exécution passe de la gestion en ligne à la réponse aux événements agent.custom_tool_use. Voir Flux d'événements de session.
• Contexte : Vous pouvez toujours injecter du contexte via l'invite système, les ressources de fichiers, ou les compétences.

À partir du Claude Agent SDK

Si vous avez construit avec le Claude Agent SDK, vous travaillez déjà avec les agents, les outils et les sessions en tant que concepts. La différence est l'endroit où ils s'exécutent : le SDK s'exécute dans un processus que vous exploitez, tandis que Managed Agents s'exécute dans l'infrastructure d'Anthropic. La plupart de la migration consiste à mapper les objets de configuration du SDK à leurs équivalents côté API.

Ce qui change

Comparaison de code

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

Après (Managed Agents) :

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

L'Agent et l'Environnement sont créés une fois et réutilisés dans les sessions. La fonction d'outil s'exécute toujours dans votre processus ; la différence est que vous lisez l'événement agent.custom_tool_use et envoyez le résultat explicitement au lieu que le SDK le distribue pour vous.

Fonctionnalités qui passent à votre client

Le compromis pour qu'Anthropic exécute la boucle d'agent est que quelques choses que le SDK gérait automatiquement deviennent la responsabilité de votre client.

Liste de contrôle de migration

1. Créez un environnement avec la mise en réseau et les runtimes dont votre agent a besoin.
2. Portez votre invite système et votre sélection d'outils vers une définition d'agent.
3. Remplacez votre boucle par sessions.create et sessions.stream.
4. Pour tous les fichiers locaux que l'agent lit, téléchargez-les via l'API Files et montez-les en tant que resources.
5. Pour tous les gestionnaires d'outils personnalisés, déplacez l'exécution dans votre boucle d'événements en tant que réponses aux événements agent.custom_tool_use.
6. Vérifiez avec une session de test avant de diriger le trafic de production vers le nouveau flux.

Migration entre les versions de modèle

Quand un nouveau modèle Claude est publié, la migration d'une intégration Claude Managed Agents est généralement un changement d'un seul champ : mettez à jour model sur votre définition d'agent et le changement prend effet sur la prochaine session que vous créez.

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"}')"

La plupart des changements de comportement au niveau du modèle documentés dans le guide de migration de l'API Messages ne nécessitent pas d'action de votre côté :

• Changements de paramètres de demande (valeurs par défaut max_tokens, configuration thinking) sont gérés par le runtime Claude Managed Agents. Ces champs ne sont pas exposés sur la définition de l'agent.
• Le remplissage préalable du message d'assistant n'existe pas dans le modèle de session basé sur les événements, donc sa suppression sur les modèles plus récents est un non-opération.
• L'échappement JSON des arguments d'outil est analysé par le runtime avant que vous receviez les événements agent.custom_tool_use. Vous voyez des données structurées, pas des chaînes brutes.

Les descriptions de comportement du guide de l'API Messages (ce que le modèle fait différemment) s'appliquent toujours. Les étapes de migration (comment modifier votre code de demande) ne s'appliquent pas.