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 superan el tiempo de espera, alcanzan los límites de tasa, devuelven errores y envían datos en formatos que no esperabas. 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. Controla las respuestas 429 y 503 en el código de la herramienta, ten en cuenta Retry-After y limita los intentos, por lo que el modelo no tiene que decidir cuándo reintentar.
  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. Después de un número establecido de fallos, detenga e indique al usuario.
  5. Valide los resultados de la herramienta antes de pasarlos al modelo. La especificación MCP indica que los clientes deben hacerlo y deben validar los resultados estructurados con el esquema de salida de la herramienta cuando tenga 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

Approach Lo que encuentras Lo que te pierdes
Prueba el wrapper de la herramienta con un cliente simulado Cómo el código mapea el fallo que escribió Qué hace el modelo con él y cómo falla la herramienta real
Romper la herramienta real, por ejemplo, detener el servidor o revocar una clave Un verdadero fallo de ese tipo Límites de tasa, respuestas lentas y datos con formato incorrecto, que no se pueden producir a petición
Escribe una API falsa o un servidor MCP Cualquier respuesta que programes Tiene que apuntar el agente al falso, y se desvía de la herramienta real.
Interceptar el tráfico real de herramientas del agente e insertar errores Qué hacen el agente en ejecución y el modelo con errores, latencia y datos incorrectos de la herramienta real Tu código por sí solo. Mantenga las pruebas unitarias para eso.

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. Establezca Retry-After en @dynamic en sus respuestas de 429. El RetryAfterPlugin comprueba solo esos.

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, coloque esto en stdio-mocks.json para devolver un error de ejecución de la herramienta para 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 probar lo que hace el agente cuando se produce un error en el propio modelo, LanguageModelFailurePlugin hace que el modelo alucine, omita las instrucciones o responda en el formato incorrecto. Consulta las pruebas de mi aplicación con fallos del modelo de lenguaje.

Para instalar Dev Proxy, consulte Configurar Dev Proxy.

Pasos siguientes

Simulación de respuestas STDIO para servidores MCP

Consulte también

  • Se actualizó por última vez el