Der Quickstart für den Microsoft Foundry Agent Service ist für Python geschrieben. Er verbirgt die Azure-Infrastruktur hinter einem so dichten Gerüst, dass man das Tutorial abschließen kann, ohne zu wissen, welche Ressourcen tatsächlich erstellt wurden. Wenn man mit .NET arbeitet, beginnt man mit einem Handicap: Die Beispiele führen in die falsche Richtung, Paketnamen ändern sich ohne Vorwarnung, und das kürzliche Rebranding von Azure AI Foundry zu Microsoft Foundry hat dazu geführt, dass zwei Sätze von Dokumentationen in den Suchergebnissen miteinander konkurrieren.

Ich habe vor Kurzem meinen ersten Agenten in C# gebaut. Der Dienst funktioniert gut, sobald man das Rauschen entfernt und die wesentlichen Schritte von der Verwirrung durch die Preview-Versionen trennt. Hier ist die Übersicht, die ich mir am ersten Tag gewünscht hätte.

Die vier Ressourcen, die Sie tatsächlich benötigen

Sie benötigen keine Dutzend Azure-Dienste, um einen einfachen Prompt Agent auszuführen. Sie benötigen genau vier Dinge, und das CLI macht diese auf eine Weise sichtbar, wie es die Python-Notebooks nicht tun.

Erstens eine Foundry-Ressource mit dem Typ AIServices. Diese fungiert als übergeordnete Kapazität für die Modelle, die Sie aufrufen werden. Zweitens ein project innerhalb dieser Ressource. Das Project ist der Bereich (Scope), in dem Ihre Agenten-Definitionen, Konversationsverläufe und Deployment-Einstellungen liegen. Drittens ein deployed model. Ohne ein aktives Deployment hat der Agent keinen Endpunkt zum Aufrufen. Viertens eine role assignment für Ihre eigene Identität, damit das SDK sich gegenüber dem Project authentifizieren kann.

Das ist alles. Kein Kubernetes-Cluster, keine benutzerdefinierte Rechenleistung (custom compute), kein manuell verwalteter Redis-Cache für den Konversationsverlauf.

Prompt Agents versus Hosted Agents

Foundry bietet Ihnen zwei Möglichkeiten, Agenten auszuführen. Wählen Sie nicht standardmäßig die komplexere Option.

Prompt Agents sind der einfachere Weg. Sie wählen ein Modell, schreiben Systemanweisungen, und Foundry führt den Agenten für Sie aus. Sie verwalten keine Rechenleistung, Container oder Routing-Logik. Dies eignet sich für interne Tools, Helpdesk-Bots und einfaches Question-Answering über Dokumente hinweg.

Hosted Agents erfordern, dass Sie Anwendungscode schreiben, diesen als Container paketieren und in Foundry einbinden. Sie wählen diesen Weg nur, wenn Sie eine benutzerdefinierte Geschäftslogik benötigen, die Foundry nicht durch Prompts und integrierte Tools ausdrücken kann, wie etwa den Aufruf einer internen API mit nicht standardisierter Authentifizierung.

Dieser Leitfaden konzentriert sich auf Prompt Agents, da sie der schnellste Weg sind, um zu validieren, dass Ihr .NET-Setup korrekt ist, bevor Sie Zeit in Docker-Dateien und Orchestrierung investieren.

Einrichtung über die Befehlszeile

Die Verwendung des CLI zwingt Sie dazu, jede Ressource zu sehen, was genau das ist, was der Python-Quickstart verschleiert. Erstellen Sie eine Ressourcengruppe in East US 2. Die Wahl der Region ist hier entscheidend. Foundry rollt die Tool-Unterstützung ungleichmäßig aus, und East US 2 bietet derzeit das breiteste Spektrum. Wenn Sie eine Region wählen, der der Code-Interpreter oder die Dateisuche-Tools fehlen, wird Ihr Aufruf zur Agentenerstellung mit einer undurchsichtigen Fehlermeldung über nicht unterstützte Funktionen fehlschlagen.

Erstellen Sie die Foundry-Ressource mit dem Flag --allow-project-management. Ohne dieses Flag bleibt die Ressource ein eigenständiger Cognitive Services Endpoint und akzeptiert keine projektbezogenen Deployments, die Agenten erfordern. Erstellen Sie dann das Project, deployen Sie Ihr Modell und weisen Sie sich selbst die Rolle Foundry User zu.

Verwenden Sie die stabile Rollen-GUID anstelle des Anzeigenamens:

53ca6127-db72-4b80-b1b0-d745d6d5456d

Rollennamen werden im Azure Active Directory je nach Tenant mit unterschiedlicher Geschwindigkeit propagiert. Eine Organisation sieht Foundry User heute im Portal; eine andere wird es erst in Tagen sehen. Die GUID verweist direkt auf die Definition und wird während des Rollouts nicht fehlschlagen. Dieses eine Detail kann Ihnen eine Stunde Debugging von "Permission-Denied"-Fehlern ersparen, die wie Richtlinienprobleme aussehen, aber eigentlich Probleme bei der Namensauflösung sind.

Vermeiden Sie das falsche NuGet-Paket

Hier bleiben .NET-Entwickler oft stecken. Sie werden in älteren Code-Snippets Verweise auf Azure.AI.Projects.OpenAI sehen. Dieses Paket ist nur in der Preview-Phase verfügbar und überschneidet sich mit Azure.AI.Extensions.OpenAI. Beide definieren Extension-Methoden und Typen in ähnlichen Namespaces. Wenn Sie sie nebeneinander installieren, bricht Ihr Build mit Fehlern aufgrund mehrdeutiger Referenzen ab, die