Armazenamento de estado durável para agentes alojados no Microsoft Foundry

A durable state store para agentes alojados no Microsoft Foundry fornece armazenamento chave-valor suportado por servidor para dados JSON que devem persistir quando um contentor de agente crasha, reinicia ou é despejado após um período de inatividade. Use-o para armazenar checkpoints do framework, histórico de conversas geridas pela aplicação, artefactos intermédios e preferências do utilizador.

O seu agente escreve e atualiza explicitamente os itens do armazenamento de estado. Ao contrário das sessões e conversas, a plataforma não preenche a loja automaticamente. A loja suporta isolamento por utilizador, etiquetas, concorrência otimista e expiração configurável.

Este artigo explica como particionar dados, gerir a identidade do chamador, criar e aceder a armazenamentos e itens, e trabalhar dentro dos limites do serviço. O armazenamento de estado está disponível apenas para agentes hospedados.

O que guardar na loja oficial

A computação de um agente hospedado é efémera. Quando o contentor reinicia ou a plataforma o despeja após um período de inatividade, o seu agente perde tudo o que escreve no disco local fora de uma sessão. O armazenamento do estado armazena o estado que tem de persistir para além do ciclo de vida do contentor.

Os conteúdos típicos incluem:

  • Pontos de verificação do framework, ou seja, um framework de trazer o seu próprio agente, como o LangGraph ou o Microsoft Agent Framework, pode retomar o seu próprio estado de grafo ou fluxo de trabalho.
  • Histórico de conversas que o seu agente gere por si, ou seja, no caso do protocolo Invocations, em que a plataforma não lhe armazena o histórico.
  • Geraram artefactos e trabalhos intermédios que um turno posterior precisa.
  • Perfis por utilizador, preferências e outros dados de aplicações de longa duração.

A loja estatal não é a única opção. Uma base de dados, um armazenamento de blobs ou outro armazenamento pertencente à aplicação funciona da mesma forma. A loja de estado elimina a necessidade de provisionar e proteger esse armazenamento por si próprio, e aplica automaticamente o modelo de identidade do agente.

Mantenha os valores suficientemente pequenos para serem obtidos conforme necessário. Um item tem um limite limitado a 1 MB, pelo que os binários grandes pertencem ao armazenamento em blobs, com a loja a guardar uma referência a eles.

Tip

Agentes de longa duração podem manter marcadores de progresso e pontos de controlo em massa em itens separados na mesma loja de estado. Para um padrão de recuperação, consulte Gerir o estado de agentes de longa duração.

Lojas

Um FoundryStateStore cliente associa-se a um nome de loja que escolhes. Esse nome serve tanto para a identidade da loja como para a sua partição mais exterior. Uma loja guarda itens JSON com chave que podes ler, escrever, eliminar e listar.

  • O nome da loja é a identidade: Não podes mudar o nome da loja após a criação, por isso escolhe um esquema de nomes estável desde o início.
  • Get-or-create é a operação ao nível da loja: uma única chamada get-or-create recupera a loja ou cria-a quando esta está ausente. As opções de criação aplicam-se apenas na primeira criação, por isso o serviço ignora-as quando a loja já existe. A escrita de um item não cria um armazenamento inexistente.
  • Vida útil dos itens: Uma janela de inatividade ao nível da loja remove itens. O padrão é 30 dias, e podes configurar uma loja para que os itens nunca expirem. As escritas renovam a janela, e as leituras não a renovam. Define esta opção na criação.

Dados de partição

A loja dá-te duas formas independentes de particionar dados, e a maioria dos agentes precisa de apenas uma delas.

  • Por nome de loja: Cada nome de loja constitui a sua própria partição. Os nomes podem conter /, por isso podes usá-lo como separador de hierarquia, como em checkpoints/thread-abc ou workflow-state/run-42. Escolha esta partição quando o código que lê um item tiver sempre o identificador de partição disponível para reconstruir o nome.
  • Por utilizador final: Uma loja criada com isolamento de utilizador particiona os seus itens por utilizador final, de modo que um único nome de loja é seguro para partilhar entre os utilizadores de um agente multiinquilino. Escolha esta partição quando o mesmo nome de loja for utilizado por mais do que um utilizador. Defines esta opção na criação, e a loja resolve o utilizador a partir do pedido em vez de qualquer coisa que o teu código transmite. Para mais detalhes, veja Identidade do Chamador.

Prefira a partição mais estreita que o seu caminho de pesquisa possa reconstruir. Um nome de loja que codifica um identificador só é útil se todos os chamadores que leem o item ainda tiverem esse identificador. Quando uma pesquisa inclui apenas a chave do item, como normalmente acontece com um carregador de checkpoints da framework, mantenha simples o nome do armazenamento e deixe que o isolamento do utilizador trate da particionação em vez disso.

Os dois eixos combinam-se, mas mantenha-os separados quanto à sua natureza: o nome do armazenamento deve incluir apenas um âmbito que não seja do utilizador, como um identificador de thread, execução ou fluxo de trabalho.

Importante

Não codifique um identificador de utilizador final num nome de loja. Os nomes das lojas aparecem em superfícies operacionais, como registos e mensagens de erro, e um nome que o seu próprio código constrói não é uma identidade verificada. Utilize o isolamento de utilizadores para o particionamento por utilizador, para que a plataforma imponha o limite com base no autor da chamada que identificou, em vez de se basear num valor fornecido pelo seu agente.

Identidade do chamador

A loja de estado aplica o modelo de identidade de agente hospedado. No protocolo de contentor 2.0.0, cada pedido que a plataforma encaminha para o seu agente inclui um cabeçalho x-agent-foundry-call-id que identifica o autor da chamada, e o armazenamento determina o utilizador final efetivo com base nele. Os SDKs da Foundry encaminham o cabeçalho nas chamadas da loja por si, por isso a maioria dos agentes nunca trata diretamente disso.

Duas consequências importam quando se desenha com ela:

  • O isolamento do utilizador deriva do ID da chamada: Num armazenamento com isolamento por utilizador, a partição é determinada pelo autor da chamada que a plataforma identificou, não por nada do que o seu agente transmitir. Um agente alojado não fornece um identificador de utilizador final próprio. Se o seu runtime emitir os seus próprios pedidos HTTP em vez de usar um cliente SDK, encaminhe o cabeçalho sem alterações e trate o valor como opaco.
  • As execuções locais não suportam isolamento do utilizador: A plataforma não fornece o ID da chamada fora da plataforma. Nem o SDK Python nem o .NET conseguem impor isolamento do utilizador quando executas o contentor localmente. Teste os limites de isolamento do utilizador com um agente alojado implementado.

Transfira o ID da chamada para o trabalho diferido

As operações de itens são executadas em nome do chamador, e as operações de armazenamento não o são.

Funcionamento Scope Utilizador em exercício
create_item, set_item, get_item, delete_item, list_keys Os itens na loja associada Resolvido a partir do ID da chamada quando a loja usa isolamento do utilizador
Obter ou criar para a loja A própria loja Não resolvido; a operação é ao nível da loja

Por predefinição, uma operação sobre um item utiliza o ID da chamada do pedido em que é executada, o que é o pretendido para trabalho que termina durante esse pedido.

Um trabalho que continua para além da requisição não tem um ID de chamada contextual para herdar, como acontece no processamento em segundo plano ou numa etapa que é retomada mais tarde, numa execução posterior do processo. Cada operação sobre um item aceita um identificador de chamada explícito neste caso. Captura-o enquanto ainda tens o pedido, leva-o juntamente com o trabalho e passa-o de volta a cada operação de item, para que essas operações continuem a representar o chamador original.

O ID da chamada identifica quem efetua a chamada do pedido atual e serve apenas para particionar os itens dentro de um armazenamento isolado por utilizador. Não divide em partições mais nada que o seu contentor armazene. Para ficheiros, linhas de base de dados ou caches que o seu próprio código controla, identifique-os pelo ID da sessão e pelo ID do utilizador, conforme descrito em Multiplexar utilizadores numa sessão partilhada.

Itens

Um item é uma chave e um valor JSON, com etiquetas de string opcionais.

  • Os valores são a sua aplicação JSON: A loja não interpreta o valor de um item. Serialize explicitamente a tua estrutura ou os teus modelos de domínio.
  • As etiquetas servem para filtrar: As etiquetas são rótulos simples de cadeias de caracteres, combinadas com o operador E ao listar chaves. Promova apenas os campos pelos quais precisa de filtrar.
  • Listagem devolve apenas chaves: Uma página de chaves é barata mesmo quando os valores são grandes, por isso listar e buscar são etapas separadas.
  • Concorrência otimista: Cada item transporta um ETag. Use uma If-Match pré-condição para operações de leitura-modificação-escrita em itens mutáveis, como contadores, onde uma atualização perdida corromperia o estado. Uma pré-condição falhada reporta o ETag atual.
  • Pontos de verificação só de acréscimo não precisam de pré-condições: Quando cada gravação é feita numa nova chave, não existe contenção de escrita, pelo que o caminho do ponto de verificação nunca precisa de If-Match.

Crie uma loja e artigos

O exemplo seguinte obtém ou cria um armazenamento isolado do utilizador, escreve um item, volta a lê-lo e lista as chaves por etiqueta. Get-or-create é a única chamada ao nível da loja que um agente precisa: recupera a loja ou cria-a com as opções que passa quando a loja está ausente.

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)

Quando não é especificado um endpoint, o cliente determina o endpoint do projeto a partir das variáveis de ambiente, definidas pela plataforma para um agente hospedado.

Limites de serviço

O serviço impõe estes limites. Se violar um limite, o serviço devolve 400 Bad Request e nomeia o campo inválido na mensagem de erro.

Field Limit
Nome da loja 1-128 caracteres, únicos dentro do projeto e do agente.
Chave do item 1-128 caracteres, único na loja.
Valor do item Até 1 MB de JSON serializado.
Etiquetas da loja ou do item Até 16 entradas. Uma chave é de 1 a 64 caracteres, e um valor pode ser até 256 caracteres.
Description Até 1.024 caracteres.
Chaves por página da lista 1-100, com predefinição de 20.