자습서: 프로토타입에 대한 아이디어 - 엔터프라이즈 에이전트 빌드 및 평가

이 자습서에서는 초기 아이디어에서 작업 프로토타입에 이르기까지 Microsoft Foundry 개발자 경험의 첫 번째 단계를 설명합니다. Microsoft Foundry SDK를 사용하여 내부 회사 지식과 외부 기술 지침을 결합하는 최신 작업 공간 도우미 를 빌드합니다.

비즈니스 시나리오: 다음을 결합하여 직원을 돕는 AI 도우미를 만듭니다.

회사 정책 (SharePoint 문서)
기술 구현 지침 (MCP를 통한 Microsoft Learn에서)
전체 솔루션 (비즈니스 구현을 위한 두 원본 결합)
실제 비즈니스 시나리오에서 에이전트 성능을 검증하기 위한 일괄 평가

자습서 결과: 끝까지 진행하면 정책, 기술 및 결합 구현 질문에 답할 수 있는 최신 Workplace Assistant가 실행되고, 반복 가능한 일괄 평가 스크립트와 명확한 확장 지점(기타 도구, 다중 에이전트 패턴, 보다 풍부한 평가)을 얻게 됩니다.

너는 할 거야:

SharePoint 및 MCP 통합을 사용하여 최신 Workplace Assistant를 빌드합니다.
내부 및 외부 지식을 결합한 실제 비즈니스 시나리오를 보여 줍니다.
강력한 오류 처리 및 점진적 성능 저하를 구현합니다.
비즈니스 중심 테스트를 위한 평가 프레임워크를 만듭니다.
거버넌스 및 프로덕션 배포를 위한 기초를 준비합니다.

이 최소 샘플은 현실적인 비즈니스 시나리오를 사용하는 엔터프라이즈 지원 패턴을 보여 줍니다.

중요합니다

이 문서의 코드는 현재 미리 보기로 제공되는 패키지를 사용합니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

필수 조건

Azure 구독 및 CLI 인증(az login)
Azure CLI 2.67.0 이상(확인은 az version로 확인)
배포된 모델(예: )이 있는 Foundry gpt-4o-mini입니다. 없는 경우: 프로젝트를 만든 다음 모델을 배포합니다(모델 개요: 모델 카탈로그 참조).
Python 3.10 이상
프로젝트에 구성된 SharePoint 연결(SharePoint 도구 설명서)

비고

SharePoint 연결을 위해 Foundry 프로젝트를 구성하려면 SharePoint 도구 설명서를 참조하세요.
(선택 사항) 샘플 리포지토리를 복제하기 위해 설치된 Git

1단계: 샘플 코드 가져오기

큰 리포지토리 트리를 탐색하는 대신 다음 방법 중 하나를 사용합니다.

옵션 A(전체 샘플 리포지토리 복제)

팁 (조언)

코드는 Foundry 프로젝트(새) API(미리 보기) 를 사용하며 Foundry 프로젝트(클래식) API와 호환되지 않습니다.

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

옵션 B(이 자습서에서는 스파스 체크 아웃만 제공 - 다운로드 감소)

git clone --no-checkout https://github.com/azure-ai-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

필요에 따라 경로 csharp 또는 java 변형을 반복합니다.

옵션 C(리포지토리의 ZIP 다운로드)

리포지토리 ZIP을 다운로드하여 로컬 환경에 추출한 다음 자습서 폴더로 이동합니다.

중요합니다

프로덕션 채택의 경우 독립 실행형 리포지토리를 사용합니다. 이 자습서에서는 공유 샘플 리포지토리를 사용합니다. 스파스 체크 아웃은 로컬 노이즈를 최소화합니다.

지금 Python 코드 다운로드

최소 구조에는 필수 파일만 포함됩니다.

enterprise-agent-tutorial/
└── 1-idea-to-prototype/
    ├── main.py                          # Modern Workplace Assistant
    ├── evaluate.py                      # Business evaluation framework
    ├── questions.jsonl                  # Business test scenarios (4 questions)
    ├── requirements.txt                 # Python dependencies
    ├── .env.template                    # Environment variables template
    ├── README.md                        # Complete setup instructions
    ├── MCP_SERVERS.md                   # MCP server configuration guide
    ├── sharepoint-sample-data           # Sample business documents for SharePoint
        └── collaboration-standards.docx # Sample content for policies
        └── remote-work-policy.docx      # Sample content for policies
        └── security-guidelines.docx     # Sample content for policies
        └── data-governance-policy.docx  # Sample content for policies

2단계: 즉시 샘플 실행

먼저 에이전트를 실행하여 구현 세부 정보를 살펴보기 전에 작업 기능을 확인합니다.

환경 설정 및 가상 환경

개발 환경 준비에 설명된 대로 필요한 언어 런타임, 전역 도구 및 VS Code 확장을 설치합니다.
requirements.txt에서 종속성을 설치합니다.
```
pip install -r requirements.txt
```
환영 화면에서 엔드포인트를 복사하세요. 다음 단계에서 사용합니다.

.env 구성.

.env.template를 .env로 복사하고 구성합니다.

# Foundry Configuration  
PROJECT_ENDPOINT=https://<your-project>.aiservices.azure.com
MODEL_DEPLOYMENT_NAME=gpt-4o-mini
AI_FOUNDRY_TENANT_ID=<your-tenant-id>

# The Microsoft Learn MCP Server (public authoritative Microsoft docs index)
MCP_SERVER_URL=https://learn.microsoft.com/api/mcp

# SharePoint Integration (Optional - requires connection setup)
SHAREPOINT_RESOURCE_NAME=your-sharepoint-connection
SHAREPOINT_SITE_URL=https://<your-company>.sharepoint.com/teams/your-site

팁 (조언)

테넌트 ID를 가져오려면 다음을 실행합니다.

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

프로젝트 엔드포인트를 얻으려면 Foundry 포털에서 프로젝트를 열고 거기에 표시된 값을 복사합니다.

에이전트 및 평가 실행

python main.py
python evaluate.py

예상 출력(에이전트 처음 실행)

SharePoint를 사용하여 성공적으로 실행:

🤖 Creating Modern Workplace Assistant...
✅ SharePoint connected: YourConnection
✅ Agent created: asst_abc123

SharePoint가 없는 우아한 성능 저하:

⚠️  SharePoint connection not found: Connection 'YourConnection' not found
✅ Agent created: asst_abc123

이제 작업 에이전트가 있으므로 다음 섹션에서는 작동 방식을 설명합니다. 이러한 섹션을 읽는 동안 아무 작업도 수행할 필요가 없습니다. 설명용입니다.

3단계: 샘플 SharePoint 비즈니스 문서 설정

SharePoint 사이트(연결에 설정된)로 이동합니다.
문서 라이브러리 "회사 정책"을 만들거나 기존 "문서"를 사용합니다.
폴더에 제공된 4개의 샘플 Word 문서를 업로드합니다 sharepoint-sample-data .
- remote-work-policy.docx
- security-guidelines.docx
- collaboration-standards.docx
- data-governance-policy.docx

샘플 구조

📁 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

4단계: 도우미 구현 이해

이 섹션에서는 main.py의 핵심 코드를 설명합니다. 에이전트를 이미 실행했습니다. 이 섹션은 개념적이며 변경이 필요하지 않습니다. 읽은 후 다음을 수행할 수 있습니다.

새 내부 및 외부 데이터 도구를 추가합니다.
동적 지침을 확장합니다.
다중 에이전트 오케스트레이션을 소개합니다.
관찰 가능성 및 진단을 향상시킵니다.

코드는 전체 샘플 코드에 표시되는 순서대로 다음의 주요 섹션으로 나뉩니다.

가져오기 및 인증 구성
Azure에 대한 인증 구성
SharePoint 도구 구성
MCP 도구 구성
에이전트를 만들고 도구 연결
에이전트와 대화

중요합니다

가져오기 및 인증 설정

이 코드는 Microsoft Foundry SDK의 여러 클라이언트 라이브러리를 사용하여 강력한 엔터프라이즈 에이전트를 만듭니다.

import os
import time
from azure.ai.agents import AgentsClient
from azure.ai.agents.models import (
    SharepointTool,
    SharepointGroundingToolParameters,
    McpTool,
    RunHandler,
    ToolApproval
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Import for connection resolution
try:
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import ConnectionType
    HAS_PROJECT_CLIENT = True
except ImportError:
    HAS_PROJECT_CLIENT = False

Azure에서 인증 구성

에이전트를 만들기 전에 Foundry에 대한 인증을 설정합니다.

# Support default Azure credentials
credential = DefaultAzureCredential()

agents_client = AgentsClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=credential,
)
print(f"✅ Connected to Azure AI Foundry: {os.environ['PROJECT_ENDPOINT']}")

에이전트에 대한 SharePoint 도구 만들기

에이전트는 SharePoint를 사용하고 거기에 저장된 회사 정책 및 프로시저 문서에 액세스할 수 있습니다. 코드에서 SharePoint에 대한 연결을 설정합니다.

# Create SharePoint tool with the full ARM resource ID
sharepoint_tool = SharepointTool(connection_id=connection_id)
print(f"✅ SharePoint tool configured successfully")

에이전트에 대한 MCP 도구 만들기

# MCP (Model Context Protocol) enables agents to access external data sources
# like Microsoft Learn documentation. The approval flow is handled automatically
# in the chat_with_assistant function.
from azure.ai.agents.models import McpTool

mcp_server_url = os.environ.get("MCP_SERVER_URL")
mcp_tool = None

if mcp_server_url:
    print(f"📚 Configuring Microsoft Learn MCP integration...")
    print(f"   Server URL: {mcp_server_url}")
    
    try:
        # Create MCP tool for Microsoft Learn documentation access
        # server_label must match pattern: ^[a-zA-Z0-9_]+$ (alphanumeric and underscores only)
        mcp_tool = McpTool(
            server_url=mcp_server_url,
            server_label="Microsoft_Learn_Documentation"
        )
        print(f"✅ MCP tool configured successfully")
    except Exception as e:
        print(f"⚠️  MCP tool unavailable: {e}")
        print(f"   Agent will operate without Microsoft Learn access")
        mcp_tool = None
else:
    print(f"📚 MCP integration skipped (MCP_SERVER_URL not set)")

에이전트를 만들고 도구 연결

이제 에이전트를 만들고 SharePoint 및 MCP 도구를 연결합니다.

# Create the agent using Agent SDK v2 with available tools
print(f"🛠️  Creating agent with model: {os.environ['MODEL_DEPLOYMENT_NAME']}")

# Build tools list with proper serialization
tools = []

# Add SharePoint tool using .definitions property
if sharepoint_tool:
    tools.extend(sharepoint_tool.definitions)
    print(f"   ✓ SharePoint tool added")

# Add MCP tool using .definitions property
if mcp_tool:
    tools.extend(mcp_tool.definitions)
    print(f"   ✓ MCP tool added")

print(f"   Total tools: {len(tools)}")

# Create agent with or without tools
if tools:
    agent = agents_client.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="Modern Workplace Assistant",
        instructions=instructions,
        tools=tools
    )
else:
    agent = agents_client.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="Modern Workplace Assistant",
        instructions=instructions,
    )

print(f"✅ Agent created successfully: {agent.id}")
return agent

에이전트와 대화

마지막으로 대화형 루프를 구현하여 에이전트와 대화합니다.

# Get response from the agent
print("🤖 ASSISTANT RESPONSE:")
response, status = chat_with_assistant(agent.id, scenario['question'])

에이전트 샘플 코드의 예상 출력(main.py)

에이전트를 실행하면 다음 예제와 유사한 출력이 표시됩니다. 출력은 비즈니스 시나리오에 대한 성공적인 도구 구성 및 에이전트 응답을 보여 줍니다.

$ python main.py
✅ Connected to Foundry
🚀 Foundry - Modern Workplace Assistant
Tutorial 1: Building Enterprise Agents with Agent SDK v2
======================================================================
🤖 Creating Modern Workplace Assistant...
📁 Configuring SharePoint integration...
   Connection name: ContosoCorpPoliciesProcedures
   🔍 Resolving connection name to ARM resource ID...
   ✅ Resolved
✅ 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

======================================================================
🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION
======================================================================
This demonstration shows how AI agents solve real business problems
using the Azure AI Agents SDK v2.
======================================================================

📊 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
--------------------------------------------------
🤖 ASSISTANT 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
--------------------------------------------------
🤖 ASSISTANT 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
--------------------------------------------------
🤖 ASSISTANT 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:
   • Agent SDK v2 usage for enterprise AI
   • Proper thread and message management
   • 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

5단계: 일괄 처리로 도우미 평가

평가 프레임워크 코드는 SharePoint 정책과 Microsoft Learn 기술 지침을 결합하는 현실적인 비즈니스 시나리오를 테스트합니다. 이 방법은 여러 테스트 사례에서 에이전트 성능의 유효성을 검사하기 위한 일괄 처리 평가 기능을 보여 줍니다. 평가는 키워드 기반 접근 방식을 사용하여 에이전트가 예상된 정보 원본을 통합하는 관련 응답을 제공하는지 여부를 평가합니다.

이 평가 프레임워크는 다음을 테스트합니다.

회사 정책 질문에 대한 SharePoint 통합
기술 지침 질문을 위한 MCP 통합
내부 및 외부 지식이 모두 필요한 결합된 시나리오
키워드 일치 및 길이 분석을 사용하여 응답 품질

코드는 다음 주요 섹션으로 나뉩니다.

평가 데이터를 로드합니다.
일괄 처리 평가를 실행합니다.
평가 결과를 컴파일합니다.

평가 데이터 로드

이 섹션에서는 평가 프레임워크에서 테스트 질문을 questions.jsonl로드합니다. 이 파일에는 에이전트의 다양한 측면을 테스트하는 비즈니스 시나리오가 포함되어 있습니다.

{"question": "What is Contoso's remote work policy?", "expected_source": "sharepoint", "test_type": "sharepoint_only", "explanation": "Forces SharePoint tool usage - answer must contain Contoso-specific policy details", "validation": "check_for_contoso_specifics"}
{"question": "What are Contoso's security protocols for remote employees?", "expected_source": "sharepoint", "test_type": "sharepoint_only", "explanation": "Forces SharePoint tool usage - must retrieve specific security protocols from company policies", "validation": "check_for_contoso_specifics"}
{"question": "How does Contoso classify confidential business documents according to our data governance policy?", "expected_source": "sharepoint", "test_type": "sharepoint_only", "explanation": "Forces SharePoint tool usage - must retrieve data classification from governance policy", "validation": "check_for_contoso_specifics"}
{"question": "What collaboration tools are approved for internal use at Contoso?", "expected_source": "sharepoint", "test_type": "sharepoint_only", "explanation": "Forces SharePoint tool usage - must list specific tools from collaboration standards", "validation": "check_for_contoso_specifics"}
{"question": "According to Microsoft Learn documentation, what is the correct way to set up Azure Active Directory for remote workers? Include reference links.", "expected_source": "mcp", "test_type": "mcp_only", "explanation": "Forces MCP tool usage - must provide Microsoft Learn documentation with links", "validation": "check_for_microsoft_learn_links"}
{"question": "What does Microsoft Learn say about configuring Azure Security Center monitoring? Please provide the official documentation links.", "expected_source": "mcp", "test_type": "mcp_only", "explanation": "Forces MCP tool usage - must access Microsoft Learn for Security Center guidance with links", "validation": "check_for_microsoft_learn_links"}
{"question": "How do I implement data loss prevention in Microsoft 365 according to Microsoft's official documentation? Include links to the relevant Microsoft Learn articles.", "expected_source": "mcp", "test_type": "mcp_only", "explanation": "Forces MCP tool usage - must provide DLP implementation steps with documentation links", "validation": "check_for_microsoft_learn_links"}
{"question": "What are the steps to configure conditional access policies in Azure AD according to Microsoft Learn? Provide documentation links.", "expected_source": "mcp", "test_type": "mcp_only", "explanation": "Forces MCP tool usage - must provide conditional access guidance with Microsoft Learn links", "validation": "check_for_microsoft_learn_links"}
{"question": "Based on Contoso's remote work policy requirements, how should I implement Azure VPN Gateway? Include links to Microsoft documentation for each step.", "expected_source": "both", "test_type": "hybrid", "explanation": "Forces both tools - must combine Contoso policy requirements with Azure VPN implementation guidance and links", "validation": "check_for_both_sources"}
{"question": "What Azure services do I need to configure to meet Contoso's data governance requirements? Provide Microsoft Learn links for implementing each service.", "expected_source": "both", "test_type": "hybrid", "explanation": "Forces both tools - must map Contoso governance policy to specific Azure services with documentation links", "validation": "check_for_both_sources"}
{"question": "How do I configure Microsoft Teams to comply with Contoso's collaboration standards? Include Microsoft documentation links for the setup.", "expected_source": "both", "test_type": "hybrid", "explanation": "Forces both tools - must combine Contoso collaboration standards with Teams configuration guidance and links", "validation": "check_for_both_sources"}
{"question": "What Azure security services should I implement to align with Contoso's incident response procedures? Provide links to Microsoft Learn for each service.", "expected_source": "both", "test_type": "hybrid", "explanation": "Forces both tools - must connect Contoso security policy to Azure security services with documentation links", "validation": "check_for_both_sources"}

# NOTE: This code is a non-runnable snippet of the larger sample code from which it is taken.
def load_test_questions(filepath="questions.jsonl"):
    """Load test questions from JSONL file"""
    questions = []
    with open(filepath, 'r') as f:
        for line in f:
            questions.append(json.loads(line.strip()))
    return questions

일괄 처리 평가 실행

def run_evaluation(agent_id):
    """
    Run evaluation with test questions using Agent SDK v2.
    
    Args:
        agent_id: The ID of the agent to evaluate
        
    Returns:
        list: Evaluation results for each question
    """
    questions = load_test_questions()
    results = []
    
    print(f"🧪 Running evaluation with {len(questions)} test questions...")
    print("="*70)
    
    # Track results by test type
    stats = {
        "sharepoint_only": {"passed": 0, "total": 0},
        "mcp_only": {"passed": 0, "total": 0},
        "hybrid": {"passed": 0, "total": 0}
    }
    
    for i, q in enumerate(questions, 1):
        test_type = q.get("test_type", "unknown")
        expected_source = q.get("expected_source", "unknown")
        validation_type = q.get("validation", "default")
        
        print(f"\n📝 Question {i}/{len(questions)} [{test_type.upper()}]")
        print(f"   {q['question'][:80]}...")
        
        response, status = chat_with_assistant(agent_id, q["question"])
        
        # Validate response using source-specific checks
        passed, validation_details = validate_response(response, validation_type, expected_source)
        
        result = {
            "question": q["question"],
            "response": response,
            "status": status,
            "passed": passed,
            "validation_details": validation_details,
            "test_type": test_type,
            "expected_source": expected_source,
            "explanation": q.get("explanation", "")
        }
        results.append(result)
        
        # Update stats
        if test_type in stats:
            stats[test_type]["total"] += 1
            if passed:
                stats[test_type]["passed"] += 1
        
        status_icon = "✅" if passed else "⚠️"
        print(f"{status_icon} Status: {status} | Tool check: {validation_details}")
    
    print("\n" + "="*70)
    print("📊 EVALUATION SUMMARY BY TEST TYPE:")
    print("="*70)
    for test_type, data in stats.items():
        if data["total"] > 0:
            pass_rate = (data["passed"] / data["total"]) * 100
            icon = "✅" if pass_rate >= 75 else "⚠️" if pass_rate >= 50 else "❌"
            print(f"{icon} {test_type.upper()}: {data['passed']}/{data['total']} passed ({pass_rate:.1f}%)")
    
    return results

평가 결과 컴파일

def calculate_and_save_results(results):
    """Calculate pass rate and save results"""
    # Calculate pass rate
    passed = sum(1 for r in results if r.get("passed", False))
    total = len(results)
    pass_rate = (passed / total * 100) if total > 0 else 0
    
    print(f"\n📊 Overall Evaluation Results: {passed}/{total} questions passed ({pass_rate:.1f}%)")
    
    # Save results
    with open("evaluation_results.json", "w") as f:
        json.dump(results, f, indent=2)
    
    print(f"💾 Results saved to evaluation_results.json")
    
    # Print summary of failures
    failures = [r for r in results if not r.get("passed", False)]
    if failures:
        print(f"\n⚠️  Failed Questions ({len(failures)}):")
        for r in failures:
            print(f"   - [{r['test_type']}] {r['question'][:60]}...")
            print(f"     Reason: {r['validation_details']}")

평가 샘플 코드의 예상 출력(evaluate.py)

평가 스크립트를 실행하면 다음 예제와 유사한 출력이 표시됩니다. 출력은 비즈니스 테스트 시나리오의 성공적인 실행 및 평가 메트릭 생성을 보여 줍니다.

python evaluate.py
✅ Connected to Foundry
🧪 Modern Workplace Assistant - Evaluation (Agent SDK v2)
======================================================================
🤖 Creating Modern Workplace Assistant...
📁 Configuring SharePoint integration...
   Connection name: ContosoCorpPoliciesProcedures
   🔍 Resolving connection name to ARM resource ID...
   ✅ Resolved
✅ 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
   Model: gpt-4o-mini
   Name: Modern Workplace Assistant
======================================================================
🧪 Running evaluation with 12 test questions...
======================================================================

📝 Question 1/12 [SHAREPOINT_ONLY]
   What is Contosoʹs remote work policy?...
✅ Status: completed | Tool check: Contoso-specific content: True

...

📝 Question 5/12 [MCP_ONLY]
   According to Microsoft Learn documentation, what is the correct way to set up Az...
✅ Status: completed | Tool check: Microsoft Learn links: True

...

📝 Question 12/12 [HYBRID]
   What Azure security services should I implement to align with Contosoʹs incident...
✅ Status: completed | Tool check: Contoso content: True, Learn links: True

======================================================================
📊 EVALUATION SUMMARY BY TEST TYPE:
======================================================================
✅ SHAREPOINT_ONLY: 4/4 passed (100.0%)
✅ MCP_ONLY: 4/4 passed (100.0%)
✅ HYBRID: 4/4 passed (100.0%)

📊 Overall Evaluation Results: 12/12 questions passed (100.0%)
💾 Results saved to evaluation_results.json

추가 평가 자산

평가는 각 질문에 대한 메트릭(키워드 적중률, 길이 휴리스틱)을 사용하여 evaluation_results.json을 생성합니다. 이 파일을 다음으로 확장할 수 있습니다.

모델 기반 점수 매기기 프롬프트를 사용합니다.
구조화된 출력 유효성 검사를 도입합니다.
대기 시간 및 토큰 사용량을 기록합니다.

다음은 JSON 출력 구조의 샘플입니다.

[
  {
    "question": "What is Contoso's remote work policy?",
    "response": "Contoso's remote work policy includes the following key components: <...>",
    "status": "completed",
    "passed": true,
    "validation_details": "Contoso-specific content: True",
    "test_type": "sharepoint_only",
    "expected_source": "sharepoint",
    "explanation": "Forces SharePoint tool usage - answer must contain Contoso-specific policy details"
  },
  {
    "question": "What are Contoso's security protocols for remote employees?",
    "response": ...

    ...

  }
]

요약

이제 다음이 있습니다.

내부 및 외부 지식을 기반으로 하는 작동하는 단일 에이전트 프로토타입입니다.
엔터프라이즈 유효성 검사 패턴을 보여주는 반복 가능한 평가 스크립트입니다.
업그레이드 경로 지우기: 더 많은 도구, 다중 에이전트 오케스트레이션, 더 풍부한 평가, 배포.

이러한 패턴은 프로토타입 간 마찰을 줄입니다. 핵심 논리를 다시 작성하지 않고도 데이터 원본을 추가하고, 거버넌스를 적용하고, 모니터링을 통합할 수 있습니다.

다음 단계

이 자습서에서는 아이디어에서 프로토타입에 이르는 개발자 경험의 1단계 를 보여 줍니다. 이 최소 샘플은 엔터프라이즈 AI 개발을 위한 토대를 제공합니다. 여정을 계속하려면 다음 단계를 탐색합니다.

제안된 추가 개선 사항

데이터 원본을 더 추가합니다(Azure AI Search, 기타 원본).
고급 평가 방법(AI 지원 평가)을 구현합니다.
비즈니스별 작업을 위한 사용자 지정 도구를 만듭니다.
대화 메모리 및 개인 설정을 추가합니다.

2단계: 프로토타입을 프로덕션으로

3단계: 프로덕션에서 채택까지

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-22

다음을 통해 공유

자습서: 프로토타입에 대한 아이디어 - 엔터프라이즈 에이전트 빌드 및 평가

필수 조건

1단계: 샘플 코드 가져오기

옵션 A(전체 샘플 리포지토리 복제)

옵션 B(이 자습서에서는 스파스 체크 아웃만 제공 - 다운로드 감소)

옵션 C(리포지토리의 ZIP 다운로드)

2단계: 즉시 샘플 실행

환경 설정 및 가상 환경

에이전트 및 평가 실행

예상 출력(에이전트 처음 실행)

3단계: 샘플 SharePoint 비즈니스 문서 설정

샘플 구조

4단계: 도우미 구현 이해

가져오기 및 인증 설정

Azure에서 인증 구성

에이전트에 대한 SharePoint 도구 만들기

에이전트에 대한 MCP 도구 만들기

에이전트를 만들고 도구 연결

에이전트와 대화

에이전트 샘플 코드의 예상 출력(main.py)

5단계: 일괄 처리로 도우미 평가

평가 데이터 로드

일괄 처리 평가 실행

평가 결과 컴파일

평가 샘플 코드의 예상 출력(evaluate.py)

추가 평가 자산

요약

다음 단계

제안된 추가 개선 사항

2단계: 프로토타입을 프로덕션으로

3단계: 프로덕션에서 채택까지

관련 콘텐츠

피드백

추가 리소스