Azure Cosmos DB

De pakketten installeren

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

Cosmos DB-chatgeschiedenis configureren

Gebruik de extensie voor beheerde identiteit om te koppelen CosmosChatHistoryProvider aan 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);

Met de initialisatiefunctie voor de standaardstatus wordt een gespreks-id gemaakt. Geef een CosmosChatHistoryProvider.State initialisatiefunctie op wanneer uw toepassing expliciet gesprek, tenant en gebruikersroutering nodig heeft. Wanneer tenant- en gebruikers-id's aanwezig zijn, gebruikt de provider een hiërarchische partitiesleutel.

Installeer het pakket

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

CosmosHistoryProvider configureren

De Python provider accepteert een Azure referentie of een accountsleutel en gebruikt de session_id als partitiesleutel.

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

Bewaar de geserialiseerde AgentSession in vertrouwde toepassingsopslag wanneer clients later dezelfde sessie-id moeten herstellen.

Prerequisites

• Een Azure Cosmos DB-account en -database.
• Een Microsoft Foundry-project met chat- en insluitmodelimplementaties.
• Toegang met Azure-identiteit tot beide resources.

De pakketten installeren

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

De geheugenprovider configureren

Hetzelfde Foundry-project kan het chatmodel, insluitingen en het model voor geheugenextractie leveren. Koppel de provider 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()

Een stabiel user_id houdt geheugen beschikbaar in sessies en threads. Zonder een dergelijke beperkt de provider het geheugen tot de huidige sessie-ID.

Geheugenverwerking

Geheugenextractie wordt na elke draai op de achtergrond uitgevoerd. Gebruik de provider als een asynchrone contextmanager of roep flush() aan vóór het afsluiten, zodat de openstaande extractie wordt voltooid voordat de clients worden afgesloten.

De provider ondersteunt ook aangepaste extractieprompts, processorfrequentie, betrouwbaarheidsdrempels, geheugentypen en ophaallimieten.