Azure Cosmos DB

Installera programvarupaketen

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

Konfigurera Cosmos DB-chatthistorik

Använd tillägget managed-identity för att ansluta CosmosChatHistoryProvider till 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);

Standardtillståndsinitieraren skapar ett konversations-ID. Ange en CosmosChatHistoryProvider.State initialiserare när programmet behöver explicit konversation, klientorganisation och användarroutning. När klient- och användar-ID:t finns använder providern en hierarkisk partitionsnyckel.

Installera paketet

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

Konfigurera CosmosHistoryProvider

Python-providern accepterar antingen en Azure autentiseringsuppgifter eller en kontonyckel och använder session_id som partitionsnyckel.

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

Spara serialiserad AgentSession i betrodd programlagring när klienter behöver återställa samma sessionsidentifierare senare.

Förutsättningar

• Ett Azure Cosmos DB konto och en databas.
• Ett Microsoft Foundry-projekt med chatt- och inbäddningsmodelldistributioner.
• Azure identitetsåtkomst till båda resurserna.

Installera programvarupaketen

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

Konfigurera minnesprovidern

Samma Foundry-projekt kan tillhandahålla chattmodellen, inbäddningar och minnesextraheringsmodellen. Koppla providern via 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()

Ett stabilt user_id håller minnet tillgängligt mellan sessioner och trådar. Om ingen anges begränsar leverantören minnet till det aktuella sessions-ID:t.

Minnesbearbetning

Minnesextrahering körs i bakgrunden efter varje tur. Använd providern som en asynkron kontexthanterare eller anropa flush() före nedstängning, så att väntande extrahering hinner slutföras innan klienterna stängs ned.

Providern stöder även anpassade extraheringsprompter, processortakt, tröskelvärden för konfidens, minnestyper och hämtningsgränser.