Sesje agentów

Ważna

Ta funkcja jest dostępna w wersji beta. Aby z niego korzystać, administrator przestrzeni roboczej musi włączyć Sesje pamięci Agenta na stronie Podglądów . Zobacz Zarządzanie wersjami zapoznawczami usługi Azure Databricks.

Sesje agentowe zapewniają twoim agentom trwały, niezależny od frameworka magazyn stanu sesji: stan, który agent lub framework utrzymuje dla jednej interakcji. Najczęściej jest to historia konwersacji — uporządkowany chronologicznie zapis wiadomości, wywołań narzędzi i wyników, który agent odczytuje na początku tury i uzupełnia w trakcie działania. Może to być również dowolny inny stan, który framework utrzymuje na potrzeby interakcji, na przykład graf LangGraph. Azure Databricks przechowuje je w Lakebase i zarządza pamięcią za ciebie, więc nie budujesz ani nie obsługujesz bazy danych.

Note

W okresie wersji zapoznawczej opłaty są naliczane za bazową instancję Lakebase, która przechowuje Twoje sesje. Za same sesje agentów nie są naliczane żadne dodatkowe opłaty. Ceny mogą ulec zmianie w miarę postępu zapowiedzi.

Korzystaj z sesji agenta, gdy chcesz:

  • Utrzymuj historię rozmów agenta, aby przetrwała restarty i mogła być wznowiona później.
  • Odtwórz pełny kontekst (w tym wywołania narzędzi i rozumowanie) w kolejnej wiadomości.
  • Wyświetlaj, wznawiaj i twórz odgałęzienia wcześniejszych rozmów we własnym interfejsie.

Sesje agentów przechowują stan pojedynczej interakcji (stan krótkotrwały, w trakcie sesji). Dla pamięci długotrwałej, która utrzymuje się między rozmowami, używaj pamięci agenta.

Wymagania

  • Zainstaluj Python 3.10 lub nowszy, aby korzystać z SDK AgentKit. AgentKit SDK to klient Databricks Python dla API agentów, którego używają poniższe przykłady. Możesz też wywołać REST API bezpośrednio z dowolnego języka, bez konieczności używania Python.
  • Aby użyć przykładów API REST, zainstaluj Databricks CLI (aby wygenerować token OAuth), curl, oraz jq.

Jak działają sesje agentowe

Hierarchia zasobów sesji agenta: magazyn sesji zawiera wiele sesji, a każda sesja zawiera wiele uporządkowanych elementów sesji.

Sesje agentów mają trzy poziomy:

  • Repozytorium sesji to kontener ograniczony do obszaru roboczego na sesje agenta. Tworzenie sklepu automatycznie zapewnia pamięć Lakebase wspierającą. Wybierasz unikalny identyfikator sklepu w przestrzeni roboczej i używasz go do odwołania się do sklepu w późniejszych wywołaniach. Podaj identyfikator sklepu jako:
    • Argument name w AgentKit SDK.
    • Parametr session_store_id zapytania w API REST.
  • Sesja to jedna trwała interakcja (zazwyczaj wątek rozmowy) w sklepie. Sesję identyfikuje się po:
    • actor_id (wymagane): do kogo należy sesja, na przykład do użytkownika końcowego lub innego agenta. Grupuje wszystkie sesje jednego obiektu, dzięki czemu możesz je razem wyświetlać na liście i filtrować. Gdy tworzysz aplikację przypisaną do użytkownika, ustaw actor_id na identyfikator użytkownika (na przykład zweryfikowaną tożsamość użytkownika końcowego z mechanizmu uwierzytelniania w aplikacji), aby sesje każdego użytkownika były grupowane razem. Ustaw ją w zaufanym kontekście aplikacji, nigdy na podstawie wartości dostarczonej przez model ani przez użytkownika.
    • session_id (opcjonalnie): ID wybrane przez wywołującego dla interakcji. Usługa generuje jeden, gdy go pominiesz.
    • parent_session_id (opcjonalnie): Sprawia, że sesja jest sesją podrzędną względem innej sesji w magazynie, na przykład konwersacji subagenta. Ustaw to podczas tworzenia sesji.
  • Element sesji to jeden wpis w historii uporządkowanej sesji. Każdy element zawiera nieprzejrzystą, zgodną data z JSON wartość, taką jak wiadomość, wywołanie narzędzia, wynik narzędzia lub blok rozumowania. Azure Databricks przypisuje każdemu elementowi znaczniki item_id i create_time oraz nie sprawdza ani nie weryfikuje jego zawartości. Przedmioty są niezmienne po ich dodaniu.

Usługa zachowuje deterministyczną kolejność elementów danej sesji i autoryzuje każdą operację w magazynie sesji.

Wprowadzenie

Te przykłady tworzą sesje agentów dla agenta wsparcia: tworzą oni magazyn sesji, rozpoczynają sesję dla jednej rozmowy, dopisują kolejne wypowiedzi rozmowy i odczytują historię na kolejnym żądaniu. Wybierz klienta, który pasuje do Twojego projektu.

Identyfikatory sklepów są unikalne w obrębie przestrzeni roboczej. Jeśli uruchamiasz obie zakładki lub identyfikator jest już zajęty, wybierz inny identyfikator lub usuń najpierw istniejący sklep. Odpowiedzi magazynu zawierają również przypisany przez usługę UUID w session_store_id. Późniejsze połączenia używają wybranego przez Ciebie ID sklepu.

AgentKit SDK

AgentKit SDK to klient Databricks Python dla API agentów, dystrybuowany w databricks-agentbricks pakiecie. Uwierzytelnia się przy użyciu zestawu SDK Databricks WorkspaceClient.

  1. Zainstaluj AgentKit SDK:

    pip install databricks-agentbricks
    

    Pakiet databricks-agentbricks zawiera databricks_agentkit moduł Python.

  2. Utwórz magazyn danych sesji, a następnie rozpocznij sesję na potrzeby jednej rozmowy. actor_id jest tym, do kogo należy rozmowa; opcjonalne session_id jednoznacznie identyfikuje tę rozmowę:

    from databricks.sdk import WorkspaceClient
    from databricks_agentkit import AgentKitClient
    
    client = AgentKitClient(WorkspaceClient())
    session_store = client.session_stores.create("support-agent-sessions-sdk")
    session = session_store.add(actor_id="customer-123", session_id="case-456")
    
  3. Dodawaj wypowiedzi w rozmowie podczas działania agenta. Każdy element to dowolna wartość zgodna z JSON:

    session.append_items(
        [
            {"type": "message", "role": "user", "content": "I need help with my cluster."},
            {"type": "message", "role": "assistant", "content": "Let's take a look."},
        ]
    )
    
  4. Na dodatkowe żądanie załaduj sesję i przeczytaj pełną historię, aby odbudować kontekst:

    session = session_store.get("case-456")
    # Request chronological order; list_items defaults to newest-first and auto-pages.
    history = [item.data for item in session.list_items(order_by="create_time asc")]
    

interfejs API REST

Klienci wywołują interfejs API REST pod adresem /api/2.0/agents/session-stores. Wywołuj ją bezpośrednio w językach innych niż Python.

  1. Ustaw DATABRICKS_HOST adres URL swojego workspace, w tym https://, a następnie wygeneruj token OAuth za pomocą Databricks CLI:

    export DATABRICKS_HOST=https://<workspace-url>
    databricks auth login --host ${DATABRICKS_HOST}
    export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)
    
  2. Stwórz magazyn sesji dla swojego agenta:

    curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/session-stores?session_store_id=support-agent-sessions-rest" \
      -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
      -d '{"description": "Support agent conversation history"}'
    
  3. Rozpocznij sesję na jedną rozmowę. actor_id określa, do kogo należy; session_id jednoznacznie identyfikuje tę rozmowę:

    curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions?session_id=case-456" \
      -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
      -d '{"actor_id": "customer-123"}'
    
  4. Dodaj turę rozmowy podczas działania agenta:

    curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions/case-456/items:append" \
      -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
      -d '{"items": [{"data": {"type": "message", "role": "user", "content": "I need help with my cluster."}}]}'
    
  5. Przeczytaj historię w kolejności chronologicznej, aby odbudować kontekst:

    curl -G "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions/case-456/items" \
      -H "Authorization: Bearer ${DATABRICKS_TOKEN}" --data-urlencode "order_by=create_time asc"
    

    Odpowiedź zwraca elementy w session_items, do page_size elementów na jedno żądanie (domyślnie 10, maksymalnie 100). Gdy pozostaje więcej elementów, zawiera next_page_token. Przekaż tę wartość jako page_token i powtarzaj, aż odpowiedź nie będzie miała next_page_token. AgentKit SDK wykonuje stronicowanie list_items za Ciebie.

    Na przykład ta pętla odczytuje pełną historię po 100 pozycji naraz:

    PAGE_TOKEN=""
    while true; do
      RESPONSE=$(curl -s -G "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions/case-456/items" \
        -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
        --data-urlencode "order_by=create_time asc" --data-urlencode "page_size=100" \
        ${PAGE_TOKEN:+--data-urlencode "page_token=${PAGE_TOKEN}"})
      echo "${RESPONSE}" | jq -c '.session_items[]?.data'
      PAGE_TOKEN=$(echo "${RESPONSE}" | jq -r '.next_page_token // empty')
      [ -z "${PAGE_TOKEN}" ] && break
    done
    

Klienci obsługują także usunięcie najnowszego elementu, wyczyszczenie elementów sesji oraz utworzenie niezależnej kopii rozmowy (opcjonalnie do określonego elementu). Fork nie ma sesji nadrzędnej, a usunięcie sesji źródłowej jej nie usuwa. Usunięcie sesji zawsze usuwa jej sesje potomne oraz ich elementy.

Obsługuj sesję frameworka agenta za pomocą sesji agenta

Frameworki agentów, takie jak OpenAI Agents SDK i Claude Agent SDK, odczytują historię rozmów na początku przebiegu i dodają nowe elementy na końcu. Magazyn sesji bezpośrednio odpowiada temu wzorcowi:

Działanie ramowe Wywołanie AgentKit SDK
Przeczytaj historię list_items(order_by="create_time asc")
Dodaj elementy obrotu append_items(items)
Cofnij ostatni element pop_item()
Oczyść wątek clear_items()

Zakres i dostęp

Sesje agentów przechowują elementy sesji jako nieprzejrzyste, kompatybilne z JSON wartości: usługa zapisuje i zwraca wszystko, co doda Twój agent lub framework, bez interpretacji. Nie dodaje zasobów sterowania wykonaniem, takich jak uruchomienia, punkty kontrolne czy zatwierdzenia, jako podstawowych pojęć, chociaż struktura serializująca taki stan może trwale przechowywać je jako elementy.

Magazyny sesyjne są przypisane do obszaru roboczego, a dostęp jest przyznawany na poziomie magazynu. Kontrola dostępu do sklepu obejmuje sesje w sklepie. Każdy użytkownik workspace może wyświetlać listę magazynów sesji i je pobierać, w tym ich identyfikatory i opisy. Pola metadata i actor_id obsługują tylko grupowanie i filtrowanie; nie przyznają ani nie ograniczają dostępu. Ustaw actor_id na podstawie zaufanego kontekstu aplikacji, a nie wartości dostarczonej przez model lub użytkownika.

Aby umożliwić innemu podmiotowi, na przykład przedstawicielowi usługowym Twojego agenta, korzystanie z magazynu, przyznaj mu dostęp za pomocą operacji przyzwolenia sklepu (session_store.grant_permission(principal_id) w AgentKit SDK). Dostęp może przyznać tylko twórca sklepu lub administrator przestrzeni roboczej. Zobacz Zarządzanie uprawnieniami dla pamięci agenta i magazynów sesji , aby uzyskać poziomy uprawnień, obsługiwane operacje i przykłady.

Sesje agentów i pamięć agenta są niezależne. Usunięcie sesji lub magazynu sesji nie usuwa pamięci przechowywanej w magazynie pamięci. Aby zbudować pamięć długoterminową z sesji w magazynie danych, stwórz pipeline pamięci.

Następne kroki