وكلاء مستضافون في Foundry

يتيح لك الوكلاء المستضافون في Microsoft Foundry Agent Service نشر تطبيقات العامل الحاوية على البنية الأساسية المدارة Microsoft. يعالج النظام الأساسي التحجيم واستمرار حالة الجلسة والأمان وإدارة دورة الحياة حتى تتمكن من التركيز على منطق الوكيل الخاص بك. Microsoft Foundry Hosted Agents متاحة بشكل عام وتدعم العوامل التي تم إنشاؤها باستخدام التعليمات البرمجية الخاصة بك أو إطار عمل الوكيل المفضل. تتناول هذه المقالة تكامل استضافة إطار عمل العامل على وجه التحديد.

باستخدام تكامل استضافة إطار عمل العامل، يمكنك عرض Agent من خلال بروتوكول Foundry Responses أو Invocations مع الحد الأدنى من التعليمات البرمجية. يدعم Python أيضا استضافة أصلي Workflow مباشرة، دون تحويله إلى وكيل.

Note

يمكنك أيضا نشر التعليمات البرمجية للعامل التي تم إنشاؤها مع أطر عمل أخرى إلى عوامل Foundry المستضافة باستخدام مهام سير عمل Azure Developer CLI (azd). للحصول على مفاهيم غير محددة لإطار العمل وإرشادات التوزيع، راجع ما هي العوامل المستضافة؟ تركز بقية هذه المقالة على تكامل إطار عمل العامل.

متى تستخدم الوكلاء المستضافين

اختر عوامل Foundry المستضافة عندما تريد:

• البنية الأساسية المدارة - لا حاجة لتكوين الحاويات أو خوادم الويب أو قواعد التحجيم بنفسك.
• إدارة الجلسة المضمنة$HOME — يستمر النظام الأساسي في تحميل الملفات عبر فترات التشغيل والتوقف.
• هوية الوكيل المخصصة - يحصل كل عامل موزع على هوية إنترا الخاصة به للوصول الآمن إلى النماذج والأدوات وخدمات انتقال البيانات من الخادم.
• نقاط النهاية المتوافقة مع OpenAI — يمكن للعملاء التفاعل مع وكيلك باستخدام أي SDK متوافق مع OpenAI من خلال بروتوكول الاستجابات.

السيناريوهات ذات الصلة

• بالنسبة لوكلاء الصوت في الوقت الحقيقي، استخدم العوامل المستضافة مع Azure Speech في أدوات Foundry (Voice Live) للكشف عن النشاط الصوتي من جانب الخادم وإلغاء الأصداء وتقليل الضوضاء. للحصول على التفاصيل، راجع استخدام Voice Live مع الوكلاء المستضافين.

Note

يعد تكامل Python agent-framework-foundry-hosting إصدارا مسبقا. Microsoft Foundry Hosted Agents، وهي خدمة الاستضافة المدارة، متاحة بشكل عام.

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

• اشتراك Azure
• Azure Developer CLI (azd) مع ملحق عامل الذكاء الاصطناعي:azd ext install azure.ai.agents

للاختبار المحلي، تحتاج أيضا إلى:

• مشروع Microsoft Foundry مع نشر نموذج (على سبيل المثال، gpt-4o)
• Azure CLI تثبيتها ومصادقتها (az login)

• .NET 10 SDK أو أحدث

تثبيت حزمة استضافة NuGet:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease

• Python 3.10 أو أحدث

تثبيت حزمة الاستضافة التجريبية وعميل Foundry وحزمة مصادقة Azure:

pip install --pre agent-framework-foundry agent-framework-foundry-hosting azure-identity

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

بروتوكول الردود

بروتوكول الاستجابات هو نقطة البداية الموصى بها لمعظم العوامل. يعرض نقطة نهاية متوافقة مع /responses OpenAI، ويدير النظام الأساسي محفوظات المحادثات والتدفق ودورة حياة الجلسة تلقائيا.

بالنسبة Python العوامل المستضافة، تكون incomplete للاستجابة التي تنتهي مبكرا حالة. يتلقى عملاء الدفق حدث محطة طرفية response.incomplete ، بينما يتلقى status العملاء غير المتدفقين تعيين إلى incomplete. يتم content_filter تعيين سبب الانتهاء لتعيين incomplete_details.reason إلى content_filter، وتعيين length إلى max_output_tokens. يظل أي محتوى ناتج أو رفض تم إنشاؤه متوفرا في الاستجابة.

using Azure.AI.AgentServer.Core;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
var deployment = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
    ?? "gpt-4o";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

AgentHost.CreateBuilder ينشئ مضيف تطبيق تم تكوينه مسبقا لبيئة استضافة Foundry. AddFoundryResponses تسجيل العامل الخاص بك مع معالج بروتوكول الاستجابات، وتعيين MapFoundryResponses/responses نقطة نهاية HTTP.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a helpful AI assistant.",
)

server = ResponsesHostServer(agent)
server.run()

يلتف ResponsesHostServer العامل الخاص بك ويعرضه من خلال بروتوكول استجابات Foundry. يتحكم حقل المتصل store في ما إذا كانت الاستجابة الخارجية وجلسة العمل المدارة من قبل المضيف وحالة الموافقة محفوظة. history_source يحدد الإعداد بشكل مستقل من يوفر محفوظات النموذج:

history_source	سلوك محفوظات النموذج
"agent_server" (افتراضي)	يقوم المضيف بإعادة إنشاء نسخة الاستجابات الخارجية المخزنة وتعطيل تخزين خدمة انتقال البيانات من الخادم لمنع المحفوظات المكررة.
"service"	يرسل المضيف الإدخال الحالي فقط ويحفظ بشكل خاص معرف متابعة خدمة النموذج المخزن. لا يمكن أن تفرع محادثة الموفر المخزنة من استجابة سابقة.
"agent"	يرسل المضيف الإدخال الحالي فقط. يقوم تخزين خدمة انتقال البيانات من الخادم أو العامل HistoryProvider بإدارة المحفوظات.

لا تدمج "agent_server" أو "service" مع تمكين HistoryProviderالتحميل . يرفض الوضع الافتراضي أيضا خيارات متابعة انتقال البيانات من الخادم الثابتة مثل conversation_idو previous_response_idو.conversation استخدم history_source="agent" لتنفيذ مخصص SupportsAgentRun .

response_store تحدد معلمة الدالة الإنشائية الواجهة الخلفية لاستمرار الاستجابات الخارجية. معلمة store الدالة الإنشائية الأقدم هي اسم مستعار مهمل ل response_store؛ ولا تحدد أي من المعلمتين حقل المتصل لكل طلب store . الطلب باستخدام store=false هو لقطة واحدة: لا يحفظ الحالة المدارة من قبل المضيف، ويعطيل التخزين المتلقين للمعلومات المدعوم، ولا يمكنه استخدام background=true.

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

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

اختيار مثيل عامل أو مصنع

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

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

تحذير

WorkflowAgentيتم إهمال استضافة ، مثل workflow.as_agent()، من خلالagent=. WorkflowAgent يحافظ على حالة سير العمل في الذاكرة بين عمليات التشغيل، لذلك يجب ألا يخدم مثيل واحد طلبات من مستخدمين أو محادثات مختلفة. استضافة سير العمل أصلا من خلال workflow= ومصنع مدرك للطلب.

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

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

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

استضافة سير عمل أصلي مع الاستجابات

يمكن Python استضافة سير عمل مضمن مباشرة من خلال workflow=. يتطلب parse_response سير العمل الأصلي رد اتصال يعين طلب الاستجابات الحالي إما لإدخال بدء مكتوب أو دفعة كاملة من الردود المعلقة:

from pydantic import BaseModel

from agent_framework_foundry_hosting import (
    CheckpointStoreProvider,
    HostedResponseRequest,
    ResponsesHostServer,
    WorkflowTurn,
)


class Ticket(BaseModel):
    text: str


def build_workflow(request: HostedResponseRequest):
    return build_fresh_workflow()


async def parse_response(request: HostedResponseRequest) -> WorkflowTurn[Ticket]:
    items = await request.get_input_items()
    if any(item.get("type") in ("function_call_output", "mcp_approval_response") for item in items):
        return WorkflowTurn(responses=await request.get_workflow_responses())

    text = await request.get_input_text()
    return WorkflowTurn(input=Ticket.model_validate_json(text or ""))


server = ResponsesHostServer(
    workflow=build_workflow,
    parse_response=parse_response,
    checkpoint_store_provider=CheckpointStoreProvider(
        allowed_checkpoint_types=[f"{Ticket.__module__}:{Ticket.__qualname__}"],
    ),
)

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

يعزل مستخدم النظام الأساسي الموثوق به وبيئة الاختبار المعزولة Foundry حالة سير العمل الأصلية. يتحقق المضيف من صحة دفعة الرد المعلقة الكاملة قبل أن يستهلك أي مرجع رد. تفشل الردود القديمة والجزئية والتكرارية والمعاد تشغيلها والمستخدم المشترك وردود بيئة الاختبار المعزولة قبل تنفيذ سير العمل. لا يحفظ الطلب بحالة store=false سير العمل ولا يمكنه إرجاع إيقاف مؤقت قابل للاستئنافه.

بالنسبة لسير عمل قديم يقبل list[Message]، استخدم response_input_messages(request) لتحويل تحويل الاستجابات الحالية فقط. لا يقوم بتحميل المحفوظات الخارجية السابقة أو فك تشفير ردود سير العمل المعلقة. تبقى الاستضافة agent=workflow.as_agent() متاحة أثناء الإصدار التجريبي الحالي، ولكنها تصدر تحذيرا بالإيقاف. للحصول على أمثلة كاملة، راجع نماذج سير عمل الاستجابات الأصلية.

استمرار الحالة والتعامل مع المحادثات طويلة الأمد

ResponsesHostServer وتكوين InvocationsHostServer مخازن الجلسة الثابتة بشكل افتراضي. AgentSessionStoreProvider لوازم FoundryAgentSessionStore؛ تستخدم agent_sessions جلسات الاستجابات المخزن المنطقي، بينما تستخدم جلسات عمل استدعاءات المخزن المنفصل invocation_sessions . تستخدم هذه المتاجر Foundry State Store عند استضافتها وتخزين SDK المدعوم بالملفات عند التشغيل محليا.

بالنسبة لعوامل سير عمل الاستجابات، CheckpointStoreProvider يوفر FoundryCheckpointStore. تستخدم عمليات سير عمل الاستجابات والاستدعاءات الأصلية نفس الموفر لنقاط التحقق من المتابعة الدقيقة. FunctionApprovalStoreProvider يوفر للحصول على موافقات FoundryFunctionApprovalStore أداة العامل المعلقة. طلب سير العمل الأصلي وردود الموافقة مرتبطة بنقاط التحقق الخاصة بسير العمل بدلا من ذلك.

عند التشغيل في Foundry، يخزن Python الافتراضي حالة مساحة الاسم بواسطة معرف مستخدم النظام الأساسي ومعرف جلسة عمل Foundry sandbox. كما أنها تتطلب معرف استدعاء النظام الأساسي لكل عملية حالة. معرف المكالمة يخول العملية ويربطها؛ إنه ليس معرف محادثة وليس جزءا من مفتاح التخزين.

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

تنطبق هذه الضمانات على المتاجر المستضافة الافتراضية. يجب على موفري المتجر المخصصين تنفيذ عزل مكافئ للمستخدم وبيئة الاختبار المعزولة، والحفاظ على الداخلية AgentSession.session_id بشكل منفصل عن مفاتيح البحث عن المضيف، واستخدام عمليات الكتابة الشرطية حتى لا تتمكن الطلبات القديمة من الكتابة فوق لقطات أحدث. يجب أن تستخدم المفاتيح الجديدة عمليات الكتابة الإنشاء فقط بدلا من عمليات الإدخال غير المشروطة. راجع عينة التخزين المخصصة لتنفيذ Cosmos DB مع عمليات الكتابة والحذف المحمية من ETag.

مع history_source="agent"، يستمر مخزن الجلسة المكون في حالة الموفر التي يحملها AgentSession، بما في ذلك الرسائل من InMemoryHistoryProvider.

يقبل كلا المضيفين من StoreProvider[SessionStore] خلال agent_session_store_provider. يجب أن تدعم AgentSession حالة جلسة العمل التسلسل. تسجيل برامج الترميز لنوع الحالة المخصصة مع register_state_type()؛ لا تحتفظ الحالة المستعادة بهوية الكائن Python. تنتهي صلاحية الجلسات الافتراضية الجديدة بعد 30 يوما من آخر كتابة لها. يتحكم الموفرون المخصصون في استبقاء البيانات الخاصة بهم.

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

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

بالنسبة للتخزين الخاص بالردود، مرر StoreProvider إلى function_approval_store_provider أو ContextScopedStoreProvider إلى checkpoint_store_provider.

يستخدم عمل الخلفية الخارجية المتصل المرئي response.id للاستطلاع. يحتفظ الإعداد الافتراضي background_source="agent_server" بتنفيذ الخلفية في المضيف. تعيين background_source="provider" فقط مع history_source="service" عميل الاستجابات المخزنة القابلة للاستئنافه. إذا ResponsesServerOptions(resilient_background=True) تم تعيين أيضا، يمكن للمضيف استرداد التحقق من الموفر فقط بعد حفظ رمز المتابعة الخاص. جعل التأثيرات الجانبية للأداة المحلية متكررة لأن حدوث عطل قبل حفظ الرمز المميز التالي يمكن أن يعيد تشغيلها.

استيراد ResponsesServerOptions من azure.ai.agentserver.responses، وتمريره إلى ResponsesHostServer من خلال المعلمة options . تعتمد خيارات المحادثة المتوفرة طويلة الأمد على نوع العامل:

القدرة	نوع العامل	المتطلبات والسلوك
استرداد خلفية نقطة التحقق من سير العمل	سير العمل فقط	ضبط ResponsesServerOptions(resilient_background=True). أرسل طلب الاستجابات مع store=true و background=true. بعد إعادة التشغيل، يستأنف المضيف أحدث نقطة تحقق دائمة لسير العمل أو يعيد تشغيل الإدخال الأصلي إذا لم تكن هناك نقطة تحقق. لا تقم بتكوين تخزين نقطة التحقق على سير العمل لأن المضيف يديره. اجعل الآثار الجانبية الخارجية متكررة لأن العمل بعد آخر نقطة تفتيش دائمة قد يتكرر.
استجابات الخلفية الأصلية لموفر الخدمة	عدم سير العمل Agent مع عميل استجابات مخزن	تعيين history_source="service" و background_source="provider". تعيين resilient_background=True عندما يجب أن تبقى رموز متابعة الموفر المحفوظة قيد إعادة تشغيل المضيف.
محادثات قابلة للتوجيه	غير متوفر مؤقتا	لا تقم بتعيين steerable_conversations=True. يرفع RuntimeError المضيف أثناء الإنشاء حتى يتعامل Agent Server SDK بأمان مع دورات التوجيه المرفوضة.

للحصول على عمليات التنفيذ الكاملة، راجع التخزين المخصصومحفوظات الاستجابات الأساسية والخلفية وعينات سير العمل المرنة طويلة الأمد .

قراءة الملفات من بيئة الاختبار المعزولة المستضافة

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

بالنسبة لبروتوكول الاستجابات، قم بتوجيه طلب إلى جلسة مستضافة agent_session_id مع حقل النص الأساسي. محدد سلسلة الاستعلام مخصص للاستدعاءات. تحميلات الجلسة وملفات مترجم التعليمات البرمجية ل Toolbox هي موارد منفصلة؛ لا يتم تحميل ملف بيئة الاختبار المعزولة الذي تم تحميله تلقائيا في حاوية Toolbox. راجع نموذج ملفات الجلسة لقراءة UTF-8 المقيدة وإرشادات التحميل المحلية والمستضافة.

خيارات طلب التحكم

يعين المضيف حقول إنشاء الاستجابات الأصلية إلى خيارات تشغيل إطار عمل العامل. على سبيل المثال، max_output_tokens يصبح max_tokens، ويصبح parallel_tool_callsallow_multiple_tool_calls. القيم المبسطة من extra_body تجاوز القيم الأصلية المترجمة.

استخدم الخطاف المتزامن أو غير المتزامن prepare_options(request, options) لإزالة خيارات نموذج المتصل أو استبدالها قبل تشغيل عامل عادي. لا يمكن للربط تعيين حقول الهوية أو التخزين أو المتابعة أو النقل التي يتحكم فيها المضيف. لتنفيذ مخصص SupportsAgentRun لا يمكنه قبول خيارات نموذج وقت التشغيل، قم بتعيين unsupported_options إلى "warn" (الافتراضي) "ignore"أو أو ."error"

معالجة طلبات موافقة OAuth

عندما تتطلب أداة MCP المستضافة من Foundry موافقة المستخدم، ResponsesHostServer ترجع استجابة غير مكتملة مع عنصر oauth_consent_request إخراج. قدمها consent_link للمستخدم، ثم تابع معرف الاستجابة غير المكتمل كما هو الحال previous_response_id بعد إكمال المستخدم للموافقة. يحتفظ المضيف بجلسة العامل لإعادة المحاولة هذه ويعرض ارتباطات موافقة HTTPS المطلقة فقط.

إذا كان المضيف الخاص بك يعرف أصول التخويل المتوقعة، فقيد ارتباطات الموافقة مع allowed_oauth_consent_origins:

server = ResponsesHostServer(
    agent,
    allowed_oauth_consent_origins=[
        "https://logic-region.consent.azure-apihub.net",
        "https://auth.partner.example",
    ],
)

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

بروتوكول الاستدعاءات

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

باستخدام بروتوكول استدعاءات في C#، يمكنك تنفيذ مخصص InvocationHandler لمعالجة الطلبات الواردة:

using Azure.AI.AgentServer.Core;
using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

var app = builder.Build();
app.Run();

يسجل AddInvocationsServer الأسلوب خدمات بروتوكول استدعاءات. يمكنك تنفيذ InvocationHandler لتحديد كيفية معالجة وكيلك لكل طلب.

لإعداد خفيف الوزن، استخدم InvocationsHostServer من الحزمة agent_framework_foundry_hosting . فهو يلتف مع وكيلك بشكل ResponsesHostServer مشابه ويعالج إدارة الجلسة تلقائيا:

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

server = InvocationsHostServer(agent)
server.run()

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

عند استضافتها، تستخدم عمليات استدعاء نطاق الطلب الذي تم التحقق منه الموضح في الحالة "استمرار" والتعامل مع المحادثات طويلة الأمد. تعامل AgentSession.session_id كقيمة مبهمة واحدة؛ لا تحلل أو تعتمد على تمثيلها الداخلي. تحتفظ عمليات التشغيل المحلية بسلوك التخزين الحالي للمستخدم الفردي.

استضافة سير عمل أصلي مع استدعاءات

تمرير workflow= واستدعاء صريح parse_request لاستضافة سير عمل أصلي. يمتلك رد الاتصال مخطط JSON للتطبيق ويرجع WorkflowTurn إما مع إدخال مكتوب أو دفعة الرد المعلقة الكاملة:

from pydantic import BaseModel
from starlette.requests import Request

from agent_framework_foundry_hosting import (
    CheckpointStoreProvider,
    InvocationsHostServer,
    WorkflowTurn,
)


class Ticket(BaseModel):
    ticket_id: str
    question: str


class TicketDecision(BaseModel):
    approved: bool


def build_workflow(_request: Request):
    return build_fresh_workflow()


async def parse_request(request: Request) -> WorkflowTurn[Ticket]:
    payload = await request.json()
    stream = payload.get("stream", False)

    if "responses" in payload:
        decisions = {
            request_id: TicketDecision.model_validate(value)
            for request_id, value in payload["responses"].items()
        }
        return WorkflowTurn(responses=decisions, stream=stream)

    ticket = Ticket.model_validate(payload)
    return WorkflowTurn(input=ticket, stream=stream)


server = InvocationsHostServer(
    workflow=build_workflow,
    parse_request=parse_request,
    checkpoint_store_provider=CheckpointStoreProvider(
        allowed_checkpoint_types=[
            f"{Ticket.__module__}:{Ticket.__qualname__}",
            f"{TicketDecision.__module__}:{TicketDecision.__qualname__}",
        ],
    ),
)

قم بتضمين كل نوع تطبيق مخصص يحفظه سير العمل في قائمة موفر allowed_checkpoint_types نقطة التحقق.

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

تستخدم استجابات سير العمل غير المتدفقة JSON للتطبيق مع قائمة output أحداث. يصدر الدفق إطارات output وأحداث request_info ، متبوعة done فقط بعد حفظ مؤشر سير العمل الدقيق. تعامل مع الإخراج المتدفق على أنه مؤقت حتى done. لا تدعم legacy_wire_format=Trueمهام سير العمل الأصلية .

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

تخصيص طلبات واستدعاءات الاستجابات

بشكل افتراضي، POST /invocations يقبل كائن JSON بسلسلة messageوعنصر اختياري options وقيمة منطقية stream اختيارية. لقبول حمولة خاصة بالتطبيق، قم بتمرير رد اتصال متزامن أو غير متزامن parse_request يرجع InvocationRun(messages, options, stream). استخدم prepare_options لتصفية نسخة من خيارات إنشاء المتصل أو استبدالها قبل تشغيل العامل.

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

يرجع النجاح غير المتدفق JSON في النموذج {"response": "..."}. يستخدم الدفق الأحداث المرسلة من الخادم: إطار واحد أو أكثر event: delta ، متبوعا event: done بالنجاح أو event: error الفشل. يمكن أن يصدر الدفق دلتا قبل حدوث خطأ، لذلك يجب على العملاء التعامل مع done، وليس دلتا، كإكمال ناجح. يرسل المضيف done فقط بعد الانتهاء من تدفق الاستجابة ويستمر في AgentSession. هو session_id معرف مسار بيئة الاختبار المعزولة للنظام الأساسي، وليس المتسلسل AgentSession.session_id.

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

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

للتحكم الكامل في معالجة الطلب، استخدم InvocationAgentServerHost من الحزمة azure.ai.agentserver.invocations مباشرة ونفذ معالج الاستدعاء الخاص بك:

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


if __name__ == "__main__":
    app.run()

تحذير

يتم فقدان مخزن الجلسة في الذاكرة في مثال المعالج المخصص عند إعادة التشغيل. استخدم التخزين الدائم (على سبيل المثال، Cosmos DB) في الإنتاج.

للحصول على نشر استدعاءات كامل، راجع نموذج Telegram المستضاف على Foundry. يضع API Management أمام خطاف ويب العامل المستضاف ويستخدم الهويات المدارة Key Vault وCosmos DB لمحفوظات المحادثات الدائمة.

Note

انتقل إلى دعم عملاء Foundry المستضافين قريبا. راجع مستودع Agent Framework Go للحصول على أحدث حالة.

Tip

راجع نماذج Python أو نماذج C#‎ للحصول على أمثلة لمشروع عامل مستضاف. أو استخدم azd ai agent init الأمر لدعم مشروع عامل مستضاف جديد من البداية. راجع دليل التشغيل السريع هذا للحصول على إرشادات خطوة بخطوة.

التشغيل محلياً

يوفر Azure Developer CLI (azd) أسهل طريقة لتشغيل العامل المستضاف واختباره محليا.

تهيئة مشروع

إنشاء مجلد جديد وتهيئته من نموذج بيان:

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

Tip

يمكن أن يكون البيان مسارا إلى ملف YAML محلي أو عنوان URL إلى بيان بعيد.

تعيين متغيرات البيئة

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL="<your-model-deployment>"

تشغيل مضيف العامل

azd ai agent run

يبدأ مضيف العامل في http://localhost:8088.

استدعاء الوكيل

azd ai agent invoke --local "Hello!"

أو استخدم curl:

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

أو في PowerShell:

(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Hello!"}').Content

النشر إلى Foundry

بمجرد التحقق من وكيلك محليا، انشره على Microsoft Foundry:

1. توفير الموارد (إذا لم يكن لديك مشروع Foundry بالفعل):

   azd provision
   

   يؤدي هذا إلى إنشاء مجموعة موارد مع مثيل Foundry ومشروع ونشر النموذج وApplication Insights وسجل حاوية.

2. انشر العامل:

   azd deploy
   

   يقوم هذا بحزم عاملك كصورة حاوية، ودفعه إلى Azure Container Registry، ونشره في Foundry Agent Service.

تقوم البنية الأساسية لاستضافة Foundry تلقائيا بإدخال متغيرات البيئة التالية في حاوية العامل في وقت التشغيل:

المتغير	Description
FOUNDRY_PROJECT_ENDPOINT	عنوان URL لنقطة النهاية لمشروع Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME	اسم نشر النموذج المدار بواسطة azd الذي تم تكوينه أثناء azd ai agent init. يمكن أن تفضل FOUNDRY_MODEL التعليمات البرمجية Python محليا والرجوع إلى هذه القيمة المستضافة.
APPLICATIONINSIGHTS_CONNECTION_STRING	سلسلة الاتصال Application Insights لبيانات تتبع الاستخدام.

بمجرد النشر، يمكن الوصول إلى وكيلك من خلال نقطة نهاية Foundry المخصصة الخاصة به ويمكن أيضا اختباره من مدخل Foundry.

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

مفاهيم العوامل المستضافة

• نشر عامل مستضاف باستخدام Foundry SDK
• إدارة الوكلاء المستضافين
• استضافة دالات Azure ودائمة
• عوامل A2A ذاتية الاستضافة
• Python عينات
• عينات C#‎