ai-agents-for-beginners

חקר מסגרת Microsoft Agent

Agent Framework

הקדמה

שיעור זה יכסה:

מטרות הלמידה

לאחר סיום שיעור זה, תדע כיצד:

דוגמאות קוד

דוגמאות קוד ל-Microsoft Agent Framework (MAF) נמצאות במאגר זה תחת הקבצים xx-python-agent-framework ו- xx-dotnet-agent-framework.

הבנת מסגרת Microsoft Agent

Framework Intro

Microsoft Agent Framework (MAF) היא מסגרת מאוחדת של מיקרוסופט לבניית סוכני AI. היא מציעה גמישות להתמודדות עם מגוון רחב של מקרי שימוש סוכניים שנראים הן בייצור והן בסביבות מחקר, כולל:

לצורך אספקת סוכני AI בייצור, למסגרת MAF כלולים גם תכונות עבור:

מסגרת Microsoft Agent גם מתמקדת באינטרופרביליות על ידי:

בואו נבחן כיצד תכונות אלו מיושמות על חלק מהמושגים המרכזיים של מסגרת Microsoft Agent.

מושגים מרכזיים של מסגרת Microsoft Agent

סוכנים

Agent Framework

יצירת סוכנים

יצירת סוכן מתבצעת על ידי הגדרת שירות ההסקה (LLM Provider),
קבוצת הוראות שעל סוכן ה-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

ממשקי API של OpenAI Responses, ChatCompletion

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, המספק API תואם OpenAI עם חלונות הקשר גדולים (עד 204K טוקנים):

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." 


# כאשר יוצרים סוכן צ'אט ישירות

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)

Middleware של סוכן

סוכנים מתקשרים עם כלים ו-LLMs להשלמת משימות משתמש. בתרחישים מסוימים, אנו רוצים לבצע או לעקוב בין האינטראקציות הללו. Middleware של סוכן מאפשר זאת על ידי:

Middleware פונקציונלי

Middleware זה מאפשר לבצע פעולה בין הסוכן לפונקציה/כלי שהוא קורא לו. דוגמה לשימוש היא ביצוע רישום יומן במהלך קריאת פונקציה.

בקוד למטה, next מגדיר אם יש לקרוא ל-middleware הבא או לפונקציה עצמה.

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")

Middleware שיחתית

Middleware זה מאפשר לבצע או לרשום פעולה בין הסוכן לבין הבקשות בין ה-LLM.

זה כולל מידע חשוב כגון ההודעות (messages) שנשלחות לשירות ה-AI.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # עיבוד מקדים: רישום לפני קריאה ל-AI
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # המשך למידלוור או שירות AI הבא
    await next(context)

    # עיבוד לאחר מעשה: רישום לאחר תגובת AI
    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 Agent. כשאתה בונה סוכנים מורכבים יותר, הנה כמה דפוסים מתקדמים לשקול:

אירוח סוכני LangChain / LangGraph ב-Microsoft Foundry

מסגרת Microsoft Agent היא רב-פלטפורמית — אינך מוגבל לסוכנים שנכתבו עם MAF. אם כבר יש לך סוכן שבנוי עם LangChain או LangGraph, תוכל להריץ אותו כסוכן מארח ב-Microsoft Foundry כך ש-Foundry תנהל את זמן הריצה, הסשנים, הסקיילינג, הזהות ונקודות הקצה של הפרוטוקול עבורך, בעוד שהלוגיקה של הסוכן שלך נשארת ב-LangGraph.

זה נעשה עם החבילה langchain_azure_ai.agents.hosting, החשופה גרף LangGraph מותאם-קומפילציה מעל אותן פרוטוקולים בהם משתמשים סוכנים מאוחסנים ב-Foundry.

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 מותאמת אישית, נקודת קצה בסגנון webhook, או עיבוד לא שיחותי.

כיוון ש-Responses API הוא ה-API הראשי לפיתוח סגנון סוכן ב-Foundry, מומלץ להתחיל עם 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. חשוף סוכן LangGraph על פרוטוקול Responses:

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 כאן פונה לנקודת הקצה התואמת ל-OpenAI (Responses) של פרויקט Foundry.
    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, ואז שלח בקשת Responses ל-http://localhost:8088/responses.

התנהגויות מרכזיות:

גרסה רצה של דוגמה זו קיימת ב-code-samples/14-langchain-hosted-agent.py. למדריך המלא (פרוטוקול Invocations, סכמה מותאמת אישית לבקשות ופתרון תקלות), ראה Host LangGraph agents as Foundry hosted agents.

דוגמאות קוד

דוגמאות קוד למסגרת Microsoft Agent נמצאות במאגר זה תחת הקבצים xx-python-agent-framework ו- xx-dotnet-agent-framework.

שאלות נוספות על מסגרת Microsoft Agent?

הצטרף ל-Microsoft Foundry Discord כדי להיפגש עם לומדים אחרים, להשתתף בשעות משרד ולקבל תשובות לשאלותיך על סוכני AI.

שיעור קודם

זיכרון לסוכני AI

שיעור הבא

בניית סוכני שימוש במחשב (CUA)

כתב ויתור: מסמך זה תורגם באמצעות שירות תרגום אוטומטי Co-op Translator. למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש להחשיב את המסמך המקורי בשפתו הטבעית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אדם. אנו לא אחראים לכל אי-הבנה או פירוש שגוי הנובע מהשימוש בתרגום זה.

This site is open source. Improve this page.