Azure Cosmos DB

Instalar os pacotes

dotnet add package Microsoft.Agents.AI.CosmosNoSql --prerelease
dotnet add package Azure.Identity

Configurar o histórico de chat do Cosmos DB

Use a extensão de identidade gerenciada para anexar CosmosChatHistoryProvider a ChatClientAgentOptions.

using Azure.Identity;
using Microsoft.Agents.AI;

var options = new ChatClientAgentOptions
{
    ChatOptions = new() { Instructions = "You are a helpful assistant." }
}.WithCosmosDBChatHistoryProviderUsingManagedIdentity(
    accountEndpoint: Environment.GetEnvironmentVariable("AZURE_COSMOS_ENDPOINT")!,
    databaseId: Environment.GetEnvironmentVariable("AZURE_COSMOS_DATABASE_NAME")!,
    containerId: Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTAINER_NAME")!,
    tokenCredential: new DefaultAzureCredential());

AIAgent agent = chatClient.AsAIAgent(options);

O inicializador de estado padrão cria uma ID de conversa. Forneça um inicializador CosmosChatHistoryProvider.State quando seu aplicativo precisar de roteamento explícito de conversação, locatário e usuário. Quando as IDs de locatário e de usuário estão presentes, o provedor usa uma chave de partição hierárquica.

Instalar o pacote

pip install agent-framework-azure-cosmos --pre

Configurar CosmosHistoryProvider

O provedor Python aceita uma credencial do Azure ou a chave da conta e usa session_id como chave de partição.

# 1. Create an Azure credential and a CosmosHistoryProvider for agent context
async with (
    AzureCliCredential() as credential,
    CosmosHistoryProvider(
        endpoint=cosmos_endpoint,
        database_name=cosmos_database_name,
        container_name=cosmos_container_name,
        credential=cosmos_key or credential,
    ) as history_provider,
    # 2. Create an agent that uses Cosmos for persisted conversation history.
    Agent(
        client=FoundryChatClient(
            project_endpoint=project_endpoint,
            model=model,
            credential=credential,
        ),
        name="CosmosHistoryAgent",
        instructions="You are a helpful assistant that remembers prior turns.",
        context_providers=[history_provider],
        default_options={"store": False},
    ) as agent,
):
    # 3. Create a session (session_id is used as the partition key).
    session = agent.create_session()

    # 4. Run a multi-turn conversation; history is persisted by CosmosHistoryProvider.
    response1 = await agent.run("My name is Ada and I enjoy distributed systems.", session=session)
    print(f"Assistant: {response1.text}")

    response2 = await agent.run("What do you remember about me?", session=session)
    print(f"Assistant: {response2.text}")
    print(f"Container: {history_provider.container_name}")

Armazene a versão serializada de AgentSession no armazenamento confiável do aplicativo quando os clientes precisarem recuperar o mesmo identificador de sessão posteriormente.

Prerequisites

• Uma conta Azure Cosmos DB e um banco de dados.
• Um projeto do Microsoft Foundry com implantações de modelos de chat e de embeddings.
• Acesso da identidade do Azure a ambos os recursos.

Instalar os pacotes

pip install agent-framework-azure-cosmos-memory agent-framework-foundry --pre

Configurar o provedor de memória

O mesmo projeto Foundry pode fornecer o modelo de chat, as incorporações e o modelo de extração de memória. Anexe o provedor usando context_providers.

def _build_agent(provider: CosmosMemoryContextProvider, credential: DefaultAzureCredential) -> Agent:
    """Build an agent that uses the memory provider and the same Foundry endpoint for chat."""
    return Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_ENDPOINT"],
            model=os.getenv("CHAT_MODEL", "gpt-4o-mini"),
            credential=credential,
        ),
        name="Memory Assistant",
        instructions="You are a helpful assistant with long-term memory about the user.",
        context_providers=[provider],
    )


async def user_scoped_memory() -> None:
    """Memory scoped to a stable user id, so it persists across sessions and threads."""
    credential = DefaultAzureCredential()
    provider = CosmosMemoryContextProvider(
        cosmos_endpoint=os.environ["COSMOS_ENDPOINT"],
        foundry_endpoint=os.environ["FOUNDRY_ENDPOINT"],
        embedding_model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-large"),
        chat_model=os.getenv("CHAT_MODEL", "gpt-4o-mini"),
        credential=credential,
    )
    agent = _build_agent(provider, credential)

    async with provider:
        session = agent.create_session()
        # Provider state is scoped by source id; set a stable user id there so memory
        # persists across sessions rather than being limited to this one.
        session.state.setdefault(provider.source_id, {})["user_id"] = "alice"
        first = await agent.run("I love hiking and I'm allergic to peanuts.", session=session)
        print("Assistant:", first.text)

        # A brand-new session for the same user still recalls the earlier facts.
        new_session = agent.create_session()
        new_session.state.setdefault(provider.source_id, {})["user_id"] = "alice"
        recall = await agent.run("What do you remember about me?", session=new_session)
        print("Assistant:", recall.text)

        # Let background extraction finish and persist before the client closes.
        await provider.flush()

Um user_id estável mantém a memória disponível entre sessões e threads. Sem isso, o provedor restringe a memória ao ID da sessão atual.

Processamento de memória

A extração de memória é executada em segundo plano após cada turno. Use o provedor como um gerenciador de contexto assíncrono ou chame flush() antes do desligamento para que a extração pendente seja concluída antes do fechamento dos clientes.

O provedor também dá suporte a prompts de extração personalizados, cadência do processador, limites de confiança, tipos de memória e limites de recuperação.