Migration

Claude Managed Agents remplace votre boucle d'agent écrite manuellement par une infrastructure gérée. Cette page couvre ce qui change lorsque vous migrez depuis une boucle personnalisée construite sur l'API Messages ou depuis le Claude Agent SDK.



Depuis une boucle d'agent basée sur l'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 majeure partie de ce code disparaît.



Ce que vous cessez 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-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,
                        }
                    ],
                }
            )

Après (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



Ce que vous contrôlez toujours

• Invite système et modèle : Mêmes champs, désormais sur la définition de l'agent.
• Outils personnalisés : Toujours déclarés avec JSON Schema. L'exécution passe d'une gestion en ligne à une réponse aux événements agent.custom_tool_use. Consultez 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.



Depuis le Claude Agent SDK

Si vous avez construit avec le Claude Agent SDK, vous travaillez déjà avec les concepts d'agents, d'outils et de sessions. La différence réside dans l'endroit où ils s'exécutent : le SDK s'exécute dans un processus que vous opérez, tandis que Managed Agents s'exécute dans l'infrastructure d'Anthropic. La majeure partie de la migration consiste à faire correspondre 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-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)

Après (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 et l'Environnement sont créés une seule fois et réutilisés entre 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 dispatche pour vous.



Fonctionnalités qui passent à votre client

La contrepartie du fait qu'Anthropic exécute la boucle d'agent est que quelques éléments que le SDK gérait automatiquement deviennent la responsabilité de votre client.



Liste de contrôle de migration

1. Créez un environnement avec le 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.events.stream.
4. Pour tous les fichiers locaux que l'agent lit, téléversez-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 versions de modèles

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

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

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 aucune action de votre part :

• Les changements de paramètres de requête (valeurs par défaut de max_tokens, configuration de thinking) sont gérés par le runtime de Claude Managed Agents. Ces champs ne sont pas exposés sur la définition de l'agent.
• Le préremplissage des messages de l'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 sans effet.
• L'échappement JSON des arguments d'outils est analysé par le runtime avant que vous ne receviez les événements agent.custom_tool_use. Vous voyez des données structurées, pas des chaînes brutes.

Les descriptions de comportement dans le 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 requête) ne s'appliquent pas.