Azure Cosmos DB

Instalowanie pakietu

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

Konfigurowanie historii czatów usługi Cosmos DB

Użyj rozszerzenia tożsamości zarządzanej, aby dołączyć CosmosChatHistoryProvider do 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);

Domyślny inicjator stanu tworzy identyfikator konwersacji. Podaj inicjalizator CosmosChatHistoryProvider.State, gdy aplikacja wymaga jawnego kierowania konwersacją, dzierżawcą i użytkownikiem. Jeśli występują identyfikatory dzierżawcy i użytkownika, dostawca używa hierarchicznego klucza partycjonowania.

Instalowanie pakietu

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

Skonfiguruj CosmosHistoryProvider

Dostawca Python akceptuje poświadczenie Azure lub klucz konta. Jest używany session_id jako klucz partycji. Wystąpienia dostawcy, które używają tego samego konta, bazy danych, kontenera, nonempty session_idi source_id uzyskują dostęp do tej samej utrwalonej historii. source_id filtruje historię w obrębie partycji. Te identyfikatory wybierają historię przechowywania; nie są to granice uwierzytelniania ani autoryzacji. Powiąż je z uwierzytelnionymi i autoryzowanymi kontekstami aplikacji oraz używaj odrębnych zaufanych przestrzeni nazw, gdy potrzebujesz izolacji.

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

Przechowuj zserializowany obiekt AgentSession w zaufanym magazynie aplikacji, gdy klienci muszą później odzyskać ten sam identyfikator sesji.

Wymagania wstępne

• Konto Azure Cosmos DB i baza danych.
• Projekt Microsoft Foundry z wdrożeniami modeli czatu i osadzania.
• Azure dostęp tożsamości do obu zasobów.

Instalowanie pakietów

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

Konfigurowanie dostawcy pamięci

Ten sam projekt Foundry może dostarczać model konwersacyjny, embeddingi oraz model do wyodrębniania pamięci. Dołącz dostawcę przez context_providers.

def _foundry_project_endpoint() -> str:
    """Read the preferred project endpoint variable with legacy compatibility."""
    return os.environ.get("FOUNDRY_PROJECT_ENDPOINT") or os.environ["FOUNDRY_ENDPOINT"]


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=_foundry_project_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=_foundry_project_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()

Stabilne user_id zapewnia dostępność pamięci między sesjami i wątkami. Zapisz go w przestrzeni nazw stanu należącej do dostawcy: session.state[provider.source_id]["user_id"]. Nie umieszczaj go w płaskim stanie sesji, gdzie inny dostawca lub pole aplikacji może wejść z nim w konflikt. Bez identyfikatora użytkownika dostawca ogranicza pamięć do bieżącego identyfikatora sesji.

Przetwarzanie pamięci

Ekstrakcja pamięci odbywa się w tle po każdej turze. Użyj dostawcy jako asynchronicznego menedżera kontekstu lub wywołaj flush() przed zamknięciem, aby oczekujące wyodrębnianie zostało zakończone, zanim klienci zostaną zamknięci.

Dostawca obsługuje także niestandardowe prompty ekstrakcji, częstotliwość przetwarzania, progi pewności, typy pamięci i limity wyszukiwania. Wybierz fakty, procedury i odcinki za pomocą polecenia memory_types. W narzędziu Agent Memory Toolkit 0.3.0b2 lub nowszym fakty i wybrane epizody współdzielą limit rankingowanych top_k wyników. Wybrane procedury są kompilowane oddzielnie dla bieżącego zadania i nie zużywają tego limitu. Starsze obsługiwane wersje Toolkit zachowują domyślne działanie mechanizmu pobierania. Ustaw wartość top_k na dodatnią liczbę całkowitą i min_confidence na wartość od 0.0 do 1.0, włącznie. Nieprawidłowe wartości powodują wystąpienie ValueError podczas tworzenia dostawcy.

Go udostępnia usługę Cosmos DB dla magazynu wektorów NoSQL za pośrednictwem azureprovider.NewCosmosDB. Używa ona istniejącej azcosmos.Client oraz bazy danych, z kolekcjami udostępnianymi za pośrednictwem metody vectordata.

Łącznik obsługuje wygenerowane embeddingi, wyszukiwanie wektorów i wyszukiwanie hybrydowe pełnotekstowe/wektorowe. Konto musi mieć włączone wymagane możliwości wyszukiwania. Zapytania rankingowe wymagają filtrów równości dla każdej skonfigurowanej właściwości klucza partycji; ranking między partycjami nie jest obsługiwany przez ten łącznik.

Przykład języka Go usługi Cosmos DB wymaga elementów AZURE_COSMOS_ENDPOINT, AZURE_COSMOS_DATABASE, FOUNDRY_PROJECT_ENDPOINT i FOUNDRY_EMBEDDING_MODEL. Używa on schematu 3072-wymiarowego i tworzy i usuwa unikalnie nazwany kontener tymczasowy w istniejącej bazie danych.

Ten konektor nie jest dedykowanym dostawcą pamięci długoterminowej pokazanym w przykładzie języka C#. W przypadku pobierania zarządzanego przez aplikację utwórz wyszukiwanie kolekcji za pomocą funkcji text-search RAG, zachowując filtry partycji łącznika i mechanizmy kontroli dostępu aplikacji. Zobacz Integracje repozytoriów wektorowych dla dostępnych repozytoriów Go.