Claude Platform Docs
Managed AgentsPremiers pas

Migration

Déplacez 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 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 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",
        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",
    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 plutôt qu'à chaque requête. Les champs max_uses, citations et cache_control ne sont pas disponibles. Consultez Restreindre les domaines de recherche web et de récupération web.
  • 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 envoi et réception d'événements.
Fonctions décorées 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 le 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 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 ; envoyez des événements user.tool_confirmation pour les outils always_ask.

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",
    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",
    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 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 Managed Agents
Mode planExécutez d'abord une session de planification uniquement, 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 PreToolUse / PostToolUseVotre client voit déjà chaque événement agent.custom_tool_use avant de répondre ; placez la logique à cet endroit. Pour les outils intégrés, utilisez permission_policy: always_ask.
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 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 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 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" < 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 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 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, 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?