Session

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

Harness Agent ile oturum kullanma

Harness Agent, yukarıda açıklanan aynı AgentSession yaşam döngüsünü 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. Bu durumun, işlem yeniden başlatıldığında korunması gerekiyorsa oturumu serileştirin.

HarnessAgent varsayılan olarak InMemoryChatHistoryProvider şeklinde ayarlanır. Geçmişin başka bir depo kullanması gerektiğinde, onu HarnessAgentOptions.ChatHistoryProvider aracılığıyla değiştirin. AsHarnessAgent(options), new HarnessAgent(chatClient, options) oluşturmanın kısaltmasıdı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, history_provider öğesini varsayılan olarak InMemoryHistoryProvider() yapar. history’nin başka bir store kullanması gerektiğinde, özel bir HistoryProvider öğesini history_provider= üzerinden iletin.

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)

Test düzeneği, her hizmet çağrısı için geçmişin kalıcı olarak saklanmasını gerektirdiğinden, yapılandırılmış geçmiş sağlayıcısı araç döngüsü sırasında her model çağrısını 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.

Harness Agent şu anda Go SDK'sında mevcut değildir. 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);

Kendi kendine barındırılan bir uygulamada, AgentSessionStore istek işleme sürecinin bir parçası olarak oturumları bir sürdürme kimliğiyle yükleyip kaydedebilir. Bu, bir oturumu manuel olarak kalıcılaştırmaktan ve bir geçmiş sağlayıcısını yapılandırmaktan farklıdır. Bkz. Kendi kendini barındıran Aracı Çerçevesi uygulamaları.

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

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

Önemli

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ı