Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
O repositório de estado durável para agentes hospedados no Microsoft Foundry fornece armazenamento de chave-valor com suporte do servidor para dados JSON que devem persistir quando um contêiner do agente falha, reinicia ou é removido após um período ocioso. Use-o para armazenar pontos de verificação de estrutura, histórico de conversa gerenciado pelo aplicativo, artefatos intermediários e preferências do usuário.
Seu agente escreve e atualiza explicitamente os itens do armazenamento de estado. Ao contrário de sessões e conversas, a plataforma não preenche o repositório automaticamente. O repositório dá suporte a isolamento por usuário, marcas, simultaneidade otimista e expiração configurável.
Este artigo explica como particionar dados, gerenciar a identidade do chamador, criar e acessar repositórios e itens e trabalhar dentro dos limites de serviço. O armazenamento de estado está disponível apenas para agentes hospedados.
O que manter no armazenamento de estado
A computação de um agente hospedado é efêmera. Quando o contêiner é reiniciado ou a plataforma o remove após um período ocioso, o agente perde tudo o que grava no disco local fora de uma sessão. O armazenamento de estado armazena o estado que deve persistir além do contêiner.
O conteúdo típico inclui:
- Pontos de verificação do framework, para que um framework no modelo "traga seu próprio agente", como o LangGraph ou o Microsoft Agent Framework, possa retomar o estado do próprio grafo ou do fluxo de trabalho.
- Histórico de conversas que seu agente gerencia por conta própria, ou seja, o caso do protocolo Invocations em que a plataforma não armazena o histórico para ele.
- Artefatos gerados e trabalho intermediário necessários posteriormente.
- Perfis, preferências e outros dados de aplicativo de longa duração por usuário.
O armazenamento de estado não é a única opção. Um banco de dados, armazenamento de blobs ou outro repositório de propriedade do aplicativo funciona da mesma maneira. O repositório de estado remove a necessidade de provisionar e proteger esse armazenamento por conta própria e aplica o modelo de identidade do agente automaticamente.
Mantenha os valores pequenos o suficiente para carregá-los quando necessário. Um item tem limite de 1 MB, portanto binários grandes devem ser armazenados no armazenamento de blobs, enquanto o repositório armazena uma referência a eles.
Tip
Agentes de execução longa podem manter marcadores de progresso e pontos de verificação em massa em itens separados no mesmo repositório de estado. Para obter um padrão de recuperação, consulte Gerenciar o estado para agentes de execução longa.
Repositórios
Um FoundryStateStore cliente se associa a um nome de repositório que você escolher. Esse nome serve tanto como a identidade do armazenamento quanto como sua partição mais externa. Um repositório contém itens JSON chaveados que você pode ler, gravar, excluir e listar.
- O nome da loja é a identidade: você não pode alterar um nome de repositório após a criação, portanto, escolha um esquema de nomenclatura estável antecipadamente.
- Get-or-create é a operação no nível do armazenamento: Uma única chamada de get-or-create recupera o armazenamento ou o cria caso ele não exista. As opções de criação se aplicam somente na primeira criação, de modo que o serviço as ignora quando o repositório já existe. A gravação de um item não cria um armazenamento inexistente.
- Vida útil do item: uma janela de inatividade no nível do armazenamento remove os itens. O padrão é 30 dias e você pode configurar um repositório para que os itens nunca expirem. As gravações renovam a janela, e as leituras não. Você define essa opção na criação.
Dados de partição
O armazenamento fornece duas maneiras independentes de particionar dados e a maioria dos agentes precisa apenas de um deles.
-
Por nome de repositório: cada nome de repositório é sua própria partição. Os nomes podem conter
/, para que você possa usá-lo como um separador de hierarquia, como emcheckpoints/thread-abcouworkflow-state/run-42. Escolha essa partição quando o código que lê um item sempre tiver o identificador de partição disponível para recompilar o nome. - Por usuário final: um repositório criado com isolamento do usuário particiona seus itens por usuário final, portanto, um único nome de repositório é seguro para compartilhar entre os usuários de um agente multilocatário. Escolha esta partição quando o mesmo nome da loja for usado por mais de um usuário. Você define essa opção no momento da criação, e o armazenamento determina o usuário a partir da solicitação, em vez de qualquer informação que seu código forneça. Para obter detalhes, consulte a identidade do chamador.
Prefira a partição mais estreita que seu caminho de pesquisa possa reconstruir. Um nome de repositório que codifica um identificador só será útil se cada chamador que lê o item ainda tiver esse identificador. Quando uma pesquisa carrega apenas uma chave de item, como um carregador de ponto de verificação de estrutura normalmente faz, mantenha o nome do repositório simples e permita que o isolamento do usuário faça o particionamento.
Os dois eixos se combinam, mas mantenha-os separados quanto à natureza: um nome de armazenamento deve conter apenas escopo não relacionado ao usuário, como uma thread, uma execução ou um identificador de fluxo de trabalho.
Important
Não codificar um identificador de usuário final em um nome de repositório. Os nomes de armazenamento aparecem em contextos operacionais, como logs e mensagens de erro, e um nome gerado pelo seu próprio código não é uma identidade verificada. Use o isolamento do usuário para particionamento por usuário, para que a plataforma imponha o limite com base no chamador que ela estabeleceu, em vez de se basear em um valor fornecido pelo seu agente.
Identidade do chamador
O armazenamento de estado aplica o modelo de identidade do agente hospedado. No protocolo de container 2.0.0, cada solicitação que a plataforma encaminha para seu agente carrega um cabeçalho x-agent-foundry-call-id que identifica o solicitante, e o armazenamento determina a partir dele o usuário final em nome de quem a ação está sendo executada. Os SDKs do Foundry encaminham o cabeçalho nas chamadas de armazenamento para você, de modo que a maioria dos agentes nunca precise lidar com ele diretamente.
Duas consequências são importantes ao projetar com isso:
- O isolamento do usuário deriva da ID da chamada: em um armazenamento com isolamento por usuário, a partição é derivada do chamador identificado pela plataforma, não de qualquer informação que o seu agente envie. Um agente hospedado não fornece um identificador de usuário final próprio. Se o runtime emitir suas próprias solicitações HTTP em vez de usar um cliente SDK, encaminhe o cabeçalho inalterado e trate o valor como opaco.
- As execuções locais não dão suporte ao isolamento do usuário: a plataforma não fornece a ID de chamada fora da plataforma. Nem o Python nem .NET SDK podem impor o isolamento do usuário quando você executa o contêiner localmente. Teste os limites de isolamento do usuário com um agente hospedado implantado.
Transferir o ID da chamada para o trabalho posterior
As operações de item atuam em nome do chamador, e as operações de armazenamento não.
| Operation | Scope | Usuário interino |
|---|---|---|
create_item, set_item, get_item, delete_item, list_keys |
Os itens do armazenamento vinculado | Resolvido a partir do ID da chamada quando o armazenamento usa o isolamento do usuário |
| Obter ou criar para o armazenamento | A loja em si | Não resolvido; a operação é restrita ao armazenamento |
Por padrão, uma operação de item usa a ID de chamada da solicitação em que ela é executada, que é o que você deseja para o trabalho que é concluído durante essa solicitação.
O trabalho que continua após a solicitação não tem nenhum ID de chamada de contexto para herdar, como no caso de processamento em segundo plano ou de uma etapa que é retomada em um ciclo de vida posterior do processo. Cada operação em item aceita um identificador de chamada explícito neste caso. Capture-o enquanto você ainda tiver a solicitação, mantenha-o junto com o trabalho e repasse-o em cada operação de item, para que essas operações continuem sendo executadas em nome do solicitante original.
A ID de chamada identifica o chamador da solicitação atual e particiona apenas os itens dentro de um repositório isolado pelo usuário. Ele não particiona mais nada que seu contêiner armazene. Para arquivos, linhas de banco de dados ou caches que pertencem ao seu próprio código, identifique-os usando o ID da sessão e o ID do usuário, conforme descrito em Multiplexar usuários em uma sessão compartilhada.
Itens
Um item é uma chave e um valor JSON, com marcas de cadeia de caracteres opcionais.
- Os valores são json do aplicativo: o repositório não interpreta um valor de item. Serialize explicitamente seus modelos de estrutura ou domínio.
- As marcas são para filtragem: as marcas são rótulos de cadeia de caracteres simples, correspondentes com AND quando você lista chaves. Promova apenas os campos nos quais você precisa filtrar.
- A listagem retorna somente chaves: uma página de chaves é barata mesmo quando os valores são grandes, portanto, listagem e busca são etapas separadas.
-
Concorrência otimista: Cada item tem uma ETag. Use uma precondição
If-Matchpara operações de leitura-modificação-gravação em itens mutáveis, como contadores, em que uma atualização perdida poderia corromper o estado. Uma pré-condição com falha relata a ETag atual. -
Os pontos de verificação somente de anexação não precisam de pré-condições: quando cada salvamento grava uma nova chave, não há contenção de gravação, portanto, o caminho do ponto de verificação nunca precisa de
If-Match.
Criar uma loja e itens
O exemplo a seguir obtém ou cria um armazenamento isolado por usuário, escreve um item, lê esse item de volta e lista as chaves por tag. Get-or-create é a única chamada no nível do repositório que um agente precisa: ele busca o repositório ou cria-o com as opções que você passa quando o repositório 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 você não especifica um endpoint, o cliente resolve o endpoint do projeto a partir do ambiente, que a plataforma configura para um agente hospedado.
Limites de serviço
O serviço impõe esses limites. Se você violar um limite, o serviço retornará 400 Bad Request e nomeará o campo inválido na mensagem de erro.
| Campo | Limit |
|---|---|
| Nome da loja | 1 a 128 caracteres, exclusivos dentro do projeto e do agente. |
| Chave do item | 1 a 128 caracteres, únicos na loja. |
| Valor do item | Até 1 MB de JSON serializado. |
| Etiquetas da loja ou do item | Até 16 itens. Uma chave é de 1 a 64 caracteres e um valor é de até 256 caracteres. |
| Description | Até 1.024 caracteres. |
| Número de chaves por página da lista | 1 a 100, com valor padrão de 20. |