وكلاء مستضافون في 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)

تثبيت حزمة استضافة 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.",
    default_options={"store": False},
)

server = ResponsesHostServer(agent)
server.run()

يلتف ResponsesHostServer العامل الخاص بك ويعرضه من خلال بروتوكول استجابات Foundry. يؤدي الإعداد store إلى في default_options إلى False تجنب تكرار محفوظات المحادثات، نظرا لأن البنية الأساسية للاستضافة تدير المحفوظات تلقائيا.

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

يمنحك بروتوكول استدعاءات التحكم الكامل في طلب واستجابة 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) في الإنتاج.

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.

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

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

  • Last updated on