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

Seu agente de IA chama ferramentas: APIs HTTP, servidores MCP e outros serviços. Essas ferramentas expiram, excedem os limites de taxa, retornam erros e enviam dados em formatos que você não esperava. O modelo decide o que fazer a seguir com base no que seu código passa de volta para ele. Se o código retornar uma exceção, uma cadeia de caracteres vazia ou nada depois de uma longa espera, o agente se comportará de forma diferente do que se receber um erro claro.

Como as falhas das ferramentas dão errado

• O agente trava. Uma chamada de ferramenta sem tempo limite mantém o usuário aguardando.
• O agente entra em loop. O modelo chama a ferramenta com falha repetidamente, usando tokens e o limite de taxa da ferramenta.
• O agente encobriu isso. Seu código engole o erro e o modelo responde como se a ferramenta tivesse sido bem-sucedida.
• O agente trava. Uma exceção sem tratamento encerra toda a conversa.

Como lidar com falhas de ferramenta

1. Defina um tempo limite em cada chamada de ferramenta e um orçamento para toda a interação. A especificação do MCP diz que os clientes devem implementar tempos limite para chamadas de ferramenta.
2. Tente novamente em caso de erros temporários no código. Manipule as respostas 429 e 503 em seu código de ferramenta, respeite Retry-After e limite as tentativas, para que o modelo não precise decidir quando tentar novamente.
3. Retornar falhas ao modelo como resultados claros. O MCP separa erros de protocolo, como uma ferramenta desconhecida ou argumentos inválidos, de erros de execução de ferramenta, como uma falha de API. Isso relata erros de execução no resultado da ferramenta com isError: true, para que o modelo possa ver o que deu errado. Diga o que falhou e se tentar novamente faz sentido.
4. Limite o número de chamadas de ferramenta por turno. Após um número definido de falhas, pare e informe ao usuário.
5. Valide os resultados da ferramenta antes de passá-los para o modelo. A especificação do MCP diz que os clientes devem fazer isso e devem validar os resultados estruturados em relação ao esquema de saída da ferramenta quando ele tiver um.
6. Diga ao usuário o que não funcionou. Uma resposta baseada em uma chamada de ferramenta com falha deve dizer isso.

Como testar o tratamento de falhas de ferramenta em seu agente

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

Teste no seu aplicativo

Dev Proxy fica entre seu agente e suas ferramentas e injeta falhas, sem alterações no código do agente.

Para ferramentas que chamam APIs HTTP, combine erros aleatórios, latência e uma verificação de que o agente aguarda pelo tempo que a API solicitar:

{
  "$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 meu aplicativo com erros aleatórios. Defina Retry-After como @dynamic em suas 429 respostas. O RetryAfterPlugin verifica somente esses itens.

Para servidores MCP que usam STDIO, inicie o servidor devproxy stdio com uma configuração que habilita o MockStdioResponsePlugin, conforme mostrado no exemplo de stdio configuração. Guarde-o como devproxyrc-stdio.json. Em seguida, coloque-o em stdio-mocks.json para retornar um erro de execução de ferramenta para cada tools/call solicitação:

{
  "$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 agente o use, altere o comando na configuração do servidor MCP do agente para que ele inicie o servidor por meio de devproxy stdio. Use a propriedade nth em um mock para falhar apenas em uma chamada específica e adicione o LatencyPlugin para diminuir a velocidade das respostas do servidor.

Para testar o que seu agente faz quando o próprio modelo falha, o LanguageModelFailurePlugin faz o modelo alucinar, ignorar instruções ou responder no formato errado. Consulte Testar meu aplicativo com falhas de modelo de idioma.

Para instalar o Dev Proxy, consulte Configurar o Dev Proxy.

Próximas Etapas 

Consulte também

• stdio comando
• Simule respostas lentas da API
• Limites de taxa de LLM: tokens por minuto, solicitações por minuto e o que acontece quando você os atinge
• Como testar se o agente de IA segue instruções ocultas nas respostas da ferramenta