تطوير وكلاء باستخدام LangGraph وخدمة Microsoft Foundry Agent Service (الكلاسيكية)

ينطبق فقط على:بوابة Foundry (كلاسيكية). هذه المقالة غير متاحة لبوابة Foundry الجديدة. تعرف على المزيد حول البوابة الجديدة.

ملحوظة

قد تفتح الروابط في هذا المقال محتوى في وثائق Microsoft Foundry الجديدة بدلا من وثائق Foundry (الكلاسيكية) التي تشاهدها الآن.

استخدم الحزمة langchain-azure-ai لربط تطبيقات LangGraph وLangChain بخدمة وكيل Foundry. تستعرض هذه المقالة سيناريوهات عملية، من وكلاء الموجه الأساسي إلى سير العمل المعتمد على الأدوات.

المتطلبات المسبقه

• اشتراك في Azure. أنشئ واحدا مجانا.
• مشروع فاوندري في فاوندري كلاسيك.
• نموذج دردشة منشور (على سبيل المثال، gpt-4.1) في مشروعك.
• Python 3.10 أو أحدث.
• Azure CLI تسجيل الدخول (az login) بحيث يمكن DefaultAzureCredential المصادقة.

تكوين بيئتك

قم بتثبيت الحزم المستخدمة في هذا المقال:

pip install langchain-azure-ai[tools,v1] azure-ai-agents azure-identity pandas

مهم

قم بالتثبيت [v1] ليشمل دعم Foundry الكلاسيكي.

قم بتثبيت الإضافات [tools] لاستخدام أدوات مثل Document Intelligence أو موصلات Azure Logic Apps.

اضبط متغيرات البيئة المستخدمة في العينات:

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export MODEL_DEPLOYMENT_NAME="gpt-4.1"

أنشئ مصنع الوكلاء

أنشئ أداة AgentServiceFactory باستخدام دمج v1. يتم إدارة الوكلاء الذين يتم إنشاؤهم من خلال هذا المصنع في Foundry الكلاسيكي.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.v1 import AgentServiceFactory

factory = AgentServiceFactory(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

ما الذي يفعله هذا المقتطف: يربط الإصدار الأول AgentServiceFactory بمشروعك بحيث يمكن إنشاء وإدارة وكلاء LangGraph لاحقين في Foundry الكلاسيكي.

ملحوظة

الوكلاء الذين تم إنشاؤهم مع langchain_azure_ai.agents.v1.AgentServiceFactory يمكن رؤيتهم في بوابة Foundry (الكلاسيكي).

إنشاء وكيل مطالبات أساسي

ابدأ بوكيل طلب بسيط للتحقق من إعدادك بسرعة.

agent = factory.create_prompt_agent(
    name="my-echo-agent",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions=(
        "You are a helpful AI assistant that always replies back saying the "
        "opposite of what the user says."
    ),
    trace=True,
)

print(f"Agent with ID {factory.get_agents_id_from_graph(agent)} created.")

Agent with ID {'my-echo-agent:1'} created.

استدعاء الفاعل:

from langchain_core.messages import HumanMessage
from langchain_azure_ai.utils.agents import pretty_print

messages = [HumanMessage(content="I'm a genius and I love programming!")]
state = agent.invoke({"messages": messages})

pretty_print(state)

================================ Human Message =================================

I'm a genius and I love programming!
================================== Ai Message ==================================
Name: my-echo-agent

You are not a genius and you hate programming!

ما الذي يفعله هذا المقتطف: ينشئ وكيل v1 قائم على الأوامر في خدمة وكيل الصابك (الكلاسيكي)، يستدعيه، ويطبع تسلسل الرسائل الكامل من حالة LangGraph.

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

from IPython import display

display.Image(agent.get_graph().draw_mermaid_png())

factory.delete_agent(agent)

ما الذي يفعله هذا المقتطف: يعرض الرسم البياني ليظهر عقدة خدمة الوكيل الواحدة ثم يحذف الوكيل المؤقت للعينة القديمة.

تكوين الإعدادات المتقدمة‬

يمكنك تكوين سلوك النموذج والبيانات الوصفية عن طريق تمرير الوسطط الاختياري إلى create_prompt_agent.

custom_agent = factory.create_prompt_agent(
    name="custom-configured-agent",
    description="A creative writing assistant with poetic flair",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions="You are a creative writing assistant. Write in a poetic style.",
    temperature=0.8,
)

response = custom_agent.invoke(
    {"messages": [HumanMessage("Describe a sunset over the ocean.")]}
)

pretty_print(response)

================================ Human Message =================================

Describe a sunset over the ocean.
================================== Ai Message ==================================
Name: custom-configured-agent

...poetic response...

تشمل الخيارات temperatureالشائعة ، top_p، response_format، tools، tool_resources، و metadata.

ما الذي يفعله هذا المقتطف: ينشئ وكيلا ثانيا بإعدادات التوليد غير الافتراضية ويتحقق من السلوك باستخدام طلب عينة.

أضف أدوات لوكيلك

يمكنك إضافة أدوات لوكيلك لتنفيذ الإجراءات. الطريقة create_prompt_agent تنفذ حلقة الوكلاء نيابة عنك.

يجب أن تميز بين نوعين من الأدوات:

• الأدوات المحلية: هي أدوات تعمل في موقع كود الوكيل الخاص بك. يمكن أن تكون هذه الدوال قابلة للاستدعاء أو أي وظيفة متاحة لنظام لانغتشين/لانغغراف البيئي.
• الأدوات المدمجة: هذه أدوات يمكن تشغيلها حصريا في خدمة وكلاء الصيادة؛ على جانب الخادم. يمكن تطبيق أدوات الخادم فقط على وكلاء Foundry.

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

القسم التالي يشرح كيفية استخدام كلاهما:

إضافة الأدوات المحلية

حدد دوال Python محلية ومررها في tools.

def multiply(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b


def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b


def divide(a: int, b: int) -> float:
    """Divide one integer by another."""
    return a / b


tools = [add, multiply, divide]

math_agent = factory.create_prompt_agent(
    name="math-agent",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions=(
        "You are a helpful assistant tasked with performing arithmetic on "
        "a set of inputs."
    ),
    tools=tools,
)

استدعاء الوكيل المفعل بالأداة:

messages = [
    HumanMessage(content="Add 3 and 4. Multiply the output by 2. Divide the output by 5")
]
state = math_agent.invoke({"messages": messages})
pretty_print(state)

================================ Human Message =================================

Add 3 and 4. Multiply the output by 2. Divide the output by 5
================================== Ai Message ==================================
Tool Calls:
    add (...)
    multiply (...)
    divide (...)
...
================================== Ai Message ==================================
Name: math-agent

The final result is 2.8.

ما يفعله هذا المقتطف: يربط ثلاث أدوات Python محلية بوكيل موجه v1 ويعرض استدعاءات أدوات متعددة الخطوات يتم تنسيقها عبر حلقة الوكيل.

استخدم أدوات أخرى من نظام LangGraph/LangChain مثل Azure Document Intelligence في أدوات Foundry من نفس تدفق الوكيل. بينما هذه الأدوات مرتبطة بمورد من Foundry، فهي ليست حصرية لخدمة الوكيل وبالتالي تعمل كأداة محلية.

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

document_parser_agent = factory.create_prompt_agent(
    name="document-agent",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions="You are a helpful assistant tasked with analyzing documents.",
    tools=[AzureAIDocumentIntelligenceTool(credential=DefaultAzureCredential())],
)

نصيحة

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

اطلب من الوكيل تحليل فاتورة من رابط:

messages = [
    HumanMessage(
        content=(
            "What's the total amount in the invoice at "
            "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/"
            "sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/"
            "forms/Form_1.jpg"
        )
    )
]
response = document_parser_agent.invoke({"messages": messages})
pretty_print(response)

================================ Human Message =================================

What's the total amount in the invoice at ...
================================== Ai Message ==================================
Tool Calls:
    azure_ai_document_intelligence (...)
...
================================== Ai Message ==================================
Name: document-agent

The total amount in the invoice is **$144.00**.

ما الذي يفعله هذا المقتطف: يطلب من الوكيل استخراج البيانات من صورة فاتورة نموذجية. يقوم الوكيل بالاتصال AzureAIDocumentIntelligenceTool لتحليل المستند ويعيد النتيجة. الناتج المتوقع: "المبلغ الإجمالي في الفاتورة هو 144.00 دولار."

إضافة أدوات مدمجة

الأدوات المدمجة في خدمة وكيل الصيادة تعمل على جانب الخادم بدلا من عقدة الأدوات مثل الأدوات المحلية. في هذا النمط v1، أنشئ أدوات مدمجة من azure.ai.agents.models ولفها ب AgentServiceBaseTool ل .create_prompt_agent

مثال: استخدم أداة مفسر الشيفرة

أنشئ وكيل مفسر كود لتحليل البيانات واستدعيه بملف بيانات وهمي data.csv .

قبل تشغيل هذه العينة، أنشئ ملفا محليا data.csv في مجلد العمل الحالي الخاص بك.

from pathlib import Path

import pandas as pd

data = {
    "month": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
    "sales": [12000, 15000, 18000, 14000, 22000, 25000],
    "region": ["North", "South", "East", "West", "North", "South"],
}

df = pd.DataFrame(data)
csv_path = Path.cwd() / "data.csv"
df.to_csv(csv_path, index=False, encoding="utf-8-sig")

print(f"Created sample data file: {csv_path}")

Created sample data file: .../data.csv

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

رفع وتكوين الملفات للأدوات

نحتاج إلى رفع هذا الملف ليكون متاحا لأداة مفسر الكود. استخدم حزمة تطوير Foundry لرفعها.

from azure.ai.agents import AgentsClient
from azure.ai.agents.models import CodeInterpreterTool, FilePurpose

client = AgentsClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

uploaded_file = client.files.upload_and_poll(
    file_path=str(csv_path),
    purpose=FilePurpose.AGENTS,
)
print(f"Uploaded file ID: {uploaded_file.id}")

Uploaded file ID: file_...

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

ثم قم بتكوين الأداة:

code_interpreter = CodeInterpreterTool(file_ids=[uploaded_file.id])
print("Code interpreter tool configured.")

Code interpreter tool configured.

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

تحتاج الطريقة create_prompt_agent إلى تغليف أدوات خدمة الوكيل في AgentServiceBaseTool.

from langchain_azure_ai.agents.v1.prebuilt.tools import AgentServiceBaseTool


code_interpreter_agent = factory.create_prompt_agent(
    name="code-interpreter-agent",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions=(
        "You are a data analyst agent. Analyze the provided CSV data and "
        "create visualizations when helpful."
    ),
    tools=[AgentServiceBaseTool(tool=code_interpreter)],
)

دعونا نرى ذلك عمليا:

messages = [
    HumanMessage(
        content=(
            "Create a pie chart with the previously uploaded file "
            f"(ID: {uploaded_file.id}) showing sales by region and show it "
            "to me as a PNG image."
        )
    )
]
state = code_interpreter_agent.invoke({"messages": messages})
pretty_print(state)

================================ Human Message =================================

Create a pie chart with the previously uploaded file ...
================================== Ai Message ==================================
Name: code-interpreter-agent

[
    {'type': 'text', 'text': 'Here is the pie chart ...'},
    {'type': 'image', 'mime_type': 'image/png', 'base64': 'iVBORw0...'}
]

ما الذي يفعله هذا المقتطف: يلف CodeInterpreterTool ب AgentServiceBaseTool، وينفذ التحليل في خدمة الوكيل، ويعرض صورة PNG المرتجعة من محتوى base64.

إرسال محتوى الملف داخل الخط

عندما تمرر محتوى الملف كمدخلات وتكون أداة مفسر الكود متصلة بالوكيل، يتم رفع الملفات تلقائيا.

import base64

code_interpreter_agent = factory.create_prompt_agent(
    name="code-interpreter-agent-inline-file",
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    instructions=(
        "You are a data analyst agent. Analyze the provided CSV data and "
        "create visualizations when helpful."
    ),
    tools=[AgentServiceBaseTool(tool=CodeInterpreterTool())],
)

with open("data.csv", "rb") as file_handle:
    csv_data = base64.b64encode(file_handle.read()).decode()

state = code_interpreter_agent.invoke(
    {
        "messages": [
            HumanMessage(
                content=[
                    {"type": "file", "mime_type": "text/csv", "base64": csv_data},
                    {
                        "type": "text",
                        "text": (
                            "Create a pie chart with the uploaded data showing "
                            "sales by region and show it as a PNG image."
                        ),
                    },
                ]
            )
        ]
    }
)

ما الذي يفعله هذا المقتطف: يرسل ملف CSV داخل حمولة الرسالة حتى يتمكن مفسر الكود من معالجته دون الحاجة إلى خطوة رفع صريحة منفصلة.

تشغيل العمليات غير المتزامنة

يمكنك استدعاء وكلاء v1 بشكل غير متزامن مع ainvoke.

async def async_example() -> None:
    async_agent = factory.create_prompt_agent(
        name="async-demo-agent",
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        instructions="You are an async AI assistant.",
    )

    try:
        response = await async_agent.ainvoke(
            {
                "messages": [
                    HumanMessage("What are the benefits of asynchronous programming?")
                ]
            }
        )
        print(response)
    finally:
        factory.delete_agent(async_agent)


await async_example()

{'messages': [...], ...}

ما الذي يفعله هذا المقتطف: يظهر استدعاء غير متزامن مع ainvoke ويضمن التنظيف باستخدام factory.delete_agent الكتلة finally الواحدة.

عملاء التنظيف

احذف الوكلاء الذين أنشأتهم أثناء جلستك.

factory.delete_agent(math_agent)
factory.delete_agent(document_parser_agent)
factory.delete_agent(custom_agent)
factory.delete_agent(code_interpreter_agent)

استكشاف الأخطاء وإصلاحها

استخدم هذه القائمة لتشخيص المشاكل الشائعة في الإعداد ووقت التشغيل.

تمكين التسجيل

import logging

logging.getLogger("langchain_azure_ai").setLevel(logging.DEBUG)

للتشخيصات الأوسع:

import logging

logging.basicConfig(level=logging.DEBUG)

تحقق من تكوينك

• تأكد AZURE_AI_PROJECT_ENDPOINT من النقاط إلى نقطة نهاية مشروع Foundry الكلاسيكي الصحيح.
• تأكيد MODEL_DEPLOYMENT_NAME تطابق النموذج الحالي لنشره.
• تحقق من سياق المصادقة باستخدام az account show.
• ابدأ أولا بمثال وكيل التوجيه الأدنى.

تحقق من الموارد والأصوات

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

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

• تطوير التطبيقات باستخدام LlamaIndex
• تصور وإدارة الآثار في Foundry
• استخدام نماذج Foundry
• المرجع: واجهة برمجة تطبيقات الاستدلال النموذجي