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

Używanie sesji z agentem uprzęży

Korzystanie z agenta korzysta z tego samego AgentSession cyklu życia opisanego powyżej. Użyj ponownie jednej sesji na kolei, aby historia czatu i funkcje uprzęży oparte na sesji — takie jak todos, tryb operacyjny, pamięć pliku, zatwierdzenia narzędzi i stan zadania w tle — pozostają połączone. Serializuj sesję, gdy ten stan musi przetrwać ponowne uruchomienie procesu.

Właściwość HarnessAgent domyślnie przyjmuje wartość InMemoryChatHistoryProvider. Zastąp ją, gdy HarnessAgentOptions.ChatHistoryProvider historia musi używać innego magazynu. 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ć tę historię w pętli i stan domyślnych dostawców kontekstu.

create_harness_agent wartość domyślna history_provider to InMemoryHistoryProvider(). Przekaż niestandardową HistoryProvider metodę, history_provider= gdy historia musi używać innego magazynu.

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ślne oprogramowanie pośredniczące zatwierdzania narzędzi; użyj ponownie i przywróć go, aby zachować stan zatwierdzenia i dostawcy kontekstu.

Agent platformy Harness nie jest obecnie dostępny w zestawie SDK języka Go. 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 AgentSessionStore hostowanej samodzielnie może ładować i zapisywać sesje przy użyciu identyfikatora kontynuacji w ramach przetwarzania żądań. Różni się to od ręcznego utrwalania sesji i konfigurowania dostawcy historii. Zobacz Self-host Agent Framework applications (Aplikacje platformy agentów self-host).

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żna

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