Session

AgentSession az ügynökfuttatások során használt beszélgetési állapottároló.

Mit AgentSession tartalmaz?

Field	Alkalmazás célja
StateBag	Tetszőleges állapottároló ehhez a munkamenethez

A C# AgentSession egy absztrakt alaposztály. A konkrét implementációk (létrehozva CreateSessionAsync()) további állapotot is hozzáadhatnak, például egy azonosítót a távoli chat előzmények tárolásához, amikor a szolgáltatás által kezelt előzményeket használják.

Field	Alkalmazás célja
session_id	A munkamenet helyi egyedi azonosítója
service_session_id	Szolgáltatás által felügyelt előzmények használata esetén a távoli szolgáltatás munkamenet-azonosítója (például beszélgetés vagy válaszazonosító)
state	Környezet- és előzményszolgáltatókkal megosztott módosítható szótár

Field	Alkalmazás célja
agent.Session	Beszélgetéshez kötött kulcs-érték alapú állapottároló

A munkamenetek gépelt kulcs-érték tárolót biztosítanak:

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

Szolgáltatás munkamenet-azonosító hatókörének meghatározása

Szolgáltatás által felügyelt előzmények használata esetén a munkamenetek tartalmazhatnak szolgáltatás által kibocsátott munkamenet-azonosítót. Például az OpenAI Responses egy resp_* válaszazonosítót használhat previous_response_idként, az OpenAI Conversations API pedig egy conv_* beszélgetésazonosítót használhat beszélgetésként.

Az OpenAI alapértelmezés szerint a háttér API-kulcsra vagy projektre irányítja ezeket az azonosítókat. Ez általában akkor elegendő, ha ez a kulcs vagy projekt már megfelel az alkalmazás határának, például egy egyfelhasználós alkalmazásnak vagy bérlőnként egy külön kulcsnak/projektnek. A kockázatos üzemeltetett minta egy háttérkulcsot vagy projektet használ több végfelhasználó számára, nyers szolgáltatásoldali azonosítókat ad vissza az ügyfeleknek, és a tulajdonjog ellenőrzése nélkül fogadja vissza ezeket az azonosítókat. Az üzemeltetett vagy többfelhasználós alkalmazásokban, amelyek ugyanazt a háttérkulcsot vagy projektet használják, ne tekintse service_session_id, previous_response_id vagy conversation/conversation_id végfelhasználói hitelesítési határnak. A szolgáltatásoldali azonosítókat megbízható alkalmazástárolóban tárolhatja, leképezheti az ügyfél által látható munkamenet-azonosítókat ezekre a szolgáltatásoldali azonosítókra, és a beszélgetés folytatása előtt ellenőrizze a hitelesített felhasználót vagy bérlőt.

Beépített használati minta

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

Munkamenetek használata a Harness Agenttel

A Harness Agent a fent leírt, ugyanazt a AgentSession életciklust használja. Használjon újra egy munkamenetet a különböző fordulókban, így a csevegési előzmények és a munkamenet-háttérrendszer funkciói – például a todos, az üzemeltetési mód, a fájlmemória, az eszközjóváhagyások és a háttérfeladat állapota – továbbra is csatlakoztatva maradnak. Szerializálja a munkamenetet, ha az állapotnak túl kell élnie a folyamat újraindítását.

HarnessAgent alapértelmezés szerint InMemoryChatHistoryProvider. Cserélje le a(z) HarnessAgentOptions.ChatHistoryProvider használatával, ha az előzményeknek másik tárolót kell használniuk. AsHarnessAgent(options) a(z) new HarnessAgent(chatClient, options) létrehozásának rövidítése.

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

A heveder megőrzi a helyi csevegési előzményeket minden modellhívás után egy eszközhívó cikluson belül, nem csak a külső ügynök futtatása után. Folytassa ugyanazt a munkamenetet, hogy megőrizze ezt a cikluson belüli előzményt és az alapértelmezett környezetszolgáltatók állapotát.

alapértelmezés szerint értékét értékre állítja. Adjon át egy egyéni HistoryProvider elemet a history_provider= komponensen keresztül, ha az előzményeknek másik tárolót kell használniuk.

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)

A heveder szolgáltatásonkénti híváselőzmények megőrzését igényli, ezért a konfigurált előzményszolgáltató minden modellhívást egy eszközhurkon belül ment. Az alapértelmezett eszközjóváhagyási middleware-nek is szüksége van munkamenetre; használja újra, és állítsa vissza azt a jóváhagyási és a kontextusszolgáltatói állapot megőrzése érdekében.

A Harness Agent jelenleg nem érhető el a Go SDK-ban. Használja a fent látható szokásos munkamenet-mintát.

Munkamenet létrehozása meglévő szolgáltatásbeszélgetés-azonosítóból

Új munkamenet létrehozása meglévő beszélgetési azonosítóból ügynöktípustól függően változik. Íme néhány példa.

"ChatClientAgent használatakor"

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Amikor egy A2AAgent

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

Ezt akkor használja, ha a háttérszolgáltatás már rendelkezik beszélgetési állapottal.

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

Hosztolt alkalmazásokban az aktuális felhasználó vagy bérlő ellenőrzése után oldja fel a(z) <service-conversation-id> elemet az alkalmazás tulajdonában lévő tárolóból. Ne fogadjon el nyers szolgáltatásoldali azonosítókat az ügyféltől, kivéve, ha először ellenőrzi, hogy a hívóé-e a beszélgetés.

Szerializálás és visszaállítás

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

A saját üzemeltetésű alkalmazásokban AgentSessionStore a munkameneteket egy folytatási azonosítóval töltheti be és mentheti a kérésfeldolgozás részeként. Ez eltér a munkamenetek manuális megőrzésétől és az előzményszolgáltató konfigurálásától. Lásd : Önkiszolgáló ügynök-keretrendszeralkalmazások.

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

A teljes példáért tekintse meg a fenntartott beszélgetési mintát .

Important

A munkamenetek ügynök-/szolgáltatásspecifikusak. Ha egy munkamenetet egy másik ügynökkonfigurációval vagy szolgáltatóval újrahasznál, az érvénytelen környezethez vezethet. Ha a szerializált munkamenet szolgáltatásoldali munkamenet-azonosítót tartalmaz, csak az adott azonosítóval rendelkező alkalmazásfelhasználó vagy bérlő számára állítsa vissza.

Következő lépések

Kontextusszolgáltatók