"Session"

AgentSession هي حاوية حالة المحادثة المستخدمة عبر عمليات تشغيل العامل.

ما AgentSession يحتوي على

الحقل	الغرض
StateBag	حاوية حالة عشوائية لجلسة العمل هذه

C#‎ AgentSession هي فئة أساسية مجردة. قد تضيف عمليات التنفيذ الملموسة (التي تم إنشاؤها عبر CreateSessionAsync()) حالة إضافية مثل معرف لتخزين محفوظات الدردشة عن بعد، عند استخدام المحفوظات المدارة بواسطة الخدمة.

الحقل	الغرض
session_id	المعرف الفريد المحلي لجلسة العمل هذه
service_session_id	معرف جلسة عمل الخدمة عن بعد، مثل معرف المحادثة أو الاستجابة، عند استخدام المحفوظات المدارة بواسطة الخدمة
state	قاموس قابل للتغيير تمت مشاركته مع موفري السياق/المحفوظات

الحقل	الغرض
agent.Session	حاوية حالة قيمة المفتاح المرتبطة بمحادثة

توفر جلسات العمل تخزينا مكتوبا بقيمة المفتاح:

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

نطاق معرف جلسة الخدمة

عند استخدام المحفوظات المدارة بواسطة الخدمة، يمكن أن تحتوي جلسة العمل على معرف جلسة صادر عن الخدمة. على سبيل المثال، قد تستخدم استجابات OpenAI معرف استجابة resp_* ك previous_response_id، وقد تستخدم conv_* واجهة برمجة تطبيقات محادثات OpenAI معرف محادثة كمحادثة.

يقوم OpenAI بتحديد نطاق هذه المعرفات إلى مفتاح أو مشروع واجهة برمجة التطبيقات المدعومة بشكل افتراضي. عادة ما يكون هذا كافيا عندما يتطابق هذا المفتاح أو المشروع بالفعل مع حد التطبيق، مثل تطبيق مستخدم واحد أو مفتاح/مشروع منفصل لكل مستأجر. يستخدم النمط المستضاف المحفيف بالمخاطر مفتاح دعم أو مشروع واحد لعدة مستخدمين، ويكرر معرفات جانب الخدمة الأولية للعملاء، ويقبل هذه المعرفات مرة أخرى دون التحقق من الملكية. في التطبيقات المستضافة أو متعددة المستخدمين التي تعيد استخدام مفتاح أو مشروع واحد للنسخ الاحتياطي، لا تعامل service_session_idأو أو كحدود conversation/conversation_id تخويل المستخدم النهائي. previous_response_id قم بتخزين معرفات جانب الخدمة في تخزين التطبيقات الموثوق به، وتعيين معرفات الجلسة المرئية للعميل إلى معرفات جانب الخدمة هذه، والتحقق من المستخدم أو المستأجر المصادق عليه قبل استئناف محادثة.

نمط الاستخدام المضمن

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

يستخدم Harness Agent نفس AgentSession دورة الحياة الموضحة أعلاه. أعد استخدام جلسة واحدة عبر المنعطفات حتى تظل محفوظات الدردشة وميزات التسخير المدعومة بجلسة العمل - مثل المهام ووضع التشغيل وذاكرة الملف والموافقات على الأدوات وحالة مهمة الخلفية - متصلة. قم بتسلسل جلسة العمل عندما يجب أن تنجو هذه الحالة من إعادة تشغيل العملية.

HarnessAgent يقيم افتراضيا إلى InMemoryChatHistoryProvider. استبدله عبر HarnessAgentOptions.ChatHistoryProvider عندما يجب أن يستخدم المحفوظات متجرا آخر. AsHarnessAgent(options) هو اختصار لإنشاء 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);

يستمر التسخير في محفوظات الدردشة المحلية بعد كل استدعاء نموذج داخل حلقة استدعاء أداة، ليس فقط بعد تشغيل العامل الخارجي. استمر في تمرير نفس جلسة العمل للحفاظ على محفوظات التكرار الحلقي وحالة موفري السياق الافتراضيين.

create_harness_agent الإعدادات الافتراضية history_provider إلى InMemoryHistoryProvider(). تمرير مخصص HistoryProvider من خلال 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)

يتطلب التسخير استمرار محفوظات استدعاء لكل خدمة، لذلك يحفظ موفر المحفوظات المكون كل استدعاء نموذج داخل حلقة أداة. مطلوب أيضا جلسة عمل بواسطة البرنامج الوسيط الافتراضي للموافقة على الأدوات؛ أعد استخدامها واستعادتها للحفاظ على حالة الموافقة وموفر السياق.

Harness Agent غير متوفر حاليا في Go SDK. استخدم نمط الجلسة العادية الموضح أعلاه.

إنشاء جلسة عمل من معرف محادثة خدمة موجود

يختلف إنشاء جلسة عمل جديدة من معرف محادثة موجود حسب نوع العامل. وإليك بعض الأمثلة.

عند استخدام ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

عند استخدام A2AAgent

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

استخدم هذا عندما يكون لخدمة النسخ الاحتياطي حالة محادثة بالفعل.

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

في التطبيقات المستضافة، حل <service-conversation-id> من التخزين المملوك للتطبيق بعد التحقق من المستخدم الحالي أو المستأجر الحالي. تجنب قبول معرفات جانب الخدمة الأولية من عميل ما لم تتحقق أولا من أن المتصل يمتلك المحادثة.

التسلسل والاستعادة

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

في تطبيق مستضاف ذاتيا، AgentSessionStore يمكن تحميل الجلسات وحفظها بواسطة معرف متابعة كجزء من معالجة الطلب. يختلف هذا عن استمرار جلسة العمل يدويا وعن تكوين موفر المحفوظات. راجع تطبيقات إطار عمل عامل المضيف الذاتي.

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

راجع نموذج المحادثة المستمر للحصول على مثال كامل.

Important

جلسات العمل خاصة بالعامل/الخدمة. يمكن أن تؤدي إعادة استخدام جلسة عمل مع تكوين عامل مختلف أو موفر إلى سياق غير صالح. إذا كانت جلسة العمل المتسلسلة تحتوي على معرف جلسة عمل من جانب الخدمة، فاستعيده فقط لمستخدم التطبيق أو المستأجر الذي يمتلك هذا المعرف.

الخطوات التالية

موفرو السياق