ai-agents-for-beginners

Prozkoumávání Microsoft Agent Framework

Agent Framework

Úvod

Tato lekce pokryje:

Cíle učení

Po dokončení této lekce budete vědět, jak:

Ukázky kódu

Ukázky kódu pro Microsoft Agent Framework (MAF) lze nalézt v tomto repozitáři pod soubory xx-python-agent-framework a xx-dotnet-agent-framework.

Porozumění Microsoft Agent Framework

Framework Intro

Microsoft Agent Framework (MAF) je jednotné prostředí Microsoftu pro vytváření AI agentů. Nabízí flexibilitu řešit širokou škálu agentních scénářů použití, které se vyskytují jak v produkčních, tak ve výzkumných prostředích, včetně:

Pro dodání AI agentů v produkci má MAF také zahrnuty funkce pro:

Microsoft Agent Framework se také zaměřuje na interoperabilitu tím, že:

Podívejme se, jak jsou tyto funkce aplikovány na některé základní koncepty Microsoft Agent Framework.

Klíčové koncepty Microsoft Agent Framework

Agenti

Agent Framework

Vytváření agentů

Vytváření agentů se provádí definováním inference služby (poskytovatele LLM),
sady instrukcí, kterými se má AI agent řídit, a přiřazeného jménem:

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

Výše uvedené používá Azure OpenAI, ale agenti mohou být vytvořeni pomocí různých služeb včetně 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.", )

nebo MiniMax, který poskytuje OpenAI-kompatibilní API s velkými kontextovými okny (až 204K tokenů):

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

nebo vzdálené agenty pomocí protokolu A2A:

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

Spouštění agentů

Agenti jsou spouštěni pomocí metod .run nebo .run_stream pro ne-streamované nebo streamované odpovědi.

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ý běh agenta může mít také volby pro přizpůsobení parametrů jako max_tokens, které agent používá, tools, které může agent volat, a dokonce i samotný model, který agent používá.

To je užitečné v případech, kdy jsou pro dokončení uživatelského úkolu vyžadovány specifické modely nebo nástroje.

Nástroje

Nástroje lze definovat jak při definici 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." 


# Při přímém vytváření ChatAgenta

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

a také při spuštění agenta:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Nástroj poskytovaný pouze pro tento běh )

Agentní vlákna

Agentní vlákna se používají k obsluze vícetahových konverzací. Vlákna lze vytvořit buď:

K vytvoření vlákna vypadá kód takto:

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

Vlákno lze pak serializovat a uložit pro pozdější použití:

# Vytvořit nový vláknový proces.
thread = agent.get_new_thread() 

# Spustit agenta s vláknem.

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

# Serializovat vlákno pro uložení.

serialized_thread = await thread.serialize() 

# Deserializovat stav vlákna po načtení z úložiště.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Agentní middleware

Agent interagují s nástroji a LLM, aby dokončili uživatelské úkoly. V některých scénářích chceme vykonat nebo sledovat akce mezi těmito interakcemi. Agent middleware nám to umožňuje prostřednictvím:

Funkční middleware

Tento middleware nám umožňuje vykonat akci mezi agentem a funkcí/nástrojem, který volá. Příkladem využití je zaznamenávání volání funkce.

V následujícím kódu next určuje, zda se má zavolat další middleware nebo skutečná funkce.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Předzpracování: Záznam před vykonáním funkce
    print(f"[Function] Calling {context.function.name}")

    # Pokračovat na další střední vrstvu nebo vykonání funkce
    await next(context)

    # Pozpracování: Záznam po vykonání funkce
    print(f"[Function] {context.function.name} completed")

Chat middleware

Tento middleware nám umožňuje vykonat nebo zaznamenat akci mezi agentem a požadavky mezi LLM.

Obsahuje důležité informace jako messages, které jsou posílány AI službě.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Předzpracování: Protokolovat před voláním AI
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Pokračovat na další middleware nebo AI službu
    await next(context)

    # Post-processing: Protokolovat po odpovědi AI
    print("[Chat] AI response received")

Agentní paměť

Jak bylo pokryto v lekci Agentic Memory, paměť je důležitým prvkem pro umožnění agentovi pracovat v různých kontextech. MAF nabízí několik různých typů pamětí:

Paměť v rámci aplikace (In-Memory Storage)

Jedná se o paměť uloženou ve vláknech během běhu aplikace.

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

Perzistentní zprávy

Tato paměť se používá při ukládání historie konverzace přes různé relace. Je definována pomocí chat_message_store_factory :

from agent_framework import ChatMessageStore

# Vytvořit vlastní úložiště zprá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ěť

Tato paměť se přidává do kontextu před spuštěním agentů. Tyto paměti mohou být uloženy v externích službách jako mem0:

from agent_framework.mem0 import Mem0Provider

# Používání Mem0 pro pokročilé paměťové schopnosti
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
)

Pozorovatelnost agenta

Pozorovatelnost je důležitá pro vytváření spolehlivých a udržitelných agentních systémů. MAF se integruje s OpenTelemetry, aby poskytoval trasování a metry pro lepší pozorovatelnost.

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # udělej něco
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Pracovní postupy

MAF nabízí pracovní postupy, což jsou předdefinované kroky k dokončení úkolu, které zahrnují AI agenty jako součást těchto kroků.

Pracovní postupy se skládají z různých komponent, které umožňují lepší řízení toku. Pracovní postupy také umožňují víceagentní orchestraci a checkpointing pro ukládání stavů pracovního postupu.

Základními komponentami pracovního postupu jsou:

Prováděče

Prováděči přijímají vstupní zprávy, vykonávají přidělené úkoly a poté vytvářejí výstupní zprávu. Tím posouvají pracovní postup vpřed k dokončení většího úkolu. Prováděči mohou být buď AI agenti, nebo vlastní logika.

Hrany

Hrany se používají k definování toku zpráv v pracovním postupu. Mohou být:

Přímé hrany - jednoduché spojení jeden na jednoho mezi prováděči:

from agent_framework import WorkflowBuilder

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

Podmíněné hrany - aktivují se po splnění určité podmínky. Například když nejsou dostupné hotelové pokoje, prováděč může navrhnout jiné možnosti.

Přepínací hrany (switch-case) - směrují zprávy k různým prováděčům na základě definovaných podmínek. Například pokud má cestující prioritní přístup, jeho úkoly budou řešeny jiným pracovním postupem.

Fan-out hrany - posílají jednu zprávu do více cílů.

Fan-in hrany - shromažďují více zpráv od různých prováděčů a posílají je jednomu cíli.

Události

Pro lepší pozorovatelnost pracovních postupů MAF nabízí vestavěné události pro jejich vykonávání, zahrnující:

Pokročilé vzory MAF

Výše uvedené části pokrývají klíčové koncepty Microsoft Agent Frameworku. Při vytváření složitějších agentů zvážte následující pokročilé vzory:

Hostování agentů LangChain / LangGraph na Microsoft Foundry

Microsoft Agent Framework je kompatibilní s různými frameworky — nejste omezeni na agenty napsané s MAF. Pokud již máte agenta vytvořeného pomocí LangChain nebo LangGraph, můžete jej provozovat jako hostovaného agenta Microsoft Foundry, takže Foundry spravuje runtime, relace, škálování, identitu a protokolové koncové body za vás, zatímco logika vašeho agenta zůstává v LangGraph.

To se provádí balíčkem langchain_azure_ai.agents.hosting, který vystavuje kompilovaný LangGraph graf přes stejné protokoly, jaké používají hostovaní agenti Foundry.

1. Nainstalujte hostingový doplněk:

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

Doplněk hosting instaluje knihovny protokolu Foundry: azure-ai-agentserver-responses (kompatibilní OpenAI endpoint /responses) a azure-ai-agentserver-invocations (obecný endpoint /invocations).

2. Vyberte hostingový protokol:

Protokol Třída hostitele Endpoint Použití
Responses ResponsesHostServer /responses Chcete chat kompatibilní s OpenAI, streamování, historii odpovědí a konverzační vlákna — doporučený výchozí režim pro konverzační agenty.
Invocations InvocationsHostServer /invocations Potřebujete vlastní JSON formát, webhookový styl endpoint nebo ne-konverzační zpracování.

Protože Responses API je primární API pro vývoj agentů v Foundry, začněte s ResponsesHostServer u většiny agentů.

3. Nastavte proměnné prostředí (az login nejdříve, aby se mohl autentizovat DefaultAzureCredential):

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

Když agent později poběží jako hostovaný agent v Foundry, platforma automaticky injektuje FOUNDRY_PROJECT_ENDPOINT.

4. Vystavte LangGraph agenta přes 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-4.1")
    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 zde cílí na OpenAI-kompatibilní (Responses) endpoint Foundry projektu.
    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()

Spusťte lokálně pomocí python main.py, poté odešlete požadavek přes Responses na http://localhost:8088/responses.

Klíčové chování:

Spustitelná verze tohoto příkladu se nachází v code-samples/14-langchain-hosted-agent.py. Pro kompletní průvodce (protokol Invocations, vlastní schémata požadavků a odstraňování problémů) viz Hostování agentů LangGraph jako hostovaných agentů Foundry.

Ukázky kódu

Ukázky kódu pro Microsoft Agent Framework naleznete v tomto repozitáři ve složkách xx-python-agent-framework a xx-dotnet-agent-framework.

Máte další otázky o Microsoft Agent Framework?

Připojte se na Microsoft Foundry Discord, kde můžete potkat další studenty, účastnit se konzultačních hodin a dostat odpovědi na své otázky o AI agentech.

Předchozí lekce

Paměť pro AI agenty

Následující lekce

Budování agentů pro používání počítače (CUA)

Prohlášení o omezení odpovědnosti: Tento dokument byl přeložen pomocí AI překladatelské služby Co-op Translator. Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu.

This site is open source. Improve this page.