Tutorial: Ide untuk membuat prototipe - Membangun dan mengevaluasi agen perusahaan

Tutorial ini mencakup tahap pertama perjalanan pengembang Microsoft Foundry: dari ide awal hingga prototipe yang berfungsi. Anda membangun asisten tempat kerja modern yang menggabungkan pengetahuan perusahaan internal dengan panduan teknis eksternal dengan menggunakan SDK Foundry Microsoft.

Skenario bisnis: Buat asisten AI yang membantu karyawan dengan menggabungkan:

  • Kebijakan perusahaan (dari dokumen SharePoint)
  • Panduan pelaksanaan teknis (dari Microsoft Learn melalui MCP)
  • Solusi lengkap (menggabungkan kedua sumber untuk implementasi bisnis)
  • Evaluasi batch untuk memvalidasi performa agen pada skenario bisnis yang realistis

Hasil tutorial: Pada akhirnya Anda memiliki Asisten Tempat Kerja Modern yang berjalan yang dapat menjawab pertanyaan kebijakan, teknis, dan implementasi gabungan; skrip evaluasi batch yang dapat diulang; dan titik ekstensi yang jelas (alat lain, pola multi-agen, evaluasi yang lebih kaya).

Anda akan:

  • Bangun Asisten Tempat Kerja Modern dengan integrasi SharePoint dan MCP.
  • Menunjukkan skenario bisnis nyata yang menggabungkan pengetahuan internal dan eksternal.
  • Terapkan penanganan kesalahan yang kuat dan degradasi yang anggun.
  • Buat kerangka evaluasi untuk pengujian yang berfokus pada bisnis.
  • Siapkan fondasi untuk tata kelola dan penyebaran produksi.

Contoh minimal ini menunjukkan pola siap untuk perusahaan dengan skenario bisnis yang realistis.

Penting

Kode dalam artikel ini menggunakan paket yang saat ini sedang dalam pratinjau. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan kami tidak merekomendasikannya untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan yang dibatasi. Untuk informasi selengkapnya, lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure.

Prasyarat

  • Langganan Azure. Jika Anda tidak memilikinya, buat secara gratis.
  • Azure CLI 2.67.0 atau yang lebih baru, diautentikasi dengan az login (periksa dengan az version)
  • Proyek Foundry dengan model yang disebarkan (misalnya, gpt-4o-mini). Jika Anda tidak memilikinya: Buat proyek lalu sebarkan model (lihat gambaran umum model: Katalog model).
  • Python 3.10 atau yang lebih baru
  • .NET SDK 8.0 atau yang lebih baru (untuk sampel C#)
  • Koneksi SharePoint dikonfigurasi dalam proyek Anda.
    • Alat SharePoint sedang dalam pratinjau dan memerlukan identitas terdelegasi milik pengguna yang masuk. Autentikasi khusus aplikasi dan autentikasi service principal tidak didukung.
    • Pengembang dan pengguna akhir memerlukan lisensi Microsoft 365 Copilot atau akses prabayar yang diaktifkan, peran Pengguna Foundry pada proyek, dan setidaknya akses Baca ke situs SharePoint target.
    • Situs SharePoint dan proyek Foundry harus berada di penyewa Microsoft Entra yang sama. Agen dapat menggunakan satu alat SharePoint. Untuk instruksi penyiapan, lihat Menggunakan alat SharePoint.
  • Peran Pengguna Foundry untuk membuat dan menguji agen. Jika Anda membuat koneksi project untuk mengautentikasi server MCP, Anda juga memerlukan peran Foundry Project Manager.
  • (Opsional) Git diinstal untuk mengkloning repositori sampel

Penting

Versi SDK dan struktur repositori sampel mungkin berubah setelah artikel ini diterbitkan. Sebelum memulai, periksa repositori sampel README untuk instruksi penyiapan terbaru, versi paket yang diperlukan, dan konfigurasi lingkungan. Jika versi yang direferensikan dalam tutorial ini tidak tersedia di PyPI atau NuGet, gunakan versi terbaru yang diterbitkan sebagai gantinya.

Dapatkan kode contoh

Alih-alih menavigasi pohon repositori besar, gunakan salah satu pendekatan berikut:

Opsi A (kloning seluruh repositori sampel)

Tips

Kode menggunakan Azure Proyek AI 2.x dan tidak kompatibel dengan Proyek AI Azure 1.x. Lihat dokumentasi Foundry (klasik) untuk versi 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

Opsi B (checkout jarang untuk tutorial ini saja - unduhan berkurang)

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

Opsi C (Unduh ZIP dari repositori)

Unduh repositori ZIP, ekstrak ke lingkungan lokal Anda, dan buka folder tutorial.

Penting

Untuk penerapan produksi, gunakan repositori yang terpisah. Tutorial ini menggunakan repositori sampel bersama. Checkout terbatas meminimalkan kebisingan lokal.

Unduh kode Python sekarang

Setelah Anda mengekstrak ZIP, buka samples/python/enterprise-agent-tutorial/1-idea-to-prototype.

Struktur minimal hanya berisi file penting:

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

Jalankan sampel

Mulailah dengan menjalankan agen sehingga Anda melihat fungsionalitas kerja sebelum menyelami detail implementasi.

Penyiapan lingkungan dan lingkungan virtual

  1. Instal runtime bahasa yang diperlukan, alat global, dan ekstensi Visual Studio Code seperti yang dijelaskan dalam Menyiapkan lingkungan pengembangan Anda.

  2. Verifikasi bahwa Anda requirements.txt menggunakan versi paket yang diterbitkan ini:

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

Instal dependensi:

python -m pip install -r requirements.txt

Verifikasi bahwa penginstalan berhasil. Anda melihat Successfully installed azure-ai-projects-... (Python) atau Restore completed (.NET) tanpa kesalahan.

  1. Temukan titik akhir proyek Anda di layar selamat datang proyek.

    Screenshot dari layar sambutan Model-Model Foundry Microsoft memperlihatkan URL titik akhir dan tombol salin.

  2. Konfigurasikan .env.

    Atur nilai lingkungan yang diperlukan untuk bahasa Anda.

Salin .env.template ke .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>

Konfirmasi .env berisi nilai yang valid dengan membuka file dan memverifikasi bahwa FOUNDRY_PROJECT_ENDPOINT dimulai dengan https:// dan FOUNDRY_MODEL_NAME cocok dengan nama model yang disebarkan dalam proyek Anda.

Untuk integrasi SharePoint, atur SHAREPOINT_CONNECTION_ID di Python ke ID koneksi proyek lengkap milik koneksi tersebut. Di C#, atur SHAREPOINT_CONNECTION_NAME ke nama koneksi.

Tips

Untuk mendapatkan ID penyewa Anda, jalankan:

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

Untuk mendapatkan titik akhir proyek Anda, buka proyek Anda di portal Foundry dan salin nilai yang ditampilkan di sana.

Jalankan agen dan penilaian

python main.py
python evaluate.py

Output yang diharapkan (luncuran pertama agen)

Kesuksesan penggunaan SharePoint:

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

Degradasi yang anggun tanpa SharePoint:

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

Sekarang setelah Anda memiliki agen yang berfungsi, bagian berikutnya menjelaskan cara kerjanya. Anda tidak perlu mengambil tindakan apa pun saat membaca bagian ini—itu untuk penjelasan.

Menyiapkan sampel SharePoint dokumen bisnis

  1. Buka situs SharePoint Anda (dikonfigurasi dalam koneksi).

  2. Buat pustaka dokumen "Kebijakan Perusahaan" (atau gunakan "Dokumen") yang sudah ada.

  3. Unggah empat sampel dokumen Word yang disediakan di folder sharepoint-sample-data:

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

  4. Verifikasi bahwa empat dokumen muncul di pustaka sebelum melanjutkan.

Struktur sampel

📁 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

Memahami implementasi asisten virtual

Catatan

Bagian ini hanya untuk referensi — tidak ada tindakan yang diperlukan. Ini menjelaskan kode yang sudah Anda jalankan.

Bagian ini menjelaskan kode inti di main.py (Python) atau ModernWorkplaceAssistant/Program.cs (C#). Anda sudah menjalankan agen. Setelah membacanya, Anda dapat:

  • Tambahkan alat data internal dan eksternal baru.
  • Perluas instruksi dinamis.
  • Memperkenalkan orkestrasi multi-agen.
  • Meningkatkan pengamatan dan diagnostik.

Kode dibagi menjadi bagian utama berikut, diurutkan sesuai dengan urutannya dalam kode sampel lengkap:

  1. Mengonfigurasi impor dan autentikasi
  2. Konfigurasi autentikasi ke Azure
  3. Konfigurasi alat SharePoint
  4. Mengonfigurasi alat MCP
  5. Membuat agen dan menyambungkan alat
  6. Berbicara dengan agen

Penting

Kode dalam artikel ini menggunakan paket yang saat ini sedang dalam pratinjau. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan kami tidak merekomendasikannya untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan yang dibatasi. Untuk informasi selengkapnya, lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure.

Penyiapan impor dan autentikasi

Kode ini menggunakan beberapa pustaka klien dari Microsoft Foundry SDK untuk membuat agen perusahaan yang kuat.

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

Mengonfigurasi autentikasi di Azure

Sebelum Anda membuat agen, siapkan autentikasi ke 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}")

Membuat alat SharePoint untuk agen

Agen menggunakan SharePoint dan dapat mengakses dokumen kebijakan dan prosedur perusahaan yang disimpan di sana. Siapkan koneksi ke SharePoint dalam kode Anda.

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

Membuat alat MCP untuk agen

Dukungan .NET SDK untuk alat MCP saat ini masih dalam pratinjau.

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

Membuat agen dan menyambungkan alat

Buat agen dan sambungkan alat SharePoint dan 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})")

Berbicara dengan agen

Terakhir, terapkan perulangan interaktif untuk berkomunikasi dengan agen.

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

Output yang diharapkan dari kode sampel agen

Saat Menjalankan agen, Anda akan melihat output yang mirip dengan contoh berikut. Output menunjukkan konfigurasi alat yang berhasil dan respons agen terhadap skenario bisnis:

✅ 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

Mengevaluasi asisten dengan evaluasi batch

Kerangka kerja evaluasi menguji skenario bisnis yang realistis dengan menggunakan kemampuan evaluasi batch dari Microsoft Foundry SDK. Alih-alih pendekatan lokal kustom, pola ini menggunakan evaluator bawaan (builtin.violence, , builtin.fluency) builtin.task_adherencedan openai_client.evals API untuk menjalankan evaluasi yang dapat diskalakan dan dapat diulang di cloud.

Evaluasi cloud Python memerlukan peran Pengguna Foundry, model GPT yang disebarkan yang mendukung penyelesaian obrolan, dan wilayah yang mendukung evaluator yang Anda pilih. Tinjau wilayah yang didukung sebelum Melanjutkan.

Kerangka kerja evaluasi ini menunjukkan:

  • Penargetan agen: Evaluasi menjalankan kueri langsung terhadap agen Anda dengan menggunakan azure_ai_target_completions.
  • Evaluator bawaan: Metrik keselamatan (deteksi kekerasan), kualitas (kefasihan), dan kepatuhan tugas.
  • Eksekusi berbasis cloud: Menghilangkan persyaratan komputasi lokal dan mendukung integrasi CI/CD.
  • Hasil terstruktur: Label lulus/gagal, skor, dan penalaran untuk setiap kasus pengujian.

Kode diuraikan menjadi bagian utama berikut:

  1. Konfigurasikan evaluasi.
  2. Jalankan evaluasi batch.
  3. Ambil hasil evaluasi.

Tips

Untuk panduan terperinci tentang evaluasi batch, lihat Menjalankan evaluasi di cloud. Untuk menemukan daftar evaluator bawaan yang komprehensif yang tersedia di Foundry, lihat Observabilitas dalam AI generatif.

Catatan

Sampel C# menggunakan pendekatan evaluasi batch lokal dengan ProjectResponsesClient alih-alih cloud openai_client.evals API yang ditampilkan dalam Python. Ini mengirim kueri ke agen, memeriksa respons terhadap kata kunci yang diharapkan, dan menulis hasil ke evaluation_results.json. Lihat sampel SDK evaluasi C# untuk pola evaluasi cloud di C#.

Konfigurasikan evaluasi

Pertama, buat objek evaluasi yang menentukan skema data dan kriteria pengujian Anda. Evaluasi menggunakan evaluator bawaan untuk deteksi kekerasan, kefasihan, dan kepatuhan tugas.

Di Python, gunakan klien OpenAI secara langsung. Di C#, dapatkan EvaluationClient dari klien proyek:

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

Array testing_criteria menentukan evaluator mana yang akan dijalankan:

  • builtin.violence: Mendeteksi konten kekerasan atau berbahaya sebagai respons.
  • builtin.fluency: Menilai kualitas respons dan keterbacaan (memerlukan penyebaran model).
  • builtin.task_adherence: Mengevaluasi apakah agen mengikuti instruksi dengan benar.

Jalankan evaluasi batch

Buat jalankan evaluasi yang menargetkan agen Anda. Sumber azure_ai_target_completions data mengirimkan kueri ke agen Anda dan menangkap respons untuk evaluasi:

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

Konfigurasi data_source :

  • jenis: azure_ai_target_completions merutekan kueri melalui agen Anda
  • sumber: Konten sebaris dengan kueri pengujian (Anda juga dapat menggunakan ID file himpunan data)
  • input_messages: Templat yang memformat setiap kueri untuk agen
  • target: Menentukan nama dan versi agen untuk dievaluasi

Mengambil hasil evaluasi

Pantau proses evaluasi hingga selesai, lalu ambil item keluaran terperinci.

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

Sebelum Anda meninjau item output individual, konfirmasikan bahwa eksekusi evaluasi selesai dan Result Counts memperlihatkan errored: 0. Jika eksekusi gagal, verifikasi peran Anda, wilayah yang dipilih, model yang disebarkan, dan dukungan evaluator.

Setiap item output meliputi:

  • Label: Hasil biner lulus atau gagal
  • Skor: Skor numerik pada skala evaluator
  • Alasan: Penjelasan mengapa skor ditetapkan (untuk evaluator berbasis LLM)

Output yang diharapkan dari evaluasi batch (evaluate.py)

Saat Menjalankan skrip evaluasi, Anda akan melihat output yang mirip dengan contoh berikut. Output menunjukkan pembuatan objek evaluasi, pengiriman eksekusi, dan pengambilan hasil:

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

Memahami hasil evaluasi

Evaluasi batch memberikan hasil terstruktur yang dapat Anda lihat di portal Foundry atau mengambil secara terprogram. Setiap item output meliputi:

Bidang Deskripsi
Label Biner "lolos" atau "gagal" berdasarkan ambang batas
Skor Skor numerik (skala tergantung pada jenis evaluator)
Ambang Nilai cutoff yang menentukan lulus/gagal
Alasan Penjelasan yang dihasilkan LLM untuk skor (jika berlaku)

Skala skor berdasarkan jenis evaluator:

  • Evaluator kualitas (kefasihan, koherensi): 1-5 skala
  • Evaluator keselamatan (kekerasan, bahaya diri sendiri): 0-7 skala keparahan (lebih rendah lebih aman)
  • Pemeriksa tugas (task_adherence): skala 1-5

Anda juga dapat melihat hasil terperinci di portal Foundry dengan memilih Evaluasi dari proyek Anda dan memilih eksekusi evaluasi. Portal menyediakan visualisasi, pemfilteran, dan opsi ekspor.

Tips

Untuk skenario produksi, pertimbangkan untuk menjalankan evaluasi sebagai bagian dari alur CI/CD Anda. Lihat Cara menjalankan evaluasi di Azure DevOps, dan Kontinu mengevaluasi agen AI Anda untuk pola integrasi.

Pemecahan masalah

Gejala Menyebabkan Resolusi
DefaultAzureCredential kesalahan autentikasi Sesi Azure CLI telah kedaluwarsa atau Anda belum masuk Jalankan az login dan coba lagi
Model deployment not found Nama model di .env tidak cocok dengan penyebaran di proyek Anda Buka proyek Anda di portal Foundry, periksa Penyebaran, dan perbarui FOUNDRY_MODEL_NAME di .env
integrasi SharePoint dilewati Variabel lingkungan SharePoint tidak diatur Di Python, atur SHAREPOINT_CONNECTION_ID ke ID koneksi proyek lengkap. Di C#, atur SHAREPOINT_CONNECTION_NAME ke nama koneksi.
SharePoint tool configured tetapi agen tidak dapat menemukan dokumen Dokumen tidak diunggah, koneksi salah, atau pengguna yang masuk tidak memiliki akses Pastikan dokumen berada di pustaka yang dikonfigurasi, koneksi mengarah ke pustaka tersebut, dan pengguna yang masuk memiliki akses Read. Gunakan autentikasi pengguna yang didelegasikan di penyewa Microsoft Entra yang sama dengan proyek Foundry.
Batas waktu alat MCP atau kesalahan koneksi Microsoft server Learn MCP tidak dapat dijangkau Verifikasi MCP_SERVER_URL diatur ke https://learn.microsoft.com/api/mcp dan pastikan jaringan Anda mengizinkan koneksi HTTPS keluar
Pembuatan koneksi proyek MCP ditolak Akun tidak memiliki peran proyek yang diperlukan Tetapkan peran Foundry Project Manager untuk membuat koneksi, lalu coba lagi.
Evaluasi cloud tidak dapat dimulai atau evaluator tidak didukung Kombinasi wilayah proyek, model, atau evaluator tidak didukung Verifikasi bahwa wilayah proyek Anda mendukung evaluator dan bahwa model GPT yang disebarkan mendukung penyelesaian obrolan.
403 Forbidden di SharePoint Izin tidak cukup pada situs SharePoint Pastikan identitas yang Anda gunakan untuk masuk memiliki setidaknya hak akses Baca ke pustaka dokumen SharePoint dan peran Pengguna Foundry di proyek.

Ringkasan

Anda sekarang memiliki:

  • Prototipe agen tunggal yang beroperasi didasarkan pada pengetahuan internal dan eksternal.
  • Skrip evaluasi berulang yang menunjukkan pola validasi perusahaan.
  • Jalur peningkatan yang jelas: lebih banyak alat, orkestrasi multi-agen, evaluasi yang lebih kaya, penyebaran.

Pola-pola ini mengurangi gesekan prototipe-ke-produksi: Anda dapat menambahkan sumber data, menerapkan tata kelola, dan mengintegrasikan pemantauan tanpa menulis ulang logika inti.

Langkah berikutnya

Tutorial ini menunjukkan Tahap 1 dari perjalanan pengembang - dari ide hingga prototipe. Sampel minimal ini menyediakan fondasi untuk pengembangan AI perusahaan. Untuk melanjutkan perjalanan Anda, jelajahi tahapan berikutnya:

Peningkatan tambahan yang disarankan

Tahap 2: Prototipe ke produksi

Tahap 3: Produksi ke adopsi

Membersihkan sumber daya

Ketika Anda tidak lagi membutuhkannya, hapus sumber daya yang Anda buat dalam tutorial ini:

  1. Delete agen: Agen secara otomatis dihapus di akhir main.py (Python) atau Program.cs (C#). Jika Anda menghentikan proses, hapus secara manual dari halaman Agen di portal Foundry.
  2. Hapus eksekusi evaluasi: Di portal Foundry, buka Evaluasi, pilih evaluasi yang dijalankan, dan hapus.
  3. Hapus dokumen sampel SharePoint: Jika Anda mengunggah sampel file .docx ke situs SharePoint produksi, hapus mereka dari pustaka dokumen.
  4. (Opsional) Hapus proyek Foundry: Jika Anda membuat proyek hanya untuk tutorial ini, hapus dari portal Foundry untuk menghapus semua sumber daya terkait.

Konten terkait

  • Terakhir diperbarui pada