ai-agents-for-beginners

Verkenning van het Microsoft Agent Framework

Agent Framework

Introductie

Deze les behandelt:

Leerdoelen

Na het voltooien van deze les weet je hoe je:

Codevoorbeelden

Codevoorbeelden voor Microsoft Agent Framework (MAF) vind je in deze repository onder de bestanden xx-python-agent-framework en xx-dotnet-agent-framework.

Inzicht in Microsoft Agent Framework

Framework Intro

Microsoft Agent Framework (MAF) is het verenigde framework van Microsoft voor het bouwen van AI-agents. Het biedt de flexibiliteit om de grote verscheidenheid aan agentusecases aan te pakken, die zowel in productie als in onderzoeksomgevingen voorkomen, waaronder:

Om AI Agents in productie te leveren, heeft MAF ook functies opgenomen voor:

Microsoft Agent Framework richt zich ook op interoperabiliteit door:

Laten we bekijken hoe deze functies worden toegepast op enkele kernconcepten van Microsoft Agent Framework.

Kernconcepten van Microsoft Agent Framework

Agents

Agent Framework

Agents maken

Het aanmaken van een agent gebeurt door het definiëren van de inference-service (LLM-provider), een set instructies die de AI-agent moet volgen, en het toewijzen van een naam:

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

Het bovenstaande gebruikt Azure OpenAI, maar agents kunnen worden aangemaakt met verschillende services, waaronder 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.", )

of MiniMax, die een OpenAI-compatibele API aanbiedt met grote contextvensters (tot 204K tokens):

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

of remote agents die het A2A-protocol gebruiken:

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

Agents uitvoeren

Agents worden uitgevoerd met de .run of .run_stream methoden voor respectievelijk niet-streaming of streaming responses.

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)

Elke agentuitvoering kan ook opties bevatten om parameters aan te passen, zoals max_tokens die door de agent worden gebruikt, tools die de agent kan aanroepen, en zelfs het gebruikte model zelf.

Dit is nuttig in gevallen waar specifieke modellen of tools nodig zijn om de taak van een gebruiker te voltooien.

Tools

Tools kunnen zowel bij het definiëren van de agent worden opgegeven:

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


# Bij het rechtstreeks aanmaken van een ChatAgent

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

en ook bij het uitvoeren van de agent:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Tool alleen beschikbaar voor deze uitvoering )

Agent Threads

Agent Threads worden gebruikt om multi-turn gesprekken af te handelen. Threads kunnen worden aangemaakt door:

De code voor het aanmaken van een thread ziet er als volgt uit:

# Maak een nieuwe thread aan.
thread = agent.get_new_thread() # Voer de agent uit met de thread.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Je kunt de thread vervolgens serialiseren zodat die later gebruikt kan worden:

# Maak een nieuwe thread aan.
thread = agent.get_new_thread() 

# Voer de agent uit met de thread.

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

# Serialiseer de thread voor opslag.

serialized_thread = await thread.serialize() 

# Deserializeer de threadstatus na het laden uit opslag.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Agent Middleware

Agents communiceren met tools en LLM’s om taken van gebruikers te voltooien. In bepaalde scenario’s willen we acties tussen deze interacties uitvoeren of volgen. Agent middleware stelt ons in staat dit te doen via:

Function Middleware

Deze middleware laat ons een actie uitvoeren tussen de agent en een functie/tool die wordt aangeroepen. Een voorbeeld van het gebruik is logging van de functietoeroep.

In onderstaande code bepaalt next of de volgende middleware of de daadwerkelijke functie moet worden aangeroepen.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Voorbewerking: Loggen vóór functievermijding
    print(f"[Function] Calling {context.function.name}")

    # Ga door naar de volgende middleware of functie-uitvoering
    await next(context)

    # Nabewerking: Loggen na functievermijding
    print(f"[Function] {context.function.name} completed")

Chat Middleware

Deze middleware laat ons een actie uitvoeren of loggen tussen de agent en de verzoeken naar de LLM.

Dit bevat belangrijke informatie zoals de messages die naar de AI-service worden gestuurd.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Voorverwerking: Log vóór AI-aanroep
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Ga door naar de volgende middleware of AI-service
    await next(context)

    # Naverwerking: Log na AI-antwoord
    print("[Chat] AI response received")

Agentgeheugen

Zoals beschreven in de les Agentic Memory, is geheugen een belangrijk element om de agent in verschillende contexten te laten opereren. MAF biedt verschillende soorten geheugen:

In-Memory Storage

Dit is het geheugen dat wordt opgeslagen in threads tijdens runtime van de applicatie.

# Maak een nieuwe thread aan.
thread = agent.get_new_thread() # Voer de agent uit met de thread.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Persistent Messages

Dit geheugen wordt gebruikt voor het opslaan van gespreksgeschiedenis over verschillende sessies heen. Het wordt gedefinieerd met behulp van chat_message_store_factory:

from agent_framework import ChatMessageStore

# Maak een aangepaste berichtopslag
def create_message_store():
    return ChatMessageStore()

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

Dynamisch geheugen

Dit geheugen wordt aan de context toegevoegd voordat agents worden uitgevoerd. Deze geheugens kunnen worden opgeslagen in externe diensten zoals mem0:

from agent_framework.mem0 import Mem0Provider

# Mem0 gebruiken voor geavanceerde geheugenmogelijkheden
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
)

Agent Observability

Observability is belangrijk om betrouwbare en onderhoudbare agentsystemen te bouwen. MAF integreert met OpenTelemetry om tracing en meters te bieden voor betere observability.

from agent_framework.observability import get_tracer, get_meter

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

Workflows

MAF biedt workflows aan die vooraf gedefinieerde stappen zijn om een taak te voltooien en AI agents als componenten in die stappen bevatten.

Workflows bestaan uit verschillende componenten die zorgen voor betere controle over de flow. Workflows maken ook multi-agent orchestratie en checkpointing mogelijk om workflow toestanden op te slaan.

De kerncomponenten van een workflow zijn:

Executors

Executors ontvangen invoerberichten, voeren hun toegewezen taken uit en produceren daarna een uitvoerbericht. Dit brengt de workflow vooruit richting het voltooien van de grotere taak. Executors kunnen AI agents zijn of aangepaste logica.

Edges

Edges worden gebruikt om de stroom van berichten in een workflow te definiëren. Deze kunnen zijn:

Directe Edges - Eenvoudige één-op-één verbindingen tussen executors:

from agent_framework import WorkflowBuilder

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

Voorwaardelijke Edges - Worden geactiveerd nadat aan een bepaalde voorwaarde is voldaan. Bijvoorbeeld, als hotelkamers niet beschikbaar zijn, kan een executor andere opties voorstellen.

Switch-case Edges - Sturen berichten naar verschillende executors op basis van gedefinieerde voorwaarden. Bijvoorbeeld als een reiziger prioriteitstoegang heeft en hun taken via een andere workflow worden afgehandeld.

Fan-out Edges - Verstuur één bericht naar meerdere doelen.

Fan-in Edges - Verzamelt meerdere berichten van verschillende executors en verstuurt deze naar één doel.

Events

Om betere observability in workflows te bieden, heeft MAF ingebouwde events voor uitvoering, waaronder:

Geavanceerde MAF-patronen

De voorgaande secties behandelen de kernconcepten van Microsoft Agent Framework. Naarmate je complexere agents bouwt, zijn er enkele geavanceerde patronen om te overwegen:

LangChain / LangGraph Agents hosten op Microsoft Foundry

Microsoft Agent Framework is framework-interoperabel — je bent niet beperkt tot agents geschreven met MAF. Als je al een agent hebt gebouwd met LangChain of LangGraph, kun je die uitvoeren als een Microsoft Foundry gehoste agent zodat Foundry de runtime, sessies, schaalbaarheid, identiteit en protocol endpoints voor je beheert, terwijl je agentlogica blijft in LangGraph.

Dit wordt gedaan met het langchain_azure_ai.agents.hosting pakket, dat een gecompileerde LangGraph graph blootlegt over dezelfde protocollen die Foundry gehoste agents gebruiken.

1. Installeer de hosting extra:

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

De hosting extra installeert de Foundry protocolbibliotheken: azure-ai-agentserver-responses (de OpenAI-compatibele /responses endpoint) en azure-ai-agentserver-invocations (de generieke /invocations endpoint).

2. Kies een hostingprotocol:

Protocol Hostklasse Endpoint Gebruik wanneer
Responses ResponsesHostServer /responses Je een OpenAI-compatibele chat, streaming, responsehistory en conversatietheading wilt – de aanbevolen standaard voor conversationele agents.
Invocations InvocationsHostServer /invocations Je een aangepaste JSON-structuur, een webhook-achtige endpoint of niet-conversationele verwerking nodig hebt.

Omdat de Responses API de primaire API is voor agent-ontwikkeling in Foundry, begin met ResponsesHostServer voor de meeste agents.

3. Configureer omgevingsvariabelen (az login eerst zodat DefaultAzureCredential kan authenticeren):

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

Wanneer de agent later draait als gehoste agent in Foundry, injecteert het platform automatisch FOUNDRY_PROJECT_ENDPOINT.

4. Stel een LangGraph agent bloot over het Responses-protocol:

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 hier richt zich op het OpenAI-compatibele (Responses) eindpunt van het Foundry-project.
    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()

Voer het lokaal uit met python main.py, en stuur vervolgens een Responses-verzoek naar http://localhost:8088/responses.

Belangrijke eigenschappen:

Een uitvoerbare versie van dit voorbeeld staat in code-samples/14-langchain-hosted-agent.py. Voor de volledige walkthrough (Invocations-protocol, aangepaste requestschemas en probleemoplossing), zie Host LangGraph agents als Foundry gehoste agents.

Codevoorbeelden

Codevoorbeelden voor Microsoft Agent Framework vind je in deze repository onder de bestanden xx-python-agent-framework en xx-dotnet-agent-framework.

Meer vragen over Microsoft Agent Framework?

Word lid van de Microsoft Foundry Discord om andere lerenden te ontmoeten, deel te nemen aan office hours en je vragen over AI Agents beantwoord te krijgen.

Vorige les

Geheugen voor AI Agents

Volgende les

Bouwen van Computer Use Agents (CUA)

Disclaimer: Dit document is vertaald met behulp van de AI vertaaldienst Co-op Translator. Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling.

This site is open source. Improve this page.