Azure Cosmos DB

Instale os pacotes

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

Configurar o histórico de chat do Cosmos DB

Utilize a extensão de identidade gerida 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 do estado predefinido cria um ID da conversa. Forneça um CosmosChatHistoryProvider.State inicializador quando a sua aplicação precisar de comunicação explícita, encaminhamento de inquilinos e utilizadores. Quando estão presentes IDs de inquilino e utilizador, o fornecedor utiliza uma chave de partição hierárquica.

Instale o pacote

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

Configurar CosmosHistoryProvider

O fornecedor Python aceita uma credencial do Azure ou uma chave de conta e usa a 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}")

Guarde a versão serializada de AgentSession no armazenamento fidedigno da aplicação quando os clientes precisarem de recuperar posteriormente o mesmo identificador de sessão.

Pré-requisitos

• Uma conta e base de dados Azure Cosmos DB.
• Um projeto Microsoft Foundry com implementações de modelos de chat e de incorporação vetorial.
• Acesso com identidade do Azure a ambos os recursos.

Instale os pacotes

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

Configurar o fornecedor de memória

O mesmo projeto Foundry pode fornecer o modelo de chat, embeddings e modelo de extração de memória. Anexe o fornecedor através de 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. Na sua ausência, o fornecedor limita a memória ao ID da sessão atual.

Processamento de memória

A extração de memória corre em segundo plano após cada turno. Utilize o provedor como gestor de contexto assíncrono ou chame flush() antes do encerramento para que a extração pendente seja concluída antes de os clientes fecharem.

O fornecedor também suporta prompts de extração personalizados, cadência do processador, limiares de confiança, tipos de memória e limites de recuperação.