Azure Cosmos DB (ein Microsoft-Datenbankdienst)

Installieren der Pakete

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

Konfigurieren des Cosmos DB-Chatverlaufs

Verwenden Sie die Erweiterung für verwaltete Identitäten, um CosmosChatHistoryProvider an ChatClientAgentOptions anzufügen.

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);

Der Standardstatusinitialisierer erstellt eine Unterhaltungs-ID. Geben Sie einen CosmosChatHistoryProvider.State-Initialisierer an, wenn Ihre Anwendung explizites Konversations-, Mandanten- und Benutzerrouting benötigt. Wenn Mandanten- und Benutzer-IDs vorhanden sind, verwendet der Anbieter einen hierarchischen Partitionsschlüssel.

Installiere das Paket

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

CosmosHistoryProvider konfigurieren

Der Python-Anbieter akzeptiert entweder eine Azure-Anmeldeinformation oder einen Kontoschlüssel und verwendet session_id als Partitionsschlüssel.

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

Speichern Sie das serialisierte AgentSession im vertrauenswürdigen Anwendungsspeicher, wenn Clients denselben Sitzungsbezeichner später wiederherstellen müssen.

Voraussetzungen

• Ein Azure Cosmos DB Konto und eine Datenbank.
• Ein Microsoft Foundry-Projekt mit Chat- und Einbettungsmodellbereitstellungen.
• Azure Identitätszugriff auf beide Ressourcen.

Installieren der Pakete

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

Konfigurieren des Speicheranbieters

Dasselbe Foundry-Projekt kann das Chatmodell, die Einbettungen und das Speicherextraktionsmodell bereitstellen. Verbinden Sie den Anbieter über 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()

Ein stabiler user_id Speicher bleibt über Sitzungen und Threads hinweg verfügbar. Ohne einen solchen beschränkt der Anbieter den Speicher auf die aktuelle Sitzungs-ID.

Speicherverarbeitung

Die Speicherextraktion wird nach jeder Drehung im Hintergrund ausgeführt. Verwenden Sie den Anbieter als Async-Kontext-Manager oder rufen Sie flush() vor dem Herunterfahren auf, damit die ausstehende Extraktion abgeschlossen wird, bevor die Clients geschlossen werden.

Der Anbieter unterstützt auch benutzerdefinierte Extraktionsaufforderungen, Prozessorrhythmen, Konfidenzschwellenwerte, Speichertypen und Abrufgrenzwerte.