Bagikan melalui

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 Company (dari dokumen SharePoint)
  • panduan implementasi teknis (dari Microsoft Learn melalui MCP)
  • Solusi lengkap (menggabungkan kedua sumber untuk implementasi bisnis)
  • Evaluasi batch untuk memvalidasi kinerja 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.

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

Penting

Kode dalam artikel ini menggunakan paket yang saat ini sedang dalam pratinjau. Pratinjau ini disediakan tanpa kesepakatan tingkat layanan, dan kami tidak merekomendasikannya untuk penggunaan dalam lingkungan produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. 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 (dokumentasi alat SharePoint)

    Nota

    Untuk mengonfigurasi proyek Foundry Anda untuk konektivitas SharePoint, lihat dokumentasi alat SharePoint.

  • (Opsional) Git diinstal untuk mengkloning repositori sampel

Penting

Versi SDK dan struktur repositori sampel dapat berubah setelah publikasi. 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.

Langkah 1: Dapatkan kode sampel

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

Opsi A (kloning seluruh repositori sampel)

Petunjuk / Saran

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 (cek keluar jarang hanya tutorial ini - 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 (Repositori ZIP Unduh)

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

Penting

Untuk digunakan dalam produksi, gunakan repositori mandiri. Tutorial ini menggunakan repositori sampel bersama. Sparse checkout meminimalkan gangguan 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

Langkah 2: Segera 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.0.0
python-dotenv

  3. Instal dependensi:

    python -m pip install -r requirements.txt

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

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

    Screenshot tampilan selamat datang pada Microsoft Foundry Models yang memperlihatkan URL endpoint dan tombol salin.

  5. Konfigurasikan .env.

    Atur nilai lingkungan yang diperlukan untuk bahasa Anda.

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

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

Petunjuk / Saran

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 evaluasi

python main.py
python evaluate.py

Output yang diharapkan (agen jalankan pertama kali)

Keberhasilan menggunakan 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_NAME 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.

Langkah 3: 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

Nota

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 telah menjalankan agen. Setelah membacanya, Anda dapat:

  • Tambahkan alat data internal dan eksternal baru.
  • Perpanjang instruksi dinamis.
  • Memperkenalkan orkestrasi multiagen.
  • Meningkatkan pengamatan dan diagnostik.

Kode terbagi menjadi bagian utama berikut, diurutkan sesuai urutan kemunculannya 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 kesepakatan tingkat layanan, dan kami tidak merekomendasikannya untuk penggunaan dalam lingkungan produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. 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

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

Berbicara dengan agen

Terakhir, terapkan perulangan interaktif untuk berinteraksi 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 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

Langkah 4: Mengevaluasi asisten dengan menggunakan evaluasi batch

Kerangka kerja evaluasi menguji skenario bisnis yang realistis dengan menggunakan kapabilitas evaluasi batch pada 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.

Kerangka kerja evaluasi ini menunjukkan:

  • Penentuan Sasaran Agen: Evaluasi menjalankan permintaan 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.

Petunjuk / Saran

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.

Nota

Sampel C# menggunakan pendekatan evaluasi batch lokal dengan ProjectResponsesClient alih-alih API awan openai_client.evals 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#.

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

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

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 sampai selesai, lalu ambil item output 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")

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 kelompok (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 "berhasil" 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)
  • Penilai 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.

Petunjuk / Saran

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.

Troubleshooting

Gejala Penyebab Resolusi
DefaultAzureCredential kesalahan autentikasi sesi Azure CLI kedaluwarsa atau 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
SharePoint tool configured tetapi agen tidak dapat menemukan dokumen Dokumen tidak diunggah atau nama koneksi salah Verifikasi dokumen muncul di perpustakaan SharePoint dan SHAREPOINT_CONNECTION_NAME cocok dengan koneksi di proyek Anda
Batas waktu alat MCP atau kesalahan koneksi Microsoft server Learn MCP tidak dapat dijangkau Verifikasi MCP_SERVER_URL disetel ke https://learn.microsoft.com/api/mcp dan jaringan Anda mengizinkan lalu lintas HTTPS keluar
403 Forbidden di SharePoint Izin tidak cukup pada situs SharePoint Konfirmasikan identitas masuk Anda memiliki setidaknya akses Read ke pustaka dokumen SharePoint

Ringkasan

Anda sekarang memiliki:

  • Prototipe agen tunggal yang berfungsi yang 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 selanjutnya

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

  • Last updated on