Almacén de estado duradero para agentes hospedados de Microsoft Foundry

El almacén de estado duradero para los agentes hospedados de Microsoft Foundry proporciona un almacenamiento de clave-valor respaldado por servidor para datos JSON que deben persistir cuando un contenedor de agente se bloquea, se reinicia o es desalojado tras un período de inactividad. Úselo para almacenar puntos de control de marco, historial de conversaciones administradas por la aplicación, artefactos intermedios y preferencias de usuario.

El agente escribe y actualiza explícitamente los elementos de almacén de estado. A diferencia de las sesiones y las conversaciones, la plataforma no rellena automáticamente el almacén. El almacenamiento admite aislamiento por usuario, etiquetas, control de concurrencia optimista y expiración configurable.

En este artículo se explica cómo crear particiones de datos, administrar la identidad del autor de la llamada, crear y acceder a almacenes y elementos, y trabajar dentro de los límites de servicio. El almacén de estados solo está disponible para los agentes hospedados.

Qué mantener en el almacén de estado

La capacidad de cómputo de un agente hospedado es efímera. Cuando el contenedor se reinicia o la plataforma lo expulsa después de un período de inactividad, el agente pierde todo lo que escribe en el disco local fuera de una sesión. El almacén de estado contiene el estado que debe persistir más allá del ciclo de vida del contenedor.

Entre los contenidos típicos se incluyen:

  • Puntos de control del marco de trabajo, para que un marco de trabajo de agente propio, como LangGraph o Microsoft Agent Framework, pueda reanudar su propio grafo o el estado de su flujo de trabajo.
  • Historial de conversaciones que tu agente gestiona por sí mismo, es decir, el caso del protocolo Invocations en el que la plataforma no almacena el historial por ti.
  • Artefactos generados y trabajo intermedio que necesita un turno posterior.
  • Perfiles, preferencias y otros datos persistentes de la aplicación por usuario.

El almacén de estado no es la única opción. Una base de datos, un almacenamiento de blobs u otro almacén que pertenece a la aplicación funciona de la misma manera. El almacén de estado elimina la necesidad de aprovisionar y proteger ese almacenamiento usted mismo y aplica automáticamente el modelo de identidad del agente.

Mantener los valores lo suficientemente pequeños como para obtenerlos bajo demanda. Un elemento tiene un límite de 1 MB, por lo que los binarios grandes deben almacenarse en el almacenamiento de blobs, y el almacén mantiene una referencia a ellos.

Tip

Los agentes de larga duración pueden mantener los marcadores de progreso y los puntos de control masivos en elementos independientes del mismo almacén de estado. Para consultar un patrón de recuperación, consulte Gestionar el estado de los agentes de larga duración.

Tiendas

Un cliente FoundryStateStore se asocia a un nombre de tienda que usted elija. Ese nombre actúa como identidad del almacén y su partición más externa. Un almacén contiene elementos JSON con clave que se pueden leer, escribir, eliminar y enumerar.

  • El nombre del almacén es la identidad: no se puede cambiar un nombre de almacén después de la creación, por lo que elija un esquema de nomenclatura estable por adelantado.
  • Get-or-create es una operación a nivel de almacén: una sola llamada a get-or-create obtiene el almacén o lo crea si no existe. Las opciones de creación solo se aplican en la primera creación, por lo que el servicio los omite cuando el almacén ya existe. Una escritura de un elemento no crea un almacén si no existe.
  • Tiempo de vida del elemento: un periodo de inactividad a nivel de almacén elimina los elementos. El valor predeterminado es de 30 días y puede configurar un almacén para que los elementos nunca expiren. Las escrituras renuevan la ventana, mientras que las lecturas no lo hacen. Configuras esta opción al crearla.

Partición de datos

El almacén proporciona dos formas independientes de crear particiones de datos y la mayoría de los agentes solo necesitan uno de ellos.

  • Por nombre de tienda: Cada nombre de tienda es su propia partición. Los nombres pueden contener /, por lo que puede usarlo como separador de jerarquía, como en checkpoints/thread-abc o workflow-state/run-42. Elija esta partición cuando el código que lee un elemento siempre tenga el identificador de partición disponible para volver a generar el nombre.
  • Por usuario final: un almacén creado con aislamiento de usuario divide sus elementos por usuario final, por lo que un único nombre de almacén es seguro para compartir entre los usuarios de un agente multiinquilino. Elija esta partición cuando el mismo nombre de almacén sirva a más de un usuario. Esta opción se establece al crearla, y el almacén de datos determina el usuario a partir de la solicitud en lugar de hacerlo a partir de cualquier valor que pase tu código. Para obtener más información, consulte Identidad del autor de la llamada.

Prefiere la partición más específica que pueda reconstruir su ruta de búsqueda. Un nombre de almacén que codifica un identificador solo es útil si cada llamador que lee el elemento todavía tiene ese identificador. Cuando una búsqueda incluye solo una clave del elemento, como suele hacer un cargador de puntos de control del marco de trabajo, conserve el nombre del almacén plano y deje que el aislamiento de usuarios se encargue de la partición.

Los dos ejes se combinan, pero deben mantenerse separados conceptualmente: el nombre del almacén solo debe incluir un ámbito no relacionado con el usuario, como un subproceso, una ejecución o un identificador de flujo de trabajo.

Important

No codifique un identificador de usuario final en un nombre de almacén. Los nombres de los almacenes aparecen en contextos operativos, como registros y mensajes de error, y un nombre que genera su propio código no es una identidad verificada. Utilice el aislamiento de usuario para el particionamiento por usuario, de modo que la plataforma aplique el aislamiento en función del llamante que haya identificado, en lugar de basarse en un valor proporcionado por su agente.

Identidad del autor de llamada

El almacén de estado aplica el modelo de identidad del agente alojado. En el protocolo de contenedor 2.0.0, cada solicitud que la plataforma dirige a su agente lleva un encabezado x-agent-foundry-call-id que identifica al llamante, y la tienda determina a partir de él qué usuario final está actuando. Los SDK de Foundry reenvían la cabecera en las llamadas a store por ti, por lo que la mayoría de los agentes nunca la gestionan directamente.

Dos consecuencias importan al diseñar con él:

  • El aislamiento del usuario se deriva del ID de llamada: en un almacén de datos con aislamiento por usuario, la partición procede del llamante que la plataforma ha identificado, no de ningún dato que envíe su agente. Un agente hospedado no proporciona un identificador de usuario final propio. Si el tiempo de ejecución emite sus propias solicitudes HTTP en lugar de usar un cliente del SDK, reenvíe el encabezado sin cambios y trate el valor como opaco.
  • Las ejecuciones locales no admiten el aislamiento de usuario: la plataforma no proporciona el identificador de llamada fuera de la plataforma. Ni el SDK de Python ni .NET pueden aplicar el aislamiento de usuario al ejecutar el contenedor localmente. Pruebe los límites de aislamiento de usuario con un agente hospedado implementado.

Trasladar el identificador de llamada al trabajo aplazado

Las operaciones sobre elementos actúan en nombre de quien realiza la llamada, y las operaciones del almacenamiento no lo hacen.

Operation Ámbito Usuario actuante
create_item, set_item, get_item, delete_item, list_keys Los elementos del almacén vinculado Se resuelve a partir del identificador de llamada cuando el almacén usa aislamiento de usuarios
Obtener o crear para el almacén La propia tienda Sin resolver; la operación se limita al almacén

De forma predeterminada, una operación de un elemento usa el ID de llamada de la solicitud en la que se ejecuta, que es lo habitual para el trabajo que termina durante esa solicitud.

El trabajo que continúa después de la solicitud no tiene ningún ID de llamada de contexto del que heredar, como ocurre con el procesamiento en segundo plano o con un paso que se reanuda en un ciclo de vida posterior del proceso. Cada operación de elemento acepta un identificador de llamada explícito para este caso. Captúrelo mientras siga teniendo la solicitud, llévelo junto con el trabajo y páselo de nuevo en cada operación sobre elementos, para que esas operaciones sigan actuando en nombre de quien hizo la llamada original.

El ID de llamada identifica a la persona que hizo la llamada de la solicitud actual y solo divide los elementos dentro de un almacén aislado para cada usuario. No particiona nada más de lo que almacena su contenedor. En el caso de los archivos, las filas de la base de datos o las cachés que gestiona su propio código, use como clave el identificador de sesión y el identificador de usuario, tal como se describe en Multiplexar usuarios en una sesión compartida.

Productos

Un elemento es una clave y un valor JSON, con etiquetas de cadena opcionales.

  • Los valores son el JSON de la aplicación: el almacén no interpreta un valor de elemento. Serialice explícitamente el marco o los modelos de dominio.
  • Las etiquetas son para filtrar: las etiquetas son etiquetas de cadena simples, coincide con AND al enumerar las claves. Promueva solo los campos en los que necesita filtrar.
  • Enumerar solo devuelve claves: una página de claves es barata incluso cuando los valores son grandes, por lo que la enumeración y la captura son pasos independientes.
  • Concurrencia optimista: Cada elemento tiene una ETag. Utilice una If-Match precondición para las operaciones de lectura-modificación-escritura en elementos mutables, como los contadores, en los que una actualización perdida corrompería el estado. Si falla una condición previa, se devuelve el ETag actual.
  • Los puntos de control de solo anexión no necesitan condiciones previas: cuando cada guardado escribe una clave nueva, no hay contención de escritura, por lo que la ruta de acceso del punto de control nunca necesita If-Match.

Creación de un almacén y elementos

En el ejemplo siguiente se obtiene o crea un almacén aislado del usuario, se escribe un elemento, se vuelve a leer y se enumeran las claves por etiqueta. Get-or-create es la única llamada en el nivel de almacén que necesita un agente: recupera el almacén o lo crea con las opciones que se le pasen si el almacén no existe.

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)

Cuando no se especifica un endpoint, el cliente obtiene el endpoint del proyecto a partir del entorno, que la plataforma configura para un agente alojado.

Límites de servicio

El servicio aplica estos límites. Si infringe un límite, el servicio devuelve 400 Bad Request y asigna un nombre al campo no válido en el mensaje de error.

Campo Limit
Nombre del almacén 1-128 caracteres, únicos dentro del proyecto y el agente.
Clave del elemento 1-128 caracteres, únicos dentro de la tienda.
Valor del elemento Hasta 1 MB de JSON serializado.
Etiquetas de almacén o elemento Hasta 16 entradas. Una clave es de 1 a 64 caracteres y un valor es de hasta 256 caracteres.
Description Hasta 1024 caracteres.
Claves por página de lista 1-100, con un valor predeterminado de 20.