ai-agents-for-beginners

Erkundung des Microsoft Agent Frameworks

Agent Framework

Einführung

Diese Lektion behandelt:

Lernziele

Nach Abschluss dieser Lektion wissen Sie, wie Sie:

Code-Beispiele

Code-Beispiele für das Microsoft Agent Framework (MAF) finden Sie in diesem Repository unter den Dateien xx-python-agent-framework und xx-dotnet-agent-framework.

Verständnis des Microsoft Agent Frameworks

Framework Intro

Das Microsoft Agent Framework (MAF) ist Microsofts einheitliches Framework zur Erstellung von KI-Agenten. Es bietet die Flexibilität, die breite Palette agentischer Anwendungsfälle abzudecken, die sowohl in produktiven als auch Forschungsumgebungen vorkommen, darunter:

Um KI-Agenten produktiv bereitzustellen, enthält MAF auch Funktionen für:

Microsoft Agent Framework legt zudem Wert auf Interoperabilität durch:

Schauen wir uns an, wie diese Funktionen auf einige der Kernkonzepte des Microsoft Agent Frameworks angewandt werden.

Schlüsselkonstrukte des Microsoft Agent Frameworks

Agenten

Agent Framework

Agenten erstellen

Die Agentenerstellung erfolgt durch Definition des Inferenzdienstes (LLM-Anbieters), einer Reihe von Anweisungen, denen der KI-Agent folgen soll, und der Zuweisung eines Namens:

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

Oben wird Azure OpenAI verwendet, aber Agenten können mit verschiedenen Diensten erstellt werden, darunter 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.", )

oder MiniMax, das eine OpenAI-kompatible API mit großen Kontextfenstern (bis zu 204K Tokens) bereitstellt:

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

oder entfernte Agenten mit dem A2A-Protokoll:

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

Agenten ausführen

Agenten werden mit den Methoden .run oder .run_stream für nicht-Streaming- oder Streaming-Antworten ausgeführt.

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)

Jeder Agentenlauf kann auch Optionen enthalten, um Parameter wie die verwendeten max_tokens, tools, die der Agent verwenden kann, und sogar das verwendete model anzupassen.

Das ist nützlich, wenn für die Erfüllung der Benutzeraufgabe bestimmte Modelle oder Werkzeuge erforderlich sind.

Werkzeuge

Werkzeuge können sowohl bei der Definition des Agenten festgelegt werden:

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


# Beim direkten Erstellen eines ChatAgent

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

als auch beim Ausführen des Agenten:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Werkzeug nur für diesen Lauf bereitgestellt )

Agenten-Threads

Agenten-Threads werden verwendet, um Multirunden-Konversationen zu verwalten. Threads können entweder durch:

Zur Erstellung eines Threads sieht der Code so aus:

# Erstelle einen neuen Thread.
thread = agent.get_new_thread() # Führe den Agenten mit dem Thread aus.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Der Thread kann dann serialisiert und für die spätere Verwendung gespeichert werden:

# Einen neuen Thread erstellen.
thread = agent.get_new_thread() 

# Führe den Agenten mit dem Thread aus.

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

# Serialisiere den Thread zur Speicherung.

serialized_thread = await thread.serialize() 

# Deserialisiere den Thread-Zustand nach dem Laden aus dem Speicher.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Agent Middleware

Agenten interagieren mit Werkzeugen und LLMs, um Aufgaben der Benutzer zu erfüllen. In bestimmten Szenarien möchte man zwischen diesen Interaktionen Vorgänge ausführen oder verfolgen. Agent-Middleware ermöglicht dies durch:

Funktions-Middleware

Diese Middleware erlaubt, eine Aktion zwischen dem Agenten und einer Funktion/einem Werkzeug, das er aufruft, auszuführen. Zum Beispiel kann man die Middleware nutzen, um Funktionsaufrufe zu protokollieren.

Im Code unten definiert next, ob die nächste Middleware oder die eigentliche Funktion aufgerufen werden soll.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Vorverarbeitung: Protokollieren vor der Funktionsausführung
    print(f"[Function] Calling {context.function.name}")

    # Fortfahren mit der nächsten Middleware oder Funktionsausführung
    await next(context)

    # Nachverarbeitung: Protokollieren nach der Funktionsausführung
    print(f"[Function] {context.function.name} completed")

Chat-Middleware

Diese Middleware erlaubt es, eine Aktion zwischen dem Agenten und den Anfragen an das LLM auszuführen oder zu protokollieren.

Sie enthält wichtige Informationen wie die messages, die an den KI-Dienst gesendet werden.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Vorverarbeitung: Protokollieren vor dem KI-Aufruf
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Fortfahren zur nächsten Middleware oder zum KI-Dienst
    await next(context)

    # Nachbearbeitung: Protokollieren nach der KI-Antwort
    print("[Chat] AI response received")

Agentenspeicher

Wie in der Lektion Agentic Memory behandelt, ist Speicher ein wichtiges Element, um dem Agenten zu ermöglichen, über verschiedene Kontexte zu operieren. MAF bietet verschiedene Arten von Speicher:

In-Memory-Speicher

Das ist der in Threads während der Anwendungslaufzeit gespeicherte Speicher.

# Erstellen Sie einen neuen Thread.
thread = agent.get_new_thread() # Führen Sie den Agenten mit dem Thread aus.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Persistente Nachrichten

Dieser Speicher wird verwendet, um den Gesprächsverlauf über verschiedene Sitzungen hinweg zu speichern. Er wird mit chat_message_store_factory definiert:

from agent_framework import ChatMessageStore

# Erstelle einen benutzerdefinierten Nachrichtenspeicher
def create_message_store():
    return ChatMessageStore()

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

Dynamischer Speicher

Dieser Speicher wird vor dem Ausführen von Agenten dem Kontext hinzugefügt. Diese Speicher können in externen Diensten wie mem0 abgelegt werden:

from agent_framework.mem0 import Mem0Provider

# Verwendung von Mem0 für erweiterte Speicherfunktionen
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
)

Agenten-Beobachtbarkeit

Beobachtbarkeit ist wichtig für den Aufbau zuverlässiger und wartbarer agentischer Systeme. MAF integriert OpenTelemetry, um Tracing und Metriken für bessere Beobachtbarkeit zu bieten.

from agent_framework.observability import get_tracer, get_meter

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

Workflows

MAF bietet Workflows an, die vordefinierte Schritte zur Erledigung einer Aufgabe umfassen und KI-Agenten als Komponenten in diesen Schritten enthalten.

Workflows bestehen aus verschiedenen Komponenten, die eine bessere Steuerung des Ablaufs erlauben. Workflows ermöglichen auch Multi-Agent-Orchestrierung und Checkpointing, um Workflow-Zustände zu speichern.

Die Kernkomponenten eines Workflows sind:

Executor

Executor erhalten Eingabenachrichten, führen ihre zugewiesenen Aufgaben aus und erzeugen dann eine Ausgabenachricht. Dadurch wird der Workflow vorangetrieben, um die größere Aufgabe zu erfüllen. Executor können entweder KI-Agenten oder benutzerdefinierte Logik sein.

Kanten

Kanten definieren den Nachrichtenfluss in einem Workflow. Diese können sein:

Direkte Kanten – einfache Eins-zu-Eins-Verbindungen zwischen Executor:

from agent_framework import WorkflowBuilder

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

Bedingte Kanten – werden aktiviert, nachdem eine bestimmte Bedingung erfüllt wurde. Zum Beispiel, wenn Hotelzimmer nicht verfügbar sind, kann ein Executor andere Optionen vorschlagen.

Switch-Case-Kanten – leiten Nachrichten auf verschiedene Executor basierend auf definierten Bedingungen. Zum Beispiel, wenn ein Reisekunde Vorrangzugang hat und seine Aufgaben durch einen anderen Workflow bearbeitet werden.

Fan-out-Kanten – senden eine Nachricht an mehrere Ziele.

Fan-in-Kanten – sammeln mehrere Nachrichten von verschiedenen Executor und senden sie an ein Ziel.

Ereignisse

Zur besseren Beobachtbarkeit von Workflows bietet MAF eingebaute Ereignisse während der Ausführung an, darunter:

Fortgeschrittene MAF-Muster

Die obigen Abschnitte behandeln die Schlüsselkonstrukte des Microsoft Agent Frameworks. Beim Erstellen komplexerer Agenten gibt es einige fortgeschrittene Muster zu beachten:

LangChain / LangGraph-Agenten auf Microsoft Foundry hosten

Microsoft Agent Framework ist framework-übergreifend kompatibel — Sie sind nicht auf mit MAF geschriebene Agenten beschränkt. Wenn Sie bereits einen Agenten mit LangChain oder LangGraph erstellt haben, können Sie ihn als Microsoft Foundry gehosteten Agenten ausführen, sodass Foundry Laufzeit, Sitzungen, Skalierung, Identität und Protokollendpunkte verwaltet, während Ihre Agentenlogik in LangGraph bleibt.

Dies erfolgt mit dem Paket langchain_azure_ai.agents.hosting, das einen kompilierten LangGraph-Graph über dieselben Protokolle bereitstellt, die von Foundry-gehosteten Agenten verwendet werden.

1. Installieren Sie das Hosting-Extra:

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

Das hosting Extra installiert die Foundry-Protokollbibliotheken: azure-ai-agentserver-responses (den OpenAI-kompatiblen /responses-Endpunkt) und azure-ai-agentserver-invocations (den generischen /invocations-Endpunkt).

2. Wählen Sie ein Hosting-Protokoll:

Protokoll Host-Klasse Endpunkt Verwendung wenn
Responses ResponsesHostServer /responses Sie eine OpenAI-kompatible Chat-, Streaming-, Antwortverlauf- und Konversationsthread-Funktionalität möchten – der empfohlene Standard für konversationelle Agenten.
Invocations InvocationsHostServer /invocations Sie ein benutzerdefiniertes JSON-Format, einen Webhook-artigen Endpunkt oder nicht-konversationelle Verarbeitung benötigen.

Weil die Responses-API die primäre API für agentenorientierte Entwicklung in Foundry ist, beginnen Sie für die meisten Agenten mit ResponsesHostServer.

3. Konfigurieren Sie Umgebungsvariablen (az login zuerst, damit DefaultAzureCredential sich authentifizieren kann):

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

Wenn der Agent später als gehosteter Agent in Foundry ausgeführt wird, injiziert die Plattform automatisch FOUNDRY_PROJECT_ENDPOINT.

4. Stellen Sie einen LangGraph-Agenten über das Responses-Protokoll bereit:

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 hier zielt auf den OpenAI-kompatiblen (Responses) Endpunkt des Foundry-Projekts ab.
    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()

Führen Sie ihn lokal mit python main.py aus, und senden Sie dann eine Responses-Anfrage an http://localhost:8088/responses.

Wichtige Verhaltensweisen:

Eine lauffähige Version dieses Beispiels finden Sie in code-samples/14-langchain-hosted-agent.py. Für die vollständige Anleitung (Invocations-Protokoll, benutzerdefinierte Anfrageschemata und Fehlerbehebung) siehe Host LangGraph agents as Foundry hosted agents.

Code-Beispiele

Code-Beispiele für Microsoft Agent Framework finden Sie in diesem Repository unter den Dateien xx-python-agent-framework und xx-dotnet-agent-framework.

Haben Sie noch Fragen zum Microsoft Agent Framework?

Treten Sie dem Microsoft Foundry Discord bei, um andere Lernende zu treffen, an Office Hours teilzunehmen und Ihre Fragen zu KI-Agenten beantwortet zu bekommen.

Vorherige Lektion

Speicher für KI-Agenten

Nächste Lektion

Erstellung von Computerbenutzungsagenten (CUA)

Haftungsausschluss: Dieses Dokument wurde mit dem KI-Übersetzungsdienst Co-op Translator übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Bei kritischen Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen.

This site is open source. Improve this page.