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

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

مع تكامل استضافة إطار عمل العامل، يمكنك عرض Agent، بما في ذلك سير عمل ملتف مع Workflow.as_agent()، من خلال بروتوكول استجابات Foundry أو استدعاءات مع الحد الأدنى من التعليمات البرمجية.

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

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

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

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
dotnet add package Azure.AI.Projects --prerelease

• Python 3.10 أو أحدث

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

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

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

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

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

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("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["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. بالنسبة إلى عامل غير سير العمل، يستخدم الافتراضي history_source="agent_server" موفر استجابة خادم العامل المكون كمصدر محفوظات النموذج. يمنع المضيف خدمة نموذج انتقال البيانات من الخادم من الاحتفاظ بنسخة ثانية عندما يخزن العميل المحفوظات بشكل افتراضي.

لا تقم بدمج مصدر المحفوظات الافتراضي مع الذي يحتوي على HistoryProviderload_messages=True. لا تقم أيضا بتعيين conversation_idprevious_response_idخيارات متابعة الخدمة أو أو conversation انتقال البيانات من الخادم. يرفض المضيف هذه التكوينات لمنع المحفوظات المكررة.

استخدم ResponsesHostServer(agent, history_source="agent") عندما يجب على موفر محفوظات العامل أو خدمة نموذج انتقال البيانات من الخادم إدارة محفوظات المحادثات. يمرر هذا الوضع إدخال الطلب الحالي فقط من خادم العامل ويحافظ على محفوظات العامل وسلوك تخزين الخدمة. يجب أن تستخدم عمليات التنفيذ المخصصة SupportsAgentRun هذا الوضع. store تظل المعلمة منفصلة: تحدد موفر الاستجابة الذي يستمر في مدخلات ومخرجات واجهة برمجة تطبيقات الاستجابات في كلا الوضعين.

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

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

ResponsesHostServer تكوين المتاجر المدعومة من Foundry بشكل افتراضي. بالنسبة للوكلاء غير التابعين لسير العمل، AgentSessionStoreProvider يوفر FoundryAgentSessionStore. بالنسبة لوكلاء سير العمل، CheckpointStoreProvider يوفر FoundryCheckpointStore. FunctionApprovalStoreProvider يوفر FoundryFunctionApprovalStore للحصول على الموافقات المعلقة. تستخدم هذه المتاجر Foundry State Store عند استضافتها وحالة خادم العامل المحلي عند التشغيل محليا.

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

لتخصيص التخزين، مرر StoreProvider إلى agent_session_store_provider أو function_approval_store_provider. مرر إلى ContextScopedStoreProvidercheckpoint_store_provider. على سبيل المثال، قم بتنفيذ SessionStoreStoreProvider[SessionStore] واستخدام مخزن جلسة عمل عامل غير سير العمل الخاص بك.

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

القدرة	نوع العامل	المتطلبات والسلوك
استجابات الخلفية المرنة	سير العمل فقط	ضبط ResponsesServerOptions(resilient_background=True). أرسل طلب الاستجابات مع store=true و background=true. بعد إعادة التشغيل، يستأنف المضيف أحدث نقطة تحقق دائمة لسير العمل أو يعيد تشغيل الإدخال الأصلي إذا لم تكن هناك نقطة تحقق. لا تقم بتكوين تخزين نقطة التحقق على سير العمل لأن المضيف يديره. اجعل الآثار الجانبية الخارجية متكررة لأن العمل بعد آخر نقطة تفتيش دائمة قد يتكرر.
محادثات قابلة للتوجيه	غير سير العمل فقط	تعيين ResponsesServerOptions(steerable_conversations=True) طلبات الاستجابات وإرسالها باستخدام store=true. استمر في تشغيل سلسلة خطية واحدة عن طريق إعادة استخدام نفس conversation القيمة. بدلا من ذلك، أرسل السابق previous_response_id مباشرة واحتفظ بالحل agent_session_id. يرفض المضيف المهام السابقة القديمة التي من شأنها إنشاء نسخة المستودع.

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

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

عندما تتطلب أداة MCP المستضافة من Foundry موافقة المستخدم، ResponsesHostServer ترجع استجابة غير مكتملة مع عنصر oauth_consent_request إخراج. قدمها consent_link للمستخدم، ثم تابع معرف الاستجابة غير المكتمل كما هو الحال previous_response_id بعد إكمال المستخدم للموافقة. يحتفظ المضيف بجلسة العامل لإعادة المحاولة هذه ويعرض ارتباطات موافقة 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["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()

للتحكم الكامل في معالجة الطلب، استخدم 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["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 AZURE_AI_MODEL_DEPLOYMENT_NAME="<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 ai agent init).
APPLICATIONINSIGHTS_CONNECTION_STRING	سلسلة الاتصال Application Insights لبيانات تتبع الاستخدام.

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

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

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

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