Come testare le operazioni eseguite dall'agente di intelligenza artificiale quando i suoi strumenti falliscono

L'agente di intelligenza artificiale chiama gli strumenti: API HTTP, server MCP e altri servizi. Questi strumenti raggiungono il timeout, i limiti di frequenza, restituiscono errori e inviano dati in forme non previste. Il modello decide cosa fare successivamente in base a ciò che il tuo codice gli restituisce. Se il codice restituisce un'eccezione, una stringa vuota o nulla dopo un lungo periodo di attesa, l'agente si comporta in modo diverso rispetto a se riceve un errore chiaro.

Come si verificano i malfunzionamenti degli strumenti

• L'Agent si blocca. Una chiamata allo strumento senza timeout mantiene l'utente in attesa.
• L'agente va in loop. Il modello chiama più e più volte lo strumento che non riesce, usando token e il limite di velocità dello strumento.
• L'agente lo nasconde. Il codice ingoia l'errore e il modello risponde come se lo strumento avesse funzionato correttamente.
• L'agent si arresta in modo anomalo. Un'eccezione non gestita termina l'intera conversazione.

Come gestire i guasti degli strumenti

1. Impostare un timeout per ogni chiamata di strumento e un budget per l'intera interazione. La specifica MCP indica che i client devono implementare i timeout per le chiamate agli strumenti.
2. Riprova in caso di errori temporanei nel codice. Gestisci le risposte 429 e 503 nel codice dello strumento, rispetta Retry-After e limita i tentativi, così il modello non deve decidere quando riprovare.
3. Restituisci i fallimenti al modello come risultati chiari. MCP separa gli errori del protocollo, ad esempio uno strumento sconosciuto o argomenti non validi, dagli errori di esecuzione degli strumenti, ad esempio un errore dell'API. Segnala gli errori di esecuzione nel risultato dello strumento con isError: true, in modo che il modello possa vedere cosa è andato storto. Dire cosa non è riuscito e se riprovare ha senso.
4. Limitare il numero di chiamate degli strumenti per turno. Dopo un numero prestabilito di errori, arrestare e indicare all'utente.
5. Convalida i risultati dello strumento prima di passarli al modello. La specifica MCP indica che i client dovrebbero eseguire questa operazione e dovrebbero convalidare i risultati strutturati rispetto allo schema di output dello strumento quando ne ha uno.
6. Indicare all'utente cosa non ha funzionato. Una risposta basata su una chiamata di strumento non riuscita dovrebbe dirlo.

Come testare la gestione dei guasti degli strumenti nell'agente

L'output del modello può variare tra le esecuzioni, quindi eseguire più volte ogni scenario di errore.

Provalo nella tua app

Dev Proxy si trova tra l'agente e i relativi strumenti e inietta guasti, senza modifiche al codice dell'agente.

Per gli strumenti che chiamano le API HTTP, combinare errori casuali, latenza e verificare che l'agente attenda per il tempo richiesto dall'API:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/rc.schema.json",
  "plugins": [
    {
      "name": "RetryAfterPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
    },
    {
      "name": "LatencyPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "latencyPlugin"
    },
    {
      "name": "GenericRandomErrorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "errorsContosoApi"
    }
  ],
  "urlsToWatch": [
    "https://api.contoso.com/*"
  ],
  "latencyPlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/latencyplugin.schema.json",
    "minMs": 2000,
    "maxMs": 10000
  },
  "errorsContosoApi": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/genericrandomerrorplugin.schema.json",
    "errorsFile": "errors-contoso-api.json",
    "rate": 50
  }
}

Definire gli errori in errors-contoso-api.json, come descritto in Testare l'app con errori casuali. Imposta Retry-After su @dynamic per le risposte 429. Il RetryAfterPlugin controlla solo tali elementi.

Per i server MCP che usano STDIO, avviare il server tramite devproxy stdio con una configurazione che abilita MockStdioResponsePlugin, come illustrato nel stdio esempio di configurazione. Salvalo con il nome devproxyrc-stdio.json. Inserire quindi questa opzione in stdio-mocks.json per restituire un errore di esecuzione dello strumento per ogni tools/call richiesta:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/mockstdioresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "bodyFragment": "tools/call"
      },
      "response": {
        "stdout": "{\"jsonrpc\":\"2.0\",\"id\":@stdin.body.id,\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Failed to fetch weather data: API rate limit exceeded\"}],\"isError\":true}}\n"
      }
    }
  ]
}

devproxy stdio --config-file devproxyrc-stdio.json npx -y @modelcontextprotocol/server-filesystem

Per fare in modo che il tuo agente lo usi, modificare il comando nella configurazione del server MCP dell'agente in modo che avvii il server tramite devproxy stdio. Usare la proprietà nth su un mock per far fallire solo una chiamata specifica e aggiungere LatencyPlugin per rallentare le risposte del server.

Per testare le operazioni dell'agente quando il modello stesso fallisce, LanguageModelFailurePlugin fa sì che il modello allucini, ignori le istruzioni o risponda nel formato errato. Vedi Testare l'app con errori del modello linguistico.

Per installare Dev Proxy, vedere Configurare Dev Proxy.

Passaggi successivi

Vedere anche

• stdio comando
• Simulare risposte API lente
• Limiti di frequenza LLM: token al minuto, richieste al minuto e cosa accade quando vengono raggiunti
• Come verificare se l'agente di intelligenza artificiale segue le istruzioni nascoste nelle risposte degli strumenti