Démarrer une session

Une session est une instance d'agent au sein d'un environnement. Chaque session référence un agent et un environnement (tous deux créés séparément), et maintient l'historique de conversation à travers plusieurs interactions. Les sessions suivent un cycle de vie en deux étapes : d'abord créer la session, puis envoyer un événement utilisateur pour démarrer le travail. Vous pouvez également regrouper les deux étapes en un seul appel avec initial_events.



Création d'une session

Une session nécessite un ID d'agent et un ID d'environment. Les agents sont des ressources versionnées ; passer l'ID d'agent sous forme de chaîne de caractères démarre la session avec la dernière version de l'agent.

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

Pour épingler une session à une version spécifique de l'agent, passez un objet. Cela vous permet de contrôler exactement quelle version s'exécute et de déployer progressivement de nouvelles versions de manière indépendante.

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



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 est un tableau optionnel d'événements 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, 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 :

SEEDED_SESSION_ID=$(ant beta:sessions create \
  --transform id --raw-output <<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
)

# Les initial_events ne sont pas renvoyés dans la réponse de création ; listez les
# événements de la session pour voir le message amorcé.
echo "Seeded event: $(ant beta:sessions:events list \
  --session-id "$SEEDED_SESSION_ID" \
  --format raw \
  --transform 'data.#(type=="user.message").content.0.text' --raw-output)"

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 aux initial_events d'un déploiement planifié, les initial_events d'une session n'acceptent pas system.message.

Chaque événement dans initial_events est validé et persisté avant que la réponse de création ne soit renvoyée, 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 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 de type tout ou rien : si un événement échoue à la validation, la requête entière est rejetée et aucune session n'est créée.

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

Un événement user.define_outcome dans initial_events est accepté dans les mêmes conditions que l'envoi d'un tel événement à une session existante ; consultez Définir les résultats.



Remplacer la configuration de l'agent pour une session

Vous pouvez passer agent sous trois formes : une chaîne de caractères d'ID d'agent, un objet de version épinglée (type: "agent"), ou un objet de remplacements. La forme avec remplacements modifie des 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 avec remplacements, définissez type sur agent_with_overrides et passez l'id de l'agent et éventuellement une version (omettez version pour utiliser la dernière version de l'agent). Incluez ensuite n'importe lequel parmi model, system, tools, mcp_servers ou 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 et skills. Il existe trois exceptions :
  • model n'est jamais effaçable. 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 effectifs de la session ne sont pas vides, car les compétences nécessitent l'outil read. Sinon, tools: null et tools: [] effacent le champ.
  • Effacer mcp_servers renvoie une erreur 400 lorsque les tools effectifs de la session contiennent encore un mcp_toolset qui référence l'un des serveurs de l'agent. Remplacez tools dans la même requête pour supprimer ces entrées mcp_toolset, puis effacez mcp_servers.
• Définir le champ sur une valeur : La valeur remplace intégralement la valeur de l'agent. Les remplacements ne fusionnent jamais avec la configuration de l'agent, donc un remplacement de tools doit lister chaque outil que la session doit avoir. Il existe une exception :
  • Un niveau effort à l'intérieur d'un remplacement de model par session n'est pas appliqué. Définissez plutôt effort sur l'agent.

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

Dans la réponse, l'objet agent reflète la configuration avec laquelle la session s'exécute après l'application des remplacements. Ses id et version identifient toujours l'agent et la version auxquels les remplacements sont appliqués. Cela vous permet de retracer une session jusqu'à son agent de base.

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

# Le champ `agent` de la réponse est l'instantané résolu : chaque surcharge remplace ce
# champ pour cette session uniquement, et la ressource agent conserve son id et sa version.
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML



Authentification MCP via les coffres

Si votre agent utilise des outils MCP qui nécessitent une authentification, passez vault_ids lors de la création de la session pour référencer un coffre contenant des identifiants OAuth stockés. Anthropic gère le rafraîchissement des jetons pour vous. Consultez S'authentifier avec les coffres pour savoir comment créer des coffres et enregistrer des identifiants.

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



Démarrage de la session

Créer une session sans initial_events enregistre la session mais ne démarre aucun travail ; le bac à sable de l'environnement est provisionné lorsque la session en a besoin pour la première fois. Pour déléguer une tâche, envoyez des événements à la session en utilisant un événement utilisateur. Pour fournir le premier événement dans la requête de création à la place, consultez Amorcer la session avec des événements initiaux. La session agit comme une machine à états qui suit la progression tandis que les événements pilotent l'exécution réelle.

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

Consultez Flux d'événements de session pour savoir comment diffuser les réponses de l'agent en streaming et gérer les confirmations d'outils.

Consultez Statuts de session pour connaître les statuts par lesquels passe une session.



Prochaines étapes