Oturum

AgentSession aracı çalıştırmaları arasında kullanılan konuşma durumu kapsayıcısıdır.

Ne içeriyor AgentSession

Alan	Purpose
StateBag	Bu oturum için rastgele durum kapsayıcısı

C# AgentSession soyut bir temel sınıftır. Somut uygulamalar (CreateSessionAsync() aracılığıyla oluşturulan) hizmet tarafından yönetilen geçmişin kullanılması durumunda, uzak sohbet geçmişi depolama için bir kimlik gibi ek bir durum ekleyebilir.

Alan	Purpose
session_id	Bu oturum için yerel benzersiz tanımlayıcı
service_session_id	Hizmet tarafından yönetilen geçmiş kullanıldığında konuşma veya yanıt kimliği gibi uzak hizmet oturumu tanımlayıcısı
state	Bağlam/geçmiş sağlayıcılarıyla paylaşılan değiştirilebilir sözlük

Alan	Purpose
agent.Session	Konuşmaya bağlı anahtar-değer durum kapsayıcısı

Oturumlar, türlenmiş anahtar-değer depolama alanı sağlar:

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

Hizmet oturumu kimliği kapsamlandırması

Hizmet tarafından yönetilen geçmiş kullanıldığında, bir oturum hizmet tarafından verilen bir oturum tanımlayıcısı içerebilir. Örneğin, OpenAI Responses, resp_* olarak bir previous_response_id yanıt kimliği kullanabilir ve OpenAI Conversations API, konuşma için bir conv_* konuşma kimliği kullanabilir.

OpenAI, bu kimlikleri varsayılan olarak ilgili API anahtarı veya proje ile sınırlandırır. Bu genellikle bu anahtar veya proje, tek kullanıcılı uygulama veya kiracı başına ayrı bir anahtar/proje gibi uygulama sınırıyla zaten eşleştiğinde yeterlidir. Riskli olan barındırılan yapı; birden çok son kullanıcı için arka planda tek bir anahtar veya proje kullanmak, ham hizmet tarafı kimliklerini istemcilere olduğu gibi iletmek ve sahipliğini doğrulamadan bu kimlikleri geri kabul etmektir. Tek bir altyapı anahtarını veya projeyi yeniden kullanan barındırılan veya çok kullanıcılı uygulamalarda, service_session_id, previous_response_id veya conversation/conversation_id ögelerini son kullanıcı yetkilendirme sınırları olarak değerlendirmeyin. Hizmet tarafı kimliklerini güvenilen uygulama depolama alanında depolayın, istemci tarafından görünen oturum kimliklerini bu hizmet tarafı kimlikleriyle eşleyin ve konuşmayı sürdürmeden önce kimliği doğrulanmış kullanıcı veya kiracıyı doğrulayın.

Yerleşik kullanım düzeni

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

Koşum Aracısı ile oturumları kullanma

Koşum Aracısı, yukarıda açıklanan yaşam döngüsünün aynısını AgentSession kullanır. Tek bir oturumu sırayla yeniden kullanın; böylece sohbet geçmişi ve oturum destekli todos, işletim modu, dosya belleği, araç onayları ve arka plan görevi durumu gibi özellikler bağlı kalır. Bir işlemin yeniden başlatılması durumunda bu durumun devam etmesi gerektiğinde oturumu seri hale getirme.

HarnessAgent varsayılan olarak InMemoryChatHistoryProvider şeklinde ayarlanır. Geçmişin başka bir depo kullanması gerektiğinde aracılığıyla HarnessAgentOptions.ChatHistoryProvider değiştirin. AsHarnessAgent(options) , oluşturmak new HarnessAgent(chatClient, options)için kısaltmadır.

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

Koşum, her model çağrısından sonra yalnızca dış aracı çalıştırıldıktan sonra değil, bir araç çağırma döngüsü içinde yerel sohbet geçmişini kalıcı hale getirir. Bu döngü geçmişini ve varsayılan bağlam sağlayıcılarının durumunu korumak için aynı oturumu geçirmeye devam edin.

create_harness_agent varsayılan değeridir history_providerInMemoryHistoryProvider(). Geçmişin başka bir depo kullanması gerektiğinde özel HistoryProvider bir geçiş history_provider= .

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)

Koşum, hizmet başına çağrı geçmişi kalıcılığı gerektirdiğinden, yapılandırılan geçmiş sağlayıcısı her model çağrısını bir araç döngüsü içinde kaydeder. Varsayılan araç onayı ara yazılımı için de bir oturum gereklidir; onay ve bağlam sağlayıcısı durumunu korumak için yeniden kullanabilir ve geri yükleyebilirsiniz.

Koşum Aracısı şu anda Go SDK'sında kullanılamıyor. Yukarıda gösterilen normal oturum düzenini kullanın.

Mevcut bir hizmet konuşma kimliğinden oturum oluşturma

Mevcut bir görüşme kimliğinden yeni bir oturum oluşturma, aracı türüne göre farklılık gösterir. Aşağıda bazı örnekler verilmiştir.

Kullanırken ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Kullanırken bir A2AAgent

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

Bunu, destek hizmetinin konuşma durumu bilgisine zaten sahip olması durumunda kullanın.

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

Barındırılan uygulamalarda, geçerli kullanıcıyı veya kiracıyı kontrol ettikten sonra <service-conversation-id> öğesini uygulamaya ait depolama alanından çözümleyin. Çağrıyı yapan tarafın konuşmanın sahibi olduğunu önce doğrulamadıkça, istemciden ham hizmet tarafı kimliklerini kabul etmekten kaçının.

Serileştirme ve geri yükleme

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

İpucu

Tam bir örnek için kalıcı olarak saklanan konuşma örneğine bakın.

Important

Oturumlar aracıya/hizmete özeldir. Oturumu farklı bir ajan yapılandırması veya sağlayıcıyla yeniden kullanmak, geçersiz bir bağlama neden olabilir. Serileştirilmiş oturum bir hizmet tarafı oturum kimliği içeriyorsa, yalnızca bu kimliğin sahibi olan uygulama kullanıcısı veya kiracı için geri yükleyin.

Sonraki Adımlar

Bağlam Sağlayıcıları