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

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

اختر المكونات استنادا إلى السلوك وحالة احتياجات التطبيق الخاص بك:

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

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

تعمل المكونات معا في دورة حياة يمكن التنبؤ بها. على سبيل المثال، ضع في اعتبارك مساعد دعم يجيب عن سؤال متابعة:

  1. يحدد التطبيق وكيلا يحدد إرشادات وأدوات الدعم.
  2. يقوم بإنشاء محادثة وإضافة السؤال الأول للعميل كعنصر إدخال.
  3. تقوم الاستجابة بتشغيل العامل مقابل المحادثة وإلحاق عناصر الإخراج.
  4. تستخدم الاستجابة التالية نفس المحادثة، بحيث يمكن للعامل الإجابة عن سؤال متابعة في السياق.

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

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

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

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

المتطلبات الأساسية

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

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).
  • استخدم أقل امتياز للوصول إلى الأداة. عندما تصل الأداة إلى أنظمة خارجية، يمكن للوكيل قراءة أو إرسال البيانات من خلال تلك الأداة.
  • كن حذرا مع غير خدمات Microsoft. إذا استدعى وكيلك أدوات مدعومة بخدمات غير خدمات Microsoft، فقد تتدفق بعض البيانات إلى تلك الخدمات. للاعتبارات ذات الصلة، راجع اكتشف الأدوات في أدوات المسبك.

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

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

محتوى ذو صلة

  • Last updated on