microsoft-foundry

Überblick

Was ist das Skill microsoft-foundry?

Das Skill microsoft-foundry ist eine kuratierte Sammlung von Workflows und Referenzdokumenten, die Sie durch den kompletten Lifecycle von Azure AI Foundry Agents führen. Der Fokus liegt auf praktischer Bereitstellung und Betrieb:

• Erstellen von prompt und hosted agents
• Bauen von Docker-Images und Push in die Azure Container Registry (ACR)
• Bereitstellen von Agents in Azure AI Foundry
• Einrichten von projects, RBAC, quota und connections
• Ausführen von evaluation datasets und Verwalten von agent-metadata.yaml
• Konfiguration von standard- und private-network-Agent-Setups
• Aktivieren von observability, tracing und troubleshooting

Alle Inhalte stammen aus dem Repository microsoft/azure-skills und sind so strukturiert, dass Sie Agents in Azure AI Foundry betreiben können, ohne das Repository-Layout „reverse engineeren“ zu müssen.

Für wen ist dieses Skill gedacht?

Verwenden Sie microsoft-foundry, wenn Sie:

• Backend- oder Platform Engineer sind und für die Bereitstellung und den Betrieb von Azure AI Foundry Agents verantwortlich sind
• AI/ML Engineer sind und Prototypen in ein produktives Foundry-Projekt überführen
• Developer sind und Foundry Agents mit bestehenden Services, SDKs oder MCP-Tools integrieren
• Technischer Verantwortlicher sind und über RBAC, Quotas, Private Networking und Umgebungs-Setup entscheiden müssen

Wenn Sie nur einfache Azure-Infrastruktur-Bereitstellung benötigen (App Service, Functions, generische Web-Apps), ist dieses Skill nicht passend – nutzen Sie stattdessen ein allgemeineres Azure Deployment-Skill.

Welche Probleme löst microsoft-foundry?

Das Skill ist darauf ausgelegt, wiederkehrende Herausforderungen zu adressieren:

• „Wie strukturiere ich mein Agent-Repo für Foundry?“
  Nutzen Sie die Anleitung in references/agent-metadata-contract.md für das .foundry/-Layout und die Felder in agent-metadata.yaml.

• „Wie erstelle und deploye ich Agents konsistent?“
  Verwenden Sie die Workflows foundry-agent/create und foundry-agent/deploy, um Prompt-/Hosted-Agents zu erstellen, Container zu bauen, nach ACR zu pushen und Agent-Container zu starten.

• „Wie konfiguriere ich projects, connections, RBAC und quota?“
  Folgen Sie project/create, rbac/rbac.md und quota/quota.md, um Projekte einzurichten, Rollen zuzuweisen und Kapazität zu planen.

• „Wie evaluiere und beobachte ich meine Agents?“
  Nutzen Sie foundry-agent/eval-datasets, foundry-agent/observe und foundry-agent/trace, um Batch-Evals auszuführen, Datasets und Evaluatoren zu verwalten und Observability-Ressourcen anzubinden.

• „Wie gehe ich mit Standard- vs. Private-Network-Setups um?“
  Verwenden Sie references/standard-agent-setup.md und references/private-network-standard-agent-setup.md, um das passende Netzwerkmodell auszuwählen und zu konfigurieren.

Wann ist microsoft-foundry die richtige Wahl?

Nutzen Sie dieses Skill, wenn Sie Folgendes benötigen:

• Bereitstellung von Prompt- oder Hosted-Agents in Azure AI Foundry
• Standardisierung der Agent-Projektstruktur mit .foundry/agent-metadata.yaml
• Integration von MCP tools und Azure SDKs in einen wiederholbaren Workflow
• Verwaltung von RBAC, quota und Kapazitätsplanung für Agent-Workloads
• Ausführen von evaluation datasets und Nachverfolgen von Ergebnissen über Umgebungen hinweg
• Einrichten von observability mit Application Insights und Traces
• Deployment in standard- oder private-network (VNet)-Konfigurationen

Nutzen Sie dieses Skill nicht, wenn Sie nur Folgendes brauchen:

• Generisches Azure-App-Deployment (Web-Apps, Functions, App Service)
• High-Level-Vorbereitung von Azure Accounts oder Subscriptions

In diesen Fällen kombinieren Sie dieses Skill mit allgemeineren Azure Deployment-/Vorbereitungs-Skills oder verwenden ein dediziertes Skill wie azure-deploy / azure-prepare.

Verwendung

Installation

Um microsoft-foundry aus dem Repository microsoft/azure-skills hinzuzufügen, installieren Sie es mit:

npx skills add https://github.com/microsoft/azure-skills --skill microsoft-foundry

Damit stehen die Workflows und Referenzinhalte von microsoft-foundry in Ihrer Agent- oder Tooling-Umgebung zur Verfügung. Nach der Installation ist der primäre Einstiegspunkt die Datei SKILL.md im Ordner skills/microsoft-foundry.

Repository-Struktur und wichtige Ordner

Nach der Installation des Skills oder beim Öffnen im Repository sehen Sie folgende Struktur:

• SKILL.md – Top-Level-Skill-Index und Liste der Sub-Skills
• foundry-agent/ – End-to-End-Workflows für einzelne Agents
  • create/ – Erstellen von Prompt- oder Hosted-Agents
  • deploy/ – Build und Deployment von Agents, inklusive Containern und ACR
  • eval-datasets/ – Verwalten von Eval-Datasets und Evaluationsläufen
  • invoke/ – Aufruf bestehender Agents
  • observe/ – Observability-Setup und Monitoring-Workflows
  • trace/ – Sammeln von Traces und Erstellen von Datasets aus Traces
  • troubleshoot/ – Troubleshooting-Anleitungen für fehlgeschlagene Runs
• project/
  • create/ – Erstellen und Konfigurieren von Azure AI Foundry Projects
  • connections.md – Hinweise zu Project-Level-Connections
• rbac/
  • rbac.md – RBAC-Rollen, Berechtigungen und typische Muster
• quota/
  • quota.md – Hinweise zu Quota und Kapazitätsplanung
  • references/ – Kapazitätsplanung, Fehlerbehebung, Optimierung
• references/
  • agent-metadata-contract.md – .foundry/-Layout und agent-metadata.yaml
  • auth-best-practices.md – Azure-Authentifizierungsmuster und RBAC
  • standard-agent-setup.md – Standard-Setup (nicht isolierte Agents)
  • private-network-standard-agent-setup.md – VNet-/Private-Link-Setup
  • sdk/ – SDK-Operations-Referenzen, wenn MCP tools nicht verfügbar sind

Beginnen Sie mit SKILL.md, um die Sub-Skills zu verstehen, und vertiefen Sie dann in den Ordner zum jeweiligen Szenario.

Quick-Start-Workflow: vom Projekt zum bereitgestellten Agent

In diesem Abschnitt wird ein praxisnaher Pfad mit den Inhalten des microsoft-foundry-Skills skizziert.

1. Foundry-Projekt erstellen oder vorbereiten

1. Öffnen Sie project/create/create-foundry-project.md.
2. Folgen Sie den Schritten, um:
   • Ein Azure AI Foundry project zu erstellen
   • Den project endpoint zu bestätigen (zum Beispiel https://<resource>.services.ai.azure.com/api/projects/<project>)
   • Erforderliche connections (Cosmos DB, Storage, Azure AI Search usw.) für das Standard-Setup zu verknüpfen
3. Prüfen Sie project/connections.md, um sicherzustellen, dass Thread Storage, File Storage und Vector Store Connections korrekt konfiguriert sind, insbesondere wenn Sie das standard agent setup verwenden wollen.

2. RBAC und Authentifizierung konfigurieren

1. Lesen Sie rbac/rbac.md, um zu prüfen:
   • Welche Rollen (Owner, Contributor, User Access Administrator etc.) auf der Resource Group und den Foundry-Ressourcen benötigt werden
   • Wie Rollen gemäß Azure RBAC Best Practices zugewiesen werden
2. Öffnen Sie references/auth-best-practices.md und setzen Sie die Empfehlungen um:
   • Nutzen Sie in der Produktion managed identities und Azure RBAC
   • Beschränken Sie DefaultAzureCredential auf lokale Entwicklung
   • Wählen Sie den passenden Credential-Typ für Produktion, CI/CD und Entwicklungsumgebungen

So stellen Sie sicher, dass Deployments und Agent-Operationen zuverlässig authentifizieren können, ohne Hard-Coded Secrets.

3. Basic vs. Standard vs. Private-Network-Setup wählen

1. Öffnen Sie references/standard-agent-setup.md, um zu verstehen:
   • Unterschiede zwischen Basic- und Standard-Setups
   • Erforderliche Connections für das Standard-Setup: Cosmos DB, Azure Storage, Azure AI Search und optional Azure AI Services
   • Voraussetzungen wie RBAC-Rollen auf der Resource Group
2. Wenn Sie volle Netzwerkisolation benötigen, lesen Sie references/private-network-standard-agent-setup.md:
   • Anforderungen an VNet und Subnetze (Agent-Subnet und Private-Endpoint-Subnet)
   • Regionale Ausrichtung zwischen Foundry-Ressourcen und dem VNet
   • Verwendung des offiziellen Bicep template für das Private-Network-Standard-Agent-Setup

Wählen Sie das Setup, das Ihren Compliance- und Netzwerkvorgaben entspricht, bevor Sie mit der Agent-Erstellung fortfahren.

4. Agent-Projektlayout standardisieren

1. Öffnen Sie references/agent-metadata-contract.md und richten Sie Ihr Projekt nach dem dokumentierten Layout aus:

   <agent-root>/
     .foundry/
       agent-metadata.yaml
       datasets/
       evaluators/
       results/
   

2. Stellen Sie sicher, dass agent-metadata.yaml Umgebungsdefinitionen mit Feldern wie folgenden enthält:

   • defaultEnvironment
   • environments.<name>.projectEndpoint
   • environments.<name>.agentName
   • environments.<name>.azureContainerRegistry (für hosted agents)
   • environments.<name>.observability.* (für Application Insights)
   • environments.<name>.testCases[] für Evaluation-Bundles

Diese Datei wird zur Single Source of Truth für die umgebungsspezifische Konfiguration, und die übrigen microsoft-foundry-Workflows setzen voraus, dass sie vorhanden und korrekt ist.

5. Prompt- oder Hosted-Agent erstellen

1. Für prompt agents öffnen Sie foundry-agent/create/create-prompt.md:

   • Verstehen Sie den Unterschied zwischen Prompt Agents und Workflows
   • Folgen Sie den Schritten, um den Projektkontext (Endpoint, Credentials) aufzulösen
   • Nutzen Sie MCP tools, wo verfügbar, und greifen Sie ansonsten wie dokumentiert auf das azure-ai-projects SDK zurück
   • Geben Sie Agent-Name, Model Deployment und Instructions plus optionale Tools (File Search, Code Interpreter etc.) an

2. Für hosted agents öffnen Sie foundry-agent/create/create.md:

   • Entscheiden Sie, ob Sie einen neuen Agent (Greenfield) erstellen oder ein bestehendes Projekt (Brownfield) konvertieren
   • Wählen Sie anhand der Beispielpfade ein Framework und eine Sprache (Python oder C# Frameworks wie Microsoft Agent Framework oder LangGraph)
   • Nutzen Sie die Hinweise zur Integration mit dem Repository foundry-samples, wo erforderlich

Am Ende dieses Schritts sollten Sie ein Foundry-kompatibles Agent-Projekt bereit für das Deployment haben.

6. Agent bauen und deployen

1. Öffnen Sie foundry-agent/deploy/deploy.md.
2. Folgen Sie dem Workflow, der Folgendes abdeckt:
   • Projektscan und Einsammeln von Environment Variables
   • Generierung der Dockerfile und Nutzung von docker / az acr für hosted agents
   • Einsatz von MCP tools wie agent_update, agent_container_control und agent_container_status_get
   • Erstellen oder Aktualisieren des Deployments und Starten/Stoppen von Agent-Containern
3. Führen Sie azd up, azd deploy, az acr build oder docker build nicht isoliert aus, ohne diesen Guide gelesen zu haben – das Skill koordiniert diese Befehle als Teil einer vollständigen Deployment-Pipeline.

Nach diesem Schritt sollte Ihr Agent bereitgestellt und über Azure AI Foundry erreichbar sein.

7. Agent aufrufen und testen

1. Öffnen Sie foundry-agent/invoke/invoke.md.
2. Nutzen Sie die beschriebenen Muster, um:
   • Die korrekte Umgebung und den Endpoint aus agent-metadata.yaml zu ermitteln
   • Den Agent mit Beispiel- oder Custom-Payloads aufzurufen
   • Zu prüfen, ob Responses, Tools und State wie erwartet funktionieren

In diesem Stadium eignen sich Smoke Tests, bevor Sie vollständige Evaluationssuiten ausführen.

8. Evaluieren und iterieren

1. Öffnen Sie foundry-agent/eval-datasets/eval-datasets.md.
2. Nutzen Sie die Anleitung, um:
   • Datasets und Evaluatoren unter .foundry/datasets und .foundry/evaluators zu verwalten
   • Evaluations-Workflows mit den testCases-Definitionen aus agent-metadata.yaml auszuführen
   • Outputs unter .foundry/results zu speichern und Ergebnisse nach Umgebung oder Agent-Version zu vergleichen
3. Verbessern Sie Ihre Prompts oder Instructions iterativ und führen Sie Evaluierungen erneut aus, um Fortschritte über die Zeit zu messen.

Observability, Tracing und Troubleshooting

Observability und Monitoring

1. Öffnen Sie foundry-agent/observe/observe.md.
2. Konfigurieren Sie Observability gemäß der Anleitung:
   • Binden Sie Application Insights über die Resource-ID und Connection String Felder an, wie in agent-metadata-contract.md beschrieben
   • Nutzen Sie die empfohlenen Dashboards oder Queries, um Latenz, Fehler und Durchsatz zu überwachen

So können Sie das Verhalten in Produktion überwachen und mit Deployment-Änderungen korrelieren.

Tracing und Datensatzerstellung aus Traces

1. Öffnen Sie foundry-agent/trace/trace.md.
2. Verwenden Sie die beschriebenen Workflows, um:
   • Traces Ihrer Agents zu sammeln
   • Datasets aus Traces zu kuratieren und unter .foundry/datasets abzulegen
   • Diese Datasets in die Evaluations-Workflows für realistischere Tests einzuspeisen

Das ist besonders hilfreich, wenn Sie Real User Traffic in Evaluationsszenarien überführen möchten.

Troubleshooting bei Deployments und zur Laufzeit

1. Öffnen Sie foundry-agent/troubleshoot/troubleshoot.md.
2. Folgen Sie den Troubleshooting-Guides für Probleme wie:
   • Deployment-Fehlschläge und Container-Startfehler
   • Falsch konfigurierte Endpoints, Credentials oder Connections
   • Quota- oder Kapazitätsfehler (siehe auch quota/quota.md und quota/references/*.md)

Nutzen Sie dies zusammen mit Logs und Application-Insights-Telemetrie, um Probleme zu diagnostizieren und zu beheben.

Quota, Kapazität und Optimierung

1. Öffnen Sie quota/quota.md für einen Überblick über:
   • Wie Quotas auf Modelle und Deployments in Azure AI Foundry angewendet werden
   • Wie Sie Kapazität über Umgebungen und Regionen hinweg beurteilen
2. Prüfen Sie die Dateien in quota/references/:
   • capacity-planning.md – hilft bei der Kapazitätsschätzung für Agents basierend auf der Nutzung
   • error-resolution.md – ordnet häufige quota-bezogene Fehler den empfohlenen Fixes zu
   • optimization.md – schlägt Möglichkeiten zur Optimierung von Workloads vor, um innerhalb der Quota-Grenzen zu bleiben

Diese Inhalte helfen Ihnen, Überraschungen im Scale-Betrieb zu vermeiden und Agents performant zu halten.

FAQ

Ist microsoft-foundry notwendig, um Azure AI Foundry zu verwenden?

Nein. Sie können Azure AI Foundry direkt über das Azure Portal, die CLI oder die SDKs nutzen. Das Skill microsoft-foundry ist ein strukturierter Leitfaden, der Best Practices, Workflows und Referenzen an einem Ort bündelt, damit Sie Projekte, Agents und Umgebungen konsistenter aufsetzen können.

Kann ich microsoft-foundry für andere Azure-Services als Foundry verwenden?

Nutzen Sie dieses Skill, wenn Ihr Hauptziel Deployment und Betrieb von Azure AI Foundry Agents und Projekten ist. Für das generelle Deployment von Web-Apps, APIs oder anderen PaaS-Services (App Service, Functions, generische Container) verwenden Sie stattdessen ein dediziertes Azure Deployment-Skill oder entsprechende Guidance.

Unterstützt microsoft-foundry sowohl Prompt- als auch Hosted-Agents?

Ja. Das Skill enthält dedizierte Inhalte für beide Varianten:

• foundry-agent/create/create-prompt.md behandelt prompt agents.
• foundry-agent/create/create.md und foundry-agent/deploy/deploy.md decken hosted agents ab, inklusive Containerisierung, ACR und Container-Lifecycle-Management.

Wie adressiert microsoft-foundry Authentifizierung und Sicherheit?

Sicherheit und Authentifizierung werden in references/auth-best-practices.md und rbac/rbac.md behandelt:

• Nutzen Sie managed identities und Azure RBAC in Produktion
• Verwenden Sie DefaultAzureCredential nur für lokale Entwicklung
• Wählen Sie passende Credentials für CI/CD- und On-Prem-Umgebungen

Folgen Sie diesen Dokumenten, bevor Sie SDKs oder MCP tools anbinden, um unsichere oder fragile Setups zu vermeiden.

Muss ich MCP tools verwenden oder kann ich ausschließlich SDKs nutzen?

Die Inhalte sind so geschrieben, dass sie mit MCP tools wo verfügbar funktionieren, aber auch SDK-basierte Fallbacks im Ordner references/sdk dokumentieren. So erklärt create-prompt.md zum Beispiel, wie Sie auf das azure-ai-projects SDK zurückfallen, wenn keine MCP tools vorhanden sind.

Woran erkenne ich, ob mein Agent-Projekt korrekt strukturiert ist?

Vergleichen Sie Ihr Projekt mit references/agent-metadata-contract.md. Stellen Sie sicher, dass Sie Folgendes haben:

• Ein .foundry/-Verzeichnis im Agent-Root
• Eine gültige agent-metadata.yaml mit Environments und Test Cases
• datasets/, evaluators/ und results/-Ordner wie beschrieben

Wenn Sie diesen Contract einhalten, sind die übrigen microsoft-foundry-Workflows mit Ihrem Projektlayout kompatibel.

Kann ich microsoft-foundry mit Private-Network- (VNet-)Setups nutzen?

Ja. references/private-network-standard-agent-setup.md bietet detaillierte Hinweise zu:

• Erforderlicher VNet- und Subnet-Konfiguration
• Regionalen Einschränkungen zwischen Foundry-Ressourcen und dem VNet
• Verwendung des offiziellen Bicep Templates für das Private-Network-Standard-Agent-Setup

Nutzen Sie dieses Dokument zusammen mit references/standard-agent-setup.md, wenn der Traffic strikt im privaten Netzwerk bleiben muss.

Wo sollte ich nach der Installation im Repository beginnen?

Nach der Installation des Skills starten Sie mit:

1. SKILL.md – für einen High-Level-Überblick über alle Sub-Skills
2. project/create/create-foundry-project.md – zum Einrichten Ihres Foundry-Projekts
3. references/agent-metadata-contract.md – zur Standardisierung des Agent-Layouts
4. foundry-agent/create/ und foundry-agent/deploy/ – um Ihren ersten Agent zu bauen und zu deployen

Danach können Sie je nach Szenario mit eval-datasets, observe, trace, rbac und quota weitermachen.