Microsoft Foundry Agent Tutorial: Ersten Agent bauen

KI-Agenten sind gerade überall, und viele IT-Pros fragen mich, wo sie anfangen sollen. In diesem Blogpost zeige ich dir, wie du deinen ersten Microsoft Foundry Agenten baust. Wir gehen Schritt für Schritt vor: Projekt im Portal erstellen, Modell deployen, den Agenten mit Instructions und Tools anlegen, im Playground testen und zum Schluss aus Python-Code aufrufen. Du musst kein Entwickler sein, um mitzumachen. Am Ende hast du einen funktionierenden Microsoft Foundry Agenten, den du für deine eigenen Use Cases erweitern kannst.

Was ist Microsoft Foundry?

Microsoft Foundry ist Microsofts Plattform zum Bauen von KI-Anwendungen und Agenten. Vielleicht kennst du sie noch unter dem alten Namen Azure AI Foundry — Microsoft hat sie umbenannt, und Portal und Dokumentation sagen inzwischen Microsoft Foundry. Die Plattform gibt dir drei Dinge:

• Einen Modellkatalog mit Modellen von OpenAI, Microsoft und anderen Anbietern, die du mit wenigen Klicks deployen kannst.
• Den Foundry Agent Service, der deine Agenten hostet. Ein Agent ist ein Modell plus Instructions plus Tools. Du definierst ihn einmal, und der Service hält ihn für jede Interaktion konsistent.
• SDKs und APIs, damit du deine Modelle und Agenten aus eigenem Code und aus Automatisierungen aufrufen kannst.

Der Agenten-Teil ist für uns der spannende. Statt bei jeder Anfrage einen System-Prompt mitzuschicken, erstellst du einen Microsoft Foundry Agenten einmal mit Name, Instructions und optionalen Tools wie Code Interpreter oder File Search. Danach referenziert jede App und jedes Skript den Agenten einfach über seinen Namen. Wenn du das große Bild sehen willst, wohin Microsoft mit Agenten unterwegs ist, schau in meinen Beitrag zum Agentic Stack von der Microsoft Build 2026.

Was brauche ich, bevor ich starte?

Um einen Microsoft Foundry Agenten zu bauen, brauchst du überraschend wenig:

1. Ein Azure-Abonnement. Ein kostenloses Konto reicht zum Testen.
2. Die richtigen Berechtigungen. Zum Erstellen der Foundry-Ressource und des Projekts brauchst du die Rolle Foundry Account Owner (oder Contributor/Owner) auf der Subscription oder Ressourcengruppe. Zum Arbeiten im Projekt brauchst du die Rolle Foundry User. Diese Rollen wurden kürzlich umbenannt (vorher „Azure AI User” usw.) — lass dich also nicht verwirren, wenn du noch die alten Namen siehst.
3. Für den Code-Teil: Python und die Azure CLI auf deinem Rechner.

Note: Du zahlst für die Modellnutzung pro Token, nicht für den Agenten selbst. Außerdem ist nicht jedes Modell in jeder Region verfügbar — prüfe also die Regions- und Preisseiten, bevor du eine Location für dein Projekt wählst.

Wie erstelle ich ein Projekt?

Ein Microsoft Foundry Agent lebt immer in einem Projekt. So sieht der Klickpfad aus:

1. Gehe zum Microsoft Foundry Portal und melde dich mit deinem Azure-Konto an. Achte darauf, dass der Schalter New Foundry oben aktiviert ist.
2. Beim ersten Besuch fragt dich das Portal nach einem Projekt. Wähle Create a new project. Ansonsten klickst du oben links auf den Projektnamen und wählst Create new project.
3. Vergib einen Namen, zum Beispiel my-first-agent-project.
4. Öffne Advanced options, wenn du Ressourcengruppe und Region selbst wählen willst. Ich empfehle eine Region in deiner Nähe.
5. Klicke auf Create project und warte einen Moment, bis die Projektübersicht erscheint.

Als Nächstes brauchen wir ein Modell-Deployment. Der Agent braucht ein Gehirn:

1. Wähle oben rechts Discover und dann links Models.
2. Suche ein Modell, zum Beispiel gpt-5.1-mini. Es ist günstig und für einen ersten Test völlig ausreichend.
3. Klicke auf Deploy → Default settings, um es deinem Projekt hinzuzufügen.
4. Notiere dir den Deployment-Namen. Den brauchst du später im Code.

Hint: Wenn du dein Projekt in der Region West US 3 erstellst, kannst du die neuen Instant Models (Preview) ausprobieren und den Deployment-Schritt komplett überspringen. Praktisch für eine schnelle Demo.

Wie erstelle ich den Microsoft Foundry Agenten?

Jetzt der spaßige Teil. Wir erstellen den Microsoft Foundry Agenten im Portal:

1. Wähle oben rechts Build und dann links Agents.
2. Klicke auf Create agent und vergib einen Namen, zum Beispiel MyAgent.
3. Ergänze Instructions. Das ist die Persönlichkeit und die Jobbeschreibung deines Agenten. Zum Beispiel: „Du bist ein hilfreicher Assistent für IT-Admins. Beantworte Fragen zum Device Management kurz und präzise.”
4. Wähle dein Modell-Deployment aus dem Dropdown.
5. Optional fügst du Tools hinzu. Zwei nützliche für den Anfang: Mit File Search beantwortet der Agent Fragen aus Dokumenten, die du hochlädst, und mit dem Code Interpreter kann der Agent Python-Code schreiben und ausführen, etwa um aus Zahlen ein Diagramm zu bauen.

Das war es auch schon. Der Agent ist in deinem Projekt gespeichert, und jede Kollegin und jeder Kollege mit der Foundry-User-Rolle kann ihn verwenden.

Wie teste ich den Agenten im Playground?

Zum Testen deines Microsoft Foundry Agenten brauchst du keinen Code. Der Playground öffnet sich direkt neben den Agent-Einstellungen:

1. Tippe eine Frage in die Chatbox, zum Beispiel „Schreib mir eine kurze Checkliste für das Onboarding eines neuen Windows-Geräts.”
2. Prüfe, ob die Antwort zu deinen Instructions passt. Wenn nicht, passe die Instructions an und probiere es erneut.
3. Stelle eine Folgefrage. Der Agent behält den Gesprächsverlauf und sollte den Kontext verstehen.

Diese Schleife — Instructions ändern, testen, wieder ändern — ist der Ort, an dem du die meiste Zeit verbringst. Mach das im Playground, bevor du Code anfasst.

Wie rufe ich den Agenten aus Code auf?

Für Automatisierung willst du den Microsoft Foundry Agenten aus einem Skript aufrufen. Installiere die Pakete azure-ai-projects (Version 2.0.0 oder höher) und azure-identity mit pip, führe az login aus und kopiere deinen Project Endpoint vom Startbildschirm deines Projekts. Ein minimales Beispiel sieht dann so aus:

# pip install "azure-ai-projects>=2.0.0" azure-identity
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

project = AIProjectClient(
    endpoint="https://<resource>.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
)

# Create (or update) the agent with model and instructions
agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5.1-mini",  # your model deployment name
        instructions="You are a helpful assistant for IT admins.",
    ),
)

# Chat with the agent
openai = project.get_openai_client()
response = openai.responses.create(
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    input="Write a short checklist for onboarding a new Windows device.",
)
print(response.output_text)

Der Code macht drei Dinge: Er verbindet sich über dein Azure-Login mit deinem Projekt, er erstellt eine neue Version des Agenten, und er schickt eine Frage über die Responses API. Der Teil mit agent_reference sagt Foundry, dass dein Agent mit all seinen Instructions und Tools verwendet werden soll.

Note: Die Agent-API hat sich 2025/2026 geändert. Das neue SDK (azure-ai-projects 2.x) ist nicht kompatibel mit den alten 1.x-Beispielen, und die klassischen Agents werden am 31. März 2027 abgeschaltet. Wenn du also ältere Tutorials mit Threads und Runs findest: Die nutzen die veraltete API. Die aktuellen Schritte stehen im offiziellen Microsoft Foundry Quickstart.

Wie geht es weiter?

Du hast jetzt einen funktionierenden Microsoft Foundry Agenten: ein Projekt, ein Modell-Deployment, einen Agenten mit Instructions und Tools und ein Python-Skript, das mit ihm spricht. Von hier aus kannst du mit File Search deine eigenen Daten anbinden, eigene Funktionen ergänzen oder mehrere Agenten kombinieren. Und wenn du ganz ohne Cloud mit Modellen spielen willst, schau in meinen Beitrag über KI-Modelle offline ausführen mit Foundry Local.

Ich hoffe, das hilft dir ein wenig.

Stay healthy, Cheers Jannik