---
title: Démarrer une session
url: https://platform.claude.com/docs/fr/managed-agents/sessions
description: Créez une session pour exécuter votre agent et commencer à exécuter des tâches.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

Une session est une instance d'agent au sein d'un environnement. Chaque session référence un [agent](https://platform.claude.com/docs/fr/managed-agents/agent-setup) et un [environnement](https://platform.claude.com/docs/fr/managed-agents/environments) (tous deux créés séparément), et conserve l'historique de conversation sur plusieurs interactions. Les sessions suivent un cycle de vie en deux étapes : d'abord [créer la session](https://platform.claude.com/docs/fr/managed-agents/sessions#creating-a-session), puis [envoyer un événement utilisateur](https://platform.claude.com/docs/fr/managed-agents/sessions#starting-the-session) pour démarrer le travail. Vous pouvez également regrouper les deux étapes en un seul appel avec [`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`)](https://platform.claude.com/docs/fr/managed-agents/sessions#seed-the-session-with-initial-events).

## Créer une session

Une session nécessite un ID `agent` et un ID `environment`. Les agents sont des ressources versionnées ; transmettre l'ID `agent` (csharp, go: `Agent`) sous forme de chaîne crée la session avec la dernière version de l'agent.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID"
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id
  )
  ```
</CodeGroup>

Pour épingler une session à une version spécifique de l'agent, transmettez un objet. Cela vous permet de contrôler exactement quelle version s'exécute et d'échelonner indépendamment le déploiement des nouvelles versions.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": {"type": "agent", "id": "'"$AGENT_ID"'", "version": 1},
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent:
    type: agent
    id: $AGENT_ID
    version: 1
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  pinned_session = client.beta.sessions.create(
      agent={"type": "agent", "id": agent.id, "version": 1},
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const pinnedSession = await client.beta.sessions.create({
    agent: { type: "agent", id: agent.id, version: 1 },
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var pinnedSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentParams
      {
          Type = BetaManagedAgentsAgentParamsType.Agent,
          ID = agent.ID,
          Version = 1,
      },
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  pinnedSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
  			Type:    anthropic.BetaManagedAgentsAgentParamsTypeAgent,
  			ID:      agent.ID,
  			Version: anthropic.Int(1),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var pinnedSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentParams.builder()
          .type(BetaManagedAgentsAgentParams.Type.AGENT)
          .id(agent.id())
          .version(1)
          .build())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $pinnedSession = $client->beta->sessions->create(
      agent: ['type' => 'agent', 'id' => $agent->id, 'version' => 1],
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  pinned_session = client.beta.sessions.create(
    agent: {type: :agent, id: agent.id, version: 1},
    environment_id: environment.id
  )
  ```
</CodeGroup>

### Amorcer la session avec des événements initiaux

Vous pouvez créer une session et démarrer son travail en un seul appel. `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) est un tableau facultatif d'[événements](https://platform.claude.com/docs/fr/managed-agents/reference#event-types) initiaux à envoyer à la session lors de sa création, traités dans l'ordre. Il prend en charge les événements `user.message` et [`user.define_outcome`](https://platform.claude.com/docs/fr/managed-agents/define-outcomes), et accepte un maximum de 50 événements. Une liste non vide démarre la boucle de l'agent dans le même appel : la session est créée directement avec le statut `running`, sans requête supplémentaire.

L'exemple suivant crée une session avec un seul `user.message` dans `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) :

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "initial_events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  initial_events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  seeded_session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      initial_events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  # Les initial_events ne sont pas renvoyés dans la réponse de création ; relisez-les
  # depuis la liste d'événements de la session.
  for event in client.beta.sessions.events.list(seeded_session.id):
      if event.type == "user.message":
          for block in event.content:
              if block.type == "text":
                  print(f"Seeded event: {block.text}")
  ```

  ```typescript TypeScript
  const seededSession = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });

  // Les initial_events ne sont pas renvoyés dans la réponse de création ; listez les
  // événements de la session pour relire le message initial.
  for await (const event of client.beta.sessions.events.list(seededSession.id)) {
    if (event.type === "user.message") {
      for (const block of event.content) {
        if (block.type === "text") {
          console.log(`Seeded event: ${block.text}`);
        }
      }
    }
  }
  ```

  ```csharp C#
  var seededSession = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      InitialEvents =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  // Les initial_events ne sont pas renvoyés dans la réponse de création ; relisez-les
  // depuis la liste d'événements de la session.
  var seededEvents = await client.Beta.Sessions.Events.List(seededSession.ID);
  await foreach (var sessionEvent in seededEvents.Paginate())
  {
      if (sessionEvent.TryPickUserMessage(out var userMessage))
      {
          foreach (var contentBlock in userMessage.Content)
          {
              if (contentBlock.TryPickBetaManagedAgentsTextBlock(out var textBlock))
              {
                  Console.WriteLine($"Seeded event: {textBlock.Text}");
              }
          }
      }
  }
  ```

  ```go Go
  seededSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	InitialEvents: []anthropic.BetaSessionNewParamsInitialEventUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  // Les initial_events ne sont pas renvoyés dans la réponse de création ; listez donc les
  // événements de la session pour relire le user.message injecté.
  seededEvents, err := client.Beta.Sessions.Events.List(ctx, seededSession.ID, anthropic.BetaSessionEventListParams{})
  if err != nil {
  	panic(err)
  }
  for _, event := range seededEvents.Data {
  	if event.Type != "user.message" {
  		continue
  	}
  	for _, contentBlock := range event.AsUserMessage().Content {
  		if contentBlock.Type == "text" {
  			fmt.Printf("Seeded event: %s\n", contentBlock.AsText().Text)
  		}
  	}
  }
  ```

  ```java Java
  var seededSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addInitialEvent(BetaManagedAgentsUserMessageEventParams.builder()
          .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
          .addTextContent("List the files in the working directory.")
          .build())
      .build());
  // Les initial_events ne sont pas renvoyés dans la réponse de création ; lister les
  // événements de la session pour relire le user.message initial.
  for (var event : client.beta().sessions().events().list(seededSession.id()).autoPager()) {
      if (event.isUserMessage()) {
          for (var contentBlock : event.asUserMessage().content()) {
              if (contentBlock.isText()) {
                  IO.println("Seeded event: " + contentBlock.asText().text());
              }
          }
      }
  }
  ```

  ```php PHP
  $seededSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      initialEvents: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );

  // les initial_events ne sont pas renvoyés dans la réponse de création ; les relire
  // depuis la liste d'événements de la session.
  $seededEvents = $client->beta->sessions->events->list($seededSession->id);
  foreach ($seededEvents->getItems() as $event) {
      if ($event->type === 'user.message') {
          echo "Seeded event: {$event->content[0]->text}\n";
      }
  }
  ```

  ```ruby Ruby
  seeded_session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )

  # Les initial_events ne sont pas renvoyés dans la réponse de création ; relisez-les depuis
  # la liste d'événements de la session.
  client.beta.sessions.events.list(seeded_session.id).auto_paging_each do |event|
    next unless event.type == :"user.message"
    event.content.each do |block|
      puts "Seeded event: #{block.text}" if block.type == :text
    end
  end
  ```
</CodeGroup>

Aucun autre type d'événement n'est accepté. Les événements qui répondent à un tour de l'agent (`user.tool_confirmation`, `user.tool_result` et `user.custom_tool_result`) ne sont pas acceptés car aucun tour de l'agent n'existe encore, et `user.interrupt` n'est pas accepté car il n'y a aucun tour à arrêter. Contrairement à `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) sur un déploiement planifié, les `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) d'une session n'acceptent pas `system.message`.

Chaque événement de `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) est validé et persisté avant le retour de la réponse de création, dans l'ordre de la liste, avec un ID attribué par le serveur, exactement comme si vous l'aviez publié sur le point de terminaison d'[envoi d'événements](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming#send-events) immédiatement après la création. Les règles de contenu par événement sont également les mêmes que sur ce point de terminaison. Une liste vide équivaut à omettre le champ. La validation est en tout-ou-rien : si un événement échoue à la validation, toute la requête est rejetée et aucune session n'est créée.

La requête de création est rejetée dans les cas suivants :

| Condition                                                                                                                                                               | Statut |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Plus d'un événement `user.define_outcome`                                                                                                                               | 400    |
| Un événement `user.define_outcome` sans `rubric`                                                                                                                        | 400    |
| Plus de 100 [blocs de contenu `document`](https://platform.claude.com/docs/fr/build-with-claude/files#document-blocks) provenant de fichiers sur l'ensemble de la liste | 400    |
| Un corps de requête de plus de 32 Mo                                                                                                                                    | 413    |

Un événement `user.define_outcome` dans `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) est accepté dans les mêmes conditions que l'envoi d'un tel événement à une session existante ; consultez [Définir des résultats](https://platform.claude.com/docs/fr/managed-agents/define-outcomes).

### Remplacer la configuration de l'agent pour une session

Vous pouvez transmettre `agent` (csharp, go: `Agent`) sous trois formes : une chaîne d'ID d'agent, un objet de version épinglée (`type: "agent"`) ou un objet de remplacements. La forme de remplacements modifie certaines parties de la configuration de l'agent pour une seule session. Utilisez-la pour essayer un modèle différent ou accorder un outil supplémentaire dans une session sans versionner l'agent. Pour la forme de remplacements, définissez `type` sur `agent_with_overrides` et transmettez l'`id` (csharp, go: `ID`) de l'agent et éventuellement une `version` (csharp, go: `Version`) (omettez `version` (csharp, go: `Version`) pour utiliser la dernière version de l'agent). Incluez ensuite l'un des champs `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) ou `skills` (csharp, go: `Skills`) avec les valeurs que la session doit utiliser.

Chaque champ remplaçable suit les trois mêmes règles :

* **Omettre le champ :** la session hérite de la valeur de la version de l'agent qu'elle référence.

* **Définir le champ sur `null`, ou sur un tableau vide pour les champs de type liste :** la session s'exécute avec ce champ effacé. Cette règle s'applique intégralement à `system` (csharp, go: `System`; ruby: `system_`) et `skills` (csharp, go: `Skills`). Il existe trois exceptions :

  * `model` ne peut jamais être effacé. Une session a toujours besoin d'un modèle, donc `model: null` renvoie une erreur 400 `agent_model_required`.
  * Effacer `tools` renvoie une erreur 400 lorsque les `skills` (csharp, go: `Skills`) effectifs de la session ne sont pas vides, car les skills nécessitent l'outil `read`. Sinon, `tools: null` et `tools: []` effacent le champ.
  * Effacer `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) renvoie une erreur 400 lorsque les `tools` (csharp, go: `Tools`) effectifs de la session contiennent encore un `mcp_toolset` qui référence l'un des serveurs de l'agent. Remplacez `tools` (csharp, go: `Tools`) dans la même requête pour supprimer ces entrées `mcp_toolset`, puis effacez `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).

* **Définir le champ sur une valeur :** la valeur remplace intégralement celle de l'agent. Les remplacements ne fusionnent jamais avec la configuration de l'agent, donc un remplacement de `tools` (csharp, go: `Tools`) doit lister tous les outils dont la session doit disposer. De même, un remplacement de `model` (csharp, go: `Model`) remplace intégralement l'objet `model` (csharp, go: `Model`) de l'agent, de sorte que l'`effort` (csharp, go: `Effort`) propre à l'agent n'est pas conservé. Pour exécuter la session à un niveau d'effort spécifique, définissez `effort` (csharp, go: `Effort`) dans l'objet `model` (csharp, go: `Model`) du remplacement. Un niveau que le modèle ne prend pas en charge renvoie une erreur 400, et un remplacement de `model` (csharp, go: `Model`) sans `effort` (csharp, go: `Effort`) s'exécute au niveau d'effort par défaut de ce modèle.

Les remplacements s'appliquent uniquement à la session que vous créez. Ils ne modifient pas la ressource de l'agent et ne créent pas de nouvelle version de l'agent, de sorte que les autres sessions qui référencent le même agent ne sont pas affectées.

Dans la réponse, l'objet `agent` (csharp, go: `Agent`) reflète la configuration avec laquelle la session s'exécute après l'application des remplacements. Son `id` (csharp, go: `ID`) et sa `version` (csharp, go: `Version`) identifient toujours l'agent et la version auxquels les remplacements sont appliqués. Cela vous permet de remonter d'une session à son agent de base.

L'exemple suivant démarre une session qui remplace le modèle et efface l'invite système :

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-sonnet-5-5"},
        "system": null
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # The response's `agent` is the resolved snapshot: each override replaces that
  # field for this session only, and the agent resource keeps its id and version.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-sonnet-5-5
    system: null
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  override_session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          "model": {"id": "claude-sonnet-5-5"},
          "system": None,  # clear the agent's system prompt for this session
      },
      environment_id=environment.id,
  )
  # L'agent de la réponse est l'instantané résolu avec les remplacements appliqués.
  print(f"Model: {override_session.agent.model.id}")
  print(f"System: {override_session.agent.system}")
  ```

  ```typescript TypeScript
  const overrideSession = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      model: { id: "claude-sonnet-5-5" },
      system: null // clear the agent's system prompt for this session
    },
    environment_id: environment.id
  });
  // L'agent de la réponse est l'instantané résolu avec les surcharges appliquées.
  console.log(`Model: ${overrideSession.agent.model.id}`);
  console.log(`System: ${overrideSession.agent.system}`);
  ```

  ```csharp C#
  var overrideSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeSonnet5_5,
          },
          System = null, // clear the agent's system prompt for this session
      },
      EnvironmentID = environment.ID,
  });
  // L'agent de la réponse est l'instantané résolu avec les remplacements appliqués.
  Console.WriteLine($"Model: {overrideSession.Agent.Model.ID.Raw()}");
  Console.WriteLine($"System: {overrideSession.Agent.System ?? "null"}");
  ```

  ```go Go
  overrideSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID: anthropic.BetaManagedAgentsModelClaudeSonnet5_5,
  			},
  			// Efface l'invite système de l'agent pour cette session.
  			System: param.Null[string](),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  // L'agent de la réponse est l'instantané résolu avec les overrides appliqués.
  fmt.Printf("Model: %s\n", overrideSession.Agent.Model.ID)
  fmt.Printf("System: %q\n", overrideSession.Agent.System)
  ```

  ```java Java
  var overrideSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_SONNET_5_5)
              .build())
          .system((String) null) // clear the agent's system prompt for this session
          .build())
      .environmentId(environment.id())
      .build());
  // L'agent de la réponse est l'instantané résolu avec les overrides appliqués.
  IO.println("Model: " + overrideSession.agent().model().id());
  IO.println("System: " + overrideSession.agent().system().orElse("null"));
  ```

  ```php PHP
  $overrides = BetaManagedAgentsAgentWithOverridesParams::with(
      id: $agent->id,
      type: 'agent_with_overrides',
      model: ['id' => 'claude-sonnet-5-5'],
  );
  // Effacer l'invite système de cette session. L'accès par tableau est essentiel ici :
  // create() retire les null des tableaux bruts et ::with() traite les arguments null comme omis.
  $overrides['system'] = null;

  $overrideSession = $client->beta->sessions->create(
      agent: $overrides,
      environmentID: $environment->id,
  );
  // L'agent de la réponse est l'instantané résolu avec les overrides appliqués.
  echo "Model: {$overrideSession->agent->model->id}\n";
  echo 'System: ' . ($overrideSession->agent->system ?? 'null') . "\n";
  ```

  ```ruby Ruby
  # Le remplacement de l'invite système est `system_` (underscore final) car
  # `system` seul est le Kernel#system de Ruby. Le définir à nil efface le prompt.
  override_session = client.beta.sessions.create(
    agent: Anthropic::Beta::BetaManagedAgentsAgentWithOverridesParams.new(
      type: :agent_with_overrides,
      id: agent.id,
      model: {id: "claude-sonnet-5-5"},
      system_: nil
    ),
    environment_id: environment.id
  )
  # L'agent de la réponse est l'instantané résolu avec les remplacements appliqués.
  puts "Model: #{override_session.agent.model.id}"
  puts "System: #{override_session.agent.system_.inspect}"
  ```
</CodeGroup>

#### Épingler la géographie d'inférence pour une session

Comme un remplacement de `model` (csharp, go: `Model`) remplace intégralement l'objet `model` (csharp, go: `Model`) de l'agent, il définit ou efface également l'épinglage de la [géographie d'inférence](https://platform.claude.com/docs/fr/manage-claude/data-residency) du modèle pour la session : un remplacement qui inclut `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) épingle la géographie qui traite les requêtes de modèle de la session, et un remplacement qui l'omet efface l'épinglage de l'agent, de sorte que la session suit le `default_inference_geo` de l'espace de travail. La valeur remplacée est validée par rapport aux `allowed_inference_geos` de l'espace de travail lors de la création de la session.

L'exemple suivant démarre une session à partir d'un agent dont le modèle n'a pas d'épinglage géographique, épingle les requêtes de modèle de la session à l'inférence aux États-Unis en incluant `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) dans le remplacement de `model` (csharp, go: `Model`), et affiche la valeur renvoyée dans le `agent.model` (csharp, go: `Agent.Model`) de la réponse :

<CodeGroup>
  ```bash cURL
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"}
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-opus-5-5
      inference_geo: us
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          # Remplace entièrement le `model` de l'agent : réindiquez `id`, ajoutez `inference_geo` pour épingler.
          "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
      },
      environment_id=environment.id,
  )
  print(f"Inference geo: {session.agent.model.inference_geo}")
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      // Remplace intégralement le `model` de l'agent : réindiquez `id`, ajoutez `inference_geo` pour épingler.
      model: { id: "claude-opus-5-5", inference_geo: "us" }
    },
    environment_id: environment.id
  });
  console.log(`Inference geo: ${session.agent.model.inference_geo}`);
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          // Remplace entièrement le `model` de l'agent : réindiquer `id`, ajouter `inference_geo` pour épingler.
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeOpus5_5,
              InferenceGeo = "us",
          },
      },
      EnvironmentID = environment.ID,
  });
  Console.WriteLine($"Inference geo: {session.Agent.Model.InferenceGeo}");
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			// Remplace entièrement le `model` de l'agent : réindiquez `id`, ajoutez `inference_geo` pour épingler.
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID:           anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  				InferenceGeo: anthropic.String("us"),
  			},
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  fmt.Printf("Inference geo: %s\n", session.Agent.Model.InferenceGeo)
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          // Remplace entièrement le `model` de l'agent : réindiquez `id`, ajoutez `inference_geo` pour épingler.
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
              .inferenceGeo("us")
              .build())
          .build())
      .environmentId(environment.id())
      .build());
  IO.println("Inference geo: " + session.agent().model().inferenceGeo().orElseThrow());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: BetaManagedAgentsAgentWithOverridesParams::with(
          id: $agent->id,
          type: 'agent_with_overrides',
          // Remplace entièrement le `model` de l'agent : réindiquez `id`, ajoutez `inference_geo` pour épingler.
          model: BetaManagedAgentsModelConfigParams::with(
              id: 'claude-opus-5-5',
              inferenceGeo: 'us',
          ),
      ),
      environmentID: $environment->id,
  );
  echo "Inference geo: {$session->agent->model->inferenceGeo}\n";
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: {
      type: :agent_with_overrides,
      id: agent.id,
      # Remplace entièrement le `model` de l'agent : réindiquez `id`, ajoutez `inference_geo` pour épingler.
      model: {id: "claude-opus-5-5", inference_geo: "us"}
    },
    environment_id: environment.id
  )
  puts "Inference geo: #{session.agent.model.inference_geo}"
  ```
</CodeGroup>

<Tip>
  L'agent définit le comportement de Claude au sein de la session, y compris le modèle, l'invite système, les outils et les serveurs MCP. Consultez [Définir votre agent](https://platform.claude.com/docs/fr/managed-agents/agent-setup) pour plus de détails.
</Tip>

### Définir un budget de session

Pour plafonner ce qu'une session peut dépenser, transmettez l'objet facultatif `budget` (csharp, go: `Budget`) lors de sa création. Un budget est un plafond strict sur le coût catalogue de la session : la plateforme tarifie tout ce que la session consomme aux tarifs catalogue publics, et la session cesse d'émettre de nouvelles requêtes de modèle dès que ce total cumulé atteint `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`). Définissez `type` (csharp, go: `Type`) sur `limit` et donnez à `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) un `amount` (csharp, go: `Amount`) et une `currency` (csharp, go: `Currency`). `amount` (csharp, go: `Amount`) est un nombre entier de cents américains écrit sous forme de chaîne, par exemple `"125"` pour 1,25 $. L'API accepte une chaîne plutôt qu'un nombre afin qu'aucun arrondi en virgule flottante ne soit jamais appliqué. `USD` est la seule devise actuellement prise en charge. Lorsque la session atteint le plafond, elle se met en pause et passe à l'état inactif avec la raison d'arrêt `budget_reached`. Le plafond est appliqué entre les requêtes de modèle, de sorte que la requête qui le franchit se termine d'abord et que le coût catalogue final de la session peut [dépasser légèrement le plafond](https://platform.claude.com/docs/fr/managed-agents/budgets#when-a-session-reaches-its-budget). Un budget ne peut être associé qu'à la création : vous pouvez le [modifier ou le supprimer](https://platform.claude.com/docs/fr/managed-agents/session-operations#updating-the-session-budget) ultérieurement, mais vous ne pouvez pas en ajouter un à une session créée sans budget.

L'exemple suivant crée une session avec un budget de 1,25 $ :

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "budget": {
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"}
      }
    }'
  ```

  ```bash CLI
  # Gardez le montant entre guillemets pour qu'il soit envoyé comme chaîne, et non comme nombre.
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID" \
    --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}'
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      budget={
          "type": "limit",
          "max_list_cost": {"amount": "125", "currency": "USD"},
      },
  )
  print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: { amount: "125", currency: "USD" }
    }
  });
  console.log(session.id, session.budget?.max_list_cost.amount); // sesn_01... 125
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Budget = new()
      {
          Type = BetaManagedAgentsBudgetLimitType.Limit,
          MaxListCost = new() { Amount = "125", Currency = BetaCurrency.Usd },
      },
  });
  Console.WriteLine($"{session.ID} {session.Budget?.MaxListCost.Amount}");  // sesn_01... 125
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
  		Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
  		MaxListCost: anthropic.BetaMonetaryAmountParam{
  			Amount:   "125",
  			Currency: anthropic.BetaCurrencyUsd,
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(session.ID, session.Budget.MaxListCost.Amount) // sesn_01... 125
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .budget(BetaManagedAgentsBudgetLimit.builder()
          .type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
          .maxListCost(BetaMonetaryAmount.builder()
              .amount("125")
              .currency(BetaCurrency.USD)
              .build())
          .build())
      .build());
  IO.println(session.id() + " " + session.budget().orElseThrow().maxListCost().amount());  // sesn_01... 125
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      budget: [
          'type' => 'limit',
          'max_list_cost' => ['amount' => '125', 'currency' => 'USD'],
      ],
  );
  echo "{$session->id} {$session->budget->maxListCost->amount}\n"; // sesn_01... 125
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: {amount: "125", currency: "USD"}
    }
  )
  puts "#{session.id} #{session.budget.max_list_cost.amount}" # sesn_01... 125
  ```
</CodeGroup>

Consultez [Budgets de session](https://platform.claude.com/docs/fr/managed-agents/budgets) pour savoir comment fonctionne l'application du budget, ce qui est comptabilisé dans le coût catalogue et comment les budgets se comportent dans les sessions multiagents.

## Authentification MCP via les coffres

Si votre agent utilise des outils MCP qui nécessitent une authentification, transmettez `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) lors de la création de la session pour référencer un coffre contenant des identifiants OAuth stockés. Anthropic gère l'actualisation des jetons en votre nom. Consultez [S'authentifier avec des coffres](https://platform.claude.com/docs/fr/managed-agents/vaults) pour savoir comment créer des coffres et enregistrer des identifiants.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "vault_ids": ["'"$VAULT_ID"'"]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  vault_ids:
    - $VAULT_ID
  YAML
  ```

  ```python Python
  vault_session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      vault_ids=[vault.id],
  )
  ```

  ```typescript TypeScript
  const vaultSession = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  });
  ```

  ```csharp C#
  var vaultSession = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      VaultIds = [vault.ID],
  });
  ```

  ```go Go
  vaultSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	VaultIDs:      []string{vault.ID},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var vaultSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addVaultId(vault.id())
      .build());
  ```

  ```php PHP
  $vaultSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      vaultIDs: [$vault->id],
  );
  ```

  ```ruby Ruby
  vault_session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  )
  ```
</CodeGroup>

## Démarrer la session

Créer une session sans `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) enregistre la session mais ne démarre aucun travail ; le sandbox de l'environnement commence son provisionnement dès la création de la session, de sorte que le premier appel d'outil n'a pas à l'attendre. Pour déléguer une tâche, envoyez des événements à la session à l'aide d'un [événement utilisateur](https://platform.claude.com/docs/fr/managed-agents/reference#event-types). Pour fournir plutôt le premier événement dans la requête de création, consultez [Amorcer la session avec des événements initiaux](https://platform.claude.com/docs/fr/managed-agents/sessions#seed-the-session-with-initial-events). La session agit comme une machine à états qui suit la progression tandis que les événements pilotent l'exécution réelle.

<CodeGroup>
  ```bash cURL
  curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions:events send \
    --session-id "$SESSION_ID" <<'YAML'
  events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  client.beta.sessions.events.send(
      session.id,
      events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  await client.beta.sessions.events.send(session.id, {
    events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });
  ```

  ```csharp C#
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  ```

  ```go Go
  if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  }); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().sessions().events().send(
      session.id(),
      EventSendParams.builder()
          .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
              .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
              .addTextContent("List the files in the working directory.")
              .build())
          .build());
  ```

  ```php PHP
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );
  ```

  ```ruby Ruby
  client.beta.sessions.events.send_(
    session.id,
    events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )
  ```
</CodeGroup>

Consultez [Flux d'événements de session](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming) pour savoir comment diffuser en streaming les réponses de l'agent et gérer les confirmations d'outils.

Consultez [Statuts de session](https://platform.claude.com/docs/fr/managed-agents/session-operations#session-statuses) pour connaître les statuts par lesquels passe une session.

## Étapes suivantes

<CardGroup cols={3}>
  <Card title="Opérations de session" icon="settings" href="https://platform.claude.com/docs/fr/managed-agents/session-operations">
    Récupérez, listez, mettez à jour, archivez et supprimez des sessions Claude Managed Agents.
  </Card>

  <Card title="Flux d'événements de session" icon="lightning" href="https://platform.claude.com/docs/fr/managed-agents/events-and-streaming">
    Envoyez des événements, diffusez les réponses en streaming, et interrompez ou redirigez votre session en cours d'exécution.
  </Card>

  <Card title="Déploiements planifiés" icon="arrows-clockwise" href="https://platform.claude.com/docs/fr/managed-agents/scheduled-deployments">
    Créez et gérez des déploiements avec l'API Claude : exécutez un agent selon une planification cron récurrente et inspectez son historique d'exécutions.
  </Card>
</CardGroup>