Azure Cosmos DB (la base de datos de Azure Cosmos)

Instalación de los paquetes

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

Configuración del historial de chats de Cosmos DB

Use la extensión managed-identity para asociar 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);

El inicializador de estado predeterminado crea un identificador de conversación. Proporcione un inicializador CosmosChatHistoryProvider.State cuando su aplicación necesite un enrutamiento explícito de conversaciones, inquilinos y usuarios. Cuando los identificadores de inquilino y de usuario están presentes, el proveedor usa una clave de partición jerárquica.

Instalar el paquete

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

Configurar CosmosHistoryProvider

El proveedor de Python acepta una credencial de Azure o una clave de cuenta y usa session_id como clave de partición.

# 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}")

Conserve el serializado AgentSession en el almacenamiento de aplicaciones de confianza cuando los clientes necesiten recuperar el mismo identificador de sesión más adelante.

Prerequisites

• Una cuenta y una base de datos de Azure Cosmos DB.
• Un proyecto de Microsoft Foundry con implementaciones de modelos de chat y de incrustación.
• Acceso de identidad de Azure a ambos recursos.

Instalación de los paquetes

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

Configuración del proveedor de memoria

El mismo proyecto foundry puede proporcionar el modelo de chat, las incrustaciones y el modelo de extracción de memoria. Conecte el proveedor a travé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()

Un user_id estable mantiene la memoria disponible a través de sesiones e hilos. Sin uno, el proveedor limita la memoria al identificador de sesión actual.

Procesamiento de memoria

La extracción de memoria se ejecuta en segundo plano después de cada turno. Use el proveedor como gestor de contexto asíncrono o llame a flush() antes del apagado para que se complete cualquier extracción pendiente antes de que los clientes se cierren.

El proveedor también admite solicitudes de extracción personalizadas, cadencia del procesador, umbrales de confianza, tipos de memoria y límites de recuperación.