Claude Platform Docs
Managed AgentsPremiers pas

Migration

Migrez un agent existant construit sur l'API Messages ou le Claude Agent SDK vers Claude Managed Agents.

Claude Managed Agents remplace votre boucle d'agent écrite à la main par une infrastructure gérée. Cette page décrit 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 de l'API Messages

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

Ce que vous cessez de gérer

AvantAprès
Vous maintenez le tableau de l'historique de la conversation et le renvoyez à chaque tour.La session stocke l'historique côté serveur. Envoyez des événements, recevez des événements.
Vous parcourez les blocs de contenu tool_use, exécutez chaque outil et rebouclez avec des messages tool_result.Les outils préconstruits s'exécutent automatiquement dans le sandbox. Vous ne gérez que les outils personnalisés via les événements agent.custom_tool_use.
Vous provisionnez votre propre sandbox pour exécuter le code généré par l'agent.Le sandbox de la session gère l'exécution de code, les opérations sur les fichiers et bash.
Vous décidez quand la boucle est terminée.La session émet session.status_idle lorsque l'agent n'a plus rien à faire.

Comparaison de code

Avant (boucle de l'API Messages, simplifiée) :

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

Après (Claude Managed Agents) :

agent = client.beta.agents.create(
    name="Task Runner",
    model="claude-opus-5-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

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.
  • Paramètres de recherche web et de récupération web : mêmes champs allowed_domains, blocked_domains, max_content_tokens et user_location, désormais définis une seule fois sur les entrées web_search et web_fetch du tableau configs de l'ensemble d'outils de l'agent, au lieu de l'être à chaque requête. Les champs max_uses, citations et cache_control ne sont pas disponibles. Consultez Différences avec les outils de l'API Messages.
  • Contexte : vous pouvez toujours injecter du contexte via l'invite système, les ressources de fichiers ou les skills.

Depuis le 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 réside dans 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 majeure partie de la migration consiste à faire correspondre les objets de configuration du SDK à leurs équivalents côté API.

Ce qui change

Agent SDKManaged Agents
ClaudeAgentOptions(...) construit à chaque exécutionclient.beta.agents.create(...) une seule fois ; l'Agent est persisté et versionné côté serveur. Consultez Configuration de l'agent.
async with ClaudeSDKClient(...) ou query(...)client.beta.sessions.create(...) puis envoyez et recevez des événements.
Fonctions définies avec @tool, distribuées automatiquement par le SDKDéclarez-les comme {"type": "custom", ...} sur l'Agent ; votre client gère les événements agent.custom_tool_use et répond avec user.custom_tool_result. Consultez Outils.
Les outils intégrés s'exécutent dans votre processus sur votre système de fichiers{"type": "agent_toolset_20260401"} exécute les mêmes outils dans la sandbox de la session sur /workspace.
cwd, add_dirs pointent vers des chemins locauxTéléversez ou montez des fichiers en tant que ressources de session.
system_prompt et la hiérarchie CLAUDE.mdUne seule chaîne system sur l'Agent. Chaque mise à jour qui modifie l'agent produit une nouvelle version côté serveur ; épinglez les sessions à une version spécifique pour promouvoir une version ou revenir en arrière sans déploiement. Consultez Configuration de l'agent.
mcp_servers configurés et authentifiés en un seul endroitDéclarez les serveurs sur l'Agent ; fournissez les identifiants via un Vault sur la Session.
permission_mode, can_use_toolpermission_policy par outil (always_allow, always_ask ou auto) ; envoyez des événements user.tool_confirmation pour les appels qui se mettent en pause en attendant votre approbation.

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

Après (Managed Agents) :

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="weather-agent",
    model="claude-opus-5-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": "limited", "allow_package_managers": True},
    },
)

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:
        match event.type:
            case "agent.message":
                print(
                    "".join(
                        block.text for block in event.content if block.type == "text"
                    )
                )
            case "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}],
                        }
                    ],
                )
            case "session.status_idle":
                if event.stop_reason and event.stop_reason.type == "end_turn":
                    break

L'Agent et l'Environment sont créés une seule fois et réutilisés d'une session à l'autre. 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

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

Fonctionnalité du SDKApproche de Managed Agents
Mode planExécutez d'abord une session dédiée uniquement à la planification, puis une seconde session pour exécuter le plan.
Styles de sortie, commandes slashAppliquez-les dans votre client avant d'envoyer user.message ou après avoir reçu agent.message.
« Hooks » (crochets) PreToolUse / PostToolUseVotre client voit déjà chaque événement agent.custom_tool_use avant de répondre ; placez-y la logique. Pour les outils intégrés, utilisez permission_policy: always_ask pour examiner chaque appel. auto permet plutôt au serveur d'évaluer chaque appel, mais si le serveur évalue un appel comme sûr, celui-ci s'exécute sans atteindre votre client.
max_turnsComptez les tours côté 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 : créez une session avec client.beta.sessions.create() et diffusez ses événements en streaming avec client.beta.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 sous forme de 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èle

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 dans votre définition d'agent, et la modification prend effet à la prochaine session que vous créez.

ant apply agent.md
agent.md
---
name: Task Runner
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a task automation agent. Complete the task you are given end to end.

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 modifications des paramètres de requête (valeurs par défaut de max_tokens, configuration de thinking) sont gérées par le runtime Claude Managed Agents. Ces champs ne sont pas exposés dans 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, sa suppression sur les modèles plus récents est donc 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, et non 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 requête) ne s'appliquent pas.

Was this page helpful?