Azure Cosmos DB, une base de données distribuée globale

Installer les packages

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

Configurer l’historique des conversations Cosmos DB

Utilisez l’extension d’identité managée pour attacher CosmosChatHistoryProvider à 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);

L’initialiseur d’état par défaut crée un ID de conversation. Fournissez un CosmosChatHistoryProvider.State initialiseur lorsque votre application nécessite un routage explicite de la conversation, du tenant et de l’utilisateur. Lorsque les ID de locataire et d’utilisateur sont présents, le fournisseur utilise une clé de partition hiérarchique.

Installer le package

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

Configurer CosmosHistoryProvider

Le fournisseur Python accepte des informations d’identification Azure ou une clé de compte et utilise la session_id clé de partition.

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

Conservez la sérialisation AgentSession dans le stockage d’applications approuvées lorsque les clients doivent récupérer le même identificateur de session ultérieurement.

Prerequisites

• Un compte et une base de données Azure Cosmos DB.
• Un projet Microsoft Foundry avec des déploiements de modèles conversationnels et d’intégration vectorielle.
• Accès d’identité Azure aux deux ressources.

Installer les packages

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

Configurer le fournisseur de mémoire

Le même projet Foundry peut fournir le modèle de conversation, les incorporations et le modèle d’extraction de mémoire. Associez le fournisseur de services à l’aide 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 stable maintient la mémoire disponible d’une session et d’un fil d’exécution à l’autre. Sans un, le fournisseur limite la mémoire à l’ID de session actuel.

Traitement de la mémoire

L’extraction de mémoire s’exécute en arrière-plan après chaque tour. Utilisez le fournisseur en tant que gestionnaire de contexte asynchrone ou appel flush() avant l’arrêt afin que l’extraction en attente se termine avant la fermeture des clients.

Le fournisseur prend également en charge les invites d’extraction personnalisées, la cadence du processeur, les seuils de confiance, les types de mémoire et les limites de récupération.