Oktatóanyag: Ötlet a prototípus készítésére – Vállalati ügynök létrehozása és kiértékelése

Ez az oktatóanyag a Microsoft Foundry fejlesztői folyamatának első szakaszát ismerteti: a kezdeti ötlettől a működő prototípusig. Egy modern munkahelyi asszisztenst hozhat létre, amely a belső vállalati ismereteket és a külső technikai útmutatást ötvözi a Microsoft Foundry SDK használatával.

Üzleti forgatókönyv: Olyan AI-asszisztens létrehozása, amely a következők kombinálásával segíti az alkalmazottakat:

  • Vállalati szabályzatok (SharePoint dokumentumokból)
  • Műszaki megvalósítási útmutató (Microsoft Learn via MCP-n keresztül)
  • Teljes körű megoldások (mindkét forrás kombinálása az üzleti megvalósításhoz)
  • Batch-értékelés az ügynök teljesítményének reális üzleti forgatókönyvekben való érvényesítéséhez

Oktatóanyag eredménye: A végére egy futó Modern Munkahelyi asszisztenssel rendelkezik, amely megválaszolja a szabályzatokkal, a műszaki és az egyesített megvalósítással kapcsolatos kérdéseket; megismételhető köteg-kiértékelési szkript; és egyértelmű bővítménypontok (egyéb eszközök, többügynök-minták, gazdagabb kiértékelés).

A következőket fogja csinálni:

  • Modern munkahelyi asszisztens létrehozása SharePoint és MCP-integrációval.
  • A belső és külső tudást kombináló valós üzleti forgatókönyvek bemutatása.
  • Hatékony hibakezelés és zökkenőmentes visszaminősítés megvalósítása.
  • Értékelési keretrendszer létrehozása az üzleti alapú teszteléshez.
  • Az irányítás és a termelési telepítés előkészítése.

Ez a minimális minta a nagyvállalati használatra kész mintákat mutatja be reális üzleti forgatókönyvekkel.

Fontos

A cikkben szereplő kód jelenleg előzetes verziójú csomagokat használ. Ez az előzetes verzió szolgáltatásszint-szerződés nélkül érhető el, és éles számítási feladatokhoz nem javasoljuk. Előfordulhat, hogy bizonyos funkciók nem támogatottak, vagy korlátozott képességekkel rendelkeznek. További információ: Supplemental Terms of Use for Microsoft Azure Previews.

Előfeltételek

  • Egy Azure előfizetés. Ha nincs ilyenje, hozzon létre egyet ingyen.

  • Azure CLI 2.67.0-s vagy újabb verziójú, az login hitelesítéssel (ellenőrizze a az version)

  • Egy telepített modellel rendelkező Foundry-projekt (például). gpt-4o-mini Ha nem rendelkezik ilyenvel: Hozzon létre egy projektet , majd telepítsen egy modellt (lásd a modell áttekintését: Modellkatalógus).

  • Python 3.10 vagy újabb verzió

  • .NET SDK 8.0-s vagy újabb verziója (a C#-minta esetében)

  • SharePoint projektben konfigurált kapcsolat (SharePoint eszköz dokumentációja)

    Megjegyzés

    A Foundry-projekt SharePoint kapcsolathoz való konfigurálásához tekintse meg a SharePoint eszköz dokumentációját.

  • (Nem kötelező) Git telepítve a mintaadattár klónozásához

Fontos

Az SDK-verziók és a mintaadattár struktúrája a cikk közzététele után változhat. Mielőtt hozzákezdene, ellenőrizze a README mintaadattárban a legújabb telepítési utasításokat, a szükséges csomagverziókat és a környezetkonfigurációt. Ha az oktatóanyagban hivatkozott verzió nem érhető el PyPI vagy NuGet, használja helyette a legújabb közzétett verziót.

1. lépés: A mintakód lekérése

Ahelyett, hogy nagy adattárfát navigálna, használja az alábbi módszerek egyikét:

A lehetőség (a teljes mintatár klónozása)

Tipp

A kód Azure AI-projekteket használ 2.x és nem kompatibilis Azure AI-projektekkel 1.x. Tekintse meg a Foundry (klasszikus) dokumentációját az Azure AI Projects 1.x verziójához.

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

B opció (ritkított ellenőrzés csak ehhez az oktatóanyaghoz – kisebb letöltés)

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

C lehetőség (az adattár ZIP-fájljának letöltése)

Töltse le a ZIP-adattárat, bontsa ki a helyi környezetbe, és lépjen az oktatóanyag mappába.

Fontos

Termelési környezetbe történő bevezetéshez használjon önálló adattárat. Ez az oktatóanyag a megosztott minták adattárát használja. A ritka kivétel minimalizálja a helyi zajt.

A Python kód letöltése

A ZIP kinyerése után lépjen a(z) samples/python/enterprise-agent-tutorial/1-idea-to-prototype oldalra.

A minimális struktúra csak az alapvető fájlokat tartalmazza:

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

2. lépés: A minta azonnali futtatása

Első lépésként futtassa az ügynököt, hogy láthassa a működés funkcióit, mielőtt belemerül a megvalósítás részleteibe.

Környezet beállítása és virtuális környezet

  1. Telepítse a szükséges nyelvi futtatókörnyezeteket, globális eszközöket és VS Code-bővítményeket a fejlesztési környezet előkészítése című szakaszban leírtak szerint.

  2. Ellenőrizze, hogy a requirements.txt közzétett csomagverziókat használja-e:

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

  3. Függőségek telepítése:

    python -m pip install -r requirements.txt

    Ellenőrizze, hogy a telepítés sikeres volt-e. Hiba nélkül jelenik meg Successfully installed azure-ai-projects-... (Python) vagy Restore completed (.NET).

  4. Keresse meg a projektvégpontot a projekt üdvözlőképernyőjén.

    A Microsoft Foundry Models üdvözlőképernyőjének képernyőképe, amely a végpont URL-jét és a másolási gombot mutatja.

  5. Konfigurálja .env.

    Állítsa be a nyelvhez szükséges környezeti értékeket.

Másold a .env.template.env helyre.

# 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 connection name)
SHAREPOINT_CONNECTION_NAME=<your-sharepoint-connection-name>

Ellenőrizze .env , hogy érvényes értékeket tartalmaz-e a fájl megnyitásával, valamint annak ellenőrzésével, hogy FOUNDRY_PROJECT_ENDPOINT az a projektben üzembe helyezett modell nevével https:// kezdődik és FOUNDRY_MODEL_NAME megegyezik-e.

Tipp

A bérlőazonosító lekéréséhez futtassa a következőt:

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

A projektvégpont lekéréséhez nyissa meg a projektet az Foundry portálon , és másolja ki az ott látható értéket.

Ügynök futtatása és kiértékelése

python main.py
python evaluate.py

Várt kimenet (ügynök első futtatása)

Sikeres futtatás SharePoint:

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

Kecses lebomlás SharePoint nélkül:

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

Most, hogy már rendelkezik egy munkaügynökkel, a következő szakaszok ismertetik, hogyan működik. A szakaszok elolvasása közben nem kell semmilyen műveletet elvégeznie – ezek magyarázatra szorulnak.

3. lépés: Minta SharePoint üzleti dokumentumok beállítása

  1. Lépjen a SharePoint webhelyre (a kapcsolaton belül konfigurálva).

  2. "Vállalati szabályzatok" dokumentumtár létrehozása (vagy meglévő "Dokumentumok" használata).

  3. Töltse fel a sharepoint-sample-data mappában található négy mintadokumentumot Word:

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

  4. A folytatás előtt ellenőrizze, hogy négy dokumentum jelenik-e meg a könyvtárban.

Mintastruktúra

📁 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

Az asszisztens implementációjának megértése

Megjegyzés

Ez a szakasz csak referenciaként szolgál – nincs szükség műveletre. Ez ismerteti a már futtatott kódot.

Ez a szakasz a main.py (Python) vagy ModernWorkplaceAssistant/Program.cs (C#) alapvető kódját ismerteti. Már futtatta az ügynököt. Elolvasása után a következőt teheti:

  • Új belső és külső adateszközök hozzáadása.
  • Dinamikus utasítások kiterjesztése.
  • Többügynök-vezénylés bevezetése.
  • A megfigyelhetőség és a diagnosztika javítása.

A kód a következő fő szakaszokra bontható, a teljes mintakódban megjelenő sorrendben:

  1. Importálás és hitelesítés konfigurálása
  2. Hitelesítés konfigurálása az Azure-hoz
  3. Konfigurálja a SharePoint eszközt
  4. MCP-eszköz konfigurálása
  5. Az ügynök létrehozása és az eszközök csatlakoztatása
  6. Beszélgessen az ügynökkel

Fontos

A cikkben szereplő kód jelenleg előzetes verziójú csomagokat használ. Ez az előzetes verzió szolgáltatásszint-szerződés nélkül érhető el, és éles számítási feladatokhoz nem javasoljuk. Előfordulhat, hogy bizonyos funkciók nem támogatottak, vagy korlátozott képességekkel rendelkeznek. További információ: Supplemental Terms of Use for Microsoft Azure Previews.

Importálás és hitelesítés beállítása

A kód a Microsoft Foundry SDK számos ügyfélkódtárát használja egy robusztus vállalati ügynök létrehozásához.

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

Az Azure hitelesítésének konfigurálása

Az ügynök létrehozása előtt állítsa be a hitelesítést az Foundrybe.

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

Az ügynök SharePoint eszközének létrehozása

Az ügynök SharePoint használ, és hozzáférhet az ott tárolt vállalati szabályzat- és eljárásdokumentumokhoz. Állítsa be a SharePoint kapcsolatát a kódban.

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

Az ügynök MCP-eszközének létrehozása

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

Az ügynök létrehozása és az eszközök csatlakoztatása

Hozza létre az ügynököt, és csatlakoztassa a SharePoint és az MCP eszközöket.

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

Beszélgessen az ügynökkel

Végül implementáljon egy interaktív hurkot, amely az ügynökkel kommunikál.

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

A mintakódból származó ügynök által várt kimenet

Az ügynök futtatásakor az alábbi példához hasonló kimenet jelenik meg. A kimenet sikeres eszközkonfigurációt és ügynöki válaszokat jelenít meg az üzleti forgatókönyvekre:

✅ 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

4. lépés: Az asszisztens értékelése tömeges értékeléssel

Az értékelési keretrendszer az Microsoft Foundry SDK batch-kiértékelési képességével teszteli a reális üzleti forgatókönyveket. Egyéni helyi megközelítés helyett ez a minta a beépített kiértékelőket (builtin.violence, builtin.fluency, ) builtin.task_adherenceés az openai_client.evals API-t használja skálázható, megismételhető kiértékelések futtatására a felhőben.

Ez az értékelési keretrendszer a következőt mutatja be:

  • Ügynök megcélzása: A kiértékelés közvetlenül az ügynököt célozza meg, azure_ai_target_completions használatával futtatva a lekérdezéseket.
  • Beépített kiértékelők: Biztonság (erőszakészlelés), minőség (folyékonyság) és feladatbetartási mutatók.
  • Felhőalapú végrehajtás: Megszünteti a helyi számítási követelményeket, és támogatja a CI/CD-integrációt.
  • Strukturált eredmények: Siker/hiba címkék, pontszámok és indoklás az egyes tesztesetekhez.

A kód a következő fő szakaszokra bontható:

  1. Konfigurálja a kiértékelést.
  2. Futtassa a kötegértékelést.
  3. A kiértékelési eredmények lekérése.

Tipp

A csoportos értékelésekkel kapcsolatos részletes útmutatásért tekintse meg csoportos értékelések futtatása a felhőben. A Foundryben elérhető beépített kiértékelők átfogó listájának megkereséséhez lásd: Megfigyelhetőség a generatív AI-ben.

Megjegyzés

A C#-minta helyi kötegértékelési megközelítést használ ProjectResponsesClient a felhőbeli openai_client.evals API helyett, amely Pythonban látható. Lekérdezéseket küld az ügynöknek, ellenőrzi a várt kulcsszavakra adott válaszokat, és az eredményeket a következőre evaluation_results.jsonírja: . Tekintse meg a C# Evaluations SDK-mintát a C#-beli felhőértékelési mintákhoz.

A kiértékelés konfigurálása

Először hozzon létre egy kiértékelési objektumot, amely meghatározza az adatsémát és a tesztelési feltételeket. Az értékelés beépített kiértékelőket használ az erőszak észlelésére, a szöveg folyékonyságára és a feladatok betartására.

A Python használja közvetlenül az OpenAI-ügyfelet. hu-HU: C#-ban kérjen le egy EvaluationClient a projektszolgáltatástól:

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

A testing_criteria tömb határozza meg, hogy mely kiértékelők fussanak:

  • builtin.violence: Erőszakos vagy káros tartalmakat észlel a válaszokban.
  • builtin.fluency: Felméri a válasz minőségét és olvashatóságát (modelltelepítést igényel).
  • builtin.task_adherence: Kiértékeli, hogy az ügynök helyesen követte-e az utasításokat.

Indítsa el a köteg kiértékelését

Hozzon létre egy kiértékelési futtatási lehetőséget, amely az ügynököt célozza. Az azure_ai_target_completions adatforrás lekérdezéseket küld az ügynöknek, és kiértékeléshez rögzíti a válaszokat:

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

A data_source konfiguráció:

  • típus: azure_ai_target_completions a lekérdezések átirányítása az ügynökön keresztül
  • forrás: Beágyazott tartalom teszt lekérdezésekkel (adatkészletfájl-azonosítót is használhat)
  • input_messages: Az ügynök egyes lekérdezéseit formázó sablon
  • cél: A kiértékelendő ügynök nevét és verzióját adja meg

Kiértékelési eredmények lekérése

A kiértékelési futtatás állapotának ismételt lekérdezése, amíg be nem fejeződik, majd a részletes kimeneti elemek lekérése.

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

Minden kimeneti elem a következőket tartalmazza:

  • Címke: Bináris megfelelt vagy nem felelt meg eredmény
  • Pontszám: Numerikus pontszám az értékelő skáláján
  • Ok: A pontszám hozzárendelésének magyarázata (LLM-alapú kiértékelők esetén)

A batch értékelés várható eredménye (evaluate.py)

A kiértékelési szkript futtatásakor az alábbi példához hasonló kimenet jelenik meg. A kimenet a kiértékelési objektum létrehozását, a beküldés futtatását és az eredmények lekérését jeleníti meg:

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

A kiértékelési eredmények ismertetése

A Batch-értékelések strukturált eredményeket biztosítanak, amelyeket az Foundry portálon tekinthet meg, vagy programozott módon lekérhet. Minden kimeneti elem a következőket tartalmazza:

Mező Leírás
Címke Bináris „sikeres” vagy „sikertelen” a küszöbérték alapján
Pontszám Numerikus pontszám (a skálázás az értékelő típusától függ)
Határérték A pass/fail eredményt meghatározó határérték
Ok LLM által generált magyarázat a pontszámhoz (ha van)

Skálázási skálázás kiértékelőtípus szerint:

  • Minőségértékelők (fluencia, koherencia): 1-5 skála
  • Biztonsági értékelők (erőszak, önkárosítás): 0-7 súlyossági skálázás (alacsonyabb biztonságosabb)
  • Feladatértékelők (task_adherence): 1-5 skálázás

A részletes eredményeket az Foundry portálon is megtekintheti, ha kiválasztja a Projekt kiértékelése és a kiértékelési futtatás lehetőséget. A portál vizualizációkat, szűrési és exportálási lehetőségeket biztosít.

Tipp

Éles forgatókönyvek esetén fontolja meg az értékelések futtatását a CI/CD-folyamat részeként. Az integrációs mintákhoz tekintse meg az Azure DevOps kiértékelés végrehajtásának módját, és AI-ügynökeinek folyamatos kiértékelését.

Hibaelhárítás

Tünet Okoz Felbontás
DefaultAzureCredential hitelesítési hiba Azure CLI munkamenet lejárt vagy nincs bejelentkezve Futtatás az login és újrapróbálkozás
Model deployment not found A .env modell neve nem egyezik a projektben lévő egyik telepítéssel sem. Nyissa meg a projektet a Foundry portálon, ellenőrizze az üzemelő példányokat, és frissítse a FOUNDRY_MODEL_NAME elemet .env.
SharePoint tool configured de az ügynök nem talál dokumentumokat A dokumentumok nincsenek feltöltve, vagy a kapcsolat neve helytelen Ellenőrizze, hogy a dokumentumok megjelennek-e a SharePoint tárban, és hogy a SHAREPOINT_CONNECTION_NAME megegyezik-e a projektben lévő kapcsolattal
MCP-eszköz időtúllépése vagy csatlakozási hibája Microsoft Learn MCP-kiszolgáló nem érhető el Ellenőrizze, hogy a MCP_SERVER_URL be van-e állítva https://learn.microsoft.com/api/mcp értékre, és hogy a hálózat engedélyezi-e a kimenő HTTPS-t.
403 Forbidden a SharePoint Nem megfelelő engedélyek a SharePoint webhelyen Győződjön meg arról, hogy a bejelentkezett identitás legalább Read hozzáféréssel rendelkezik a SharePoint dokumentumtárhoz

Összefoglaló

Most a következőt használhatja:

  • Egy működő, szimpla ügynök prototípus, amely belső és külső tudásra épül.
  • Ismétlődő kiértékelési szkript, amely a vállalati érvényesítési mintákat mutatja be.
  • Egyértelmű frissítési útvonal: további eszközök, többügynök vezénylése, gazdagabb kiértékelés, üzembe helyezés.

Ezek a minták csökkentik a prototípustól a gyártásig tartó súrlódást: hozzáadhat adatforrásokat, érvényesítheti a szabályozást, és integrálhatja a monitorozást az alapvető logika újraírása nélkül.

Következő lépések

Ez az oktatóanyag bemutatja a fejlesztői folyamat 1. szakaszát – az ötlettől a prototípusig. Ez a minimális minta biztosítja a vállalati AI-fejlesztés alapjait. Az utazás folytatásához tekintse meg a következő szakaszokat:

Javasolt további fejlesztések

2. szakasz: Prototípus gyártásra

3. szakasz: Gyártásból bevezetésig

Erőforrások törlése

Ha már nincs rájuk szüksége, törölje az oktatóanyagban létrehozott erőforrásokat:

  1. Az ügynök törlése: Az ügynök automatikusan törlődik main.py (Python) vagy Program.cs (C#) végén. Ha megszakította a futtatást, törölje manuálisan az Ügynökök lapjáról a Foundry portálon.
  2. A kiértékelési futtatás törlése: Az Foundry portálon nyissa meg a Kiértékelés lapot, válassza ki a próbafuttatást, és törölje azt.
  3. Minta dokumentumok eltávolítása SharePointból: Ha a minta .docx fájlokat egy éles SharePoint webhelyre töltötte fel, távolítsa el őket a dokumentumtárból.
  4. (Nem kötelező) Törölje az Foundry-projektet: Ha csak ehhez az oktatóanyaghoz hozott létre projektet, törölje azt az Foundry portálról az összes társított erőforrás eltávolításához.

Kapcsolódó tartalom

  • Last updated on