مشاركة عبر

ابن مع الوكلاء، والمحادثات، والردود

تستخدم خدمة وكلاء مايكروسوفت فاوندري ثلاثة مكونات أساسية أثناء التشغيل — الوكلاء، والمحادثات، والردود — لتمكين التفاعلات متعددة الأدوار ذات الحالة المحددة. الوكيل يحدد النموذج والتعليمات والأدوات التي يجب استخدامها. تستمر المحادثة في التاريخ عبر المنعطفات. الاستجابة هي الناتج الذي ينتجه الوكيل عند معالجة الإدخالات.

تستعرض هذه المقالة كل مكون وتوضح كيفية استخدامها معا في الكود. ستتعلم كيفية إنشاء وكيل، وبدء محادثة، وتوليد الردود (مع وكيل أو بدونه)، وإضافة رسائل متابعة، وبث النتائج — مع أمثلة في بايثون، C#، جافا سكريبت، جافا، وREST API.

كيف تعمل مكونات وقت التشغيل معا

عندما تعمل مع وكيل، تتبع نمطا ثابتا:

  • إنشاء وكيل: حدد وكيلا لبدء إرسال الرسائل وتلقي الردود.
  • إنشاء محادثة (اختياري): استخدم محادثة للاحتفاظ بالسجل عبر الأدوار. إذا لم تستخدم محادثة، انقل السياق باستخدام مخرجات رد سابق.
  • إنشاء استجابة: يعالج الوكيل عناصر الإدخال في المحادثة وأي إرشادات متوفرة في الطلب. قد يضيف الوكيل عناصر إلى المحادثة.
  • تحقق من حالة الاستجابة: راقب الاستجابة حتى تنتهي (خاصة في وضع البث أو الخلفية).
  • استرداد الاستجابة: اعرض الاستجابة التي تم إنشاؤها للمستخدم.

يوضح الرسم البياني التالي كيف تتفاعل هذه المكونات في loop وكيل نموذجي.

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

توفر مدخلات المستخدم (وأحيانا تاريخ المحادثة)، وتقوم الخدمة بتوليد استجابة (بما في ذلك استدعاءات الأدوات عند التكوين)، ويمكن إعادة استخدام العناصر الناتجة كسياق للدور التالي.

المتطلبات المسبقه

لتشغيل العينات في هذا المقال، تحتاج:

pip install "azure-ai-projects>=2.0.0"
pip install azure-identity

إنشَاء مندوب

العامل هو تعريف تنسيق مستمر يجمع بين نماذج الذكاء الاصطناعي والإرشادات والتعليمات البرمجية والأدوات والمعلمات وعناصر التحكم الاختيارية في السلامة أو الحوكمة.

وكلاء التخزين كما هو مسمى، وأصول معدلة في Microsoft Foundry. أثناء إنشاء الاستجابة، يعمل تعريف الوكيل مع محفوظات التفاعل (المحادثة أو الاستجابة السابقة) لمعالجة مدخلات المستخدم والاستجابة لها.

المثال التالي ينشئ وكيل المطالبات مع اسم ونموذج وتعليمات. استخدم عميل المشروع لإنشاء وكيل وإصدار الإصدارات.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a prompt agent
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant.",
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

ملحوظة

يتم الآن تحديد الوكلاء باستخدام اسم الوكيل ونسخة الوكيل. لم يعد لديهم رمز GUID بعد AgentID الآن.

لأنواع الوكلاء الإضافية (سير العمل، المستضاف)، انظر دورة حياة تطوير الوكلاء.

أنشئ وكيلا باستخدام الأدوات

الأدوات تمتد إلى ما يمكن للوكيل فعله إلى ما هو أبعد من توليد النص. عند ربط أدوات بوكيل، يمكن للوكيل استدعاء خدمات خارجية، وتشغيل الكود، والبحث عن الملفات، والوصول إلى مصادر البيانات أثناء توليد الرد — باستخدام أدوات مثل البحث على الويب أو استدعاء الدوال.

يمكنك إرفاق أداة أو أكثر عند إنشاء وكيل. خلال توليد الاستجابة، يقرر الوكيل ما إذا كان سيطلب أداة بناء على مدخلات المستخدم وتعليماتها. المثال التالي ينشئ وكيلا مع أداة بحث ويب مرفقة.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create an agent with a web search tool
agent = project.agents.create_version(
    agent_name="my-tool-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

للاطلاع على القائمة الكاملة للأدوات المتاحة، راجع نظرة عامة على الأدوات. للحصول على أفضل الممارسات، راجع أفضل الممارسات لاستخدام الأدوات.

توليد الردود

يستدعي إنشاء الاستجابة العامل. يستخدم العامل تكوينه وأي محفوظات متوفرة (محادثة أو استجابة سابقة) لتنفيذ المهام عن طريق استدعاء النماذج والأدوات. كجزء من توليد الردود، يضيف الوكيل عناصر إلى المحادثة.

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

بالإضافة إلى ذلك، يمكنك تقسيم المحادثة إلى معرف الاستجابة الأولى أو معرف الاستجابة الثانية

توليد استجابة باستخدام وكيل

المثال التالي يولد إجابة باستخدام مرجع وكيل، ثم يرسل سؤالا متابعة باستخدام الإجابة السابقة كسياق.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Ask a follow-up question using the previous response
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    previous_response_id=response.id,
    input="What is the population of that city?",
)
print(follow_up.output_text)

عندما يستخدم وكيل أدوات أثناء توليد الاستجابة، يحتوي مخرجات الاستجابة على عناصر استدعاء الأدوات إلى جانب الرسالة النهائية. يمكنك التكرار response.output لفحص كل عنصر وعرض استدعاءات الأدوات—مثل عمليات البحث على الإنترنت، استدعاءات الوظائف، أو البحث في الملفات—قبل طباعة الاستجابة النصية.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What happened in the news today?",
)

# Print each output item, including tool calls
for item in response.output:
    if item.type == "web_search_call":
        print(f"[Tool] Web search: status={item.status}")
    elif item.type == "function_call":
        print(f"[Tool] Function call: {item.name}({item.arguments})")
    elif item.type == "file_search_call":
        print(f"[Tool] File search: status={item.status}")
    elif item.type == "message":
        print(f"[Assistant] {item.content[0].text}")

توليد استجابة دون تخزين

افتراضيا، تخزن الخدمة سجل الاستجابة على جانب الخادم، لذا يمكنك الرجوع previous_response_id إلى سياق متعدد الأدوار. إذا ضبطت store على ، falseفإن الخدمة لا تستمر في الاستجابة باستمرار. يجب أن تنقل سياق المحادثة بنفسك عن طريق تمرير عناصر المخرج السابقة كمدخلات للطلب التالي.

هذا النهج مفيد عندما تحتاج إلى تحكم كامل في حالة المحادثة، أو ترغب في تقليل البيانات المخزنة، أو العمل في بيئة لا تحتفظ بها بيانات.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response without storing
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
    store=False,
)
print(response.output_text)

# Carry forward context client-side by passing previous output as input
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input=[
        {"role": "user", "content": "What is the largest city in France?"},
        {"role": "assistant", "content": response.output_text},
        {"role": "user", "content": "What is the population of that city?"},
    ],
    store=False,
)
print(follow_up.output_text)

المحادثات وعناصر المحادثة

المحادثات هي كائنات متينة ذات معرفات فريدة. بعد الإنشاء، يمكنك إعادة استخدامها عبر الجلسات.

تخزن المحادثات العناصر ، والتي يمكن أن تتضمن الرسائل واستدعاءات الأدوات ومخرجات الأدوات والبيانات الأخرى.

إنشاء محادثة

المثال التالي ينشئ محادثة مع رسالة مستخدم أولية. استخدم عميل OpenAI (المستخرج من عميل المشروع) للمحادثات والاستجابات.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation with an initial user message
conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What is the largest city in France?",
        }
    ],
)
print(f"Conversation ID: {conversation.id}")

متى تستخدم المحادثة

استخدم محادثة عندما تريد:

  • استمرارية الأدوار المتعددة: حافظ على تاريخ مستقر عبر الأدوار دون إعادة بناء السياق بنفسك.
  • الاستمرارية عبر الجلسات: أعد استخدام نفس المحادثة لمستخدم يعود لاحقا.
  • تصحيح الأخطاء: فحص ما حدث مع مرور الوقت (مثل استدعاءات الأدوات والمخرجات).

عندما تستخدم المحادثة لتوليد استجابة (مع وكيل أو بدونه)، يتم توفير المحادثة الكاملة كمدخل للنموذج. ثم يتم إلحاق الرد المولد بنفس المحادثة.

ملحوظة

إذا تجاوزت المحادثة حجم السياق المدعوم للنموذج، سيقوم النموذج تلقائيا باختصار سياق الإدخال. المحادثة نفسها ليست مختصرة، بل تستخدم فقط جزءا منها لتوليد الرد.

إذا لم تنشئ محادثة، يمكنك بناء تدفقات متعددة الأدوار باستخدام مخرجات الاستجابة السابقة كنقطة انطلاق للطلب التالي. هذا النهج يمنحك مرونة أكبر من النمط القديم المعتمد على الخيوط، حيث كانت الحالة مرتبطة بإحكام مع كائنات الخيط. للحصول على إرشادات الترحيل، راجع Migration إلى Agents SDK.

أنواع عناصر المحادثة

المحادثات تخزن العناصر بدلا من الرسائل المحادثة فقط. العناصر تلتقط ما حدث أثناء توليد الاستجابة حتى يتمكن الدور التالي من إعادة استخدام هذا السياق.

تشمل أنواع العناصر الشائعة:

  • عناصر الرسالة: رسائل المستخدم أو المساعد.
  • عناصر استدعاء الأداة: سجلات استدعاءات الأدوات التي حاول الوكيل استخدامها.
  • عناصر مخرجات الأداة: المخرجات التي تعيدها الأدوات (على سبيل المثال، نتائج الاسترجاع).
  • العناصر المخرجة: محتوى الاستجابة الذي تعرضه للمستخدم.

إضافة عناصر إلى المحادثة

بعد إنشاء محادثة، استخدم conversations.items.create() ذلك لإضافة رسائل مستخدم لاحقة أو عناصر أخرى.

# Add a follow-up message to an existing conversation
openai.conversations.items.create(
    conversation_id=conversation.id,
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What about Germany?",
        }
    ],
)

استخدم محادثة مع وكيل

اجمع بين المحادثة ومرجع الوكيل للحفاظ على التاريخ عبر عدة أدوار. يقوم الوكيل بمعالجة جميع العناصر في المحادثة ويضيف مخرجاته تلقائيا.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation for multi-turn chat
conversation = openai.conversations.create()

# First turn
response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Follow-up turn in the same conversation
follow_up = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the population of that city?",
)
print(follow_up.output_text)

للحصول على أمثلة تظهر كيف تعمل المحادثات والردود معا في الكود، انظر إنشاء واستخدام الذاكرة في خدمة وكلاء المسبح.

البث والردود الخلفية

للعمليات طويلة الأمد، يمكنك إرجاع النتائج تدريجيا باستخدام streaming الوضع أو تشغيله بشكل غير متزامن تماما باستخدام background الوضع. في هذه الحالات، عادة ما تراقب الاستجابة حتى تنتهي ثم تستهلك العناصر النهائية المخرجة.

استمر ردا

البث يعيد نتائج جزئية فور توليدها. هذا النهج مفيد لعرض النتائج للمستخدمين في الوقت الحقيقي.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Stream a response using the agent
stream = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Explain how agents work in one paragraph.",
    stream=True,
)
for event in stream:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="", flush=True)

للحصول على تفاصيل حول أوضاع الاستجابة وكيفية استهلاك المخرجات، راجع واجهة برمجة التطبيقات (Responses API).

تشغيل وكيل في وضع الخلفية

وضع الخلفية يشغل الوكيل بشكل غير متزامن، وهو أمر مفيد للمهام طويلة الأمد مثل التفكير المعقد أو توليد الصور. قم بتعيين background إلى true ثم قم باستطلاع حالة الرد حتى يكملها.

from time import sleep
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Start a background response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Write a detailed analysis of renewable energy trends.",
    background=True,
)

# Poll until the response completes
while response.status in ("queued", "in_progress"):
    sleep(2)
    response = openai.responses.retrieve(response.id)

print(response.output_text)

ربط الذاكرة بوكيل (معاينة)

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

توفر خدمة Foundry Agent حل ذاكرة مدارة (معاينة) تقوم بتكوينه من خلال مخازن الذاكرة. يحدد مخزن الذاكرة أنواع المعلومات التي يجب أن يحتفظ بها الوكيل. قم بإرفاق مخزن ذاكرة بوكيلك، وسيستخدم الوكيل الذكريات المخزنة كسياق إضافي أثناء توليد الردود.

المثال التالي ينشئ مخزن ذاكرة ويربطه بوكيل.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    MemoryStoreDefaultDefinition,
    MemoryStoreDefaultOptions,
)

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a memory store
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
)
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",
    embedding_model="text-embedding-3-small",
    options=options,
)
memory_store = project.beta.memory_stores.create(
    name="my_memory_store",
    definition=definition,
    description="Memory store for my agent",
)
print(f"Memory store: {memory_store.name}")

للتفاصيل المفاهيمية، انظر الذاكرة في خدمة وكيل المسبك. للحصول على إرشادات كاملة للتنفيذ، راجع إنشاء واستخدام الذاكرة.

الأمن والتعامل مع البيانات

نظرا لأن المحادثات والردود يمكن أن تستمر في المحتوى والمخرجات التي يوفرها المستخدمون، تعامل بيانات وقت التشغيل كبيانات تطبيق:

  • تجنب تخزين الأسرار في المحفزات أو سجل المحادثات. استخدم الاتصالات والمخازن السرية المدارة بدلا من ذلك (على سبيل المثال، قم بإعداد اتصال Key Vault).
  • استخدم أقل امتياز لأداة access. عندما تصل الأداة إلى أنظمة خارجية، يمكن للوكيل قراءة أو إرسال البيانات من خلال تلك الأداة.
  • كن حذرا مع الخدمات غير التابعة لمايكروسوفت. إذا استدعى وكيلك أدوات مدعومة بخدمات غير مايكروسوفت، فقد تتدفق بعض البيانات إلى تلك الخدمات. للاعتبارات ذات الصلة، راجع اكتشف الأدوات في أدوات المسبك.

الحدود والقيود

يمكن أن تعتمد الحدود على النموذج، والمنطقة، والأدوات التي توصلها (على سبيل المثال، توفر البث ودعم الأدوات). للاطلاع على التوفر الحالي والقيود على الردود، راجع واجهة برمجة التطبيقات للاستجابات.

المحتوى ذو الصلة

  • Last updated on