Session

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

Co AgentSession zawiera

Pole	Purpose
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	Purpose
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	Purpose
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()

Korzystanie z sesji z Harness Agent

Harness Agent używa tego samego AgentSession cyklu życia opisanego powyżej. Użyj ponownie jednej sesji między turami, aby historia czatu i funkcje środowiska testowego oparte na sesji — takie jak lista zadań, tryb działania, pamięć plików, zatwierdzenia narzędzi i stan zadań w tle — pozostawały powiązane. Serializuj sesję, gdy ten stan musi przetrwać ponowne uruchomienie procesu.

Właściwość HarnessAgent domyślnie przyjmuje wartość InMemoryChatHistoryProvider. Zastąp ją za pomocą HarnessAgentOptions.ChatHistoryProvider, gdy historia musi używać innego repozytorium. AsHarnessAgent(options) jest skrótem do konstruowania new HarnessAgent(chatClient, options).

HarnessAgent agent = chatClient.AsHarnessAgent();
AgentSession session = await agent.CreateSessionAsync();

await agent.RunAsync("Plan the migration.", session);
await agent.RunAsync("Continue with the next step.", session);

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

Uprzęża utrzymuje lokalną historię czatów po każdym wywołaniu modelu wewnątrz pętli wywoływania narzędzi, nie tylko po uruchomieniu agenta zewnętrznego. Kontynuuj przekazywanie tej samej sesji, aby zachować historię w ramach pętli oraz stan domyślnych dostawców kontekstu.

create_harness_agent domyślnie ustawia history_provider na InMemoryHistoryProvider(). Przekaż niestandardową HistoryProvider przez history_provider=, gdy historia musi używać innego magazynu danych.

agent = create_harness_agent(client)
session = agent.create_session()

await agent.run("Plan the migration.", session=session)
await agent.run("Continue with the next step.", session=session)

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

Uprzęża wymaga trwałości historii wywołań dla usługi, dlatego skonfigurowany dostawca historii zapisuje każde wywołanie modelu wewnątrz pętli narzędzi. Sesja jest również wymagana przez domyślną warstwę pośrednią zatwierdzania narzędzi; użyj jej ponownie i przywróć ją, aby zachować stan zatwierdzania oraz stan dostawcy kontekstu.

Harness Agent nie jest obecnie dostępny w pakiecie Go SDK. Użyj wzorca sesji regularnej pokazanego powyżej.

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);

W aplikacji hostowanej samodzielnie element AgentSessionStore może ładować i zapisywać sesje za pomocą identyfikatora kontynuacji w ramach przetwarzania żądania. Różni się to od ręcznego utrwalania sesji i konfigurowania dostawcy historii. Zobacz aplikacje platformy Self-host Agent Framework.

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

Tip

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

Important

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.

Następne kroki

Dostawcy kontekstu