خدمة وكلاء مايكروسوفت فاوندري

FoundryAgentيربط إطار عمل العامل بتعريف عامل تديره Microsoft Foundry Agent Service. يتم تكوين نموذج العامل والإرشادات والأدوات المستضافة والإصدار في Foundry؛ يتصل تطبيقك بهذا التعريف ويستخدم واجهات برمجة التطبيقات القياسية لتشغيل إطار عمل العامل وتدفقه وجلساته.

استخدم هذا التكامل من أجل:

• عوامل المطالبة، التي تسمى وتعريفات عامل من جانب الخادم التي تم إصدارها.
• العوامل المستضافة، التي يتم توزيعها تطبيقات الوكيل التي تم الوصول إليها من خلال نقطة نهاية خاصة بالعامل.

للحصول على استدلال النموذج المباشر حيث يمتلك التطبيق الخاص بك تعريف العامل، راجع Microsoft موفر نموذج Foundry. لنشر تطبيق Agent Framework كعامل مستضاف، راجع Foundry Hosted Agents.

ثبت الحزم

dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

الاتصال بعامل المطالبة

AIProjectClient إنشاء لمشروع Foundry والتفاف ك AgentReferenceFoundryAgent. قم بتثبيت الإصدار عندما يجب أن يستخدم التطبيق تعريفا معينا لعامل المطالبة.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI.Foundry;

var projectClient = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!),
    new DefaultAzureCredential());

FoundryAgent agent = projectClient.AsAIAgent(
    new AgentReference(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!,
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_VERSION")!));

Console.WriteLine(await agent.RunAsync("What can you help me with?"));

يمكنك أيضا استرداد ProjectsAgentRecord لاستخدام أحدث إصدار له أو ProjectsAgentVersion لاستخدام إصدار تم استرداده بشكل صريح، ثم تمرير هذا الكائن إلى projectClient.AsAIAgent(...).

استرداد أحدث إصدار من عامل المطالبة

استخدم AgentAdministrationClient عندما يجب أن يحل التطبيق أحدث إصدار مسجل بالاسم.

ProjectsAgentRecord agentRecord =
    await projectClient.AgentAdministrationClient.GetAgentAsync(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!);

FoundryAgent latestAgent = projectClient.AsAIAgent(agentRecord);
Console.WriteLine(await latestAgent.RunAsync("What can you help me with?"));

Important

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

تحذير

DefaultAzureCredential هو مريح للتنمية. في الإنتاج، تفضل بيانات اعتماد معينة مثل ManagedIdentityCredential لتجنب فحص بيانات الاعتماد غير المقصودة.

الاتصال بعامل مستضاف

يعرض الوكلاء المستضافون نقطة نهاية OpenAI خاصة بالعامل. أنشئ نقطة النهاية من نقطة نهاية المشروع واسم العامل المسجل، ثم مررها إلى AIProjectClient.AsAIAgent(...).

Env.TraversePath().Load();

// Port the Hosted-* samples listen on when run locally with `dotnet run`.
const int LocalAgentPort = 8088;

// AZURE_AI_AGENT_NAME is the registered server-side agent name.
string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");

// Pick the server to talk to. `--local` and `--remote` mirror the flag `azd ai agent invoke`
// exposes; with neither, ask at startup.
    ══════════════════════════════════════════════════════════
    """);
Console.ResetColor();
Console.WriteLine();

يحدد محدد الإصدار الذي يتحكم فيه المسؤول لنقطة النهاية إصدار "العامل المستضاف" النشط.

ثبت الحزم

pip install agent-framework-foundry

الإعداد

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

استخدم FOUNDRY_AGENT_VERSION ل عوامل المطالبة. يمكن للوكلاء المستضافين حذفه.

الاتصال بعامل المطالبة

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

async def main() -> None:
    agent = FoundryAgent(
        project_endpoint="https://your-project.services.ai.azure.com",
        agent_name="my-prompt-agent",
        agent_version="1.0",
        credential=AzureCliCredential(),
    )

    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result}")

    # Streaming
    print("Agent (streaming): ", end="", flush=True)
    async for chunk in agent.run("Tell me a fun fact.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

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

الاتصال بعامل مستضاف

لا يتطلب agent_versionالوكلاء المستضافون . الاتصال بنقطة نهاية المشروع واسم العامل المسجل.

async def main() -> None:
    # HostedAgents don't need agent_version
    agent = FoundryAgent(
        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
        agent_name=os.getenv("FOUNDRY_AGENT_NAME"),
        credential=AzureCliCredential(),
    )

    result = await agent.run("Summarize the latest news about AI.")
    print(f"Agent: {result}")

ما الذي يعمل وما لا يعمل مع FoundryAgent

FoundryAgent يتصل بتعريف عامل موجود بالفعل في Foundry. تعد الإرشادات المخزنة وتكوين الأداة موثوقة، لذلك يختلف السلوك من جانب العميل عن السلوك المملوك Agent(client=FoundryChatClient(...))للتطبيق.

ادوات

تم تمرير نوع الأداة إلى FoundryAgent(...)	السلوك
FunctionToolمع Python محلي قابل للاستدعاء	معتمد فقط عندما يكون تعريف الدالة المطابقة موجودا بالفعل على عامل Foundry. يتم تشغيل القابل للاستدعاء في عملية التطبيق عندما يطلبه Foundry.
الأدوات المستضافة، بما في ذلك البحث على الويب، ومترجم التعليمات البرمجية، والبحث في الملفات، وMCP، وإنشاء الصور، Microsoft مربع أدوات Foundry	قم بتكوينها في تعريف عامل Foundry. تمريرها من جانب العميل لا يضيفها إلى العامل المدار بواسطة الخدمة.

للحصول على مرفق Toolbox وإرشادات استهلاك MCP المباشرة، راجع Microsoft Foundry Toolbox.

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

موفرو السياق

سلوك موفر السياق	يعمل مع FoundryAgent؟
إضافة رسائل، مثل الذاكرة المستردة أو قصاصات RAG أو معلومات ملف تعريف المستخدم	نعم. تتم إعادة توجيه السياق الذي تم إدخاله مع الطلب.
استمرار المحادثة أو مراقبتها	نعم. يعمل الموفر محليا حول الطلب والاستجابة.
إضافة الأدوات ديناميكيا	لا، ما لم يتم الإعلان عن هذه الأدوات بالفعل في تعريف عامل Foundry.

استخدم Agent(client=FoundryChatClient(...)) عندما يحتاج التطبيق إلى تحديد أداة ديناميكية أو تحميل مهارة أو أي سلوك يغير الأدوات المرئية للنموذج في وقت التشغيل.

خيارات التشغيل

لأن تعريف عامل Foundry هو مصدر الحقيقة، وليس كل خيار تم تمريره default_options أو agent.run(...) يتم تكريمه.

خيار	سلوك عامل المطالبة
model	تم تجاهله. يأتي النموذج من تعريف عامل Foundry.
tools، tool_choice، parallel_tool_calls	تمت إزالته من الطلب. يجب الإعلان عن الأدوات في تعريف عامل Foundry.
instructions ورسائل النظام أو المطور	تم تجاهله. إرشادات Foundry المخزنة موثوقة.
conversation_id	يستخدم ويتم تعيينه إلى جلسة عمل عامل Foundry عند الاقتضاء.
extra_body	تمت إعادة توجيهه ودمجه مع مرجع العامل الذي يوفره إطار العمل.
معلمات أخذ العينات وبيانات التعريف و userstoreو وresponse_format	تمت إعادة التوجيه، ولكن يمكن لعامل Foundry أو تكوين النموذج تجاوزها أو تقييدها.

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

Tip

استخدم Agent(client=FoundryChatClient(...)) عندما تحتاج إلى التحكم في كل تشغيل على الإرشادات أو خيارات الإنشاء أو الأدوات.

إدارة جلسة عمل خدمة عامل مستضاف

تتطلب العوامل المستضافة التي تستخدم جلسات من جانب الخدمة سطح استجابات المعاينة:

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

    queries = [
        "Hi!",
        "Your name is Javis. What can you do?",
        "What is your name?",
    ]
    for query in queries:
        print(f"\nUser: {query}")
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run(query, session=session, stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
    print()


async def run_service_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
) -> None:
    """Let Foundry create the hosted-agent session, then delete it when finished."""
    session = AgentSession()
    print("\nService-managed hosted-agent session")
    print(f"Before first request: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    try:
        await run_conversation(agent, session)
        print(f"After conversation: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    finally:
        hosted_session_id = session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)
        if isinstance(hosted_session_id, str) and hosted_session_id:
            await project_client.agents.delete_session(agent_name, hosted_session_id)
            print(f"Deleted session: {hosted_session_id}")


async def run_user_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
    agent_version: str | None,
) -> None:
    """Create, attach, and delete a hosted-agent session explicitly."""
    resolved_agent_version = agent_version
    if resolved_agent_version is None:
        agent_details = await project_client.agents.get(agent_name)
        resolved_agent_version = agent_details.versions.latest.version

    hosted_session = await project_client.agents.create_session(
        agent_name,
        version_indicator=VersionRefIndicator(agent_version=resolved_agent_version),
    )
    session = AgentSession()
    session.state[FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY] = hosted_session.agent_session_id

    print("\nUser-managed hosted-agent session")
    print(f"Created session: {hosted_session.agent_session_id}")
    try:
        await run_conversation(agent, session)
    finally:
        await project_client.agents.delete_session(agent_name, hosted_session.agent_session_id)
        print(f"Deleted session: {hosted_session.agent_session_id}")


async def main() -> None:
    credential = AzureCliCredential()
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    agent_name = os.environ["FOUNDRY_AGENT_NAME"]
    agent_version = os.getenv("FOUNDRY_AGENT_VERSION")

    project_client = AIProjectClient(

Tip

راجع العينةusing_deployed_agent.py للحصول على مثال كامل.

تعيين مهلة HTTP مخصصة

FoundryAgent يرث مهلة OpenAI SDK بشكل افتراضي. مرر timeout= بالثوان عندما تتطلب المحادثات متعددة الأدوار أو ظروف الشبكة حدا مختلفا.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    credential=AzureCliCredential(),
    timeout=120.0,
)

يتم تطبيق المهلة على نسخة لكل عامل من عميل HTTP ولا تؤثر على العوامل الأخرى التي تشترك في نفس AIProjectClient.

Note

FoundryAgent لا يتوفر تكامل عوامل المطالبة والمستضافة حاليا ل Agent Framework Go. راجع مستودع Agent Framework Go للحصول على أحدث حالة.

تشغيل المحادثات ودفقها ومتابعة المحادثات

بعد الاتصال، استخدم نفس واجهات برمجة التطبيقات مثل عوامل Agent Framework الأخرى:

• قم بتشغيل طلب باستخدام RunAsync أو run.
• دفق التحديثات باستخدام RunStreamingAsync أو run(..., stream=True).
• AgentSession أعد استخدام لمتابعة محادثة.
• استخدم واجهات برمجة التطبيقات للمحادثة من جانب خادم Foundry عندما يجب أن تكون المحادثة مرئية ومستمرة في مشروع Foundry.

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

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

مراجعة موفر نموذج Microsoft Foundry