La búsqueda de herramientas permite que el modelo busque herramientas de forma dinámica y las cargue en su contexto cuando las necesite. Así evitas cargar todas las definiciones de herramientas en el contexto del modelo desde el principio, lo que puede ayudar a reducir el consumo total de tokens y el costo. Para optimizar el costo y la latencia, la búsqueda de herramientas está diseñada para conservar la caché del modelo. Cuando el modelo descubre herramientas nuevas, estas se incorporan al final de la ventana de contexto.
En la API de Responses, solo gpt-5.4 y los modelos posteriores admiten tool_search.
La configuración y los ejemplos que siguen usan la API de Responses. Para obtener información sobre la carga de funciones por sesión y la detección automática de herramientas MCP, consulta Agents API.
Para activar la búsqueda de herramientas en la API de Responses, sigue estos dos pasos:
- Agrega
tool_searchcomo herramienta en tu arreglotools. - Si usas funciones, marca las que quieras cargar de forma diferida con
defer_loading: true. Si usas servidores MCP, establecedefer_loading: trueen la definición de la herramienta del servidor MCP.
Usa espacios de nombres siempre que sea posible
Puedes usar la búsqueda de herramientas con funciones de carga diferida, espacios de nombres o servidores MCP, pero recomendamos usar espacios de nombres o servidores MCP siempre que sea posible. Entrenamos nuestros modelos principalmente para buscar herramientas en esos dos tipos de agrupaciones, donde el ahorro de tokens suele ser mayor.
En los espacios de nombres, defer_loading se aplica a las funciones que contiene el espacio de nombres y no al objeto que lo representa.
Al inicio de una solicitud, el modelo sigue viendo el nombre y la descripción de cada elemento que puede buscar. Si se trata de un espacio de nombres o de un servidor MCP, al principio el modelo solo ve el nombre y la descripción del espacio o del servidor. Los detalles de las funciones solo aparecen cuando la herramienta de búsqueda carga esas funciones. Si se trata de una función diferida individual, el modelo sigue viendo el nombre y la descripción de la función, por lo que, en la práctica, lo que se difiere es principalmente la carga del esquema de parámetros.
Para maximizar el ahorro de tokens, recomendamos agrupar las funciones diferidas en espacios de nombres o servidores MCP y describir con claridad qué funciones contiene cada grupo, sin entrar en detalles. Así, el modelo puede buscar de manera eficaz y cargar solo las funciones pertinentes. Procura incluir menos de 10 funciones por espacio de nombres para aprovechar mejor los tokens y mejorar el rendimiento del modelo.
{
"tools": [
{
"type": "namespace",
"name": "crm",
"description": "CRM tools for customer lookup and order management.",
"tools": [
{
"type": "function",
"name": "list_open_orders",
"description": "List open orders for a customer ID.",
"defer_loading": true,
"parameters": {
"type": "object",
"properties": {
"customer_id": { "type": "string" }
},
"required": ["customer_id"],
"additionalProperties": false
}
}
]
},
{
"type": "tool_search"
}
]
}Un mismo espacio de nombres puede incluir herramientas de carga inmediata y de carga diferida. El modelo puede llamar de inmediato a las herramientas que no tienen defer_loading: true. Las herramientas diferidas del mismo espacio de nombres se cargan mediante la búsqueda de herramientas.
Tipos de búsqueda de herramientas
Elige entre dos tipos de búsqueda de herramientas:
- Búsqueda de herramientas alojada: OpenAI busca entre las herramientas diferidas que declaraste en la solicitud y devuelve en la misma respuesta el subconjunto que cargó.
- Búsqueda de herramientas ejecutada por el cliente: el modelo emite un
tool_search_call, tu aplicación realiza la búsqueda y tú devuelves eltool_search_outputcorrespondiente.
Empieza con la búsqueda de herramientas alojada si al crear la solicitud ya sabes entre qué herramientas se hará la búsqueda. Usa la búsqueda ejecutada por el cliente cuando la detección de herramientas dependa del estado del proyecto, del estado del inquilino o de otro sistema que controle tu aplicación.
Búsqueda de herramientas alojada
La búsqueda de herramientas alojada es la opción más sencilla cuando ya conoces el inventario completo de funciones, espacios de nombres o servidores MCP en los que quieres que busque el modelo. Decláralos desde el principio, agrega {"type": "tool_search"} y deja que la API decida qué cargar.
from openai import OpenAI
client = OpenAI()
crm_namespace = {
"type": "namespace",
"name": "crm",
"description": "CRM tools for customer lookup and order management.",
"tools": [
{
"type": "function",
"name": "get_customer_profile",
"description": "Fetch a customer profile by customer ID.",
"parameters": {
"type": "object",
"properties": {
"customer_id": {"type": "string"},
},
"required": ["customer_id"],
"additionalProperties": False,
},
},
{
"type": "function",
"name": "list_open_orders",
"description": "List open orders for a customer ID.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {
"customer_id": {"type": "string"},
},
"required": ["customer_id"],
"additionalProperties": False,
},
},
],
}
response = client.responses.create(
model="gpt-6-astra",
input="List open orders for customer CUST-12345.",
tools=[
crm_namespace,
{"type": "tool_search"},
],
parallel_tool_calls=False,
)
print(response.output)Si el modelo determina que necesita una herramienta diferida, la respuesta incluye dos elementos de salida adicionales antes de la llamada a la función:
tool_search_call, que registra el paso de búsqueda alojada.tool_search_output, que contiene el subconjunto de herramientas cargadas a las que ya se puede llamar.
[
{
"type": "tool_search_call",
"execution": "server",
"call_id": null,
"status": "completed",
"arguments": {
"paths": ["crm"]
}
},
{
"type": "tool_search_output",
"execution": "server",
"call_id": null,
"status": "completed",
"tools": [
{
"type": "namespace",
"name": "crm",
"description": "CRM tools for customer lookup and order management.",
"tools": [
{
"type": "function",
"name": "list_open_orders",
"description": "List open orders for a customer ID.",
"defer_loading": true,
"parameters": {
"type": "object",
"properties": {
"customer_id": { "type": "string" }
},
"required": ["customer_id"],
"additionalProperties": false
}
}
]
}
]
},
{
"type": "function_call",
"name": "list_open_orders",
"namespace": "crm",
"call_id": "call_abc123",
"arguments": "{\"customer_id\":\"CUST-12345\"}"
}
]En el modo alojado, execution tiene el valor server y call_id tiene el valor null.
Para tareas más complejas, el modelo también puede cargar varios espacios de nombres o servidores MCP en un mismo tool_search_call. Por ejemplo, si necesita funciones de distintos espacios de nombres para completar una tarea, puede optar por buscar en esos espacios y cargarlos juntos antes de realizar las llamadas a funciones correspondientes.
Búsqueda de herramientas ejecutada por el cliente
Con la búsqueda de herramientas ejecutada por el cliente, tu aplicación controla por completo cómo se descubren las herramientas. Esta opción es útil cuando las herramientas disponibles dependen de información que no resulta práctico declarar en la lista inicial tools.
Configura la herramienta tool_search con execution: "client" y un esquema para los argumentos de búsqueda que espera tu aplicación:
from openai import OpenAI
client = OpenAI()
first_response = client.responses.create(
model="gpt-6-astra",
input="Find the shipping ETA tool first, then use it for order_42.",
tools=[
{
"type": "tool_search",
"execution": "client",
"description": "Find the project-specific tools needed to continue the task.",
"parameters": {
"type": "object",
"properties": {
"goal": {"type": "string"},
},
"required": ["goal"],
"additionalProperties": False,
},
}
],
parallel_tool_calls=False,
)
search_call = next(
item for item in first_response.output if item.type == "tool_search_call"
)
loaded_tools = [
{
"type": "function",
"name": "get_shipping_eta",
"description": "Look up shipping ETA details for an order.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"},
},
"required": ["order_id"],
"additionalProperties": False,
},
}
]
second_response = client.responses.create(
model="gpt-6-astra",
previous_response_id=first_response.id,
input=[
{
"type": "tool_search_output",
"execution": "client",
"call_id": search_call.call_id,
"status": "completed",
"tools": loaded_tools,
},
],
)
print(second_response.output)En el primer turno, el modelo emite un tool_search_call y se detiene:
[
{
"type": "tool_search_call",
"execution": "client",
"call_id": "call_abc123",
"status": "completed",
"arguments": {
"goal": "Find the shipping ETA tool for order_42."
}
}
]Luego, tu aplicación realiza la búsqueda y devuelve un tool_search_output con las herramientas que quiere cargar:
[
{
"type": "tool_search_output",
"execution": "client",
"call_id": "call_abc123",
"status": "completed",
"tools": [
{
"type": "function",
"name": "get_shipping_eta",
"description": "Look up shipping ETA details for an order.",
"defer_loading": true,
"parameters": {
"type": "object",
"properties": {
"order_id": { "type": "string" }
},
"required": ["order_id"],
"additionalProperties": false
}
}
]
}
]En el siguiente turno, el modelo puede llamar a la herramienta cargada como a cualquier otra función:
[
{
"type": "function_call",
"name": "get_shipping_eta",
"namespace": "get_shipping_eta",
"call_id": "call_xyz456",
"arguments": "{\"order_id\":\"order_42\"}"
}
]En el modo cliente, execution tiene el valor client y call_id está definido. Devuelve el mismo call_id del tool_search_call en tu tool_search_output.
Uso avanzado
Describe con claridad los espacios de nombres
Describe con claridad el caso de uso de cada espacio de nombres. El modelo se basa en esa descripción para decidir cuándo cargar un subconjunto de las funciones de ese espacio. Evita las descripciones demasiado extensas. Incluye los detalles en las descripciones de las funciones diferidas, que solo se cargan cuando hacen falta.
Qué herramientas se cargan
tool_search_output.tools contiene la lista de herramientas que el modelo cargó de forma dinámica. El modelo podrá llamar a cualquiera de ellas en turnos posteriores, por lo que en el modo cliente no necesitas volver a cargar la misma herramienta de un turno a otro. Las herramientas que no figuren en este arreglo no estarán disponibles para el modelo. Si quieres deshabilitar una herramienta cargada, puedes quitarla del elemento tool_search_output en el que defines el conjunto de herramientas cargadas. Ten en cuenta que cualquier cambio en ese conjunto invalidará la caché del modelo a partir de ese punto.
Patrones avanzados de inyección de herramientas
La mayoría de las integraciones declaran las herramientas en el parámetro tools de la solicitud. La búsqueda de herramientas ejecutada por el cliente también admite patrones más avanzados en los que tu aplicación devuelve herramientas que no figuraban en la solicitud original. Trátalo como un flujo de trabajo avanzado: valida cuidadosamente los esquemas devueltos y expón solo definiciones de herramientas de confianza.
Búsqueda de herramientas y caché
Todas las herramientas se cargan al final de la ventana de contexto del modelo, tanto en la búsqueda alojada como en la ejecutada por el cliente. Esto permite conservar la caché del modelo de una solicitud a otra, reducir los costos totales y aumentar la velocidad.
Agrega herramientas en un punto específico de la entrada
En flujos de trabajo avanzados, puedes usar un elemento de entrada additional_tools para que determinadas herramientas estén disponibles a partir de un punto específico de la conversación. Esto resulta útil cuando tu aplicación carga herramientas fuera del flujo habitual de búsqueda o necesita conservar el orden en que se agregaron durante una respuesta anterior.
Establece role en developer e incluye las herramientas que quieras agregar en el arreglo tools del elemento:
{
"type": "additional_tools",
"role": "developer",
"tools": [
{
"type": "function",
"name": "get_customer",
"description": "Look up a customer by ID.",
"parameters": {
"type": "object",
"properties": {
"customer_id": { "type": "string" }
},
"required": ["customer_id"],
"additionalProperties": false
}
}
]
}Las herramientas de un elemento additional_tools solo están disponibles después de que ese elemento aparece en la entrada. Cuando vuelvas a enviar manualmente los elementos de la conversación que recibiste, conserva la posición del elemento para que el modelo vea las mismas herramientas en el mismo punto de la conversación.
Agents API
De forma predeterminada, la Agents API carga las definiciones de funciones desde el inicio. Para diferir la carga de determinadas funciones, incluye { "type": "tool_search" } en agent.tools y establece defer_loading: true en cada función que quieras que el agente descubra cuando la necesite. Agregar tool_search no difiere la carga de todas las funciones.
La solicitud de sesión sigue proporcionando la definición completa de cada función, incluidos el nombre, la descripción y el esquema de argumentos. La búsqueda de herramientas cambia el momento en que el modelo recibe esa definición. Una vez descubierta la función, tu aplicación procesa la llamada y devuelve el resultado como de costumbre. Consulta Funciones para saber cómo procesar los resultados.
Configura OPENAI_API_KEY antes de ejecutar este ejemplo:
import OpenAI from "openai";
const client = new OpenAI();
const result = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
tools: [
{
type: "tool_search",
},
{
type: "function",
name: "lookup_account",
description: "Find an account by its account number.",
parameters: {
type: "object",
properties: {
account_id: {
type: "string",
},
},
required: ["account_id"],
additionalProperties: false,
},
defer_loading: true,
},
],
},
environment: {
type: "none",
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Look up account 42.",
},
],
},
],
});
console.log(result.id);Elige una estrategia de carga de funciones
| Estrategia | Configuración | Cuándo usarla | Desventajas |
|---|---|---|---|
| Carga inmediata | Omite defer_loading o establece su valor en false. |
Cuando hay pocas funciones o se necesitan en la mayoría de las tareas. | Las definiciones sin usar ocupan espacio en el contexto. Modificar una definición puede invalidar un prefijo almacenado en caché. |
| Carga diferida | Establece defer_loading: true e incluye tool_search. |
Cuando el catálogo es extenso y cada tarea requiere pocas funciones. | La detección agrega un paso y depende de que la búsqueda encuentre la herramienta pertinente. |
Una sesión de la Agents API admite funciones de carga inmediata y diferida a la vez, aunque en general no recomendamos combinarlas. Asigna nombres y descripciones claros a las funciones diferidas. Antes de elegir una estrategia predeterminada, compara los resultados de cada estrategia con solicitudes representativas: verifica si se completan las tareas y mide el consumo de tokens de entrada y la latencia.
Herramientas MCP y de complementos
La Agents API descubre automáticamente las herramientas MCP cuando el modelo y el proveedor admiten la búsqueda de herramientas. El entorno de ejecución difiere la carga de las herramientas MCP y agrega la búsqueda de herramientas cuando hay herramientas diferidas que se pueden buscar. Esto se aplica a los servidores MCP remotos, los servidores MCP de los ejecutores y las herramientas MCP que proporcionan los complementos.
No necesitas agregar { "type": "tool_search" } solo para las herramientas MCP ni establecer la marca defer_loading de una función en un servidor MCP. Configura el servidor mediante conexiones MCP. La configuración de la API de Responses que se describe más arriba no se aplica a los servidores MCP de la Agents API.
Guías relacionadas
- Usa la llamada a funciones para definir funciones a las que el modelo pueda llamar y herramientas personalizadas.
- Consulta Uso de herramientas para conocer las herramientas disponibles en la API de Responses.