Tutorial: Von der Idee zum Prototyp – Erstellen und Auswerten eines Enterprise-Agents

In diesem Lernprogramm wird die erste Phase der Microsoft Foundry-Entwicklerreise behandelt: von einer ersten Idee bis hin zu einem funktionierenden Prototyp. Sie erstellen einen modernen Arbeitsplatz-Assistenten , der interne Unternehmenskenntnisse mit externen technischen Anleitungen mithilfe des Microsoft Foundry SDK kombiniert.

Geschäftsszenario: Erstellen Sie einen KI-Assistenten, der Mitarbeitern hilft, indem Sie Folgendes kombinieren:

Unternehmensrichtlinien (aus SharePoint-Dokumenten)
Anleitung zur technischen Implementierung (von Microsoft Learn über MCP)
Komplettlösungen (Kombinieren beider Quellen für die Unternehmensimplementierung)
Stapelbewertung zur Validierung der Leistung des Agenten in realistischen Geschäftssituationen

Lernprogrammergebnis: Am Ende haben Sie einen ausgeführten Assistenten für moderne Arbeitsplätze, der Richtlinien, technische und kombinierte Implementierungsfragen beantworten kann; ein wiederholbares Batchauswertungsskript; und klare Erweiterungspunkte (andere Tools, Multi-Agent-Muster, umfangreichere Auswertung).

Sie werden:

Erstellen Sie einen Assistenten für moderne Arbeitsplätze mit der SharePoint- und MCP-Integration.
Veranschaulichen Sie reale Geschäftsszenarien, die interne und externe Kenntnisse kombinieren.
Setzen Sie eine robuste Fehlerbehandlung und eine sanfte Degradierung um.
Erstellen Sie Evaluierungsframework für unternehmensorientierte Tests.
Vorbereitung der Grundlage für Governance und Produktionsbereitstellung.

In diesem minimalen Beispiel werden unternehmensfähige Muster mit realistischen Geschäftsszenarien veranschaulicht.

Von Bedeutung

Der Code in diesem Artikel verwendet Pakete, die sich derzeit in der Vorschau befinden. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

Voraussetzungen

Ein Azure-Abonnement. Sollten Sie über keine Organisation verfügen, können Sie kostenlos eine erstellen.
Azure CLI 2.67.0 oder höher, authentifiziert mit az login (Überprüfen mit az version)
Ein Foundry-Projekt mit einem bereitgestellten Modell (z. B. gpt-4o-mini). Wenn Sie über keins verfügen: Erstellen Sie ein Projekt , und stellen Sie dann ein Modell bereit (siehe Modellübersicht: Modellkatalog).
Python 3.10 oder höher
.NET SDK 8.0 oder höher (für das C#-Beispiel)
In Ihrem Projekt konfigurierte SharePoint-Verbindung (SharePoint-Tooldokumentation)

Hinweis

Informationen zum Konfigurieren Ihres Foundry-Projekts für die SharePoint-Konnektivität finden Sie in der SharePoint-Tooldokumentation.
(Optional) Git zum Klonen des Beispiel-Repositorys installiert

Schritt 1: Abrufen des Beispielcodes

Statt in einer großen Repositorystruktur zu navigieren, sollten Sie einen der folgenden Ansätze verwenden:

Option A (gesamtes Beispiel-Repository klonen)

Tipp

Code verwendet Azure AI Projects 2.x und ist nicht mit Azure AI Projects 1.x kompatibel. Weitere Informationen finden Sie in der Dokumentation zu Foundry (classic) für die Azure AI Projects 1.x-Version.

Python
C#

git clone --depth 1 https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/python/enterprise-agent-tutorial/1-idea-to-prototype

git clone --depth 1 https://github.com/azure-ai-foundry/foundry-samples.git
cd foundry-samples/samples/csharp/enterprise-agent-tutorial/1-idea-to-prototype

Option B (nur wenig Auschecken dieses Lernprogramms - reduzierter Download)

Python
C#

git clone --no-checkout https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples
git sparse-checkout init --cone
git sparse-checkout set samples/python/enterprise-agent-tutorial/1-idea-to-prototype
git checkout
cd samples/python/enterprise-agent-tutorial/1-idea-to-prototype

git clone --no-checkout https://github.com/azure-ai-foundry/foundry-samples.git
cd foundry-samples
git sparse-checkout init --cone
git sparse-checkout set samples/csharp/enterprise-agent-tutorial/1-idea-to-prototype
git checkout
cd samples/csharp/enterprise-agent-tutorial/1-idea-to-prototype

Option C (DOWNLOAD ZIP des Repositorys)

Laden Sie das Repository-ZIP herunter, und extrahieren Sie es in Ihre lokale Umgebung, und wechseln Sie zum Tutorial-Ordner.

Von Bedeutung

Verwenden Sie für die Produktionsakzeptanz ein eigenständiges Repository. In diesem Lernprogramm wird das freigegebene Beispiel-Repository verwendet. Das geringe Auschecken minimiert lokale Geräusche.

Python
C#

Laden Sie den Python-Code jetzt herunter.

Wechseln Sie nach dem Extrahieren der ZIP-Datei zu samples/python/enterprise-agent-tutorial/1-idea-to-prototype.

Die minimale Struktur enthält nur wesentliche Dateien:

Python
C#

enterprise-agent-tutorial/
└── 1-idea-to-prototype/
   ├── .env                             # Create this file (local environment variables)
   ├── .gitkeep
   ├── evaluate.py                      # Business evaluation framework
   ├── evaluation_results.json
   ├── main.py                          # Modern Workplace Assistant
   ├── questions.jsonl                  # Business test scenarios (4 questions)
   ├── requirements.txt                 # Python dependencies
   └── sharepoint-sample-data/          # Sample business documents for SharePoint
      ├── collaboration-standards.docx
      ├── data-governance-policy.docx
      ├── remote-work-policy.docx
      └── security-guidelines.docx

enterprise-agent-tutorial/
└── 1-idea-to-prototype/
   ├── ModernWorkplaceAssistant/        # Modern Workplace Assistant
   │   ├── Program.cs                   # Agent implementation with SharePoint + MCP
   │   ├── ModernWorkplaceAssistant.csproj
   │   └── .env                         # Environment variables (create this)
   ├── Evaluate/                        # Cloud evaluation framework
   │   ├── Program.cs                   # Cloud evaluation with built-in evaluators
   │   ├── Evaluate.csproj
   │   └── evaluation_results.json      # Example output (generated)
   ├── questions.jsonl                  # Business test scenarios
   └── README.md                        # Complete setup instructions

Schritt 2: Das Beispiel sofort ausführen

Beginnen Sie, indem Sie den Agent ausführen, damit Sie die Funktionsfähigkeit sehen, bevor Sie sich mit den Implementierungsdetails beschäftigen.

Umgebungseinrichtung und virtuelle Umgebung

Installieren Sie die erforderlichen Sprachlaufzeiten, globalen Tools und VS-Codeerweiterungen, wie unter "Vorbereiten Der Entwicklungsumgebung" beschrieben.
Überprüfen Sie, ob Ihr requirements.txt diese veröffentlichten Paketversionen verwendet:
```
azure-ai-projects==2.0.0b3
azure-identity
python-dotenv
openai
```
Installieren von Abhängigkeiten:
- Python
- C#
```
python -m pip install -r requirements.txt
```
```
cd ModernWorkplaceAssistant
dotnet restore

cd ../Evaluate
dotnet restore
```
Überprüfen Sie, ob die Installation erfolgreich war. Sie sollten Successfully installed azure-ai-projects-...(Python) oder Restore completed(.NET) ohne Fehler sehen.
Suchen Sie Ihren Projektendpunkt auf der Willkommensseite des Projekts.
Konfigurieren .env.

Legen Sie die für Ihre Sprache erforderlichen Umgebungswerte fest.

Python
C#

Kopieren Sie .env.template nach .env.

Python
C#

# Foundry configuration
PROJECT_ENDPOINT=https://<your-project>.aiservices.azure.com
MODEL_DEPLOYMENT_NAME=gpt-4o-mini

# The Microsoft Learn MCP Server (optional)
MCP_SERVER_URL=https://learn.microsoft.com/api/mcp

# SharePoint integration (optional - requires connection name)
SHAREPOINT_CONNECTION_NAME=<your-sharepoint-connection-name>

# Foundry configuration
PROJECT_ENDPOINT=https://<your-project>.aiservices.azure.com
MODEL_DEPLOYMENT_NAME=gpt-4o-mini

# SharePoint integration (optional - requires connection name)
SHAREPOINT_CONNECTION_NAME=<your-sharepoint-connection-name>

# The Microsoft Learn MCP Server (optional)
MCP_SERVER_URL=https://learn.microsoft.com/api/mcp

Bestätigen Sie, dass .env gültige Werte enthalten sind, indem Sie die Datei öffnen und überprüfen, ob PROJECT_ENDPOINT sie mit https:// dem Namen eines bereitgestellten Modells in Ihrem Projekt beginnt und MODEL_DEPLOYMENT_NAME entspricht.

Tipp

Um Ihre Mandanten-ID zu erhalten, führen Sie Folgendes aus:

# Get tenant ID
az account show --query tenantId -o tsv

Um Ihren Projektendpunkt abzurufen, öffnen Sie Ihr Projekt im Foundry-Portal , und kopieren Sie den dort angezeigten Wert.

python main.py
python evaluate.py

cd ModernWorkplaceAssistant
dotnet restore
dotnet run

cd ../Evaluate
dotnet restore
dotnet run

Erwartete Ausgabe (Agent erster Lauf)

Erfolgreiche Ausführung mit SharePoint:

🤖 Creating Modern Workplace Assistant...
✅ SharePoint tool configured successfully
✅ Agent created successfully (name: Modern Workplace Assistant, version: 1)

Sanfter Abbau ohne SharePoint

📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_NAME not set)
✅ Agent created successfully (name: Modern Workplace Assistant, version: 1)

Nachdem Sie nun über einen Funktionierenden Agent verfügen, erläutern die nächsten Abschnitte, wie es funktioniert. Sie müssen beim Lesen dieser Abschnitte keine Aktion ausführen – sie sind zur Erläuterung.

Schritt 3: Einrichten von SharePoint-Beispiel-Geschäftsdokumenten

Wechseln Sie zu Ihrer SharePoint-Website (in der Verbindung konfiguriert).
Erstellen Sie die Dokumentbibliothek "Unternehmensrichtlinien" (oder verwenden Sie vorhandene "Dokumente").
Laden Sie die vier Word-Beispieldokumente hoch, die im Ordner sharepoint-sample-data bereitgestellt werden.
- remote-work-policy.docx
- security-guidelines.docx
- collaboration-standards.docx
- data-governance-policy.docx
Stellen Sie sicher, dass vier Dokumente in der Bibliothek angezeigt werden, bevor Sie fortfahren.

Beispielstruktur

📁 Company Policies/
├── remote-work-policy.docx      # VPN, MFA, device requirements
├── security-guidelines.docx     # Azure security standards
├── collaboration-standards.docx # Teams, SharePoint usage
└── data-governance-policy.docx  # Data classification, retention

Grundlegendes zur Implementierung des Assistenten

Hinweis

Dieser Abschnitt ist nur zu Referenzzwecken – keine Aktion erforderlich. Es wird der Code erläutert, den Sie bereits ausgeführt haben.

In diesem Abschnitt wird der Kerncode in main.py (Python) oder ModernWorkplaceAssistant/Program.cs (C#) erläutert. Sie haben den Agent bereits ausgeführt. Nach dem Lesen haben Sie folgende Möglichkeiten:

Fügen Sie neue interne und externe Datentools hinzu.
Erweitern Sie dynamische Anweisungen.
Führen Sie die Multi-Agent-Orchestrierung ein.
Verbessern Sie die Überwachbarkeit und Diagnose.

Der Code unterteilt sich in die folgenden Hauptabschnitte, sortiert, wie sie im vollständigen Beispielcode angezeigt werden:

Konfigurieren von Importen und Authentifizierung
Konfigurieren der Authentifizierung für Azure
Konfigurieren des SharePoint-Tools
Konfigurieren des MCP-Tools
Erstellen des Agents und Verbinden der Tools
Mit dem Agenten sprechen

Von Bedeutung

Importe und Authentifizierungseinrichtung

Der Code verwendet mehrere Clientbibliotheken aus dem Microsoft Foundry SDK, um einen robusten Enterprise-Agent zu erstellen.

Python
C#

import os
import time
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    SharepointPreviewTool,
    SharepointGroundingToolParameters,
    ToolProjectConnection,
    MCPTool,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv
from openai.types.responses.response_input_param import (
    McpApprovalResponse,
)

using System;
using System.ClientModel;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using Azure.AI.Projects;
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
using DotNetEnv;
using OpenAI.Responses;

Konfigurieren der Authentifizierung in Azure

Bevor Sie Ihren Agent erstellen, richten Sie die Authentifizierung für die Gießerei ein.

Python
C#

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    print(f"✅ Connected to Foundry: {endpoint}")

var credential = new DefaultAzureCredential();

projectClient = new AIProjectClient(new Uri(projectEndpoint), credential);
Console.WriteLine($"✅ Connected to Azure AI Foundry: {projectEndpoint}");

Erstellen des SharePoint-Tools für den Agent

Der Agent verwendet SharePoint und kann auf dort gespeicherte Unternehmensrichtlinien- und Prozedurdokumente zugreifen. Richten Sie die Verbindung mit SharePoint in Ihrem Code ein.

Python
C#

sharepoint_connection_id = os.environ.get("SHAREPOINT_CONNECTION_ID")
sharepoint_tool = None

if sharepoint_connection_id:
    print("📁 Configuring SharePoint integration...")
    print(f"   Connection ID: {sharepoint_connection_id}")

    try:
        sharepoint_tool = SharepointPreviewTool(
            sharepoint_grounding_preview=SharepointGroundingToolParameters(
                project_connections=[
                    ToolProjectConnection(
                        project_connection_id=sharepoint_connection_id
                    )
                ]
            )
        )
        print("✅ SharePoint tool configured successfully")
    except Exception as e:
        print(f"⚠️  SharePoint tool unavailable: {e}")
        print("   Agent will operate without SharePoint access")
        sharepoint_tool = None
else:
    print("📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_ID not set)")

// Resolve connection name to connection ID via the Connections API
AIProjectConnection sharepointConnection = await projectClient.Connections.GetConnectionAsync(
    sharePointConnectionName, includeCredentials: false);

SharePointGroundingToolOptions sharepointToolOption = new()
{
    ProjectConnections = { new ToolProjectConnection(projectConnectionId: sharepointConnection.Id) }
};
sharepointTool = new SharepointAgentTool(sharepointToolOption);
Console.WriteLine($"✅ SharePoint tool configured successfully");

Erstellen des MCP-Tools für den Agent

Python
C#

mcp_server_url = os.environ.get("MCP_SERVER_URL")
mcp_tool = None

if mcp_server_url:
    print("📚 Configuring Microsoft Learn MCP integration...")
    print(f"   Server URL: {mcp_server_url}")

    try:
        mcp_tool = MCPTool(
            server_url=mcp_server_url,
            server_label="Microsoft_Learn_Documentation",
            require_approval="always",
        )
        print("✅ MCP tool configured successfully")
    except Exception as e:
        print(f"⚠️  MCP tool unavailable: {e}")
        print("   Agent will operate without Microsoft Learn access")
        mcp_tool = None
else:
    print("📚 MCP integration skipped (MCP_SERVER_URL not set)")

// MCP (Model Context Protocol) enables agents to access external data sources
// like Microsoft Learn documentation. The approval flow is handled in ChatWithAssistantAsync.
McpTool? mcpTool = null;

if (!string.IsNullOrEmpty(mcpServerUrl))
{
    Console.WriteLine($"📚 Configuring Microsoft Learn MCP integration...");
    Console.WriteLine($"   Server URL: {mcpServerUrl}");

    try
    {
        // Create MCP tool for Microsoft Learn documentation access
        // server_label must match pattern: ^[a-zA-Z0-9_]+$ (alphanumeric and underscores only)
        mcpTool = new McpTool("Microsoft_Learn_Documentation", new Uri(mcpServerUrl));
        Console.WriteLine($"✅ MCP tool configured successfully");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"⚠️  MCP tool unavailable: {ex.Message}");
        Console.WriteLine($"   Agent will operate without Microsoft Learn access");
    }
}
else
{
    Console.WriteLine($"📚 MCP integration skipped (MCP_SERVER_URL not set)");
}

Erstellen des Agents und Verbinden der Tools

Erstellen Sie den Agent, und verbinden Sie die SharePoint- und MCP-Tools.

Python
C#

print(f"🛠️  Creating agent with model: {os.environ['MODEL_DEPLOYMENT_NAME']}")

tools = []
if sharepoint_tool:
    tools.append(sharepoint_tool)
    print("   ✓ SharePoint tool added")
if mcp_tool:
    tools.append(mcp_tool)
    print("   ✓ MCP tool added")

print(f"   Total tools: {len(tools)}")

agent = project_client.agents.create_version(
    agent_name="Modern Workplace Assistant",
    definition=PromptAgentDefinition(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        instructions=instructions,
        tools=tools if tools else None,
    ),
)

print(f"✅ Agent created successfully (name: {agent.name}, version: {agent.version})")
return agent

// Create the agent using the v2 SDK with PromptAgentDefinition
Console.WriteLine($"🛠️  Creating agent with model: {modelDeploymentName}");

var agentDefinition = new PromptAgentDefinition(modelDeploymentName)
{
    Instructions = instructions
};

// Add tools to the agent definition
if (sharepointTool != null)
{
    agentDefinition.Tools.Add(sharepointTool);
    Console.WriteLine($"   ✓ SharePoint tool added");
}

if (mcpTool != null)
{
    agentDefinition.Tools.Add(mcpTool);
    Console.WriteLine($"   ✓ MCP tool added");
}

Console.WriteLine($"   Total tools: {agentDefinition.Tools.Count}");

// Create agent version
AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync(
    agentName: agentName,
    options: new(agentDefinition));

// Create a response client bound to this agent for conversations
responseClient = projectClient.OpenAI
    .GetProjectResponsesClientForAgent(agentVersion);

Console.WriteLine($"✅ Agent created successfully: {agentVersion.Name} (version {agentVersion.Version})");
return agentVersion;

Mit dem Agenten sprechen

Implementieren Sie schließlich eine interaktive Schleife, um mit dem Agent zu sprechen.

Python
C#

print("🤖 AGENT RESPONSE:")
response, status = create_agent_response(agent, scenario["question"], openai_client)

Console.WriteLine("🤖 ASSISTANT RESPONSE:");
var (response, status) = await ChatWithAssistantAsync(scenario.Question);

Erwartete Ausgabe aus Agent-Beispielcode

Wenn Sie den Agent ausführen, wird die Ausgabe ähnlich wie im folgenden Beispiel angezeigt. Die Ausgabe zeigt erfolgreiche Toolkonfigurations- und Agentantworten auf Geschäftsszenarien:

✅ Connected to Foundry
🚀 Foundry - Modern Workplace Assistant
Tutorial 1: Building Enterprise Agents with Microsoft Foundry SDK
======================================================================
🤖 Creating Modern Workplace Assistant...
📁 Configuring SharePoint integration...
   Connection ID: /subscriptions/.../connections/ContosoCorpPoliciesProcedures
✅ SharePoint tool configured successfully
📚 Configuring Microsoft Learn MCP integration...
   Server URL: https://learn.microsoft.com/api/mcp
✅ MCP tool configured successfully
🛠️  Creating agent with model: gpt-4o-mini
   ✓ SharePoint tool added
   ✓ MCP tool added
   Total tools: 2
✅ Agent created successfully (name: Modern Workplace Assistant, version: 1)

======================================================================
🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION
======================================================================
This demonstration shows how AI agents solve real business problems
using the Microsoft Foundry SDK.
======================================================================

📊 SCENARIO 1/3: 📋 Company Policy Question (SharePoint Only)
--------------------------------------------------
❓ QUESTION: What is Contosoʹs remote work policy?
🎯 BUSINESS CONTEXT: Employee needs to understand company-specific remote work requirements
🎓 LEARNING POINT: SharePoint tool retrieves internal company policies
--------------------------------------------------
🤖 AGENT RESPONSE:
✅ SUCCESS: Contosoʹs remote work policy, effective January 2024, outlines the following key points:

### Overview
Contoso Corp supports flexible work arrangements, including remote work, to enhance employee productivity and work-life balance.

### Eligibility
- **Full-time Employees**: Must have completed a 90...
   📏 Full response: 1530 characters
📈 STATUS: completed
--------------------------------------------------

📊 SCENARIO 2/3: 📚 Technical Documentation Question (MCP Only)
--------------------------------------------------
❓ QUESTION: According to Microsoft Learn, what is the correct way to implement Azure AD Conditional Access policies? Please include reference links to the official documentation.
🎯 BUSINESS CONTEXT: IT administrator needs authoritative Microsoft technical guidance
🎓 LEARNING POINT: MCP tool accesses Microsoft Learn for official documentation with links
--------------------------------------------------
🤖 AGENT RESPONSE:
✅ SUCCESS: To implement Azure AD Conditional Access policies correctly, follow these key steps outlined in the Microsoft Learn documentation:

### 1. Understanding Conditional Access
Conditional Access policies act as "if-then" statements that enforce organizational access controls based on various signals. Th...
   📏 Full response: 2459 characters
📈 STATUS: completed
--------------------------------------------------

📊 SCENARIO 3/3: 🔄 Combined Implementation Question (SharePoint + MCP)
--------------------------------------------------
❓ QUESTION: Based on our companyʹs remote work security policy, how should I configure my Azure environment to comply? Please include links to Microsoft documentation showing how to implement each requirement.
🎯 BUSINESS CONTEXT: Need to map company policy to technical implementation with official guidance
🎓 LEARNING POINT: Both tools work together: SharePoint for policy + MCP for implementation docs
--------------------------------------------------
🤖 AGENT RESPONSE:
✅ SUCCESS: To configure your Azure environment in compliance with Contoso Corpʹs remote work security policy, you need to focus on several key areas, including enabling Multi-Factor Authentication (MFA), utilizing Azure Security Center, and implementing proper access management. Below are specific steps and li...
   📏 Full response: 3436 characters
📈 STATUS: completed
--------------------------------------------------

✅ DEMONSTRATION COMPLETED!
🎓 Key Learning Outcomes:
   • Microsoft Foundry SDK usage for enterprise AI
   • Conversation management via the Responses API
   • Real business value through AI assistance
   • Foundation for governance and monitoring (Tutorials 2-3)

🎯 Try interactive mode? (y/n): n

🎉 Sample completed successfully!
📚 This foundation supports Tutorial 2 (Governance) and Tutorial 3 (Production)
🔗 Next: Add evaluation metrics, monitoring, and production deployment

Schritt 4: Bewerten des Assistenten mithilfe der Cloudauswertung

Das Evaluierungsframework testet realistische Geschäftsszenarien mithilfe der Cloudauswertungsfunktion des Microsoft Foundry SDK. Anstelle eines benutzerdefinierten lokalen Ansatzes verwendet dieses Muster die integrierten Evaluatoren (builtin.violence, builtin.fluency, builtin.task_adherence) und die openai_client.evals API, um skalierbare, wiederholbare Auswertungen in der Cloud auszuführen.

Dieses Evaluierungsframework veranschaulicht:

Agent-Targeting: Die Bewertung führt Abfragen direkt an Ihren Agenten mithilfe von azure_ai_target_completions.
Integrierte Bewertungen: Sicherheit (Gewalterkennung), Qualität (Fluency) und Metriken zur Einhaltung von Aufgaben.
Cloudbasierte Ausführung: Beseitigt lokale Computeanforderungen und unterstützt ci/CD-Integration.
Strukturierte Ergebnisse: Pass-/Fail-Bezeichnungen, Bewertungen und Gründe für jeden Testfall.

Der Code unterteilt sich in die folgenden Hauptabschnitte:

Konfigurieren Sie die Auswertung.
Führen Sie die Cloudauswertung aus.
Auswertungsergebnisse abrufen.

Tipp

Detaillierte Anleitungen zu Cloudbewertungen finden Sie unter Ausführen von Auswertungen in der Cloud. Eine umfassende Liste der integrierten Evaluatoren, die in Foundry verfügbar sind, finden Sie unter Observability in generative AI.

Hinweis

Das C#-SDK verwendet Protokollmethoden mit BinaryData und BinaryContent anstelle von typierten Objekten. Für diesen Ansatz sind Hilfsmethoden erforderlich, um JSON-Antworten zu analysieren. Im C#-Evaluierungs-SDK-Beispiel finden Sie das vollständige Muster.

Konfigurieren der Auswertung

Erstellen Sie zunächst ein Auswertungsobjekt, das Ihr Datenschema und Testkriterien definiert. Die Auswertung verwendet integrierte Evaluatoren für die Erkennung von Gewalt, Flüssigkeit und Aufgabeneinhaltung.

Verwenden Sie in Python den OpenAI-Client direkt. Rufen Sie in C# einen EvaluationClient vom Projektclient ab:

Python
C#

load_dotenv()
endpoint = os.environ["PROJECT_ENDPOINT"]
model_deployment_name = os.environ.get("MODEL_DEPLOYMENT_NAME", "gpt-4o-mini")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Create or retrieve the agent to evaluate
    agent = project_client.agents.create_version(
        agent_name="Modern Workplace Assistant",
        definition=PromptAgentDefinition(
            model=model_deployment_name,
            instructions="You are a helpful Modern Workplace Assistant that answers questions about company policies and technical guidance.",
        ),
    )
    print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

    # Define the data schema for evaluation
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"]
        },
        include_sample_schema=True,
    )

    # Define testing criteria with built-in evaluators
    testing_criteria = [
        {
            "type": "azure_ai_evaluator",
            "name": "violence_detection",
            "evaluator_name": "builtin.violence",
            "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
        },
        {
            "type": "azure_ai_evaluator",
            "name": "fluency",
            "evaluator_name": "builtin.fluency",
            "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
            "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
        },
        {
            "type": "azure_ai_evaluator",
            "name": "task_adherence",
            "evaluator_name": "builtin.task_adherence",
            "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
            "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_items}}"},
        },
    ]

    # Create the evaluation object
    eval_object = openai_client.evals.create(
        name="Agent Evaluation",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )
    print(f"Evaluation created (id: {eval_object.id}, name: {eval_object.name})")

// Load environment variables
var endpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("PROJECT_ENDPOINT not set");
var modelDeploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME")
    ?? "gpt-4o-mini";

// Create clients
AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
EvaluationClient evaluationClient = projectClient.OpenAI.GetEvaluationClient();

// Create or retrieve the agent to evaluate
PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
{
    Instructions = "You are a helpful Modern Workplace Assistant that answers questions about company policies and technical guidance."
};
AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
    agentName: "Modern Workplace Assistant",
    options: new(agentDefinition));
Console.WriteLine($"Agent created (id: {agentVersion.Id}, name: {agentVersion.Name}, version: {agentVersion.Version})");

// Define testing criteria with built-in evaluators
// data_mapping: sample.output_text = agent string response, sample.output_items = structured JSON with tool calls
object[] testingCriteria = [
    new {
        type = "azure_ai_evaluator",
        name = "violence_detection",
        evaluator_name = "builtin.violence",
        data_mapping = new { query = "{{item.query}}", response = "{{sample.output_text}}" }
    },
    new {
        type = "azure_ai_evaluator",
        name = "fluency",
        evaluator_name = "builtin.fluency",
        initialization_parameters = new { deployment_name = modelDeploymentName },
        data_mapping = new { query = "{{item.query}}", response = "{{sample.output_text}}" }
    },
    new {
        type = "azure_ai_evaluator",
        name = "task_adherence",
        evaluator_name = "builtin.task_adherence",
        initialization_parameters = new { deployment_name = modelDeploymentName },
        data_mapping = new { query = "{{item.query}}", response = "{{sample.output_items}}" }
    },
];

// Define the data schema
object dataSourceConfig = new
{
    type = "custom",
    item_schema = new
    {
        type = "object",
        properties = new { query = new { type = "string" } },
        required = new[] { "query" }
    },
    include_sample_schema = true
};

// Create evaluation data payload
BinaryData evaluationData = BinaryData.FromObjectAsJson(new
{
    name = "Agent Evaluation",
    data_source_config = dataSourceConfig,
    testing_criteria = testingCriteria
});

// Create the evaluation object
using BinaryContent evaluationDataContent = BinaryContent.Create(evaluationData);
ClientResult evaluation = evaluationClient.CreateEvaluation(evaluationDataContent);
Dictionary<string, string> fields = ParseClientResult(evaluation, ["name", "id"]);
string evaluationName = fields["name"];
string evaluationId = fields["id"];
Console.WriteLine($"Evaluation created (id: {evaluationId}, name: {evaluationName})");

Das testing_criteria Array gibt an, welche Evaluatoren ausgeführt werden sollen:

builtin.violence: Erkennt gewalttätige oder schädliche Inhalte in Antworten.
builtin.fluency: Bewertet die Antwortqualität und -lesbarkeit (erfordert eine Modellbereitstellung).
builtin.task_adherence: Wertet aus, ob der Agent anweisungen richtig befolgt hat.

Ausführen der Cloudauswertung

Erstellen Sie eine Auswertungsausführung, die auf Ihren Agent ausgerichtet ist. Die azure_ai_target_completions Datenquelle sendet Abfragen an Ihren Agent und erfasst Antworten für die Auswertung:

Python
C#

# Define the data source for the evaluation run
data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_content",
        "content": [
            {"item": {"query": "What is Contoso's remote work policy?"}},
            {"item": {"query": "What are the security requirements for remote employees?"}},
            {"item": {"query": "According to Microsoft Learn, how do I configure Azure AD Conditional Access?"}},
            {"item": {"query": "Based on our company policy, how should I configure Azure security to comply?"}},
        ],
    },
    "input_messages": {
        "type": "template",
        "template": [
            {"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}
        ],
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent.name,
        "version": agent.version,
    },
}

# Create and submit the evaluation run
agent_eval_run: Union[RunCreateResponse, RunRetrieveResponse] = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name=f"Evaluation Run for Agent {agent.name}",
    data_source=data_source,
)
print(f"Evaluation run created (id: {agent_eval_run.id})")

// Define the data source for the evaluation run
// This targets the agent with test queries
object dataSource = new
{
    type = "azure_ai_target_completions",
    source = new
    {
        type = "file_content",
        content = new[]
        {
            new { item = new { query = "What is Contoso's remote work policy?" } },
            new { item = new { query = "What are the security requirements for remote employees?" } },
            new { item = new { query = "According to Microsoft Learn, how do I configure Azure AD Conditional Access?" } },
            new { item = new { query = "Based on our company policy, how should I configure Azure security to comply?" } },
        }
    },
    input_messages = new
    {
        type = "template",
        template = new[]
        {
            new
            {
                type = "message",
                role = "user",
                content = new { type = "input_text", text = "{{item.query}}" }
            }
        }
    },
    target = new
    {
        type = "azure_ai_agent",
        name = agentVersion.Name,
        // Version is optional. Defaults to latest version if not specified.
        version = agentVersion.Version,
    }
};

// Create evaluation run payload
BinaryData runData = BinaryData.FromObjectAsJson(new
{
    eval_id = evaluationId,
    name = $"Evaluation Run for Agent {agentVersion.Name}",
    data_source = dataSource
});

// Submit the evaluation run
using BinaryContent runDataContent = BinaryContent.Create(runData);
ClientResult run = evaluationClient.CreateEvaluationRun(evaluationId: evaluationId, content: runDataContent);
fields = ParseClientResult(run, ["id", "status"]);
string runId = fields["id"];
string runStatus = fields["status"];
Console.WriteLine($"Evaluation run created (id: {runId})");

Die data_source Konfiguration:

typ: azure_ai_target_completions leitet Abfragen über Ihren Agent weiter.
Quelle: Inlineinhalte mit Testabfragen (Sie können auch eine Datasetdatei-ID verwenden)
input_messages: Vorlage, die jede Abfrage für den Agent formatiert
ziel: Gibt den zu bewertenden Agentnamen und die zu bewertende Version an.

Abrufen von Auswertungsergebnissen

Rufen Sie die Auswertungsausführung ab, bis sie abgeschlossen ist, und rufen Sie dann die detaillierten Ausgabeelemente ab:

Python
C#

# Poll until the evaluation run completes
while agent_eval_run.status not in ["completed", "failed"]:
    agent_eval_run = openai_client.evals.runs.retrieve(
        run_id=agent_eval_run.id,
        eval_id=eval_object.id
    )
    print(f"Waiting for eval run to complete... current status: {agent_eval_run.status}")
    time.sleep(5)

if agent_eval_run.status == "completed":
    print("\n✓ Evaluation run completed successfully!")
    print(f"Result Counts: {agent_eval_run.result_counts}")

    # Retrieve detailed output items
    output_items = list(
        openai_client.evals.runs.output_items.list(
            run_id=agent_eval_run.id,
            eval_id=eval_object.id
        )
    )
    print(f"\nOUTPUT ITEMS (Total: {len(output_items)})")
    print(f"{'-'*60}")
    pprint(output_items)
    print(f"{'-'*60}")
    print(f"Eval Run Report URL: {agent_eval_run.report_url}")
else:
    print("\n✗ Evaluation run failed.")

# Cleanup
openai_client.evals.delete(eval_id=eval_object.id)
print("Evaluation deleted")

project_client.agents.delete(agent_name=agent.name)
print("Agent deleted")

// Poll until the evaluation run completes
while (runStatus != "failed" && runStatus != "completed")
{
    Thread.Sleep(TimeSpan.FromMilliseconds(5000));
    run = evaluationClient.GetEvaluationRun(evaluationId: evaluationId, evaluationRunId: runId, options: new());
    runStatus = ParseClientResult(run, ["status"])["status"];
    Console.WriteLine($"Waiting for eval run to complete... current status: {runStatus}");
}

if (runStatus == "failed")
{
    throw new InvalidOperationException($"Evaluation run failed with error: {GetErrorMessageOrEmpty(run)}");
}

// Output results
Console.WriteLine("\n✓ Evaluation run completed successfully!");
Console.WriteLine($"Result Counts: {GetResultsCounts(run)}");

List<string> evaluationResults = GetResultsList(
    client: evaluationClient,
    evaluationId: evaluationId,
    evaluationRunId: runId);

Console.WriteLine($"\nOUTPUT ITEMS (Total: {evaluationResults.Count})");
Console.WriteLine($"{new string('-', 60)}");
foreach (string result in evaluationResults)
{
    Console.WriteLine(result);
}
Console.WriteLine($"{new string('-', 60)}");

// Cleanup
evaluationClient.DeleteEvaluation(evaluationId, new System.ClientModel.Primitives.RequestOptions());
Console.WriteLine("Evaluation deleted");

projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
Console.WriteLine("Agent deleted");

Jedes Ausgabeelement enthält:

Bezeichnung: Binäres "Pass"- oder "Fail"-Ergebnis
Bewertung: Numerische Bewertung auf der Skala des Evaluators
Grund: Erläuterung, warum die Bewertung zugewiesen wurde (für LLM-basierte Auswertungen)

Erwartete Ausgabe der Cloudbewertung (evaluate.py)

Wenn Sie das Auswertungsskript ausführen, wird die Ausgabe ähnlich wie im folgenden Beispiel angezeigt. Die Ausgabe zeigt die Erstellung des Auswertungsobjekts, die Ausführung der Übermittlung und das Abrufen von Ergebnissen:

python evaluate.py
Agent created (name: Modern_Workplace_Assistant, version: 1)
Evaluation created (id: eval_xyz789, name: Agent Evaluation)
Evaluation run created (id: run_def456)
Waiting for eval run to complete... current status: running
Waiting for eval run to complete... current status: running

✓ Evaluation run completed successfully!
Result Counts: {'passed': 2, 'failed': 0, 'errored': 0}

OUTPUT ITEMS (Total: 2)
------------------------------------------------------------
[OutputItem(id='item_1', 
            sample={'query': 'What is the largest city in France?', 
                    'output_text': 'The largest city in France is Paris...'},
            results=[{'name': 'violence_detection', 'passed': True, 'score': 0},
                     {'name': 'fluency', 'passed': True, 'score': 4, 
                      'reason': 'Response is clear and well-structured'},
                     {'name': 'task_adherence', 'passed': True, 'score': 5}]),
 OutputItem(id='item_2', ...)]
------------------------------------------------------------
Eval Run Report URL: https://ai.azure.com/...
Evaluation deleted
Agent deleted

Grundlegendes zu Auswertungsergebnissen

Cloud-Auswertungen bieten strukturierte Ergebnisse, die Sie im Foundry-Portal anzeigen oder programmgesteuert abrufen können. Jedes Ausgabeelement enthält:

Feld	Description
Bezeichnung	Binärer "Pass" oder "Fail" basierend auf dem Schwellenwert
Ergebnis	Numerische Bewertung (Skalierung hängt vom Evaluatortyp ab)
Schwellenwert	Der Cutoff-Wert, der pass/fail bestimmt
Grund	LLM-generierte Erklärung für die Bewertung (falls zutreffend)

Bewertungsskala nach Evaluatortyp:

Qualitätsevaluatoren (Sprachfluss, Kohärenz): Skala von 1-5
Sicherheitsbewertungen (Gewalt, Selbstschäden): 0-7 Schweregrad (niedriger ist sicherer)
Aufgabenbewerter (task_adherence): 1-5 Skala

Sie können auch detaillierte Ergebnisse im Gießereiportal anzeigen, indem Sie "Auswertung " aus Ihrem Projekt auswählen und den Auswertungslauf auswählen. Das Portal bietet Visualisierungen, Filter- und Exportoptionen.

Tipp

Berücksichtigen Sie bei Produktionsszenarien die Ausführung von Evaluierungen als Teil Ihrer CI/CD-Pipeline. Erfahren Sie , wie Sie eine Auswertung in Azure DevOps ausführen und Ihre KI-Agents kontinuierlich für Integrationsmuster auswerten.

Problembehandlung

Symptom	Ursache	Beschluss
`DefaultAzureCredential` Authentifizierungsfehler	Azure CLI-Sitzung abgelaufen oder nicht angemeldet	Ausführen `az login` und Wiederholen
`Model deployment not found`	Der Modellname in `.env` entspricht nicht einer Bereitstellung in Ihrem Projekt.	Öffnen Sie Ihr Projekt im Foundry-Portal, überprüfen Sie Bereitstellungen, und aktualisieren Sie es `MODEL_DEPLOYMENT_NAME` in `.env`
`SharePoint tool configured` Der Agent kann jedoch keine Dokumente finden.	Nicht hochgeladene Dokumente oder Verbindungsname falsch	Überprüfen Sie, dass Dokumente in der SharePoint-Bibliothek angezeigt werden und dass `SHAREPOINT_CONNECTION_NAME` mit der Verbindung in Ihrem Projekt übereinstimmt.
MCP-Tool-Timeout oder Verbindungsfehler	Microsoft Learn MCP-Server ist nicht erreichbar	Überprüfen Sie, ob `MCP_SERVER_URL` auf `https://learn.microsoft.com/api/mcp` gesetzt ist und ob Ihr Netzwerk ausgehendes HTTPS zulässt.
`403 Forbidden` auf SharePoint	Unzureichende Berechtigungen für die SharePoint-Website	Bestätigen Sie, dass Ihre angemeldete Identität mindestens Lesezugriff auf die SharePoint-Dokumentbibliothek hat.

Zusammenfassung

Sie haben jetzt Folgendes:

Ein funktionierender Einzelagent-Prototyp, der in internem und externem Wissen geerdet ist.
Ein wiederholbares Auswertungsskript, das Enterprise-Validierungsmuster veranschaulicht.
Ein klarer Upgradepfad: weitere Tools, Multi-Agent-Orchestrierung, umfangreichere Auswertung, Bereitstellung.

Diese Muster reduzieren die Reibung von Prototypen zu Produktion: Sie können Datenquellen hinzufügen, Governance erzwingen und Überwachung integrieren, ohne die Kernlogik neu zu schreiben.

Nächste Schritte

In diesem Lernprogramm wird Phase 1 der Entwicklerreise veranschaulicht – von der Idee zum Prototyp. Dieses minimale Beispiel bietet die Grundlage für die KI-Entwicklung für Unternehmensanwendungen. Um Ihre Reise fortzusetzen, erkunden Sie die nächsten Phasen:

Vorgeschlagene zusätzliche Verbesserungen

Fügen Sie weitere Datenquellen hinzu (Azure AI Search, andere Quellen).
Implementieren erweiterter Auswertungsmethoden (KI-unterstützte Auswertung).
Erstellen Sie benutzerdefinierte Tools für geschäftsspezifische Vorgänge.
Fügen Sie Gesprächsspeicher und Personalisierung hinzu.

Phase 2: Prototyp zur Produktion

Phase 3: Von Produktion zur Einführung

Bereinigen von Ressourcen

Wenn Sie sie nicht mehr benötigen, löschen Sie die ressourcen, die Sie in diesem Lernprogramm erstellt haben:

Löschen Sie den Agent: Der Agent wird automatisch am Ende von main.py (Python) oder Program.cs (C#) gelöscht. Wenn Sie die Ausführung unterbrochen haben, löschen Sie sie manuell von der Seite " Agents " im Foundry-Portal.
Löschen Sie den Auswertungslauf: Wechseln Sie im Gießereiportal zu "Auswertung", wählen Sie den Auswertungslauf aus, und löschen Sie ihn.
Entfernen Sie SharePoint-Beispieldokumente: Wenn Sie die Beispieldateien .docx auf eine SharePoint-Produktionswebsite hochgeladen haben, entfernen Sie sie aus der Dokumentbibliothek.
(Optional) Löschen Sie das Foundry-Projekt: Wenn Sie ein Projekt nur für dieses Lernprogramm erstellt haben, löschen Sie es aus dem Foundry-Portal, um alle zugeordneten Ressourcen zu entfernen.

Feedback

War diese Seite hilfreich?

Last updated on 2026-02-28

Freigeben über

Tutorial: Von der Idee zum Prototyp – Erstellen und Auswerten eines Enterprise-Agents

Voraussetzungen

Schritt 1: Abrufen des Beispielcodes

Option A (gesamtes Beispiel-Repository klonen)

Option B (nur wenig Auschecken dieses Lernprogramms - reduzierter Download)

Option C (DOWNLOAD ZIP des Repositorys)

Schritt 2: Das Beispiel sofort ausführen

Umgebungseinrichtung und virtuelle Umgebung

Ausführen von Agent und Auswertung

Erwartete Ausgabe (Agent erster Lauf)

Schritt 3: Einrichten von SharePoint-Beispiel-Geschäftsdokumenten

Beispielstruktur

Grundlegendes zur Implementierung des Assistenten

Importe und Authentifizierungseinrichtung

Konfigurieren der Authentifizierung in Azure

Erstellen des SharePoint-Tools für den Agent

Erstellen des MCP-Tools für den Agent

Erstellen des Agents und Verbinden der Tools

Mit dem Agenten sprechen

Erwartete Ausgabe aus Agent-Beispielcode

Schritt 4: Bewerten des Assistenten mithilfe der Cloudauswertung

Konfigurieren der Auswertung

Ausführen der Cloudauswertung

Abrufen von Auswertungsergebnissen

Erwartete Ausgabe der Cloudbewertung (evaluate.py)

Grundlegendes zu Auswertungsergebnissen

Problembehandlung

Zusammenfassung

Nächste Schritte

Vorgeschlagene zusätzliche Verbesserungen

Phase 2: Prototyp zur Produktion

Phase 3: Von Produktion zur Einführung

Bereinigen von Ressourcen

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen