Poradnik: Od pomysłu do prototypu — budowanie i ocenianie agenta firmowego

Ten samouczek obejmuje pierwszy etap ścieżki rozwoju dewelopera w Microsoft Foundry: od początkowego pomysłu do działającego prototypu. Tworzysz modernistycznego asystenta miejsca pracy który łączy wewnętrzną wiedzę firmową z zewnętrznymi wskazówkami technicznymi przy użyciu zestawu SDK Microsoft Foundry.

Scenariusz biznesowy: stwórz asystenta AI, który pomaga pracownikom poprzez integrację:

  • Zasady firmy (z dokumentów SharePoint)
  • Przewodnik po wdrażaniu technicznym (z Microsoft Learn przez MCP)
  • Kompletne rozwiązania (łączenie obu źródeł na potrzeby implementacji biznesowej)
  • Ocena zbiorcza w celu zweryfikowania efektywności agenta w realistycznych scenariuszach biznesowych

Wynik samouczka: na końcu masz uruchomionego nowoczesnego asystenta miejsca pracy, który może odpowiedzieć na pytania dotyczące zasad, technicznych i połączonych implementacji; powtarzalny skrypt oceny wsadowej; i jasne punkty rozszerzenia (inne narzędzia, wzorce wielu agentów, bogatsza ocena).

Wykonasz:

  • Tworzenie nowoczesnego asystenta miejsca pracy przy użyciu integracji z platformą SharePoint i aplikacją MCP.
  • Prezentacja rzeczywistych scenariuszy biznesowych łączących wiedzę wewnętrzną i zewnętrzną.
  • Implementowanie niezawodnej obsługi błędów i łagodnego obniżenia wydajności.
  • Tworzenie struktury oceny na potrzeby testowania ukierunkowanego na działalność biznesową.
  • Przygotuj podstawy dla zarządzania i wdrożenia produkcji.

Ten minimalny przykład przedstawia wzorce gotowe do użycia w przedsiębiorstwie z realistycznymi scenariuszami biznesowymi.

Ważne

Kod w tym artykule używa pakietów, które są obecnie w wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Wygólne warunki użytkowania Microsoft Azure Previews.

Wymagania wstępne

  • Subskrypcja Azure. Jeśli go nie masz, utwórz go bezpłatnie.
  • Azure CLI 2.67.0 lub nowszej, uwierzytelnione za pomocą az login (sprawdź az version)
  • Projekt Foundry posiadający wdrożony model (na przykład ). Jeśli go nie masz: Utwórz projekt , a następnie wdróż model (zobacz omówienie modelu: Wykaz modeli).
  • Python 3.10 lub nowszy
  • zestaw SDK .NET w wersji 8.0 lub nowszej (dla przykładu języka C#)
  • Połączenie SharePoint skonfigurowane w projekcie.
    • Narzędzie SharePoint jest w wersji zapoznawczej i wymaga tożsamości delegowanej zalogowanego użytkownika. Uwierzytelnianie tylko dla aplikacji i jednostki usługi nie jest obsługiwane.
    • Deweloperzy i użytkownicy końcowi potrzebują licencji Microsoft 365 Copilot lub włączonego dostępu rozliczanego zgodnie z użyciem, roli Foundry User w projekcie oraz co najmniej uprawnienia Odczyt do docelowej witryny SharePoint.
    • Witryna SharePoint i projekt Foundry muszą znajdować się w tej samej dzierżawie Microsoft Entra. Agent może użyć jednego narzędzia SharePoint. Aby uzyskać instrukcje dotyczące konfiguracji, zobacz Korzystanie z narzędzia SharePoint.
  • Rola Użytkownika usługi Foundry w celu utworzenia i przetestowania agenta. Jeśli utworzysz połączenie projektu do uwierzytelniania serwera MCP, musisz również mieć rolę Menedżer projektu Foundry.
  • (Opcjonalnie) Narzędzie Git zainstalowane do klonowania przykładowego repozytorium

Ważne

Wersje zestawu SDK i struktura przykładowego repozytorium mogą ulec zmianie po opublikowaniu tego artykułu. Przed rozpoczęciem sprawdź przykładowe repozytorium README , aby uzyskać najnowsze instrukcje konfiguracji, wymagane wersje pakietów i konfigurację środowiska. Jeśli wersja, do których odwołuje się ten samouczek, nie jest dostępna w PyPI lub NuGet użyj najnowszej opublikowanej wersji.

Pobieranie przykładowego kodu

Zamiast nawigowania po dużym drzewie repozytorium, użyj jednego z następujących podejść:

Opcja A (klonowanie całego repozytorium przykładów)

Wskazówka

Kod używa Azure AI Projects 2.x i jest niezgodny z projektami sztucznej inteligencji Azure 1.x. Zobacz dokumentację Foundry (klasyczną) dla wersji Azure AI Projects 1.x.

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

Opcja B (sparse checkout tylko tego samouczka – skrócone pobieranie)

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

Opcja C (Pobierz plik ZIP z repozytorium)

Pobierz ZIP repozytorium, wyodrębnij go do lokalnego systemu/komputera i przejdź do folderu tutorial.

Ważne

W przypadku wdrożenia produkcyjnego użyj autonomicznego repozytorium. W tym samouczku korzystamy ze wspólnego repozytorium przykładów. Rozrzedliwe wyewidencjonowania minimalizuje hałas lokalny.

Pobierz teraz kod Python

Po wyodrębnieniu pliku ZIP przejdź do strony samples/python/enterprise-agent-tutorial/1-idea-to-prototype.

Minimalna struktura zawiera tylko niezbędne pliki:

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

Uruchamianie aplikacji przykładowej

Zacznij od uruchomienia agenta, aby zobaczyć działającą funkcjonalność przed zagłębieniu się w szczegóły implementacji.

Konfiguracja środowiska i środowisko wirtualne

  1. Zainstaluj wymagane środowiska uruchomieniowe języka, narzędzia globalne i rozszerzenia programu VS Code zgodnie z opisem w temacie Przygotowywanie środowiska projektowego.

  2. Sprawdź, czy requirements.txt używa tych opublikowanych wersji pakietów.

    azure-ai-projects>=2.3.0
azure-identity
python-dotenv

Zainstaluj zależności:

python -m pip install -r requirements.txt

Sprawdź, czy instalacja zakończyła się pomyślnie. Widzisz Successfully installed azure-ai-projects-... (Python) lub Restore completed (.NET) bez żadnych błędów.

  1. Znajdź punkt końcowy projektu na ekranie powitalnym projektu.

    Oświet ekranu powitalnego Microsoft Foundry Models przedstawiający adres URL punktu końcowego i przycisk kopiowania.

  2. Skonfiguruj .env.

    Ustaw wartości środowiska wymagane dla danego języka.

Skopiuj .env.template do .env.

# Foundry configuration
FOUNDRY_PROJECT_ENDPOINT=https://<your-resource>.services.ai.azure.com/api/projects/<your-project>
FOUNDRY_MODEL_NAME=gpt-4o-mini

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

# SharePoint integration (optional - requires a project connection ID)
SHAREPOINT_CONNECTION_ID=/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<foundry-account>/projects/<project>/connections/<connection-name>

Potwierdzenie .env zawiera prawidłowe wartości, otwierając plik i sprawdzając, czy FOUNDRY_PROJECT_ENDPOINT rozpoczyna się od https:// i FOUNDRY_MODEL_NAME pasuje do nazwy wdrożonego modelu w projekcie.

W przypadku integracji z SharePoint ustaw SHAREPOINT_CONNECTION_ID w języku Python na pełny identyfikator połączenia projektu dla tego połączenia. W języku C# ustaw wartość SHAREPOINT_CONNECTION_NAME na nazwę połączenia.

Wskazówka

Aby uzyskać identyfikator dzierżawcy, uruchom:

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

Aby uzyskać punkt końcowy projektu, otwórz projekt w portalu Foundry i skopiuj wyświetloną tam wartość.

Uruchomienie agenta i ewaluacja

python main.py
python evaluate.py

Oczekiwane dane wyjściowe (pierwszy przebieg agenta)

Pomyślne uruchomienie z SharePoint:

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

Łagodna degradacja bez SharePoint.

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

Teraz, gdy masz działającego agenta, w następnych sekcjach wyjaśniono, jak to działa. Nie musisz podejmować żadnych działań podczas czytania tych sekcji — są one przeznaczone do wyjaśnienia.

Konfigurowanie przykładowych dokumentów biznesowych SharePoint

  1. Przejdź do witryny SharePoint (skonfigurowanej w połączeniu).

  2. Utwórz bibliotekę dokumentów "Zasady firmy" (lub użyj istniejącej "Dokumenty").

  3. Przekaż cztery przykładowe dokumenty Word podane w folderze sharepoint-sample-data:

    • remote-work-policy.docx
    • security-guidelines.docx
    • collaboration-standards.docx
    • data-governance-policy.docx

  4. Zanim przejdziesz dalej, sprawdź, czy w bibliotece pojawiają się cztery dokumenty.

Struktura przykładu

📁 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

Omówienie implementacji asystenta

Uwaga

Ta sekcja jest tylko do wglądu — nie jest potrzebne żadne działanie. Wyjaśnia kod, który już uruchomiłeś.

W tej sekcji wyjaśniono podstawowy kod w main.py (Python) lub ModernWorkplaceAssistant/Program.cs (C#). Agent został już uruchomiony. Po przeczytaniu możesz:

  • Dodaj nowe narzędzia do obsługi danych wewnętrznych i zewnętrznych.
  • Rozszerzanie instrukcji dynamicznych.
  • Wprowadzenie orkiestracji systemów wieloagentowych.
  • Zwiększ obserwowalność i diagnostykę.

Kod dzieli się na następujące główne sekcje uporządkowane w miarę ich wyświetlania w pełnym przykładowym kodzie:

  1. Konfigurowanie importu i uwierzytelniania
  2. Konfiguruj uwierzytelnianie Azure
  3. Konfiguruj narzędzie SharePoint
  4. Konfigurowanie narzędzia MCP
  5. Tworzenie agenta i łączenie narzędzi
  6. Rozmowa z agentem

Ważne

Kod w tym artykule używa pakietów, które są obecnie w wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Wygólne warunki użytkowania Microsoft Azure Previews.

Importowanie i konfigurowanie uwierzytelniania

Kod używa kilku bibliotek klienckich z zestawu SDK Microsoft Foundry w celu utworzenia niezawodnego agenta przedsiębiorstwa.

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

Konfigurowanie uwierzytelniania w Azure

Przed utworzeniem agenta skonfiguruj uwierzytelnianie w usłudze Foundry.

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}")

Tworzenie narzędzia SharePoint dla agenta

Agent używa SharePoint i może uzyskiwać dostęp do zasad i procedur firmy przechowywanych tam dokumentów. Skonfiguruj połączenie do SharePoint w kodzie.

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

Tworzenie narzędzia MCP dla agenta

Obsługa narzędzia MCP w zestawie SDK .NET jest obecnie w wersji zapoznawczej.

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

Tworzenie agenta i łączenie narzędzi

Utwórz agenta i połącz narzędzia SharePoint i MCP.

print(f"🛠️  Creating agent with model: {os.environ['FOUNDRY_MODEL_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["FOUNDRY_MODEL_NAME"],
        instructions=instructions,
        tools=tools if tools else None,
    ),
)

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

Rozmowa z agentem

Na koniec zaimplementuj pętlę interaktywną, aby rozmawiać z agentem.

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

Oczekiwane dane wyjściowe z przykładowego kodu agenta

Po uruchomieniu agenta zobaczysz dane wyjściowe podobne do poniższego przykładu. Dane wyjściowe przedstawiają pomyślną konfigurację narzędzia i odpowiedzi agenta na scenariusze biznesowe:

✅ 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 Microsoft Entra 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 Microsoft Entra 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

Oceń asystenta za pomocą oceny wsadowej

Struktura oceny testuje realistyczne scenariusze biznesowe przy użyciu batch evaluation możliwości zestawu MICROSOFT Foundry SDK. Zamiast niestandardowego podejścia lokalnego ten wzorzec używa wbudowanych ewaluatorów (builtin.violence, builtin.fluency, builtin.task_adherence) i interfejsu openai_client.evals API do uruchamiania skalowalnych, powtarzalnych ocen w chmurze.

Ocena Python w chmurze wymaga roli Użytkownika usługi Foundry, wdrożonego modelu GPT obsługującego uzupełnianie czatów oraz regionu obsługującego wybranych ewaluatorów. Przed kontynuowanie przejrzyj obsługiwane regiony .

Ta struktura oceny pokazuje:

  • Celowanie agenta: ocena uruchamia zapytania bezpośrednio względem agenta przy użyciu azure_ai_target_completions.
  • Wbudowane ewaluatory: bezpieczeństwo (wykrywanie przemocy), jakość (płynność) i metryki zgodności z zadaniami.
  • Wykonywanie w chmurze: eliminuje lokalne wymagania obliczeniowe i wspiera integrację CI/CD.
  • Wyniki ustrukturyzowane: etykiety z powodzeniem/niepowodzeniem, wyniki i rozumowanie dla każdego przypadku testowego.

Kod dzieli się na następujące główne sekcje:

  1. Skonfiguruj ocenę.
  2. Uruchom ewaluację wsadową.
  3. Pobieranie wyników oceny.

Wskazówka

Aby uzyskać bardziej szczegółowe wskazówki dotyczące ewaluacji wsadowych, zobacz Uruchamianie ewaluacji w chmurze. Aby znaleźć kompleksową listę wbudowanych ewaluatorów dostępnych w narzędziu Foundry, zobacz Obserwowanie w generowaniu sztucznej inteligencji.

Uwaga

Przykład C# używa lokalnego podejścia do oceny wsadowej z ProjectResponsesClient zamiast API w chmurze openai_client.evals używanego w Pythonie. Wysyła zapytania do agenta, sprawdza odpowiedzi względem oczekiwanych słów kluczowych i zapisuje wyniki w pliku evaluation_results.json. Zobacz przykład C# Evaluations SDK dla wzorców oceny chmury w języku C#.

Konfigurowanie oceny

Najpierw utwórz obiekt oceny, który definiuje schemat danych i kryteria testowania. Ocena używa wbudowanych ewaluatorów do wykrywania przemocy, biegłości i przestrzegania zadań.

W Python użyj klienta OpenAI bezpośrednio. W języku C#pobierz element EvaluationClient z klienta projektu:

load_dotenv()
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ.get("FOUNDRY_MODEL_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})")

Tablica testing_criteria określa, którzy ewaluatorzy mają być uruchamiani:

  • builtin.violence: Wykrywa brutalną lub szkodliwą zawartość w odpowiedziach.
  • builtin.fluency: Ocenia jakość i czytelność odpowiedzi (wymaga wdrożenia modelu).
  • builtin.task_adherence: Ocenia, czy agent poprawnie postępował zgodnie z instrukcjami.

Uruchom ocenę wsadową

Utwórz proces oceny ukierunkowany na agenta. Źródło azure_ai_target_completions danych wysyła zapytania do agenta i przechwytuje odpowiedzi na potrzeby oceny:

# 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})")

Konfiguracja data_source :

  • typ: azure_ai_target_completions kieruje zapytania za pośrednictwem agenta
  • źródło: zawartość śródliniowa z zapytaniami testowymi (można również użyć identyfikatora pliku zestawu danych)
  • input_messages: szablon, który formatuje każde zapytanie dla agenta
  • target: określa nazwę i wersję agenta do oceny

Pobieranie wyników oceny

Sonduj przebieg oceny do momentu zakończenia, a następnie pobierz szczegółowe elementy wyjściowe.

# 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")

Zanim przejrzysz poszczególne elementy wyjściowe, upewnij się, że uruchomienie oceny zostało zakończone i Result Counts wyświetla errored: 0. Jeśli przebieg zakończy się niepowodzeniem, sprawdź swoją rolę, wybrany region, wdrożony model i pomoc techniczną ewaluatora.

Każdy element wyjściowy zawiera następujące elementy:

  • Etykieta: binarny wynik powodzenia lub niepowodzenia
  • Wynik: Wynik liczbowy w skali ewaluatora
  • Przyczyna: Wyjaśnienie, dlaczego ocena została przypisana (dla ewaluatorów opartych na usłudze LLM)

Oczekiwane dane wyjściowe z oceny wsadowej (evaluate.py)

Po uruchomieniu skryptu oceny zobaczysz dane wyjściowe podobne do poniższego przykładu. Dane wyjściowe przedstawiają tworzenie obiektu oceny, przesyłanie zadań i przechwytywanie wyników.

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

Informacje o wynikach oceny

Ewaluacje wsadowe zapewniają ustrukturyzowane wyniki, które można wyświetlić w portalu Foundry lub pobrać za pomocą programowania. Każdy element wyjściowy zawiera następujące elementy:

Pole Opis
Etykiety Binarne "pass" lub "fail" na podstawie progu
Ocena Wynik liczbowy (skala zależy od typu ewaluatora)
Próg Wartość graniczna określająca zaliczenie/niezaliczenie
Powodu Wyjaśnienie wygenerowane przez LLM dla wyniku, jeśli dotyczy

Skale ocen w zależności od typu ewaluatora:

  • Ewaluatory jakości (płynność, spójność): 1–5 skali
  • Ewaluatorzy bezpieczeństwa (przemoc, samookaleczenia): 0-7 skala ważności (niższa jest bezpieczniejsza)
  • Ocena zadań (task_adherence): 1–5 skala

Szczegółowe wyniki można również wyświetlić w portalu Foundry, wybierając pozycję Ocena w projekcie i wybierając przebieg oceny. Portal udostępnia wizualizacje, filtrowanie i opcje eksportowania.

Wskazówka

W przypadku scenariuszy produkcyjnych rozważ uruchomienie ewaluacji w ramach potoku CI/CD. Zobacz Jak uruchomić ocenę w Azure DevOps i Ciągle oceniaj agentów sztucznej inteligencji na potrzeby wzorców integracji.

Rozwiązywanie problemów

Objaw Przyczyna Rozdzielczość
DefaultAzureCredential błąd uwierzytelniania sesja Azure CLI wygasła lub nie została zalogowana Uruchom az login i spróbuj ponownie
Model deployment not found Nazwa modelu w programie .env nie jest zgodna z wdrożeniem w projekcie Otwórz projekt w portalu Foundry, sprawdź Wdrożenia i zaktualizuj FOUNDRY_MODEL_NAME w .env
SharePoint integracja została pominięta Zmienna środowiskowa SharePoint nie jest ustawiona W Pythonie ustaw SHAREPOINT_CONNECTION_ID na pełny identyfikator połączenia projektu. W języku C# ustaw SHAREPOINT_CONNECTION_NAME na nazwę połączenia.
SharePoint tool configured, ale agent nie może znaleźć dokumentów Dokumenty nie są przekazywane, połączenie jest nieprawidłowe lub zalogowany użytkownik nie ma dostępu Sprawdź, czy dokumenty znajdują się w skonfigurowanej bibliotece, czy połączenie jest skierowane do tej biblioteki oraz czy zalogowany użytkownik ma uprawnienia odczytu. Użyj delegowanego uwierzytelniania użytkownika w tej samej dzierżawie Microsoft Entra co projekt Foundry.
Limit czasu narzędzia MCP lub błąd połączenia Serwer Microsoft Learn MCP jest niedostępny. Sprawdź, czy MCP_SERVER_URL jest ustawione na https://learn.microsoft.com/api/mcp i czy sieć zezwala na połączenia HTTPS wychodzące
Nie można utworzyć połączenia projektu MCP Konto nie ma wymaganej roli projektu Przypisz rolę Menedżer usługi Foundry Project, aby utworzyć połączenie, a następnie ponów próbę.
Nie można uruchomić oceny w chmurze lub ewaluator nie jest obsługiwany Kombinacja regionu projektu, modelu lub ewaluatora nie jest obsługiwana Sprawdź, czy region projektu obsługuje ewaluatora i czy wdrożony model GPT obsługuje uzupełnianie czatów.
403 Forbidden na SharePoint Niewystarczające uprawnienia w witrynie SharePoint Upewnij się, że konto, na które jesteś zalogowany(-a), ma co najmniej uprawnienia Odczyt do biblioteki dokumentów SharePoint oraz rolę Foundry User w projekcie.

Krótki opis

Masz teraz:

  • Działający prototyp agenta pojedynczego oparty na wewnętrznej i zewnętrznej wiedzy.
  • Powtarzalny skrypt oceny demonstrujący wzorce weryfikacji przedsiębiorstwa.
  • Wyraźna ścieżka uaktualnienia: więcej narzędzi, orkiestracja wielu agentów, bogatsza ocena, wdrożenie.

Te wzorce zmniejszają problemy związane z tworzeniem prototypów: możesz dodawać źródła danych, wymuszać nadzór i integrować monitorowanie bez ponownego pisania podstawowej logiki.

Następne kroki

W tym samouczku przedstawiono Etap 1 podróży dewelopera — od pomysłu do prototypu. Ten minimalny przykład stanowi podstawę do opracowywania sztucznej inteligencji w przedsiębiorstwie. Aby kontynuować podróż, zapoznaj się z kolejnymi etapami:

Sugerowane dodatkowe ulepszenia

Etap 2. Prototyp do środowiska produkcyjnego

Etap 3. Wdrażanie w środowisku produkcyjnym

Czyszczenie zasobów

Gdy nie są już potrzebne, usuń zasoby utworzone w tym samouczku:

  1. Usuń agenta: Agent zostanie automatycznie usunięty na końcu main.py (Python) lub Program.cs (C#). Jeśli uruchomienie zostało przerwane, usuń je ręcznie ze strony Agenci w portalu Foundry.
  2. Usuń przebieg oceny: w portalu Foundry przejdź do pozycji Ocena, wybierz przebieg oceny i usuń go.
  3. Usuń przykładowe dokumenty SharePoint: Jeśli załadowano przykładowe pliki .docx do produkcyjnej witryny SharePoint, usuń je z biblioteki dokumentów.
  4. (Opcjonalnie) Usuń projekt Foundry: jeśli utworzono projekt tylko dla tego samouczka, usuń go z portalu Foundry, aby usunąć wszystkie skojarzone zasoby.

Powiązana zawartość

  • Last updated on