Tutorial: Ideia para prototipar - Constrói e avalie um agente empresarial

Este tutorial cobre a primeira fase da jornada do programador Microsoft Foundry: desde uma ideia inicial até um protótipo funcional. Constrói um assistente moderno no local de trabalho que combina conhecimento interno da empresa com orientação técnica externa, usando o SDK Microsoft Foundry.

Cenário de negócio: Crie um assistente de IA que ajude os colaboradores combinando:

  • Políticas da empresa (de documentos SharePoint)
  • Orientação técnica de implementação (do Microsoft Learn via MCP)
  • Soluções completas (combinando ambas as fontes para implementação empresarial)
  • Avaliação em lote para validar o desempenho dos agentes em cenários de negócio realistas

Resultado do tutorial: No final, tem um Assistente de Local de Trabalho Moderno em funcionamento que pode responder a questões de políticas, técnicas e de implementação combinada; um script de avaliação por lote repetível; e pontos de extensão claros (outras ferramentas, padrões multi-agente, avaliação mais rica).

Irá:

  • Construa um Assistente Moderno de Local de Trabalho com integração com SharePoint e MCP.
  • Demonstre cenários empresariais reais que combinam conhecimento interno e externo.
  • Implementar um tratamento robusto de erros e uma degradação gradual.
  • Crie um quadro de avaliação para testes focados no negócio.
  • Preparar a base para governação e implementação em produção.

Esta amostra mínima demonstra padrões prontos para empresas com cenários empresariais realistas.

Importante

O código deste artigo utiliza pacotes que estão atualmente em pré-lançamento. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e não a recomendamos para cargas de trabalho em produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos de Utilização Suplementares para Microsoft Azure Pré-visualizações.

Pré-requisitos

  • Uma subscrição do Azure. Se não tiveres um, cria um gratuitamente.
  • CLI do Azure 2.67.0 ou posterior, autenticado com az login (verificar com az version)
  • Um projeto Foundry com um modelo já implementado (por exemplo, gpt-4o-mini). Se não tiver: Crie um projeto e depois implemente um modelo (ver visão geral do modelo: Catálogo de modelos).
  • Python 3.10 ou posterior
  • .NET SDK 8.0 ou posterior (para o exemplo C#)
  • Uma ligação ao SharePoint configurada no seu projeto.
    • A ferramenta do SharePoint está em versão preliminar e requer a identidade delegada de um utilizador autenticado. A autenticação exclusiva da aplicação e a entidade de serviço não são suportadas.
    • Os programadores e os utilizadores finais precisam de uma licença do Microsoft 365 Copilot ou de acesso pay-as-you-go ativado, da função Foundry User no projeto e de, pelo menos, acesso de Leitura ao site do SharePoint de destino.
    • O site SharePoint e o projeto Foundry devem estar no mesmo tenant Microsoft Entra. Um agente pode usar uma ferramenta do SharePoint. Para instruções de configuração, consulte Usar a ferramenta SharePoint.
  • A função Foundry User para criar e testar o agente. Se criares uma ligação de projeto para autenticar um servidor MCP, também precisas da função de gestor de projeto do Foundry.
  • (Opcional) Git instalado para clonar o repositório de samples

Importante

As versões do SDK e a estrutura do repositório de exemplo podem mudar após a publicação deste artigo. Antes de começar, verifique o README do repositório de exemplo para as instruções de configuração mais recentes, versões de pacotes necessárias e configuração do ambiente. Se uma versão referenciada neste tutorial não estiver disponível em PyPI ou NuGet, use antes a versão publicada mais recente.

Obtenha o código de exemplo

Em vez de navegar por um grande diretório de repositório, use uma destas abordagens:

Opção A (clonar repositório de amostras inteiro)

Dica

O código usa Azure AI Projects 2.x e é incompatível com Azure AI Projects 1.x. Consulte a documentação do Foundry (clássico) para a versão 1.x do Azure AI Projects.

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

Opção B (checkout esparso apenas neste tutorial - download reduzido)

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

Opção C (Descarregar o ZIP do repositório)

Descarregue o repositório ZIP, extraia-o para o seu ambiente local e vá à pasta do tutorial.

Importante

Para adoção em produção, use um repositório autónomo. Este tutorial utiliza o repositório de samples partilhados. O descarregamento esparso minimiza o ruído local.

Descarregue o código Python agora

Depois de extrair o ZIP, vá a samples/python/enterprise-agent-tutorial/1-idea-to-prototype.

A estrutura mínima contém apenas ficheiros essenciais:

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

Executar o exemplo

Começa por executar o agente para veres funcionalidades a funcionar antes de te aprofundares nos detalhes da implementação.

Configuração do ambiente e ambiente virtual

  1. Instale os runtimes de linguagem necessários, ferramentas globais e extensões VS Code conforme descrito em Preparar o seu ambiente de desenvolvimento.

  2. Verifique se requirements.txt utiliza estas versões publicadas do pacote:

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

Dependências de instalação:

python -m pip install -r requirements.txt

Verifica se a instalação foi bem-sucedida. Vê Successfully installed azure-ai-projects-... (Python) ou Restore completed (.NET) sem erros.

  1. Encontre o endpoint do seu projeto no ecrã de boas-vindas do projeto.

    Captura de ecrã do ecrã de boas-vindas Microsoft Foundry Models mostrando a URL do endpoint e o botão de cópia.

  2. Configurar .env.

    Defina os valores de ambiente necessários para a sua língua.

Copiar .env.template para .env.

# Foundry configuration
FOUNDRY_PROJECT_ENDPOINT=https://<your-resource>.services.ai.azure.com/api/projects/<your-project>
FOUNDRY_MODEL_NAME=gpt-4o-mini

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

# SharePoint integration (optional - requires a project connection ID)
SHAREPOINT_CONNECTION_ID=/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<foundry-account>/projects/<project>/connections/<connection-name>

Confirmar .env contém valores válidos abrindo o ficheiro e verificando que FOUNDRY_PROJECT_ENDPOINT começa com https:// e FOUNDRY_MODEL_NAME corresponde ao nome de um modelo implementado no seu projeto.

Para integração com SharePoint, defina SHAREPOINT_CONNECTION_ID em Python o ID completo da ligação do projeto. Em C#, defina SHAREPOINT_CONNECTION_NAME para o nome da ligação.

Dica

Para obter o seu ID de inquilino, execute:

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

Para obter o endpoint do seu projeto, abra o seu projeto no portal Foundry e copie o valor aí mostrado.

Agente de execução e avaliação

python main.py
python evaluate.py

Saída esperada (primeira execução do agente)

Corrida bem-sucedida com SharePoint:

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

Degradação elegante sem SharePoint:

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

Agora que tem um agente em funcionamento, as secções seguintes explicam como funciona. Não precisa de agir enquanto lê estas secções — são para explicação.

Configurar exemplos de documentos empresariais do SharePoint

  1. Vai ao teu site SharePoint (configurado na ligação).

  2. Crie a biblioteca de documentos "Políticas da Empresa" (ou use os "Documentos" existentes).

  3. Carregue os quatro documentos de exemplo Word fornecidos na pasta sharepoint-sample-data:

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

  4. Verifique se quatro documentos aparecem na biblioteca antes de prosseguir.

Estrutura da amostra

📁 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

Compreenda a implementação do assistente

Nota

Esta secção é apenas para referência — não é necessária qualquer ação. Explica o código que já usaste.

Esta secção explica o código central em main.py (Python) ou ModernWorkplaceAssistant/Program.cs (C#). Já executaste o agente. Depois de o ler, pode:

  • Adicione novas ferramentas de dados internas e externas.
  • Expanda instruções dinâmicas.
  • Introduzir orquestração multi-agente.
  • Melhorar a observabilidade e o diagnóstico.

O código divide-se nas seguintes secções principais, ordenadas conforme aparecem no código de exemplo completo:

  1. Configurar importações e autenticação
  2. Configurar autenticação para Azure
  3. Configurar a ferramenta SharePoint
  4. Configurar a ferramenta MCP
  5. Crie o agente e ligue as ferramentas
  6. Converse com o agente

Importante

O código deste artigo utiliza pacotes que estão atualmente em pré-lançamento. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e não a recomendamos para cargas de trabalho em produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos de Utilização Suplementares para Microsoft Azure Pré-visualizações.

Importações e configuração de autenticação

O código utiliza várias bibliotecas clientes do Microsoft Foundry SDK para criar um agente empresarial robusto.

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

Configurar autenticação no Azure

Antes de criar o seu agente, configure a autenticação na 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}")

Crie a ferramenta SharePoint para o agente

O agente utiliza SharePoint e pode aceder a documentos de políticas e procedimentos da empresa armazenados lá. Configura a ligação ao SharePoint no teu código.

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

Crie a ferramenta MCP para o agente

O suporte ao SDK .NET para a ferramenta MCP está atualmente em pré-visualização.

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

Crie o agente e ligue as ferramentas

Cria o agente e liga as ferramentas SharePoint e MCP.

print(f"🛠️  Creating agent with model: {os.environ['FOUNDRY_MODEL_NAME']}")

tools = []
if sharepoint_tool:
    tools.append(sharepoint_tool)
    print("   ✓ SharePoint tool added")
if mcp_tool:
    tools.append(mcp_tool)
    print("   ✓ MCP tool added")

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

agent = project_client.agents.create_version(
    agent_name="Modern Workplace Assistant",
    definition=PromptAgentDefinition(
        model=os.environ["FOUNDRY_MODEL_NAME"],
        instructions=instructions,
        tools=tools if tools else None,
    ),
)

print(f"✅ Agent created successfully (name: {agent.name}, version: {agent.version})")

Converse com o agente

Por fim, implemente um ciclo interativo para conversar com o agente.

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

Saída esperada do código de exemplo do agente

Quando executa o agente, vê uma saída semelhante ao exemplo seguinte. O resultado mostra a configuração bem-sucedida da ferramenta e as respostas dos agentes a cenários de negócio:

✅ 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

Avalie o assistente utilizando a avaliação em lote

O quadro de avaliação testa cenários de negócio realistas utilizando a capacidade de avaliação lote do SDK Microsoft Foundry. Em vez de uma abordagem local personalizada, este padrão utiliza os avaliadores incorporados (builtin.violence, builtin.fluency, builtin.task_adherence) e a openai_client.evals API para executar avaliações escaláveis e repetíveis na cloud.

A avaliação do Python na cloud requer a função de Foundry User, um modelo GPT implementado que suporte conclusões de chat e uma região que suporte os avaliadores selecionados. Revise as regiões suportadas antes de continuar.

Este quadro de avaliação demonstra:

  • Segmentação de agentes: A avaliação executa consultas diretamente ao seu agente usando azure_ai_target_completions.
  • Avaliadores incorporados: Segurança (deteção de violência), qualidade (fluência) e métricas de adesão às tarefas.
  • Execução baseada na cloud: Elimina requisitos de computação local e suporta integração CI/CD.
  • Resultados estruturados: Rótulos de aprovação/reprovação, pontuações e raciocínio para cada caso de teste.

O código divide-se nas seguintes secções principais:

  1. Configura a avaliação.
  2. Executa a avaliação em lote.
  3. Recuperar os resultados da avaliação.

Dica

Para orientações detalhadas sobre avaliações em lote, consulte Executar avaliações na cloud. Para encontrar uma lista abrangente de avaliadores incorporados disponíveis no Foundry, consulte Observabilidade em IA generativa.

Nota

A amostra de C# utiliza uma abordagem local de avaliação por lote com ProjectResponsesClient em vez da API cloud openai_client.evals mostrada em Python. Envia consultas ao agente, verifica as respostas com palavras-chave esperadas e escreve resultados em evaluation_results.json. Consulte a amostra do SDK de Avaliações C# para padrões de avaliação em nuvem em C#.

Configurar a avaliação

Primeiro, crie um objeto de avaliação que defina o seu esquema de dados e critérios de teste. A avaliação utiliza avaliadores incorporados para deteção de violência, fluência e adesão às tarefas.

Em Python, usa diretamente o cliente OpenAI. Em C#, obtenha um EvaluationClient do cliente do projeto:

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

O testing_criteria array especifica quais os avaliadores a executar:

  • builtin.violence: Deteta conteúdo violento ou prejudicial nas respostas.
  • builtin.fluency: Avalia a qualidade da resposta e a legibilidade (requer uma implementação de modelo).
  • builtin.task_adherence: Avalia se o agente seguiu corretamente as instruções.

Execute a avaliação em lote

Crie uma sessão de avaliação que tenha como alvo o seu agente. A azure_ai_target_completions fonte de dados envia questões ao seu agente e recolhe respostas para avaliação:

# 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 configuração:

  • Tipo: azure_ai_target_completions encaminha consultas através do seu agente
  • fonte: Conteúdo em linha com consultas de teste (também pode usar um ID de ficheiro de conjunto de dados)
  • input_messages: Modelo que formata cada consulta para o agente
  • alvo: Especifica o nome e a versão do agente a avaliar

Recuperar resultados da avaliação

Monitorize a execução da avaliação até que termine e, em seguida, obtenha os itens de saída detalhados.

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

Antes de analisar os itens de saída individuais, confirme que a execução da avaliação está concluída e Result Counts mostra errored: 0. Se a execução falhar, verifique o seu papel, região selecionada, modelo implementado e suporte ao avaliador.

Cada item de saída inclui:

  • Rótulo: Resultado binário de aprovação ou reprovação
  • Pontuação: Pontuação numérica na escala do avaliador
  • Razão: Explicação do motivo pelo qual a pontuação foi atribuída (para avaliadores baseados em LLM)

Resultado esperado da avaliação em lote (evaluate.py)

Quando executas o script de avaliação, vês uma saída semelhante ao exemplo seguinte. O resultado mostra a criação do objeto de avaliação, submissão da execução e recuperação dos resultados:

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

Compreender os resultados das avaliações

As avaliações em lote fornecem resultados estruturados que pode visualizar no portal Foundry ou recuperar programaticamente. Cada item de saída inclui:

Campo Descrição
Etiqueta Resultado binário "passar" ou "reprovar" baseado no limiar
Banda sonora Pontuação numérica (a escala depende do tipo de avaliador)
Limiar O limiar que determina a aprovação/não aprovação
Razão Explicação gerada por LLM para a pontuação (quando aplicável)

Escalas de pontuação por tipo de avaliador:

  • Avaliadores de qualidade (fluência, coerência): escala 1-5
  • Avaliadores de segurança (violência, autoagressão): escala de gravidade 0-7 (menor é o mais seguro)
  • Avaliadores de tarefas (task_adherence): escala 1-5

Também pode consultar resultados detalhados no portal da Foundry selecionando Avaliação do seu projeto e selecionando a execução de avaliação. O portal disponibiliza visualizações, filtragem e opções de exportação.

Dica

Para cenários de produção, considere executar avaliações como uma parte do seu pipeline de CI/CD. Veja Como executar uma avaliação em Azure DevOps, e Avalie continuamente os seus agentes de IA para padrões de integração.

Resolução de problemas

Sintoma Causa Resolução
DefaultAzureCredential Erro de autenticação Sessão de CLI do Azure expirada ou não iniciada Executar az login e tentar novamente
Model deployment not found O nome do modelo em .env não corresponde a uma implementação no teu projeto Abra o seu projeto no portal Foundry, verifique Implementações e atualize FOUNDRY_MODEL_NAME em .env
A integração do SharePoint é ignorada A variável de ambiente do SharePoint não está definida Em Python, define SHAREPOINT_CONNECTION_ID para o ID de ligação completo do projeto. Em C#, defina SHAREPOINT_CONNECTION_NAME para o nome da ligação.
SharePoint tool configured mas o agente não consegue encontrar documentos Os documentos não são carregados, a ligação está incorreta ou o utilizador iniciado não tem acesso Verifique se os documentos estão na biblioteca configurada, se a ligação aponta para essa biblioteca e se o utilizador com sessão iniciada tem acesso de Leitura. Use autenticação delegada de utilizador no mesmo tenant Microsoft Entra do projeto Foundry.
Tempo limite ou erro de ligação da ferramenta MCP O servidor MCP do Microsoft Learn está inacessível Verifique se MCP_SERVER_URL está definido como https://learn.microsoft.com/api/mcp e se a sua rede permite saída HTTPS
A criação de ligação ao projeto MCP é negada A conta não tem o papel de projeto exigido Atribua a função Gestor de Projetos do Foundry para criar a ligação e, em seguida, tente novamente.
A avaliação na cloud não pode iniciar ou um avaliador não é suportado A região do projeto, modelo ou combinação do avaliador não é suportada Verifique se a região do seu projeto suporta o avaliador e que o modelo GPT implementado suporta a conclusão de chat.
403 Forbidden no SharePoint Permissões insuficientes no site SharePoint Confirme que a sua identidade com sessão iniciada tem, pelo menos, acesso de Leitura à biblioteca de documentos do SharePoint e a função de Utilizador do Foundry no projeto.

Resumo

Agora tens:

  • Um protótipo funcional de agente único, fundamentado em conhecimento interno e externo.
  • Um script de avaliação repetível que demonstra padrões de validação empresarial.
  • Um caminho claro de atualização: mais ferramentas, orquestração multi-agente, avaliação mais enriquecida, implementação.

Estes padrões reduzem o atrito entre protótipo e produção: pode adicionar fontes de dados, impor a governação e integrar a monitorização sem reescrever a lógica central.

Próximos passos

Este tutorial demonstra a Fase 1 da jornada do programador – da ideia ao protótipo. Esta amostra mínima fornece a base para o desenvolvimento de IA empresarial. Para continuar a sua jornada, explore as próximas etapas:

Sugestões de melhorias adicionais

Fase 2: Protótipo para produção

Fase 3: Da produção à adoção

Liberar recursos

Quando já não precisares deles, apaga os recursos que criaste neste tutorial:

  1. Eliminar o agente: O agente é automaticamente eliminado no final de main.py (Python) ou Program.cs (C#). Se interrompeste a execução, apaga-a manualmente da página de Agentes no portal da Foundry.
  2. Apagar a execução de avaliação: No portal Foundry, vá a Avaliação, selecione a execução de avaliação e elimine-a.
  3. Remover documentos de exemplo do SharePoint: Se carregaste os ficheiros de exemplo .docx para um site de SharePoint de produção, remove-os da biblioteca de documentos.
  4. (Opcional) Eliminar o projeto Foundry: Se criou um projeto apenas para este tutorial, elimine-o do portal Foundry para remover todos os recursos associados.

Conteúdo relacionado

  • Last updated on