Como testar o que o seu agente de IA faz quando as suas ferramentas falham

O seu agente de IA chama ferramentas: APIs HTTP, servidores MCP e outros serviços. Essas ferramentas expiram por tempo limite, excedem o limite de taxa, devolvem erros e enviam dados em formas inesperadas. O modelo decide o que fazer a seguir com base no que o teu código lhe devolve. Se o teu código retorna uma exceção, uma cadeia vazia ou nada depois de uma longa espera, o agente comporta-se de forma diferente do que se receber um erro claro.

Como as falhas da ferramenta ocorrem

• O agente bloqueia. Uma chamada de ferramenta sem timeout faz o utilizador esperar.
• O agente entra em ciclo. O modelo chama repetidamente a ferramenta com falha, esgotando os tokens e o limite de taxa da ferramenta.
• O agente encobre isso. O teu código engole o erro e o modelo responde como se a ferramenta tivesse tido sucesso.
• O agente falha. Uma exceção não processada termina toda a conversa.

Como lidar com falhas de ferramentas

1. Define um tempo para cada chamada de ferramenta e um orçamento para toda a interação. A especificação MCP diz que os clientes devem implementar timeouts para chamadas de ferramenta.
2. Retentar em caso de erros temporários no código. Trata das respostas 429 e 503 no teu código de ferramentas, respeita Retry-Aftere limita as tentativas, para que o modelo não tenha de decidir quando tentar novamente.
3. Apresente falhas ao modelo como resultados claros. O MCP separa erros de protocolo, como uma ferramenta desconhecida ou argumentos inválidos, dos erros de execução de ferramentas, como uma falha na API. Reporta erros de execução no resultado da ferramenta com isError: true, para que o modelo possa ver o que correu mal. Diz o que falhou e se faz sentido tentar novamente.
4. Limite o número de chamadas de ferramenta por turno. Após um número definido de falhas, pare e informe o utilizador.
5. Valide os resultados da ferramenta antes de os passar ao modelo. A especificação MCP diz que os clientes devem fazer isto e devem validar resultados estruturados contra o esquema de saída da ferramenta quando este o tiver.
6. Diz ao utilizador o que não funcionou. Uma resposta baseada numa chamada de ferramenta falhada deve dizê-lo.

Como testar o tratamento de falhas de ferramentas no seu agente

A saída do modelo pode variar entre execuções, por isso execute cada cenário de falha mais de uma vez.

Experimente na sua app

Dev Proxy situa-se entre o seu agente e as suas ferramentas e injeta falhas, sem alterações ao código do seu agente.

Para ferramentas que chamam APIs HTTP, combine erros aleatórios, latência e uma verificação de que o seu agente espera durante o tempo que a API indicar:

{
  "$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
  }
}

Defina os erros em errors-contoso-api.json, conforme descrito em Testar a minha aplicação com erros aleatórios. Defina Retry-After em @dynamic nas suas respostas 429. O RetryAfterPlugin verifica apenas esses elementos.

Para servidores MCP que utilizam STDIO, inicie o servidor através de devproxy stdio com uma configuração que permita o MockStdioResponsePlugin, como mostrado no stdio exemplo de configuração. Guarde-o como devproxyrc-stdio.json. Depois coloca isto em stdio-mocks.json para devolver um erro de execução de ferramenta para cada tools/call pedido:

{
  "$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

Para que o seu agente o utilize, altere o comando na configuração do servidor MCP do seu agente para que o servidor seja iniciado através de devproxy stdio. Usa a propriedade nth num mock para falhar apenas uma chamada específica e adiciona o LatencyPlugin para abrandar as respostas do servidor.

Para testar o que o seu agente faz quando o próprio modelo falha, o LanguageModelFailurePlugin faz com que o modelo alucine, ignore instruções ou responda no formato errado. Veja Testar a minha aplicação com falhas no modelo de linguagem.

Para instalar Dev Proxy, consulte Configurar Dev Proxy.

Passos seguintes

Ver também

• stdio comando
• Simule respostas lentas da API
• Limites de taxa dos LLMs: tokens por minuto, pedidos por minuto e o que acontece quando os atinges
• Como testar se o seu agente de IA segue instruções ocultas nas respostas da ferramenta