The Php Times

Laravel AI v0.11.0 añade ToolSearch, una contribución de behzadsp en el pull request #697. Hasta ahora, cada definición de herramienta que un agente exponía se enviaba al proveedor en cada petición, un coste fijo que se vuelve pesado con decenas de herramientas y reduce la precisión del modelo al elegir herramientas. El wrapper se apoya en la búsqueda de herramientas alojada que OpenAI y Anthropic ya ofrecen: el proveedor recibe una entrada de búsqueda más las definiciones diferidas, y solo carga la definición completa de una herramienta cuando decide usarla.

use Laravel\Ai\Providers\Tools\ToolSearch;

public function tools(): iterable
{
    return [
        new LookupAccount,
        new ToolSearch(tools: [
            new IssueRefund,
            new ChangePlan,
            new ResendInvoice,
            new TransferSeat,
        ]),
    ];
}

ToolSearch recibe las herramientas a diferir como primer argumento del constructor. Todo lo que queda fuera del wrapper se envía como antes, y las clases de herramientas no necesitan cambios: ni interfaz ni opción por herramienta. La misma clase puede diferirse en un agente y enviarse directamente en otro. Un segundo argumento elige la estrategia de búsqueda de Anthropic, regex (por defecto) o bm25, validada en la construcción con una InvalidArgumentException para cualquier otro valor. Campos adicionales del proveedor como cache_control pasan por withProviderOptions(); en Anthropic el wrapper es el único lugar para un punto de corte de caché, porque su API rechaza herramientas con defer_loading: true y cache_control a la vez.

En OpenAI el wrapper se convierte en una entrada {"type": "tool_search"}; en Anthropic, en un tipo versionado como tool_search_tool_regex_20251119. Las herramientas diferidas siguen como definiciones ordinarias marcadas con defer_loading: true. Cuando el modelo llama a una herramienta diferida, la pasarela la resuelve por nombre desde dentro del wrapper, por lo que la ejecución es idéntica a la de una herramienta de primer nivel. Anthropic informa la búsqueda con bloques server_tool_use y tool_search_tool_result (a los que no se debe responder con un tool_result), OpenAI con ítems tool_search_call y tool_search_output; el SDK solo cubre el lado de la petición y no analiza ninguna de las dos formas.

Solo OpenAiProvider y AnthropicProvider implementan el marcador SupportsToolSearch. Todos los demás proveedores, incluidos Azure, Groq, DeepSeek, Mistral, OpenRouter, Gemini, xAI, Bedrock y Ollama, lanzan una LogicException antes de que salga cualquier petición. Se aplican tres reglas más: la comprobación de soporte se ejecuta incluso con un wrapper vacío, solo se permite un ToolSearch por petición, y en OpenAI el paquete rechaza ToolSearch combinado con store=false, porque la búsqueda alojada requiere respuestas almacenadas. Un wrapper vacío en un proveedor compatible no emite nada.

ToolSearch::budget() expande cada wrapper a su número de herramientas diferidas al derivar el presupuesto maxSteps por defecto, de modo que envolver veinte herramientas no reduce el presupuesto de pasos. Las herramientas diferidas nunca añaden pasos propios, porque el proveedor las carga dentro de su propia llamada. Para probarlo basta simular la llamada HTTP y verificar que las definiciones diferidas llevan defer_loading: true; los nombres los resuelve ToolNameResolver a partir del nombre corto de la clase, salvo que esta defina un método name().

El consejo del artículo: diferir solo merece la pena con catálogos grandes. Cuatro herramientas no lo justifican, ya que el modelo debe buscar antes de llamar. Las cadenas de failover lanzan una excepción al llegar a un proveedor no compatible, y las aplicaciones que usan store=false no pueden emplear la búsqueda alojada de OpenAI. Un enfoque de clasificación en el cliente, válido para todos los proveedores, se propuso en el PR #805 pero se cerró sin fusionar. ToolSearch se publicó en la v0.11.0 junto a los eventos de ciclo de vida de ejecuciones, un failover más amplio y la reproducción stateless de salidas para OpenAI.