Cómo probar lo que hace el agente de IA cuando fallan sus herramientas

El agente de IA llama a herramientas: API HTTP, servidores MCP y otros servicios. Esas herramientas agotan el tiempo de espera, alcanzan los límites de frecuencia, devuelven errores y envían datos en formatos que no esperaba. El modelo decide qué hacer a continuación en función de lo que tu código le devuelve. Si el código devuelve una excepción, una cadena vacía o nada en absoluto tras una larga espera, el agente se comporta de forma distinta a cuando recibe un error claro.

Cómo se producen los fallos de las herramientas

• El agente se bloquea. Una llamada de herramienta sin tiempo de espera mantiene al usuario en espera.
• El agente entra en bucle. El modelo llama a la herramienta que falla una y otra vez, agotando tokens y el límite de tasa de la herramienta.
• El agente lo oculta. El código silencia el error y el modelo responde como si la herramienta hubiera funcionado correctamente.
• El agente se bloquea. Una excepción no controlada finaliza toda la conversación.

Cómo gestionar los fallos de las herramientas

1. Establezca un tiempo de espera en cada llamada a la herramienta y un presupuesto para toda la interacción. La especificación de MCP indica que los clientes deben implementar tiempos de espera para las llamadas a herramientas.
2. Vuelva a intentarlo ante errores temporales en el código. Administre las respuestas 429 y 503 en el código de su herramienta, respete Retry-After y limite el número de intentos, para que el modelo no tenga que decidir cuándo volver a intentarlo.
3. Devuelve fallos al modelo como resultados claros. MCP separa los errores de protocolo, como una herramienta desconocida o argumentos no válidos, de errores de ejecución de herramientas, como un error de API. Notifica errores de ejecución en el resultado de la herramienta con isError: true, por lo que el modelo puede ver lo que salió mal. Diga lo que falló y si intentarlo de nuevo tiene sentido.
4. Limite el número de llamadas de herramienta por turno. Tras un número determinado de fallos, detente e informa al usuario.
5. Valide los resultados de la herramienta antes de pasarlos al modelo. La especificación MCP establece que los clientes deben hacer esto y deben validar los resultados estructurados comparándolos con el esquema de salida de la herramienta, cuando esta disponga de uno.
6. Dile al usuario qué no funcionó. Una respuesta basada en una llamada a herramienta con error debe indicarlo.

Cómo probar la gestión de fallos de herramientas en el agente

La salida del modelo puede variar entre ejecuciones, por lo que ejecuta cada escenario de error más de una vez.

Pruébalo en tu app

Dev Proxy se encuentra entre el agente y sus herramientas e inserta errores, sin cambios en el código del agente.

En el caso de las herramientas que llaman a las API HTTP, combine errores aleatorios, latencia y una comprobación de que el agente espere tanto tiempo como solicite la 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
  }
}

Defina los errores en errors-contoso-api.json, como se describe en Probar mi aplicación con errores aleatorios. Establece Retry-After en @dynamic en tus respuestas 429. El RetryAfterPlugin solo comprueba esas.

En el caso de los servidores MCP que usan STDIO, inicie el servidor a través de devproxy stdio con una configuración que habilite MockStdioResponsePlugin, como se muestra en el stdio ejemplo de configuración. Guárdelo como devproxyrc-stdio.json. A continuación, introduce esto en stdio-mocks.json para devolver un error de ejecución de la herramienta por cada solicitud tools/call:

{
  "$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 el agente lo use, cambie el comando en la configuración del servidor MCP del agente para que inicie el servidor a través de devproxy stdio. Use la nth propiedad en un mock para producir un error solo en una llamada específica y agregue LatencyPlugin para ralentizar las respuestas del servidor.

Para comprobar qué hace tu agente cuando el propio modelo falla, el LanguageModelFailurePlugin hace que el modelo alucine, ignore instrucciones o responda en un formato incorrecto. Consulta Probar mi aplicación con fallos del modelo de lenguaje.

Para instalar Dev Proxy, consulte Configurar Dev Proxy.

Pasos siguientes

Consulte también

• stdio comando
• Simular respuestas lentas de API
• Límites de tasa de LLM: tokens por minuto, solicitudes por minuto y lo que sucede cuando se alcanzan
• Cómo comprobar si el agente de IA sigue las instrucciones ocultas en las respuestas de las herramientas