Magasin d’état durable pour les agents hébergés dans Microsoft Foundry

Le magasin d’état persistant pour les agents hébergés dans Microsoft Foundry fournit un stockage clé-valeur côté serveur pour les données JSON qui doivent persister lorsqu’un conteneur d’agent tombe en panne, redémarre ou est évincé après une période d’inactivité. Utilisez-le pour stocker les points de contrôle de l’infrastructure, l’historique des conversations gérées par l’application, les artefacts intermédiaires et les préférences utilisateur.

Votre agent écrit et met à jour explicitement les éléments du magasin d’état. Contrairement aux sessions et aux conversations, la plateforme n’alimente pas automatiquement le stockage. Le magasin prend en charge l’isolation par utilisateur, les balises, l’accès concurrentiel optimiste et l’expiration configurable.

Cet article explique comment partitionner les données, gérer l’identité de l’appelant, créer des magasins et des éléments, et y accéder, ainsi que comment fonctionner dans les limites du service. Le stockage d’état est disponible uniquement pour les agents hébergés.

Éléments à conserver dans le magasin d’état

Les ressources de calcul d’un agent hébergé sont éphémères. Lorsque le conteneur redémarre ou que la plateforme la supprime après une période d’inactivité, votre agent perd tout ce qu’il écrit sur le disque local en dehors d’une session. Le store d’état contient l’état qui doit persister au-delà du conteneur.

Le contenu typique est le suivant :

  • Points de contrôle du framework, afin qu’un framework d’agent de type bring-your-own, tel que LangGraph ou Microsoft Agent Framework, puisse reprendre l’état de son propre graphe ou workflow.
  • Historique des conversations que votre agent gère lui-même, c’est-à-dire le cas de protocole Invocations où la plateforme ne stocke pas l’historique pour vous.
  • Artéfacts générés et résultats intermédiaires nécessaires à un tour suivant.
  • Profils, préférences et autres données d’application persistantes par utilisateur.

Le magasin d’états n’est pas la seule option. Une base de données, un stockage d’objets blob ou un autre espace de stockage propre à l’application fonctionne de la même façon. Le magasin d’état vous évite d’avoir à provisionner et à sécuriser vous-même ce stockage, et applique automatiquement le modèle d’identité de l’agent.

Gardez des valeurs suffisamment petites pour les récupérer à la demande. Un élément est limité à 1 Mo ; les binaires volumineux doivent donc être stockés dans le stockage d’objets blob, celui-ci conservant une référence à ceux-ci.

Tip

Les agents de longue durée peuvent conserver les marqueurs de progression et les points de contrôle en bloc dans des éléments distincts dans le même magasin d’états. Pour obtenir un modèle de récupération, consultez Gérer l’état pour les agents de longue durée.

Stores

Un FoundryStateStore client se lie à un nom de magasin que vous choisissez. Ce nom sert à la fois d’identité du magasin et sa partition la plus externe. Un magasin contient des éléments JSON clés que vous pouvez lire, écrire, supprimer et répertorier.

  • Le nom du magasin est l’identité : vous ne pouvez pas modifier un nom de magasin après la création. Choisissez donc un schéma de nommage stable à l’avance.
  • Get-or-create est l’opération au niveau du magasin : un seul appel à get-or-create récupère le magasin ou le crée s’il n’existe pas. Les options de création s’appliquent uniquement à la première création, de sorte que le service les ignore quand le magasin existe déjà. Une écriture d’élément ne crée pas un stockage inexistant.
  • Durée de vie des éléments : une fenêtre inactive au niveau du magasin supprime les éléments. La valeur par défaut est de 30 jours et vous pouvez configurer un magasin afin que les éléments n’expirent jamais. Les opérations d’écriture réinitialisent la fenêtre, pas les opérations de lecture. Vous définissez cette option lors de la création.

Données de partition

Le magasin vous offre deux façons indépendantes de partitionner des données, et la plupart des agents n’ont besoin que de l’un d’eux.

  • Par nom de magasin : chaque nom de magasin est sa propre partition. Les noms peuvent contenir /, de sorte que vous pouvez l’utiliser comme séparateur de hiérarchie, comme dans checkpoints/thread-abc ou workflow-state/run-42. Choisissez cette partition lorsque le code qui lit un élément a toujours l’identificateur de partition disponible pour reconstruire le nom.
  • Par utilisateur final : un magasin créé avec des partitions d’isolation utilisateur partitionne ses éléments par utilisateur final. Par conséquent, un nom de magasin unique est sûr à partager entre les utilisateurs d’un agent multilocataire. Choisissez cette partition lorsque le même nom de magasin sert plusieurs utilisateurs. Vous définissez cette option lors de la création, et le stockage détermine l’utilisateur à partir de la requête plutôt qu’à partir de ce que votre code transmet. Pour plus d’informations, consultez l’identité de l’appelant.

Préférez la partition la plus étroite que votre chemin de recherche peut reconstruire. Un nom de magasin qui encode un identificateur n’est utile que si chaque appelant qui lit l’élément a toujours cet identificateur. Lorsqu’une recherche ne contient que la clé de l’élément, comme c’est généralement le cas d’un chargeur de point de contrôle du framework, gardez un nom de magasin non hiérarchique et laissez l’isolation des utilisateurs assurer le partitionnement à la place.

Les deux axes se combinent, mais conservez-les distincts par nature : un nom de magasin ne doit inclure qu’une portée non liée à l’utilisateur, telle qu’un fil d’exécution, une exécution ou un identifiant de workflow.

Important

N’encodez pas d’identificateur d’utilisateur final dans un nom de magasin. Les noms des magasins apparaissent dans des interfaces opérationnelles telles que les journaux et les messages d’erreur, et un nom généré par votre propre code n’est pas une identité vérifiée. Utilisez l’isolation utilisateur pour le partitionnement par utilisateur. Par conséquent, la plateforme applique la limite de l’appelant qu’elle a établie plutôt qu’à partir d’une valeur fournie par votre agent.

Identité de l’appelant

Le magasin d’états applique le modèle d’identité de l’agent hébergé. Avec le protocole de conteneur 2.0.0, chaque requête que la plateforme achemine vers votre agent comporte un en-tête x-agent-foundry-call-id qui identifie l’appelant, et le store détermine l’utilisateur final effectif à partir de cet en-tête. Les SDK Foundry transmettent l’en-tête lors des appels de stockage à votre place, de sorte que la plupart des agents n’ont jamais à le gérer directement.

Deux conséquences sont importantes lorsque vous concevez avec elle :

  • L’isolation de l’utilisateur est dérivée de l’identifiant d’appel : dans un magasin avec isolation par utilisateur, la partition provient de l’appelant identifié par la plateforme, et non de ce que transmet votre agent. Un agent hébergé ne fournit pas d’identificateur d’utilisateur final propre. Si votre runtime émet ses propres requêtes HTTP au lieu d’utiliser un client sdk, transférez l’en-tête inchangé et traitez la valeur comme opaque.
  • Les exécutions locales ne prennent pas en charge l’isolation des utilisateurs : la plateforme ne fournit pas l’ID d’appel hors plateforme. Ni le Python ni le SDK .NET ne peuvent appliquer l’isolation utilisateur lorsque vous exécutez le conteneur localement. Testez les limites d’isolation utilisateur avec un agent hébergé déployé.

Reporter l’identifiant de l’appel dans les tâches différées

Les opérations sur les éléments s’exécutent pour le compte de l’appelant, contrairement aux opérations de boutique.

Operation Scope Utilisateur agissant
create_item, set_item, get_item, delete_item, list_keys Éléments dans le magasin lié Résolu à partir de l’ID d’appel lorsque le magasin utilise l’isolation utilisateur
Obtenir ou créer pour le magasin Magasin lui-même Non résolu ; l’opération est limitée au magasin

Par défaut, une opération sur un élément utilise l’identifiant d’appel de la requête dans laquelle elle s’exécute, ce qu’il faut pour le travail qui s’achève pendant cette requête.

Le travail qui se poursuit au-delà de la requête n’a pas d’identifiant d’appel ambiant à hériter, comme dans le cas d’un traitement en arrière-plan ou d’une étape qui reprend lors d’une exécution ultérieure du processus. Chaque opération sur un élément accepte un identifiant d’appel explicite pour ce cas. Capturez-la tant que vous disposez encore de la requête, transmettez-la avec le travail, puis renvoyez-la à chaque opération sur un élément, afin que ces opérations continuent de s’exécuter au nom de l’appelant d’origine.

L’ID de l’appel identifie l’appelant de la requête en cours et sert uniquement à partitionner les éléments dans un magasin isolé par utilisateur. Il ne partitionne rien d’autre de ce que votre conteneur stocke. Pour les fichiers, les lignes de base de données ou les caches qui appartiennent à votre propre code, indexez-les par l’ID de session et l’ID de l’utilisateur, comme décrit dans Multiplexer les utilisateurs dans une session partagée.

Objets

Un élément est une clé et une valeur JSON, avec des balises de chaîne facultatives.

  • Les valeurs correspondent au JSON de votre application : le stockage n’interprète pas la valeur d’un élément. Sérialisez explicitement votre framework ou vos modèles de domaine.
  • Les balises sont destinées au filtrage : les étiquettes sont des étiquettes de chaîne simples, mises en correspondance avec AND lorsque vous répertoriez des clés. Promouvez uniquement les champs sur lesquelles vous devez filtrer.
  • La liste renvoie uniquement les clés : une page de clés est bon marché même si les valeurs sont volumineuses, de sorte que la description et la récupération sont des étapes distinctes.
  • Concurrence optimiste : chaque élément possède un ETag. Utilisez une condition préalable If-Match pour les opérations de lecture-modification-écriture sur des éléments mutables, tels que les compteurs, pour lesquels une perte de mise à jour corromprait l’état. Une condition préalable ayant échoué signale l’ETag actuel.
  • Les points de contrôle d’ajout uniquement n’ont pas besoin de conditions préalables : lorsque chaque enregistrement écrit une nouvelle clé, il n’y a pas de contention d’écriture. Par conséquent, le chemin de point de contrôle n’a jamais besoin de If-Match.

Créer un magasin et des éléments

L’exemple suivant récupère ou crée un magasin isolé pour l’utilisateur, écrit un élément, le relit et répertorie les clés par balise. Get-or-create est le seul appel au niveau du magasin dont un agent a besoin : il extrait le magasin ou le crée avec les options que vous passez lorsque le magasin est absent.

from azure.ai.agentserver.core.storage import FoundryStateStore

# Fetch the store, or create it on first use
store = await FoundryStateStore.get_or_create(
    "checkpoints/thread-abc",
    user_isolation=True,
)

# Write an item; the value is your own application JSON
await store.set_item(
    "step-1",
    {"done": False, "attempt": 1},
    tags={"kind": "checkpoint"},
)

# Read it back
item = await store.get_item("step-1")
if item is not None:
    print(item.key, item.value["done"], item.etag)

# List keys by tag, then fetch only the values you need
page = await store.list_keys(tags={"kind": "checkpoint"}, limit=50, order="asc")
for key in page.keys:
    print(key.key, key.etag)

Lorsque vous ne passez pas de point de terminaison, le client résout le point de terminaison du projet à partir de l’environnement, que la plateforme définit pour un agent hébergé.

Limites de service

Le service applique ces limites. Si vous ne respectez pas une limite, le service retourne et nomme 400 Bad Request le champ non valide dans le message d’erreur.

Champ Limite
Nom du magasin de 1 à 128 caractères, uniques au sein du projet et pour l’agent.
Clé de l’élément 1 à 128 caractères, uniques dans le magasin.
Valeur de l’élément Jusqu’à 1 Mo de JSON sérialisé.
Étiquettes de magasin ou d’élément Jusqu’à 16 entrées. Une clé est de 1 à 64 caractères et une valeur maximale de 256 caractères.
Description Jusqu’à 1 024 caractères.
Clés par page de liste 1 à 100, avec une valeur par défaut de 20.