Session

AgentSession är containern för konversationstillstånd som används mellan agentkörningar.

Vad AgentSession innehåller

Fält	Purpose
StateBag	Flexibel tillståndsbehållare för sessionen

C# AgentSession är en abstrakt basklass. Konkreta implementeringar (skapade via CreateSessionAsync()) kan lägga till ytterligare tillstånd, t.ex. ett ID för lagring av fjärrchatthistorik, när tjänsthanterad historik används.

Fält	Purpose
session_id	Lokal unik identifierare för den här sessionen
service_session_id	Identifierare för fjärrtjänstsession, till exempel en konversation eller ett svars-ID, när tjänsthanterad historik används
state	Föränderlig ordlista som delas med kontext-/historikprovidrar

Fält	Purpose
agent.Session	Nyckelvärdestillståndscontainer kopplad till en konversation

Sessioner tillhandahåller typad lagring av nyckel/värde-par:

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

Omfång för tjänstsessions-ID

När tjänsthanterad historik används kan en session innehålla en tjänst utfärdad sessionsidentifierare. Till exempel kan OpenAI-svar använda ett resp_* svars-ID som previous_response_idoch OpenAI-konversations-API:et kan använda ett conv_* konversations-ID som konversation.

OpenAI begränsar som standard dessa ID:n till den underliggande API-nyckeln eller projektet. Detta räcker vanligtvis när nyckeln eller projektet redan matchar programgränsen, till exempel en app med en användare eller en separat nyckel/ett separat projekt per klientorganisation. Det riskfyllda hostade mönstret innebär att man använder en underliggande nyckel eller ett projekt för flera slutanvändare, skickar vidare råa tjänstside-ID:n till klienter och accepterar dessa ID:n tillbaka utan att verifiera ägarskapet. I värdbaserade appar eller appar med flera användare som återanvänder en säkerhetskopieringsnyckel eller ett projekt ska du inte behandla service_session_id, previous_response_ideller conversation/conversation_id som auktoriseringsgränser för slutanvändare. Lagra ID:n på tjänstsidan i betrodd applikationslagring, koppla klientsynliga sessions-ID:n till dessa ID:n och verifiera den autentiserade användaren eller klientorganisationen innan du återupptar en konversation.

Inbyggt användningsmönster

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

Använda sessioner med Harness Agent

Harness Agent använder samma AgentSession livscykel som beskrivs ovan. Återanvänd en session över svängar så att funktioner för chatthistorik och sessionsbaserad användning – till exempel todos, driftläge, filminne, verktygsgodkännanden och bakgrundsaktivitetstillstånd – förblir anslutna. Serialisera sessionen när tillståndet måste överleva en omstart av processen.

HarnessAgent har som standard InMemoryChatHistoryProvider. Ersätt den via HarnessAgentOptions.ChatHistoryProvider när historiken måste använda ett annat arkiv. AsHarnessAgent(options) är en förkortning för att new HarnessAgent(chatClient, options)konstruera .

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

Selen bevarar lokal chatthistorik efter varje modellanrop i en verktygsanropsloop, inte bara efter att den yttre agenten har körts. Fortsätt att skicka samma session för att bevara den in-loop-historiken och tillståndet för standardkontextprovidrar.

create_harness_agent standardvärdet history_provider är InMemoryHistoryProvider(). Skicka en anpassad HistoryProvider genom history_provider= när historiken måste använda ett annat arkiv.

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)

Selen kräver beständighet per tjänstanropshistorik, så den konfigurerade historikprovidern sparar varje modellanrop i en verktygsloop. En session krävs också av standardverktyget för godkännande av mellanprogram. återanvända och återställa den för att bevara godkännande- och kontextproviderns tillstånd.

Seleagenten är för närvarande inte tillgänglig i Go SDK. Använd det vanliga sessionsmönstret som visas ovan.

Skapa en session från ett befintligt tjänstkonversations-ID

Skapa en ny session från ett befintligt konversations-ID varierar beroende på agenttyp. Här följer några exempel.

När du använder ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

När du använder en A2AAgent

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

Använd detta när den stödjande tjänsten redan har konversationstillstånd.

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

I värdbaserade appar hämtar du <service-conversation-id> från programmets egen lagring efter att ha kontrollerat den aktuella användaren eller klientorganisationen. Undvik att acceptera obearbetade ID:n på tjänstsidan från en klient om du inte först verifierar att anroparen äger konversationen.

Serialisering och återställning

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

I ett program med egen värd kan en AgentSessionStore läsa in och spara sessioner med ett fortsättnings-ID som en del av bearbetningen av begäranden. Detta skiljer sig från att manuellt bevara en session och från att konfigurera en historikprovider. Se Agent Framework-program med egen värd.

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

Tips/Råd

Se det bevarade konversationsexemplet för ett fullständigt exempel.

Important

Sessioner är agent-/tjänstspecifika. Om du återanvänder en session med en annan agentkonfiguration eller leverantör kan det leda till en ogiltig kontext. Om den serialiserade sessionen innehåller ett sessions-ID på tjänstsidan återställer du det endast för programanvändaren eller klientorganisationen som äger det ID:t.

Nästa steg

Kontextprovidrar