Руководство. Создание прототипа и оценка корпоративного агента

В этом руководстве рассматривается первый этап пути разработчика Microsoft Foundry: от первоначальной идеи до рабочего прототипа. Вы создаете современный помощник по работе, который объединяет внутренние знания компании с внешним техническим руководством, используя SDK Microsoft Foundry.

Бизнес-сценарий: создание помощника по искусственному интеллекту, помогающего сотрудникам объединить:

• Политики компании (из документов SharePoint)
• Руководство по технической реализации (от Microsoft Learn через MCP)
• Полные решения (объединение обоих источников для бизнес-реализации)
• Пакетная оценка для проверки производительности агента в реалистичных бизнес-сценариях

Результаты учебника: к концу этого учебника у вас будет работающий Ассистент для современного рабочего пространства, который может отвечать на вопросы о политике, технической и объединенной реализации; повторяемый сценарий пакетной оценки; и четкие точки расширения (другие средства, шаблоны с несколькими агентами, более богатые возможности оценки).

Этот минимальный пример демонстрирует готовые для предприятия шаблоны с реалистичными бизнес-сценариями.

Необходимые условия

• Подписка Azure. Если у вас его нет, создайте его бесплатно.

• Azure CLI 2.67.0 или более поздней версии, прошедшие проверку подлинности с помощью az login (проверьте az version)

• Проект Foundry с развернутой моделью (например, ). Если у вас нет одного: создайте проект и разверните модель (см. обзор модели: каталог моделей).

• Python 3.10 или более поздней версии

• пакет SDK .NET версии 8.0 или более поздней версии (для примера C#)

• Подключение SharePoint, настроенное в проекте (документация по инструменту SharePoint)

  Примечание

  Сведения о настройке проекта Foundry для подключения SharePoint см. в документации по средству SharePoint.

• (Необязательно) Установка Git для клонирования репозитория-примера

Шаг 1. Получение примера кода

Вместо навигации по большому дереву репозитория используйте один из следующих подходов:

Вариант A (клонирование всего репозитория примеров)

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/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/csharp/enterprise-agent-tutorial/1-idea-to-prototype

Вариант B (разреженная выгрузка только для этого руководства — сокращенная загрузка)

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/microsoft-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 (Скачать ZIP-файл репозитория)

Скачайте ZIP-файл репозитория, извлеките его в локальную среду и перейдите в папку учебника.

Минимальная структура содержит только основные файлы:

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/                        # Batch evaluation framework
   │   ├── Program.cs                   # Batch evaluation with built-in evaluators
   │   ├── Evaluate.csproj
   │   └── evaluation_results.json      # Example output (generated)
   ├── questions.jsonl                  # Business test scenarios
   └── README.md                        # Complete setup instructions

Шаг 2. Немедленное выполнение примера

Начните с запуска агента, чтобы вы видели рабочие функции, прежде чем перейти к сведениям о реализации.

Настройка среды и виртуальная среда

1. Установите необходимые языковые среды выполнения, глобальные средства и расширения VS Code, как описано в разделе "Подготовка среды разработки".

2. Проверьте, что ваш requirements.txt использует следующие опубликованные версии пакетов:

   azure-ai-projects>=2.0.0
   python-dotenv
   

3. Установите зависимости:

   • Python
   • C#

   python -m pip install -r requirements.txt
   

   Убедитесь, что установка выполнена успешно. Вы должны увидеть Successfully installed azure-ai-projects-... (Python) или Restore completed (.NET) без ошибок.

4. Найдите конечную точку проекта на экране приветствия проекта.

   

5. Настройте .env.

   Задайте значения среды, необходимые для языка.

# Foundry configuration
FOUNDRY_PROJECT_ENDPOINT=https://<your-project>.aiservices.azure.com
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 connection name)
SHAREPOINT_CONNECTION_NAME=<your-sharepoint-connection-name>

# Foundry configuration
FOUNDRY_PROJECT_ENDPOINT=https://<your-project>.aiservices.azure.com
FOUNDRY_MODEL_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

Подтвердите, что .env содержит допустимые значения, открыв файл и убедившись, что FOUNDRY_PROJECT_ENDPOINT начинается с https://, а FOUNDRY_MODEL_NAME соответствует имени развернутой модели в вашем проекте.

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

Запуск агента и оценка

python main.py
python evaluate.py

cd ModernWorkplaceAssistant
dotnet restore
dotnet run

cd ../Evaluate
dotnet restore
dotnet run

Ожидаемые выходные данные (первый запуск агента)

Успешный запуск с SharePoint:

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

Плавная деградация без использования SharePoint.

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

Теперь, когда у вас есть рабочий агент, в следующих разделах объясняется, как это работает. При чтении этих разделов вам не нужно предпринимать никаких действий — они предназначены для объяснения.

Шаг 3. Настройка примера SharePoint бизнес-документов

1. Перейдите на сайт SharePoint (настроено в соединении).

2. Создайте библиотеку документов "Политики компании" (или используйте существующие "Документы").

3. Отправьте четыре примера документов Word, указанных в папке sharepoint-sample-data:

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

4. Прежде чем продолжить, убедитесь, что четыре документа отображаются в библиотеке.

Пример структуры

📁 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

Общие сведения о реализации помощника

В этом разделе объясняется основной код в main.py (Python) или ModernWorkplaceAssistant/Program.cs (C#). Вы уже запустили агент. Прочитав его, вы можете:

• Добавьте новые внутренние и внешние средства данных.
• Расширение динамических инструкций.
• Представьте оркестрацию с несколькими агентами.
• Повышение наблюдаемости и диагностики.

Код разбивается на следующие основные разделы, упорядоченные по мере их отображения в полном примере кода:

1. Настройка импорта и проверки подлинности
2. Настройка аутентификации в Azure
3. Настройка средства SharePoint
4. Настройка средства MCP
5. Создание агента и подключение средств
6. Беседа с агентом

Импорт и настройка проверки подлинности

В коде используется несколько клиентских библиотек из пакета SDK для Microsoft Foundry для создания надежного корпоративного агента.

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;

Настройка проверки подлинности в Azure

Перед созданием агента настройте проверку подлинности в 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}")

var credential = new DefaultAzureCredential();

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

Создание средства SharePoint для агента

Агент использует SharePoint и может получить доступ к документам политики и процедуры компании, хранящимся там. Настройте подключение для SharePoint в коде.

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

Создание средства MCP для агента

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

Создание агента и подключение средств

Создайте агент и подключите средства SharePoint и 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})")

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

Беседа с агентом

Наконец, реализуйте интерактивный цикл для взаимодействия с агентом.

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

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

Ожидаемые выходные данные из примера кода агента

При запуске агента вы увидите выходные данные, аналогичные следующему примеру. В результатах показана успешная конфигурация инструмента и ответы агента на бизнес-сценарии.

✅ 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

Шаг 4. Оценка помощника с помощью пакетной оценки

Структура оценки тестирует реалистичные бизнес-сценарии, используя возможность пакетной оценки в SDK Microsoft Foundry. Вместо пользовательского локального подхода этот шаблон использует встроенные вычислители (builtin.violence, , builtin.fluencybuiltin.task_adherence) и openai_client.evals API для выполнения масштабируемых повторяющихся вычислений в облаке.

Эта платформа оценки демонстрирует следующее:

• Назначение агента: оценка выполняет запросы непосредственно к агенту с помощью azure_ai_target_completions.
• Встроенные оценщики: безопасность (обнаружение насилия), качество (беглость) и метрики соблюдения требований.
• Облачное выполнение: устраняет локальные требования к вычислительным ресурсам и поддерживает интеграцию CI/CD.
• Структурированные результаты: метки пройдено/непройдено, оценки и обоснование для каждого тестового случая.

Код разбивается на следующие основные разделы:

1. Настройте оценку.
2. Запустите пакетную оценку.
3. Получение результатов оценки.

Настройка оценки

Сначала создайте объект оценки, определяющий схему данных и критерии тестирования. В этой оценке используются встроенные оценщики для обнаружения насилия, беглости и соблюдения задач.

В Python напрямую используйте клиент OpenAI. В C#получите EvaluationClient от клиента проекта:

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

var questions = File.ReadAllLines(GetFile("questions.jsonl"))
    .Select(line => JsonSerializer.Deserialize<JsonElement>(line))
    .ToList();

Массив testing_criteria указывает, какие вычислители необходимо выполнить:

• builtin.violence: обнаруживает насильственное или вредное содержимое в ответах.
• builtin.fluency: оценивает качество отклика и удобочитаемость (требуется развертывание модели).
• builtin.task_adherence: Оценивает, правильно ли агент выполнил инструкции.

Запуск пакетной оценки

Создайте оценку, нацеленную на вашего агента. Источник azure_ai_target_completions данных отправляет запросы агенту и записывает ответы для оценки:

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

// NOTE: This code is a non-runnable snippet of the larger sample code from which it is taken.
var results = new List<object>();

Console.WriteLine($"Running {questions.Count} evaluation questions...\n");

for (int i = 0; i < questions.Count; i++)
{
    var q = questions[i];
    var question = q.GetProperty("question").GetString()!;
    
    string[] expectedKeywords = Array.Empty<string>();
    if (q.TryGetProperty("expected_keywords", out var keywordsElem))
    {
        expectedKeywords = keywordsElem.EnumerateArray()
            .Select(e => e.GetString()!)
            .ToArray();
    }

    Console.WriteLine($"Question {i + 1}/{questions.Count}: {question}");

    // Create a conversation to maintain state
    ProjectConversation conversation = await client.OpenAI.Conversations.CreateProjectConversationAsync();

    // Get OpenAI client from the agents client
    ProjectResponsesClient responseClient = client.OpenAI.GetProjectResponsesClientForAgent(agent, conversation.Id);

    // Create the user message item
    List<ResponseItem> items = [ResponseItem.CreateUserMessageItem(question)];

    string response = "";
    try
    {
        // Create response from the agent
        ResponseResult openAIResponse = await responseClient.CreateResponseAsync(items);
        response = openAIResponse.GetOutputText();
    }
    catch (Exception ex)
    {
        Console.WriteLine($"   ⚠️  Error: {ex.Message}");
        response = "";
    }

    bool passed = response.Length > 50;
    if (expectedKeywords.Length > 0)
    {
        passed = passed && expectedKeywords.Any(k => response.Contains(k, StringComparison.OrdinalIgnoreCase));
    }

    Console.WriteLine($"   Status: {(passed ? "✅ PASS" : "❌ FAIL")}");
    Console.WriteLine($"   Response length: {response.Length} characters\n");

    results.Add(new
    {
        question,
        response,
        passed,
        response_length = response.Length
    });
}

Конфигурация data_source :

• тип: azure_ai_target_completions маршрутизирует запросы через агент
• источник: встроенное содержимое с тестовыми запросами (можно также использовать идентификатор файла набора данных)
• input_messages. Шаблон, который форматирует каждый запрос агента
• целевой объект: указывает имя агента и версию для оценки

Получение результатов оценки

Опрашивает выполнение оценки до завершения, а затем извлекает подробные выходные элементы:

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

// NOTE: This code is a non-runnable snippet of the larger sample code from which it is taken.
var summary = new
{
    total_questions = questions.Count,
    passed = results.Count(r => ((dynamic)r).passed),
    failed = results.Count(r => !((dynamic)r).passed),
    results
};

var json = JsonSerializer.Serialize(summary, new JsonSerializerOptions { WriteIndented = true });
File.WriteAllText("evaluation_results.json", json);

Console.WriteLine($"📊 Evaluation Complete:");
Console.WriteLine($"   Total: {summary.total_questions}");
Console.WriteLine($"   Passed: {summary.passed}");
Console.WriteLine($"   Failed: {summary.failed}");
Console.WriteLine($"\n📄 Results saved to evaluation_results.json");

Каждый выходной элемент включает:

• Метка: двоичный результат "pass" или "fail"
• Оценка: числовая оценка по шкале оценивателя
• Причина: объяснение того, почему оценка была назначена (для оценщиков на основе LLM)

Ожидаемые выходные данные из пакетной оценки (evaluate.py)

При запуске скрипта оценки вы увидите выходные данные, аналогичные следующему примеру. Выходные данные показывают создание объекта оценки, отправку и получение результатов:

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

Общие сведения о результатах оценки

Пакетные оценки предоставляют структурированные результаты, которые можно просмотреть на портале Foundry или получить программным способом. Каждый выходной элемент включает:

Шкалы оценки по типу вычислителя:

• Оценка качества (беглость, согласованность): 1-5 шкалы
• Оценщики безопасности (насилие, самоповреждение): 0-7 шкала серьезности (ниже безопаснее)
• Оценщики задач (task_adherence): по шкале от 1 до 5

Вы также можете просмотреть подробные результаты на портале Foundry, выбрав оценку проекта и выбрав выполнение оценки. На портале предоставляются параметры визуализации, фильтрации и экспорта.

Устранение неполадок

Сводка

Теперь у вас есть:

• Рабочий прототип одиночного агента, основанный на внутренних и внешних знаниях.
• Повторяющийся скрипт оценки, демонстрирующий шаблоны корпоративной проверки.
• Четкий путь обновления: дополнительные средства, оркестрация с несколькими агентами, более подробная оценка, развертывание.

Эти шаблоны снижают трение при переходе от прототипа к промышленной эксплуатации: вы можете добавлять источники данных, применять гавернанс и интегрировать мониторинг, не перезаписывая основную логику.

Дальнейшие действия

В этом руководстве демонстрируется этап 1 пути разработчика — от идеи до прототипа. Этот минимальный пример предоставляет основу для разработки корпоративного ИИ. Чтобы продолжить свое путешествие, изучите следующие этапы:

Предлагаемые дополнительные улучшения

• Добавьте дополнительные источники данных (Поиск с использованием ИИ Azure, other sources).
• Реализуйте расширенные методы оценки (с помощью ИИ).
• Создайте настраиваемые средства для операций, относящихся к бизнесу.
• Добавьте память беседы и персонализацию.

Этап 2: Прототип в производство

• Реализуйте оценку безопасности с помощью red-team testing.
• Создание комплексных наборов данных оценки с помощью метрик качества.
• Применение политик управления на уровне организации и сравнения моделей.
• Настройте мониторинг парка, интеграцию CI/CD и конечные точки развертывания в производственной среде.

Этап 3. Переход от производства к внедрению

• Сбор данных трассировки и отзывов пользователей из продуктовых развертываний.
• Детализируйте модели и создайте аналитические сведения об оценке для непрерывного улучшения.
• Интегрируйте шлюз Azure API Management с системой непрерывного мониторинга качества.
• Реализуйте управление парком, элементы управления соответствием требованиям и оптимизацию затрат.

Очистка ресурсов

Если они больше не нужны, удалите ресурсы, созданные в этом руководстве:

1. Удалить агента: агент автоматически удаляется в конце main.py (Python) или Program.cs (C#). Если выполнение прервано, удалите его вручную со страницы "Агенты" на портале Foundry.
2. Удалите выполнение оценки: на портале Foundry перейдите к разделу "Оценка", выберите выполнение оценки и удалите его.
3. Удалите примерные документы SharePoint. Если вы добавили примерные файлы на рабочий сайт SharePoint, удалите их из библиотеки документов.
4. (Необязательно) Удалите проект Foundry: если вы создали проект только для этого руководства, удалите его на портале Foundry, чтобы удалить все связанные ресурсы.

Связанное содержимое

• Общие сведения о службе агента Foundry
• документация по SharePoint
• Интеграция средств MCP
• Шаблоны нескольких агентов