Testare un agente ospitato

Testa il tuo agente ospitato a diversi livelli, dal test unitario dei singoli componenti ai test di integrazione end-to-end eseguiti su un agente Microsoft Foundry distribuito. Imparerai anche quando usare esecuzioni strutturate azd ai agent eval invece di test ad hoc con invoke.

Prerequisiti

• Progetto di agente ospitato inizializzato con codice e test dell'agente. Per creare un progetto, vedere Inizializzare un progetto agente.
• Le estensioni azd di Foundry installate. Per la procedura di installazione, vedere Installare le estensioni azd Foundry.
• Una sessione autenticata di Azure Developer CLI. Eseguire azd auth login se necessario.
• Strumenti di test necessari per la lingua, ad esempio pytest per Python o xUnit per .NET.
• Per i test di integrazione distribuiti e le valutazioni strutturate, un agente ospitato. Per distribuirne una, vedere Distribuire un agente ospitato.

Scegliere un livello di test

Logica dell'agente di unit test

Testare la logica di base dell'agente senza eseguire il server completo o chiamare modelli esterni.

# test_agent.py
import pytest
from unittest.mock import MagicMock

def test_tool_handler_returns_expected_format():
    """Test that your tool handler returns valid output."""
    from my_agent.tools import weather_tool

    result = weather_tool("Seattle")
    assert "temperature" in result
    assert isinstance(result["temperature"], (int, float))

def test_system_prompt_includes_required_context():
    """Verify system prompt contains key instructions."""
    from my_agent.config import SYSTEM_PROMPT

    assert "helpful assistant" in SYSTEM_PROMPT.lower()
    assert "weather" in SYSTEM_PROMPT.lower()

pytest test_agent.py

// AgentTests.cs
using Xunit;

public class AgentTests
{
    [Fact]
    public void ToolHandler_ReturnsExpectedFormat()
    {
        var result = WeatherTool.GetWeather("Seattle");
        Assert.Contains("temperature", result.Keys);
    }

    [Fact]
    public void SystemPrompt_IncludesRequiredContext()
    {
        Assert.Contains("helpful assistant",
            AgentConfig.SystemPrompt, StringComparison.OrdinalIgnoreCase);
    }
}

dotnet test

Eseguire test di integrazione locale

Testare l'agente completo in locale, comprese le chiamate ai modelli e la gestione dei protocolli.

Eseguire il test manualmente con invoke

1. Avviare l'agente in un terminale e inviare messaggi di test in un altro:

   # Terminal 1: Start the agent
   azd ai agent run
   
   # Terminal 2: Send test messages
   azd ai agent invoke --local "What's the weather in Seattle?"
   azd ai agent invoke --local "Can you summarize this document?" -f test-doc.json
   

Esegui un test con curl

1. Per i test ripetibili, usare curl o qualsiasi client HTTP:

   # Check the readiness probe (expects HTTP 200)
   curl -i http://localhost:8088/readiness
   
   # Test the responses protocol
   curl -s -X POST http://localhost:8088/responses \
     -H "Content-Type: application/json" \
     -d '{"input": "Hello, what can you do?"}' | jq .
   
   # Test with a specific session
   curl -s -X POST http://localhost:8088/responses \
     -H "Content-Type: application/json" \
     -d '{"input": "Follow up question", "metadata": {"session_id": "test-session-1"}}' | jq .
   

Automatizzare i test locali

Racchiudere i test di integrazione locali in uno script che avvia l'agente, esegue i test e ripulisce.

#!/bin/bash
# test-integration.sh

# Start agent in background
azd ai agent run --port 9090 &
AGENT_PID=$!
sleep 5  # Wait for startup

# Run tests
RESPONSE=$(curl -s -X POST http://localhost:9090/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Say hello"}')

echo "$RESPONSE" | jq -e '.output' > /dev/null
if [ $? -eq 0 ]; then
  echo "[x] Basic invoke test passed"
else
  echo "[!] Basic invoke test failed"
  echo "$RESPONSE"
fi

# Cleanup
kill $AGENT_PID

Eseguire test di integrazione distribuiti

Dopo la distribuzione in Foundry, verificare che l'agente funzioni completamente.

# Deploy
azd up

# Test basic invoke
azd ai agent invoke "Hello, what can you do?"

# Test with a new session
azd ai agent invoke --new-session "Start a fresh conversation"

# Test with file input
azd ai agent invoke -f test-request.json

Eseguire valutazioni strutturate

Quando l'agente esegue qualcosa di interessante, le chiamate ad hoc invoke smettono di essere un segnale affidabile. Hai modificato un prompt o sostituito uno strumento, hai eseguito un paio di prompt e ora devi decidere se questa modifica ha comportato un miglioramento complessivo. azd ai agent eval è il percorso strutturato oltre il test ad hoc invoke: esegue l'agente su un set di dati fisso e assegna punteggi alle risposte con uno o più analizzatori, in modo che la stessa modifica possa essere misurata allo stesso modo ogni volta.

Scegliere la valutazione strutturata

Usare la valutazione strutturata quando:

• Hai modificato un prompt, uno strumento o un modello e vuoi sapere se il cambiamento ha migliorato o peggiorato la situazione.
• Più di una persona sta modificando l'agente e gli smoke test informali non coprono più abbastanza superficie.
• Vuoi un quality gate che puoi integrare nella CI per intercettare automaticamente le regressioni.

Inizializzare le risorse di valutazione

• Esegui questo comando una sola volta dopo la distribuzione dell'agente, in genere subito dopo il primo azd up:

  azd ai agent eval generate
  

  Si tratta di un'operazione a esecuzione prolungata che richiede alcuni minuti. Genera un piccolo set di dati smoke, un valutatore adattivo predefinito con ambito per il comportamento dell'agente e un eval.yaml eseguibile. Passare --reset-defaults per sovrascrivere una configurazione esistente.

Eseguire una valutazione

• Una volta creato eval.yaml, eseguire la valutazione ed esaminare i risultati:

  azd ai agent eval run
  azd ai agent eval show --eval-run-id <run-id>
  

  eval run risolve eval.yaml nella radice del progetto dell'agente per impostazione predefinita e segnala i punteggi per valutatore, in modo da poter vedere esattamente dove l'agente è regredito. Usare --config <file> per puntare a una ricetta specifica e --no-wait per inviare e scollegare. Controllare la cronologia di esecuzione e i dettagli con eval show.

Passa a una suite condivisa

Lo stato finale raccomandato è quello di promuovere una ricetta locale funzionante in una suite condivisa del progetto e sottoposta a controllo delle versioni con azd ai agent eval suites e nell’eseguire tale suite come controllo di qualità dell'integrazione continua. Questo sottocomando non è ancora disponibile a livello generale. Finché non viene rilasciato, eseguire il controllo delle versioni di eval.yaml nel controllo del codice sorgente insieme al codice dell'agente ed eseguirlo dall'integrazione continua con azd ai agent eval run --config eval.yaml.

Convalidare prima della messa in produzione

Utilizza questa checklist quando verifichi il tuo agente prima della messa in produzione:

• [ ] L'agente inizia senza errori (azd ai agent run)
• [ ] Il probe di idoneità restituisce 200 (curl localhost:8088/readiness)
• [ ] Basic invoke restituisce una risposta valida
• [ ] L'agente gestisce correttamente l'input non valido (non si arresta in modo anomalo)
• [ ] L'agente risponde entro limiti di tempo accettabili
• [ ] La persistenza della sessione funziona (conversazione a più turni)
• [ ] L'agente distribuito risponde (azd ai agent invoke senza --local)
• [ ] I log mostrano il comportamento previsto (azd ai agent monitor --follow)

Contenuti correlati

• Eseguire un agente ospitato in locale con Azure Developer CLI per configurare l'ambiente di sviluppo locale.
• Eseguire il debug di un agente ospitato per diagnosticare i problemi quando i test hanno esito negativo.
• Monitorare i log dell'agente ospitato con l'interfaccia della riga di comando per sviluppatori Azure per controllare il comportamento di runtime.