Session

AgentSession to kontener stanu konwersacji używany podczas działań agenta.

Co AgentSession zawiera

Pole Przeznaczenie
StateBag Dowolny kontener stanu dla tej sesji

C# AgentSession jest abstrakcyjną klasą bazową. Konkretne implementacje (utworzone za pośrednictwem CreateSessionAsync()) mogą dodawać dodatkowy stan, np. identyfikator zdalnego przechowywania historii rozmów, jeśli historia rozmów jest zarządzana przez usługę.

Pole Przeznaczenie
session_id Unikatowy identyfikator lokalny dla tej sesji
service_session_id Identyfikator sesji usługi zdalnej, na przykład identyfikator rozmowy lub odpowiedzi, gdy używana jest historia zarządzana przez usługę
state Słownik modyfikowalny udostępniony dostawcom kontekstu/historii
Pole Przeznaczenie
agent.Session Kontener stanu klucz-wartość powiązany z konwersacją

Sesje zapewniają magazyn par klucz-wartość z określonymi typami:

type UserPrefs struct {
    Theme    string `json:"theme"`
    Language string `json:"language"`
}

session.Set("user_prefs", UserPrefs{Theme: "dark", Language: "en"})

var prefs UserPrefs
session.Get("user_prefs", &prefs)

session.Delete("user_prefs")

Określanie zakresu identyfikatora sesji usługi

Gdy jest używana historia zarządzana przez usługę, sesja może zawierać identyfikator sesji wystawionej przez usługę. Na przykład odpowiedzi OpenAI mogą używać identyfikatora odpowiedzi resp_* jako previous_response_id, a interfejs API Conversations OpenAI może używać identyfikatora konwersacji conv_* jako konwersacji.

OpenAI domyślnie przypisuje te identyfikatory do powiązanego klucza API lub projektu. Zazwyczaj to wystarcza, gdy dany klucz lub projekt już odpowiada granicy aplikacji, na przykład w przypadku aplikacji dla jednego użytkownika albo oddzielnego klucza lub projektu dla każdego dzierżawcy. Ryzykownym rozwiązaniem w modelu hostowanym jest używanie jednego wspólnego klucza lub projektu dla wielu użytkowników końcowych, przekazywanie klientom surowych identyfikatorów po stronie usługi oraz przyjmowanie ich z powrotem bez sprawdzania, do kogo należą. W aplikacjach hostowanych lub wieloużytkownikowych, które ponownie wykorzystują jeden klucz bazowy lub projekt, nie traktuj service_session_id, previous_response_id ani conversation/conversation_id jako granic autoryzacji dla użytkownika końcowego. Przechowuj identyfikatory po stronie usługi w zaufanym magazynie aplikacji, mapuj widoczne dla klienta identyfikatory sesji na te identyfikatory po stronie usługi i weryfikuj uwierzytelnionego użytkownika lub dzierżawcę przed wznowieniem rozmowy.

Wzorzec użycia wbudowanego

AgentSession session = await agent.CreateSessionAsync();

var first = await agent.RunAsync("My name is Alice.", session);
var second = await agent.RunAsync("What is my name?", session);

session = agent.create_session()

first = await agent.run("My name is Alice.", session=session)
second = await agent.run("What is my name?", session=session)

session, err := a.CreateSession(ctx)
if err != nil {
    panic(err)
}

resp, _ := a.RunText(ctx, "Hello!", agent.WithSession(session)).Collect()
resp, _ = a.RunText(ctx, "Follow-up question.", agent.WithSession(session)).Collect()

Tworzenie sesji na podstawie istniejącego identyfikatora konwersacji usługi

Utwórz nową sesję na bazie istniejącego identyfikatora konwersacji, co zależy od typu agenta. Oto kilka przykładów.

W przypadku korzystania z ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

W przypadku korzystania z elementu A2AAgent

AgentSession session = await a2aAgent.CreateSessionAsync(contextId, taskId);

Użyj tej opcji, gdy usługa zapasowa ma już stan konwersacji.

session = agent.get_session(service_session_id="<service-conversation-id>")
response = await agent.run("Continue this conversation.", session=session)

W aplikacjach hostowanych ustal element <service-conversation-id> z magazynu należącego do aplikacji po sprawdzeniu bieżącego użytkownika lub dzierżawcy. Unikaj akceptowania nieprzetworzonych identyfikatorów po stronie usługi od klienta, chyba że najpierw sprawdzisz, czy obiekt wywołujący jest właścicielem konwersacji.

Serializacja i przywracanie

var serialized = agent.SerializeSession(session);
AgentSession resumed = await agent.DeserializeSessionAsync(serialized);

serialized = session.to_dict()
resumed = AgentSession.from_dict(serialized)

data, err := json.Marshal(session)
if err != nil {
    panic(err)
}

// Save to disk, database, etc.
if err := os.WriteFile("session.json", data, 0o644); err != nil {
    panic(err)
}

// Later, restore the session.
loaded, err := os.ReadFile("session.json")
if err != nil {
    panic(err)
}

var resumedSession agent.Session
if err := json.Unmarshal(loaded, &resumedSession); err != nil {
    panic(err)
}

resp, _ := a.RunText(ctx, "Continue from where we left off.", agent.WithSession(&resumedSession)).Collect()

Wskazówka

Zobacz przykład trwałej konwersacji, aby zapoznać się z pełnym przykładem.

Ważne

Sesje są specyficzne dla agenta/usługi. Ponowne użycie sesji z inną konfiguracją agenta lub dostawcą może prowadzić do nieprawidłowego kontekstu. Jeśli sesja serializowana zawiera identyfikator sesji po stronie usługi, przywróć ją tylko dla użytkownika aplikacji lub dzierżawy, która jest właścicielem tego identyfikatora.

Dalsze kroki

Dostawcy kontekstu

  • Last updated on