教程：从想法到原型 - 构建和评估企业智能代理

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

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

git clone --no-checkout https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples
git sparse-checkout init --cone
git sparse-checkout set samples/python/enterprise-agent-tutorial/1-idea-to-prototype
git checkout
cd samples/python/enterprise-agent-tutorial/1-idea-to-prototype

git clone --no-checkout https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples
git sparse-checkout init --cone
git sparse-checkout set samples/csharp/enterprise-agent-tutorial/1-idea-to-prototype
git checkout
cd samples/csharp/enterprise-agent-tutorial/1-idea-to-prototype

提取 ZIP 后，请转到 samples/python/enterprise-agent-tutorial/1-idea-to-prototype。

提取 ZIP 后，请转到 samples/csharp/enterprise-agent-tutorial/1-idea-to-prototype。

enterprise-agent-tutorial/
└── 1-idea-to-prototype/
   ├── .env                             # Create this file (local environment variables)
   ├── .gitkeep
   ├── evaluate.py                      # Business evaluation framework
   ├── evaluation_results.json
   ├── main.py                          # Modern Workplace Assistant
   ├── questions.jsonl                  # Business test scenarios (4 questions)
   ├── requirements.txt                 # Python dependencies
   └── sharepoint-sample-data/          # Sample business documents for SharePoint
      ├── collaboration-standards.docx
      ├── data-governance-policy.docx
      ├── remote-work-policy.docx
      └── security-guidelines.docx

enterprise-agent-tutorial/
└── 1-idea-to-prototype/
   ├── ModernWorkplaceAssistant/        # Modern Workplace Assistant
   │   ├── Program.cs                   # Agent implementation with SharePoint + MCP
   │   ├── ModernWorkplaceAssistant.csproj
   │   └── .env                         # Environment variables (create this)
   ├── Evaluate/                        # Batch evaluation framework
   │   ├── Program.cs                   # Batch evaluation with built-in evaluators
   │   ├── Evaluate.csproj
   │   └── evaluation_results.json      # Example output (generated)
   ├── questions.jsonl                  # Business test scenarios
   └── README.md                        # Complete setup instructions

将.env.template复制到.env。

在.env目录中创建一个ModernWorkplaceAssistant文件。

# Foundry configuration
FOUNDRY_PROJECT_ENDPOINT=https://<your-project>.aiservices.azure.com
FOUNDRY_MODEL_NAME=gpt-4o-mini

# The Microsoft Learn MCP Server (optional)
MCP_SERVER_URL=https://learn.microsoft.com/api/mcp

# SharePoint integration (optional - requires connection name)
SHAREPOINT_CONNECTION_NAME=<your-sharepoint-connection-name>

# Foundry configuration
FOUNDRY_PROJECT_ENDPOINT=https://<your-project>.aiservices.azure.com
FOUNDRY_MODEL_NAME=gpt-4o-mini

# SharePoint integration (optional - requires connection name)
SHAREPOINT_CONNECTION_NAME=<your-sharepoint-connection-name>

# The Microsoft Learn MCP Server (optional)
MCP_SERVER_URL=https://learn.microsoft.com/api/mcp

python main.py
python evaluate.py

cd ModernWorkplaceAssistant
dotnet restore
dotnet run

cd ../Evaluate
dotnet restore
dotnet run

import os
import time
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    SharepointPreviewTool,
    SharepointGroundingToolParameters,
    ToolProjectConnection,
    MCPTool,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv
from openai.types.responses.response_input_param import (
    McpApprovalResponse,
)

using System;
using System.ClientModel;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using Azure.AI.Projects;
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
using DotNetEnv;
using OpenAI.Responses;

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    print(f"✅ Connected to Foundry: {endpoint}")

var credential = new DefaultAzureCredential();

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

sharepoint_connection_id = os.environ.get("SHAREPOINT_CONNECTION_ID")
sharepoint_tool = None

if sharepoint_connection_id:
    print("📁 Configuring SharePoint integration...")
    print(f"   Connection ID: {sharepoint_connection_id}")

    try:
        sharepoint_tool = SharepointPreviewTool(
            sharepoint_grounding_preview=SharepointGroundingToolParameters(
                project_connections=[
                    ToolProjectConnection(
                        project_connection_id=sharepoint_connection_id
                    )
                ]
            )
        )
        print("✅ SharePoint tool configured successfully")
    except Exception as e:
        print(f"⚠️  SharePoint tool unavailable: {e}")
        print("   Agent will operate without SharePoint access")
        sharepoint_tool = None
else:
    print("📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_ID not set)")

// Resolve connection name to connection ID via the Connections API
AIProjectConnection sharepointConnection = await projectClient.Connections.GetConnectionAsync(
    sharePointConnectionName, includeCredentials: false);

SharePointGroundingToolOptions sharepointToolOption = new()
{
    ProjectConnections = { new ToolProjectConnection(projectConnectionId: sharepointConnection.Id) }
};
sharepointTool = new SharepointAgentTool(sharepointToolOption);
Console.WriteLine($"✅ SharePoint tool configured successfully");

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

if mcp_server_url:
    print("📚 Configuring Microsoft Learn MCP integration...")
    print(f"   Server URL: {mcp_server_url}")

    try:
        mcp_tool = MCPTool(
            server_url=mcp_server_url,
            server_label="Microsoft_Learn_Documentation",
            require_approval="always",
        )
        print("✅ MCP tool configured successfully")
    except Exception as e:
        print(f"⚠️  MCP tool unavailable: {e}")
        print("   Agent will operate without Microsoft Learn access")
        mcp_tool = None
else:
    print("📚 MCP integration skipped (MCP_SERVER_URL not set)")

// MCP (Model Context Protocol) enables agents to access external data sources
// like Microsoft Learn documentation. The approval flow is handled in ChatWithAssistantAsync.
McpTool? mcpTool = null;

if (!string.IsNullOrEmpty(mcpServerUrl))
{
    Console.WriteLine($"📚 Configuring Microsoft Learn MCP integration...");
    Console.WriteLine($"   Server URL: {mcpServerUrl}");

    try
    {
        // Create MCP tool for Microsoft Learn documentation access
        // server_label must match pattern: ^[a-zA-Z0-9_]+$ (alphanumeric and underscores only)
        mcpTool = new McpTool("Microsoft_Learn_Documentation", new Uri(mcpServerUrl));
        Console.WriteLine($"✅ MCP tool configured successfully");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"⚠️  MCP tool unavailable: {ex.Message}");
        Console.WriteLine($"   Agent will operate without Microsoft Learn access");
    }
}
else
{
    Console.WriteLine($"📚 MCP integration skipped (MCP_SERVER_URL not set)");
}

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

// Create the agent using the v2 SDK with PromptAgentDefinition
Console.WriteLine($"🛠️  Creating agent with model: {modelDeploymentName}");

var agentDefinition = new PromptAgentDefinition(modelDeploymentName)
{
    Instructions = instructions
};

// Add tools to the agent definition
if (sharepointTool != null)
{
    agentDefinition.Tools.Add(sharepointTool);
    Console.WriteLine($"   ✓ SharePoint tool added");
}

if (mcpTool != null)
{
    agentDefinition.Tools.Add(mcpTool);
    Console.WriteLine($"   ✓ MCP tool added");
}

Console.WriteLine($"   Total tools: {agentDefinition.Tools.Count}");

// Create agent version
AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync(
    agentName: agentName,
    options: new(agentDefinition));

// Create a response client bound to this agent for conversations
responseClient = projectClient.OpenAI
    .GetProjectResponsesClientForAgent(agentVersion);

Console.WriteLine($"✅ Agent created successfully: {agentVersion.Name} (version {agentVersion.Version})");
return agentVersion;

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

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

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

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

# Define the data source for the evaluation run
data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_content",
        "content": [
            {"item": {"query": "What is Contoso's remote work policy?"}},
            {"item": {"query": "What are the security requirements for remote employees?"}},
            {"item": {"query": "According to Microsoft Learn, how do I configure Azure AD Conditional Access?"}},
            {"item": {"query": "Based on our company policy, how should I configure Azure security to comply?"}},
        ],
    },
    "input_messages": {
        "type": "template",
        "template": [
            {"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}
        ],
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent.name,
        "version": agent.version,
    },
}

# Create and submit the evaluation run
agent_eval_run: Union[RunCreateResponse, RunRetrieveResponse] = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name=f"Evaluation Run for Agent {agent.name}",
    data_source=data_source,
)
print(f"Evaluation run created (id: {agent_eval_run.id})")

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

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

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

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

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

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

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

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

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

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

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

# Poll until the evaluation run completes
while agent_eval_run.status not in ["completed", "failed"]:
    agent_eval_run = openai_client.evals.runs.retrieve(
        run_id=agent_eval_run.id,
        eval_id=eval_object.id
    )
    print(f"Waiting for eval run to complete... current status: {agent_eval_run.status}")
    time.sleep(5)

if agent_eval_run.status == "completed":
    print("\n✓ Evaluation run completed successfully!")
    print(f"Result Counts: {agent_eval_run.result_counts}")

    # Retrieve detailed output items
    output_items = list(
        openai_client.evals.runs.output_items.list(
            run_id=agent_eval_run.id,
            eval_id=eval_object.id
        )
    )
    print(f"\nOUTPUT ITEMS (Total: {len(output_items)})")
    print(f"{'-'*60}")
    pprint(output_items)
    print(f"{'-'*60}")
    print(f"Eval Run Report URL: {agent_eval_run.report_url}")
else:
    print("\n✗ Evaluation run failed.")

# Cleanup
openai_client.evals.delete(eval_id=eval_object.id)
print("Evaluation deleted")

project_client.agents.delete(agent_name=agent.name)
print("Agent deleted")

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

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

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