ai-agents-for-beginners

مائیکروسافٹ ایجنٹ فریم ورک کی تلاش

Agent Framework

تعارف

اس سبق میں کور کیا جائے گا:

سیکھنے کے مقاصد

اس سبق کو مکمل کرنے کے بعد، آپ جان سکیں گے کہ:

کوڈ کے نمونے

Microsoft Agent Framework (MAF) کے لئے کوڈ کے نمونے اس رپوزیٹری میں xx-python-agent-framework اور xx-dotnet-agent-framework فائلوں کے تحت مل سکتے ہیں۔

مائیکروسافٹ ایجنٹ فریم ورک کو سمجھنا

Framework Intro

Microsoft Agent Framework (MAF) مائیکروسافٹ کا متحدہ فریم ورک ہے AI ایجنٹس بنانے کے لیے۔ یہ پروڈکشن اور تحقیقاتی ماحول میں مختلف قسم کے ایجنٹک استعمال کے کیسز کو حل کرنے کی لچک فراہم کرتا ہے جن میں شامل ہیں:

پروڈکشن میں AI ایجنٹس کو فراہم کرنے کے لیے، MAF میں شامل خصوصیات بھی ہیں:

مائیکروسافٹ ایجنٹ فریم ورک کا دھیان ایک دوسرے کے ساتھ انٹرآپریبل ہونے پر بھی ہے:

آئیے دیکھتے ہیں کہ یہ خصوصیات مائیکروسافٹ ایجنٹ فریم ورک کے کچھ بنیادی تصورات پر کیسے لاگو ہوتی ہیں۔

مائیکروسافٹ ایجنٹ فریم ورک کے کلیدی تصورات

ایجنٹس

Agent Framework

ایجنٹس بنانا

ایجنٹ کی تخلیق انفرنس سروس (LLM فراہم کنندہ)، AI ایجنٹ کے پیروی کرنے کے لیے ہدایات کے ایک سیٹ، اور ایک مختص شدہ name کی تعریف کر کے کی جاتی ہے:

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent( instructions="You are good at recommending trips to customers based on their preferences.", name="TripRecommender" )

اوپر Azure OpenAI استعمال کیا جا رہا ہے لیکن ایجنٹس مختلف خدمات کے ذریعے بنائے جا سکتے ہیں جن میں Microsoft Foundry Agent Service شامل ہے:

AzureAIAgentClient(async_credential=credential).create_agent( name="HelperAgent", instructions="You are a helpful assistant." ) as agent

OpenAI Responses, ChatCompletion APIs

agent = OpenAIResponsesClient().create_agent( name="WeatherBot", instructions="You are a helpful weather assistant.", )

agent = OpenAIChatClient().create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

یا MiniMax، جو کہ بڑی کانٹیکسٹ ونڈو (204K ٹوکن تک) کے ساتھ OpenAI-مطابق API فراہم کرتا ہے:

agent = OpenAIChatClient(base_url="https://api.minimax.io/v1", api_key=os.environ["MINIMAX_API_KEY"], model_id="MiniMax-M3").create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

یا A2A پروٹوکول کا استعمال کرتے ہوئے ریموٹ ایجنٹس:

agent = A2AAgent( name=agent_card.name, description=agent_card.description, agent_card=agent_card, url="https://your-a2a-agent-host" )

ایجنٹس چلانا

ایجنٹس کو .run یا .run_stream طریقوں سے چلایا جاتا ہے جو نان-اسٹریمنگ یا اسٹریمنگ جوابات کے لیے ہوتے ہیں۔

result = await agent.run("What are good places to visit in Amsterdam?")
print(result.text)

async for update in agent.run_stream("What are the good places to visit in Amsterdam?"):
    if update.text:
        print(update.text, end="", flush=True)

ہر ایجنٹ رن میں اختیارات بھی ہو سکتے ہیں تاکہ ایجنٹ کے استعمال کردہ max_tokens, ایجنٹ کے کال کرنے والے tools، اور یہاں تک کہ ایجنٹ کے لیے استعمال ہونے والے model جیسے پیرامیٹرز کو حسب ضرورت بنایا جا سکے۔

یہ ایسے حالات میں مددگار ہوتا ہے جہاں مخصوص ماڈلز یا ٹولز صارف کے کام کو مکمل کرنے کے لیے ضروری ہوں۔

ٹولز

ٹولز کو ایجنٹ کی تعریف کے دوران بھی متعین کیا جا سکتا ہے:

def get_attractions( location: Annotated[str, Field(description="The location to get the top tourist attractions for")], ) -> str: """Get the top tourist attractions for a given location.""" return f"The top attractions for {location} are." 


# جب ایک ChatAgent براہ راست بنایا جائے

agent = ChatAgent( chat_client=OpenAIChatClient(), instructions="You are a helpful assistant", tools=[get_attractions]

اور ایجنٹ کو چلانے کے وقت بھی:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # صرف اس رن کے لئے فراہم کردہ آلہ )

ایجنٹ تھریڈز

ایجنٹ تھریڈز ملٹی ٹرن بات چیت کو سنبھالنے کے لیے استعمال ہوتے ہیں۔ تھریڈز کو یا تو اس طرح بنایا جا سکتا ہے:

تھریڈ بنانے کے لیے کوڈ ایسا ہوگا:

# ایک نیا تھریڈ بنائیں۔
thread = agent.get_new_thread() # ایجنٹ کو تھریڈ کے ساتھ چلائیں۔
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

آپ پھر تھریڈ کو بعد میں استعمال کے لیے سیریلائز بھی کر سکتے ہیں:

# ایک نیا تھریڈ بنائیں۔
thread = agent.get_new_thread() 

# ایجنٹ کو تھریڈ کے ساتھ چلائیں۔

response = await agent.run("Hello, how are you?", thread=thread) 

# اسٹوریج کے لیے تھریڈ کو سیریلائز کریں۔

serialized_thread = await thread.serialize() 

# اسٹوریج سے لوڈ کرنے کے بعد تھریڈ کی حالت کو ڈیسریلائز کریں۔

resumed_thread = await agent.deserialize_thread(serialized_thread)

ایجنٹ مڈل ویئر

ایجنٹس ٹولز اور LLMs کے ساتھ تعامل کرتے ہیں تاکہ صارف کے کام مکمل کریں۔ بعض حالات میں، ہم ان تعاملات کے درمیان عمل درآمد یا ٹریک کرنا چاہتے ہیں۔ ایجنٹ مڈل ویئر ہمیں یہ کرنے کی اجازت دیتا ہے:

فنکشن مڈل ویئر

یہ مڈل ویئر ایجنٹ اور فنکشن/ٹول کے درمیان عمل درآمد کی اجازت دیتا ہے جسے ایجنٹ کال کرے گا۔ ایک مثال جب یہ استعمال ہوگا وہ ہے فنکشن کال پر لاگنگ کرنا۔

نیچے کوڈ میں next متعین کرتا ہے کہ آیا اگلا مڈل ویئر یا اصل فنکشن کو کال کیا جانا چاہیے۔

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # پروسیسنگ سے پہلے: فنکشن کے عمل درآمد سے پہلے لاگ کریں
    print(f"[Function] Calling {context.function.name}")

    # اگلے مڈل ویئر یا فنکشن کے عمل درآمد کو جاری رکھیں
    await next(context)

    # پروسیسنگ کے بعد: فنکشن کے عمل درآمد کے بعد لاگ کریں
    print(f"[Function] {context.function.name} completed")

چیٹ مڈل ویئر

یہ مڈل ویئر ایجنٹ اور LLM کے درمیان درخواستوں کے درمیان ایکشن لاگ یا عمل درآمد کرنے کی اجازت دیتا ہے۔

اس میں اہم معلومات شامل ہیں جیسے کہ AI سروس کو بھیجے جانے والے messages۔

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # پری پروسیسنگ: اے آئی کال سے پہلے لاگ
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # اگلے مڈل ویئر یا اے آئی سروس پر جاری رکھیں
    await next(context)

    # پوسٹ پروسیسنگ: اے آئی کے جواب کے بعد لاگ
    print("[Chat] AI response received")

ایجنٹ میموری

Agentic Memory سبق میں پہلے بتایا گیا ہے کہ میموری ایجنٹ کو مختلف سیاق و سباق پر کام کرنے کے قابل بنانے کا ایک اہم عنصر ہے۔ MAF کئی مختلف قسم کی میموریز پیش کرتا ہے:

ان-میموری اسٹوریج

یہ وہ میموری ہے جو تھریڈز میں درخواست کے رن ٹائم کے دوران محفوظ ہوتی ہے۔

# ایک نیا تھریڈ بنائیں۔
thread = agent.get_new_thread() # ایجنٹ کو تھریڈ کے ساتھ چلائیں۔
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

مستقل پیغامات

یہ میموری بات چیت کی تاریخ کو مختلف سیشنز کے دوران محفوظ کرنے کے لیے استعمال ہوتی ہے۔ اسے chat_message_store_factory کا استعمال کرتے ہوئے متعین کیا جاتا ہے:

from agent_framework import ChatMessageStore

# ایک حسب ضرورت پیغام اسٹور بنائیں
def create_message_store():
    return ChatMessageStore()

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a Travel assistant.",
    chat_message_store_factory=create_message_store
)

ڈائنامک میموری

یہ میموری سیاق و سباق میں ایجنٹس کے چلانے سے پہلے شامل کی جاتی ہے۔ یہ میموریز بیرونی سروسز مثلاً mem0 میں محفوظ کی جا سکتی ہیں:

from agent_framework.mem0 import Mem0Provider

# میموری کی اعلی صلاحیتوں کے لیے Mem0 کا استعمال
memory_provider = Mem0Provider(
    api_key="your-mem0-api-key",
    user_id="user_123",
    application_id="my_app"
)

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant with memory.",
    context_providers=memory_provider
)

ایجنٹ مشاہدہ کاری

مشاہدہ کاری قابل اعتماد اور قابل نگہداشت ایجنٹک نظام بنانے کے لیے اہم ہے۔ MAF OpenTelemetry کے ساتھ انضمام کرتا ہے تاکہ بہتر مشاہدہ کاری کے لیے ٹریسنگ اور میٹر فراہم کرے۔

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # کچھ کریں
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

ورک فلو

MAF ایسے ورک فلو پیش کرتا ہے جو کام مکمل کرنے کے پیشگی متعین مراحل ہیں اور ان مراحل میں AI ایجنٹس کو اجزاء کے طور پر شامل کیا جاتا ہے۔

ورک فلو مختلف اجزاء پر مشتمل ہوتے ہیں جو بہتر کنٹرول فلو کی اجازت دیتے ہیں۔ ورک فلو کثیر ایجنٹ آرکیسٹریشن اور ورک فلو ریاستوں کو محفوظ کرنے کے لیے چیک پوائنٹنگ کو بھی ممکن بناتے ہیں۔

ورک فلو کے بنیادی اجزاء یہ ہیں:

ایگزیکیوٹرز

ایگزیکیوٹرز ان پٹ پیغامات وصول کرتے ہیں، تفویض کردہ کام انجام دیتے ہیں، اور پھر ایک پیداوار پیغام دیتے ہیں۔ یہ ورک فلو کو بڑے کام کی تکمیل کی طرف بڑھاتا ہے۔ ایگزیکیوٹرز یا تو AI ایجنٹ ہو سکتے ہیں یا حسب ضرورت منطق۔

ایجز

ایجز ورک فلو میں پیغامات کے بہاؤ کو تعریف کرنے کے لیے استعمال ہوتے ہیں۔ یہ ہو سکتے ہیں:

براہ راست ایجز - ایگزیکیوٹرز کے درمیان سادہ ایک سے ایک رابطے:

from agent_framework import WorkflowBuilder

builder = WorkflowBuilder()
builder.add_edge(source_executor, target_executor)
builder.set_start_executor(source_executor)
workflow = builder.build()

مشروط ایجز - جب کوئی خاص شرط پوری ہو تو فعال ہوتے ہیں۔ مثال کے طور پر، جب ہوٹل کے کمرے دستیاب نہ ہوں، ایک ایگزیکیوٹر دوسرے اختیارات تجویز کر سکتا ہے۔

سوئچ-کیس ایجز - پیغامات کو مختلف ایگزیکیوٹرز کی طرف مختلف شرائط کی بنیاد پر بھیجتے ہیں۔ مثال کے طور پر، اگر سفر کے صارف کو ترجیحی رسائی حاصل ہو اور ان کے کام دوسرے ورک فلو کے ذریعے سنبھالے جائیں۔

فین آؤٹ ایجز - ایک پیغام کو متعدد مقامات پر بھیجنا۔

فین اِن ایجز - مختلف ایگزیکیوٹرز سے متعدد پیغامات جمع کر کے ایک ہدف کو بھیجنا۔

ایونٹس

ورک فلو کی بہتر مشاہدہ کاری کے لیے، MAF ایگزیکیوٹر کے ایگزیکیوشن کے لیے بلٹ ان ایونٹس فراہم کرتا ہے جن میں شامل ہیں:

جدید MAF پیٹرنز

اوپر کے حصے مائیکروسافٹ ایجنٹ فریم ورک کے کلیدی تصورات کو کور کرتے ہیں۔ جیسے جیسے آپ مزید پیچیدہ ایجنٹس بنائیں، یہاں کچھ جدید پیٹرنز غور کرنے کے لیے ہیں:

Microsoft Foundry پر LangChain / LangGraph ایجنٹس کی میزبانی

مائیکروسافٹ ایجنٹ فریم ورک فریم ورک-انٹرآپریبل ہے— آپ MAF کے ساتھ لکھے گئے ایجنٹس تک محدود نہیں ہیں۔ اگر آپ کے پاس پہلے سے ہی LangChain یا LangGraph میں بنایا ہوا ایجنٹ ہے، تو آپ اسے Microsoft Foundry میزبان ایجنٹ کے طور پر چلا سکتے ہیں تاکہ Foundry رن ٹائم، سیشنز، اسکیلنگ، شناخت، اور پروٹوکول اینڈ پوائنٹس کو سنبھالے جبکہ آپ کی ایجنٹ منطق LangGraph میں رہے۔

یہ langchain_azure_ai.agents.hosting پیکج کے ذریعے کیا جاتا ہے، جو وہی پروٹوکولز استعمال کرتا ہے جو Foundry میزبان ایجنٹس استعمال کرتے ہیں اور LangGraph گراف کو مرتب کر کے ایکسپورٹ کرتا ہے۔

1. ہوسٹنگ ایکسٹرا انسٹال کریں:

pip install -U "langchain-azure-ai[hosting]>=1.2.4" azure-identity

hosting ایکسٹرا Foundry پروٹوکول لائبریریاں انسٹال کرتا ہے: azure-ai-agentserver-responses (OpenAI-مطابق /responses اینڈ پوائنٹ) اور azure-ai-agentserver-invocations (عام /invocations اینڈ پوائنٹ)۔

2. ہوسٹنگ پروٹوکول منتخب کریں:

پروٹوکول میزبان کلاس اینڈ پوائنٹ کب استعمال کریں
Responses ResponsesHostServer /responses آپ OpenAI-مطابق چیٹ، اسٹریمنگ، جواب کی تاریخ، اور گفتگو کے تھریڈنگ چاہتے ہیں — مکالماتی ایجنٹس کے لیے سفارش کردہ ڈیفالٹ۔
Invocations InvocationsHostServer /invocations آپ کو حسب ضرورت JSON شکل، ویب ہک طرز اینڈ پوائنٹ، یا غیر مکالماتی پروسیسنگ کی ضرورت ہے۔

کیونکہ Responses API Foundry میں ایجنٹ-اسٹائل ترقی کے لیے بنیادی API ہے، زیادہ تر ایجنٹس کے لیے ResponsesHostServer سے شروع کریں۔

3. ماحول کے متغیرات مرتب کریں (az login پہلے کریں تاکہ DefaultAzureCredential تصدیق کر سکے):

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL_NAME="gpt-5-mini"

جب ایجنٹ بعد میں Foundry میں میزبان ایجنٹ کے طور پر چلتا ہے، تو پلیٹ فارم خود بخود FOUNDRY_PROJECT_ENDPOINT داخل کرتا ہے۔

4. Responses پروٹوکول پر LangGraph ایجنٹ کا انکشاف کریں:

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_azure_ai.agents.hosting import ResponsesHostServer

_AZURE_AI_SCOPE = "https://ai.azure.com/.default"


def build_chat_model() -> ChatOpenAI:
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
    deployment = os.environ.get("FOUNDRY_MODEL_NAME", "gpt-5-mini")
    credential = DefaultAzureCredential()
    project = AIProjectClient(endpoint=project_endpoint, credential=credential)
    openai_client = project.get_openai_client()
    token_provider = get_bearer_token_provider(credential, _AZURE_AI_SCOPE)

    # ChatOpenAI یہاں Foundry پروجیکٹ کے OpenAI مطابقت پذیر (Responses) اینڈ پوائنٹ کو ہدف بناتا ہے۔
    return ChatOpenAI(
        model=deployment,
        base_url=str(openai_client.base_url),
        api_key=token_provider,
    )


def main() -> None:
    graph = create_agent(build_chat_model(), tools=[])
    port = int(os.environ.get("PORT", "8088"))
    ResponsesHostServer(graph).run(port=port)


if __name__ == "__main__":
    main()

اسے مقامی طور پر python main.py سے چلائیں، پھر http://localhost:8088/responses پر Responses کی درخواست بھیجیں۔

کلیدی خصوصیات:

اس مثال کا چلنے والا ورژن code-samples/14-langchain-hosted-agent.py میں موجود ہے۔ مکمل رہنمائی (Invocations پروٹوکول، حسب ضرورت درخواست کے اسکیمے، اور مسئلہ حل) کے لیے دیکھیں Host LangGraph agents as Foundry hosted agents۔

کوڈ کے نمونے

مائیکروسافٹ ایجنٹ فریم ورک کے کوڈ کے نمونے اس رپوزیٹری میں xx-python-agent-framework اور xx-dotnet-agent-framework فائلوں کے تحت مل سکتے ہیں۔

مائیکروسافٹ ایجنٹ فریم ورک کے بارے میں مزید سوالات ہیں؟

Microsoft Foundry Discord میں شامل ہوں تاکہ دوسرے سیکھنے والوں سے ملیں، آفس آور میں شرکت کریں اور اپنے AI ایجنٹس کے سوالات کے جواب حاصل کریں۔

پچھلا سبق

AI ایجنٹس کے لیے میموری

اگلا سبق

کمپیوٹر یوز ایجنٹس (CUA) بنانا

ڈس کلیمر: یہ دستاویز AI ترجمہ سروس Co-op Translator کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔

This site is open source. Improve this page.