ai-agents-for-beginners

Preskúmanie Microsoft Agent Framework

Agent Framework

Úvod

Táto lekcia pokryje:

Ciele učenia

Po dokončení tejto lekcie budete vedieť:

Ukážky kódu

Ukážky kódu pre Microsoft Agent Framework (MAF) nájdete v tomto repozitári v súboroch xx-python-agent-framework a xx-dotnet-agent-framework.

Pochopenie Microsoft Agent Framework

Framework Intro

Microsoft Agent Framework (MAF) je jednotný rámec Microsoftu na budovanie AI agentov. Ponúka flexibilitu riešiť širokú škálu agentických prípadov použitia, ktoré sa vyskytujú v produkčných aj výskumných prostrediach, vrátane:

Na doručenie AI agentov v produkcii má MAF tiež zahrnuté funkcie pre:

Microsoft Agent Framework sa tiež zameriava na interoperabilitu tým, že:

Pozrime sa, ako sú tieto funkcie aplikované na niektoré z kľúčových konceptov Microsoft Agent Framework.

Kľúčové koncepty Microsoft Agent Framework

Agenti

Agent Framework

Tvorba agentov

Vytváranie agentov sa vykonáva definovaním inferenčnej služby (poskytovateľa LLM),
sady inštrukcií, ktoré AI agent má nasledovať, a priradeného mena:

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

Vyššie uvedené používa Azure OpenAI, ale agenti môžu byť vytváraní pomocou rôznych služieb vrátane Microsoft Foundry Agent Service:

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

OpenAI Responses, ChatCompletion API

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

alebo MiniMax, ktorý poskytuje OpenAI-kompatibilné API s veľkými kontextovými oknami (až 204K tokenov):

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

alebo vzdialení agenti používajúci protokol A2A:

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

Spúšťanie agentov

Agenti sa spúšťajú použitím metód .run alebo .run_stream pre ne-streamované alebo streamované odpovede.

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)

Každé spustenie agenta môže mať aj možnosti na prispôsobenie parametrov ako max_tokens používaných agentom, tools, ktoré agent môže volať, a dokonca aj samotný model použitý pre agenta.

Toto je užitočné v prípadoch, kde sú potrebné konkrétne modely alebo nástroje na dokončenie úlohy používateľa.

Nástroje

Nástroje môžu byť definované ako pri definovaní agenta:

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


# Pri priamom vytváraní ChatAgenta

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

tak aj pri spúšťaní agenta:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Nástroj poskytnutý iba pre toto spustenie )

Vlákna agentov

Vlákna agentov sa používajú na spracovanie viackrokových rozhovorov. Vlákna môžu byť vytvorené buď:

Kód na vytvorenie vlákna vyzerá takto:

# Vytvorte nový vlákno.
thread = agent.get_new_thread() # Spustite agenta vo vlákne.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Vlákno potom môžete serializovať na uloženie na neskoršie použitie:

# Vytvorte nový vláknový proces.
thread = agent.get_new_thread() 

# Spustite agenta s vláknovým procesom.

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

# Serializujte vlákno na uloženie.

serialized_thread = await thread.serialize() 

# Deserializujte stav vlákna po načítaní z ukladiska.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Middleware agenta

Agenti komunikujú s nástrojmi a LLM, aby splnili úlohy používateľa. V určitých scenároch chceme vykonať alebo sledovať medzikroky týchto interakcií. Middleware agenta nám to umožňuje prostredníctvom:

Function Middleware

Tento middleware nám umožňuje vykonať akciu medzi agentom a funkciou/nástrojom, ktorý bude volať. Príkladom použitia je napríklad vykonanie logovania volania funkcie.

V kóde nižšie next definuje, či sa má zavolať ďalší middleware alebo samotná funkcia.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Predspracovanie: Záznam pred vykonaním funkcie
    print(f"[Function] Calling {context.function.name}")

    # Pokračovať na ďalší middleware alebo vykonanie funkcie
    await next(context)

    # Pospraovanie: Záznam po vykonaní funkcie
    print(f"[Function] {context.function.name} completed")

Chat Middleware

Tento middleware nám umožňuje vykonať alebo zaznamenať akciu medzi agentom a požiadavkami na LLM.

Obsahuje dôležité informácie, ako sú messages, ktoré sa posielajú AI službe.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Predspracovanie: Záznam pred volaním AI
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Pokračovať na ďalší middleware alebo AI službu
    await next(context)

    # Postspracovanie: Záznam po odpovedi AI
    print("[Chat] AI response received")

Pamäť agenta

Ako bolo pokryté v lekcii Agentic Memory, pamäť je dôležitým prvkom, ktorý umožňuje agentovi pracovať cez rôzne kontexty. MAF ponúka niekoľko rôznych typov pamätí:

Pamäť v pamäti (In-Memory Storage)

Ide o pamäť uloženú vo vláknach počas behu aplikácie.

# Vytvorte nový vlákno.
thread = agent.get_new_thread() # Spustite agenta s vláknom.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Trvalé správy (Persistent Messages)

Táto pamäť sa používa pri ukladaní histórie rozhovorov medzi rôznymi reláciami. Definuje sa pomocou chat_message_store_factory:

from agent_framework import ChatMessageStore

# Vytvorte vlastné úložisko správ
def create_message_store():
    return ChatMessageStore()

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

Dynamická pamäť

Táto pamäť sa pridáva do kontextu pred spustením agentov. Tieto pamäte môžu byť uložené v externých službách, ako napríklad mem0:

from agent_framework.mem0 import Mem0Provider

# Použitie Mem0 pre pokročilé pamäťové funkcie
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
)

Pozorovateľnosť agenta

Pozorovateľnosť je dôležitá pre budovanie spoľahlivých a udržiavateľných agentových systémov. MAF sa integruje s OpenTelemetry, aby poskytoval sledovanie a metriky pre lepšiu pozorovateľnosť.

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # urob niečo
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Pracovné postupy

MAF ponúka pracovné postupy, ktoré sú preddefinované kroky na dokončenie úlohy a zahŕňajú AI agentov ako súčasti týchto krokov.

Pracovné postupy sa skladajú z rôznych komponentov, ktoré umožňujú lepšiu riadiacu logiku. Pracovné postupy tiež umožňujú orchestráciu viacerých agentov a checkpointovanie na uloženie stavov pracovných postupov.

Kľúčové komponenty pracovného postupu sú:

Vykonávacie jednotky

Vykonávacie jednotky prijímajú vstupné správy, vykonávajú priradené úlohy a potom produkujú výstupnú správu. Tým sa pracovný postup posúva k dokončeniu väčšej úlohy. Vykonávacie jednotky môžu byť AI agenti alebo vlastná logika.

Hrany

Hrany sa používajú na definovanie toku správ v pracovnom postupe. Tie môžu byť:

Priame hrany - Jednoduché jedno-na-jedno spojenia medzi vykonávacími jednotkami:

from agent_framework import WorkflowBuilder

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

Podmienené hrany - Aktivované po splnení určitej podmienky. Napríklad, keď nie sú k dispozícii hotelové izby, vykonávacia jednotka môže navrhnúť iné možnosti.

Hrany typu switch-case - Smerujú správy k rôznym vykonávacím jednotkám na základe definovaných podmienok. Napríklad, ak má cestovný zákazník prioritný prístup, jeho úlohy budú spracované cez iný pracovný postup.

Fan-out hrany - Posielajú jednu správu na viacero cieľov.

Fan-in hrany - Zbierajú viacero správ od rôznych vykonávacích jednotiek a posielajú ich jednému cieľu.

Udalosti

Pre lepšiu pozorovateľnosť pracovných postupov MAF ponúka vstavné udalosti pri vykonávaní vrátane:

Pokročilé vzory MAF

Predchádzajúce sekcie pokrývajú kľúčové koncepty Microsoft Agent Framework. Keď vytvárate komplikovanejších agentov, tu sú niektoré pokročilé vzory na zváženie:

Hostovanie agentov LangChain / LangGraph na Microsoft Foundry

Microsoft Agent Framework je kompatibilný s rôznymi frameworkami — nie ste limitovaní iba na agentov napísaných v MAF. Ak už máte agenta vytvoreného s LangChain alebo LangGraph, môžete ho spustiť ako agenta hosťovaného Microsoft Foundry, takže Foundry spravuje runtime, relácie, škálovanie, identitu a koncové body protokolu, zatiaľ čo vaša agentová logika zostáva v LangGraph.

Toto je realizované prostredníctvom balíka langchain_azure_ai.agents.hosting, ktorý exponuje skompilovaný LangGraph graf cez tie isté protokoly, ktoré používajú Foundry hosťovaní agenti.

1. Nainštalujte hosting extra:

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

Extra hosting inštaluje knižnice protokolov Foundry: azure-ai-agentserver-responses (OpenAI kompatibilný endpoint /responses) a azure-ai-agentserver-invocations (generický endpoint /invocations).

2. Vyberte hostingový protokol:

Protokol Trieda hosťa Endpoint Použitie
Responses ResponsesHostServer /responses Chcete OpenAI-kompatibilné chatovanie, streamovanie, históriu odpovedí a prepojenie konverzácií — odporúčaná predvoľba pre konverzačných agentov.
Invocations InvocationsHostServer /invocations Potrebujete vlastný JSON formát, webhook štýl endpointu, alebo ne-konverzačné spracovanie.

Pretože Responses API je primárne API pre vývoj agentov vo Foundry, začnite s ResponsesHostServer pre väčšinu agentov.

3. Nakonfigurujte environmentálne premenné (az login najprv, aby sa DefaultAzureCredential mohol autentifikovať):

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

Keď agent neskôr beží ako hosťovaný agent vo Foundry, platforma automaticky vloží FOUNDRY_PROJECT_ENDPOINT.

4. Exponujte LangGraph agenta cez protokol 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 tu cieli na OpenAI-kompatibilný (odpovede) koncový bod projektu 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()

Spustite ho lokálne pomocou python main.py, potom odošlite požiadavku Responses na http://localhost:8088/responses.

Kľúčové správanie:

Spustiteľná verzia tohto príkladu je v code-samples/14-langchain-hosted-agent.py. Pre kompletný návod (protokol Invocations, vlastné schémy požiadaviek a riešenie problémov) si pozrite Host LangGraph agents as Foundry hosted agents.

Ukážky kódu

Ukážky kódu pre Microsoft Agent Framework nájdete v tomto repozitári pod súbormi xx-python-agent-framework a xx-dotnet-agent-framework.

Máte ďalšie otázky o Microsoft Agent Framework?

Pripojte sa k Microsoft Foundry Discord, aby ste sa stretli s ďalšími študentmi, zúčastnili sa konzultácií a dostali odpovede na vaše otázky ohľadom AI agentov.

Predchádzajúca lekcia

Pamäť pre AI agentov

Nasledujúca lekcia

Tvorba agentov pre použitie počítača (CUA)

Vyhlásenie o zodpovednosti: Tento dokument bol preložený pomocou AI prekladateľskej služby Co-op Translator. Hoci sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za žiadne nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu.

This site is open source. Improve this page.