Udostępnij przez

Samouczek: Od pomysłu do prototypu — budowanie i ocenianie agenta przedsiębiorstwa

W tym przewodniku omówiono pierwszy etap podróży dewelopera Microsoft Foundry: od początkowej idei do działającego prototypu. Utworzysz nowoczesnego asystenta w miejscu pracy , który łączy wewnętrzną wiedzę firmy z zewnętrznymi wskazówkami technicznymi przy użyciu zestawu Microsoft Foundry SDK.

Scenariusz biznesowy: Stwórz asystenta sztucznej inteligencji, który pomoże pracownikom poprzez połączenie:

  • Zasady firmy (z dokumentów programu SharePoint)
  • Wskazówki dotyczące implementacji technicznej (z witryny Microsoft Learn za pośrednictwem mcp)
  • Kompletne rozwiązania (łączenie obu źródeł na potrzeby implementacji biznesowej)
  • Ocena usługi Batch w celu zweryfikowania wydajności agenta w realistycznych scenariuszach biznesowych

Wynik samouczka: Pod koniec masz działającego nowoczesnego asystenta miejsca pracy, który może odpowiadać na pytania dotyczące polityki, zagadnień technicznych oraz w zakresie łączonych implementacji; powtarzalny skrypt do oceny wsadowej oraz jasno określone punkty rozszerzeń (inne narzędzia, wzorce wieloagentowe, bogatsza ewaluacja).

Wykonasz:

  • Tworzenie nowoczesnego asystenta miejsca pracy za pomocą integracji z programem SharePoint i aplikacją MCP.
  • Prezentacja rzeczywistych scenariuszy biznesowych łączących wiedzę wewnętrzną i zewnętrzną.
  • Implementowanie niezawodnej obsługi błędów i łagodnej degradacji.
  • Tworzenie struktury oceny na potrzeby testowania ukierunkowanego na działalność biznesową.
  • Przygotuj podstawy do wdrożenia zarządzania i wdrożenia produkcyjnego.

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

Ważna

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 Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Wymagania wstępne

  • Subskrypcja platformy Azure. Jeśli go nie masz, utwórz go bezpłatnie.

  • Interfejs wiersza polecenia platformy Azure w wersji 2.67.0 lub nowszej, uwierzytelniony za pomocą az login (sprawdź az version)

  • Projekt Foundry z wdrożonym modelem (na przykład gpt-4o-mini). Jeśli go nie masz: Utwórz projekt , a następnie wdróż model (zobacz omówienie modelu: Wykaz modeli).

  • Środowisko Python w wersji 3.10 lub nowszej

  • Zestaw .NET SDK 8.0 lub nowszy (dla przykładu języka C#)

  • Połączenie programu SharePoint skonfigurowane w projekcie (dokumentacja narzędzia programu SharePoint)

    Uwaga / Notatka

    Aby skonfigurować projekt Foundry na potrzeby łączności programu SharePoint, zobacz dokumentację narzędzia programu SharePoint.

  • (Opcjonalnie) Narzędzie Git zainstalowane do klonowania przykładowego repozytorium

Krok 1. Pobieranie przykładowego kodu

Zamiast nawigowania po dużym drzewie repozytorium, korzystaj z jednego z poniższych rozwiązań.

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

Wskazówka

Kod używa usługi Azure AI Projects 2.x i jest niezgodny z usługą Azure AI Projects 1.x. Zapoznaj się z dokumentacją rozwiązania Foundry (klasyczną) w odniesieniu do wersji 1.x Azure AI Projects.

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 (rzadkie wyewidencjonowanie 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 jako plik ZIP repozytorium)

Pobierz plik ZIP repozytorium, wyodrębnij go do środowiska lokalnego i przejdź do folderu z tutorialem.

Ważna

W przypadku wdrożenia produkcyjnego użyj autonomicznego repozytorium. W tym samouczku jest używane repozytorium przykładów udostępnionych. Rzadkie wyewidencjonowanie minimalizuje lokalne zakłócenia.

Pobierz kod języka Python teraz

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

Krok 2. Natychmiastowe uruchamianie próbki

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 twoje requirements.txt używają następujących opublikowanych wersji pakietów:

    azure-ai-projects==2.0.0b3
azure-identity
python-dotenv
openai

  3. Instalacja zależności:

    python -m pip install -r requirements.txt

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

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

    Zrzut ekranu powitalny aplikacji Microsoft Foundry Models przedstawiający adres URL punktu końcowego i przycisk kopiowania.

  5. Skonfiguruj.env.

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

Skopiuj folder .env.template do folderu .env.

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

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

Wskazówka

Aby uzyskać identyfikator dzierżawy, uruchom następujące polecenie:

# 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ść.

Uruchom agenta i przeprowadź ocenę

python main.py
python evaluate.py

Oczekiwane dane wyjściowe (pierwszy przebieg agenta)

Pomyślne uruchomienie z programem SharePoint:

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

Łaskawa degradacja bez programu SharePoint:

📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_NAME 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.

Krok 3. Konfigurowanie przykładowych dokumentów biznesowych programu SharePoint

  1. Przejdź do witryny SharePoint ustawionej w połączeniu.

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

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

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

  4. Przed kontynuowaniem sprawdź, czy w bibliotece znajdują się cztery dokumenty.

Przykładowa struktura

📁 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 / Notatka

Ta sekcja jest wyłącznie referencyjna — nie jest wymagana żadna akcja. Wyjaśnia kod, który został już uruchomiony.

W tej sekcji opisano podstawowy kod w języku 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 do orkiestracji wielu agentów.
  • 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. Konfigurowanie uwierzytelniania na platformie Azure
  3. Konfigurowanie narzędzia programu SharePoint
  4. Konfigurowanie narzędzia MCP
  5. Tworzenie agenta i łączenie narzędzi
  6. Rozmowa z agentem

Ważna

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 Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Importowanie i konfigurowanie uwierzytelniania

Kod używa kilku bibliotek klienckich z zestawu Microsoft Foundry SDK do 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 na platformie 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 programu SharePoint dla agenta

Agent używa programu SharePoint i może uzyskiwać dostęp do zasad firmy i dokumentów procedur przechowywanych tam. Skonfiguruj połączenie z programem 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

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 programu SharePoint i MCP.

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

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

Krok 4. Ocena asystenta przy użyciu oceny chmury

Struktura oceny testuje realistyczne scenariusze biznesowe przy użyciu możliwości oceny chmury 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.

Ta struktura oceny pokazuje:

  • Docelowanie agenta: ocena uruchamia zapytania bezpośrednio względem agenta za pomocą azure_ai_target_completions.
  • Wbudowane narzędzia oceny: bezpieczeństwo (wykrywanie przemocy), jakość (płynność) i metryki zgodności zadań.
  • Realizacja oparta na chmurze: eliminuje lokalne wymagania obliczeniowe i obsługuje integrację z 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 ocenę chmury.
  3. Pobieranie wyników oceny.

Wskazówka

Aby uzyskać szczegółowe wskazówki dotyczące ocen w chmurze, zobacz Run evaluations in the cloud (Uruchamianie ocen w chmurze). Aby znaleźć kompleksową listę wbudowanych ewaluatorów dostępnych w narzędziu Foundry, zobacz Obserwowanie w generowaniu sztucznej inteligencji.

Uwaga / Notatka

Zestaw SDK języka C# używa metod protokołu z BinaryData i BinaryContent zamiast obiektów typowanych. Takie podejście wymaga metod pomocnika do analizowania odpowiedzi JSON. Zobacz przykładowy zestaw SDK oceny języka C# , aby uzyskać pełny wzorzec.

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 języku Python użyj klienta OpenAI bezpośrednio. W języku C#pobierz element EvaluationClient z klienta projektu:

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

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 wykonał instrukcje.

Uruchamianie oceny chmury

Utwórz przebieg oceny przeznaczony dla 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

Monitoruj przebieg oceny aż do jego zakończenia, a następnie pobierz wyniki szczegółowe.

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

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

  • Etykieta: wynik binarny "pass" lub "fail"
  • 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 chmury (evaluate.py)

Po uruchomieniu skryptu oceny zobaczysz dane wyjściowe podobne do poniższego przykładu. Wyniki przedstawiają tworzenie obiektu ewaluacji, uruchamianie zgłoszeń i odzyskiwanie 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

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

Pole Opis
Etykieta Binarne "pass" lub "fail" na podstawie wartości progowej
Ocena Wynik liczbowy (skala zależy od typu ewaluatora)
Threshold Wartość progowa określająca zaliczenie/niezaliczenie
Powód Objaśnienie wygenerowane przez LLM dla wyniku (jeśli dotyczy)

Skale ocen według 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)
  • Oceniacze zadań (task_adherence): skala 1–5

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ągłej integracji i ciągłego wdrażania. Zobacz Jak uruchomić ocenę w usłudze Azure DevOps i Stale oceniać agentów sztucznej inteligencji pod kątem wzorców integracji.

Rozwiązywanie problemów

Objaw Przyczyna Rezolucja
DefaultAzureCredential błąd uwierzytelniania Sesja interfejsu wiersza polecenia platformy Azure straciła ważność lub użytkownik nie jest zalogowany. 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 MODEL_DEPLOYMENT_NAME w .env
SharePoint tool configured ale agent nie może znaleźć dokumentów Dokumenty nie zostały przesłane lub nazwa połączenia jest nieprawidłowa Sprawdź, czy dokumenty są wyświetlane w bibliotece SharePoint i że SHAREPOINT_CONNECTION_NAME odpowiada połączeniu w projekcie.
Limit czasu narzędzia MCP lub błąd połączenia Serwer Microsoft Learn MCP jest niedostępny Sprawdź, czy MCP_SERVER_URL jest ustawiony na https://learn.microsoft.com/api/mcp oraz czy sieć zezwala na ruch wychodzący HTTPS.
403 Forbidden w programie SharePoint Niewystarczające uprawnienia w witrynie programu SharePoint Upewnij się, że tożsamość zalogowana ma co najmniej dostęp do odczytu do biblioteki dokumentów programu SharePoint

Podsumowanie

Masz teraz:

  • Działający prototyp pojedynczego agenta 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.

Dalsze kroki

W samouczku przedstawiono Etap 1 ścieżki 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

Uprzątnij zasoby

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

  1. Usuń agenta: agent jest automatycznie usuwany na końcu main.py (Python) lub Program.cs (C#). Jeśli przerwałeś przebieg, usuń go 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 programu SharePoint: jeśli pliki przykładowe .docx zostały przekazane do produkcyjnej witryny programu 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.

Treści powiązane

  • Last updated on