Com a busca de ferramentas, o modelo pode procurar ferramentas dinamicamente e carregá-las no contexto conforme necessário. Assim, você evita carregar todas as definições de ferramentas no contexto do modelo logo no início, o que pode ajudar a reduzir o consumo total de tokens e o custo. Para otimizar o custo e a latência, a busca de ferramentas foi projetada para preservar o cache do modelo. Quando o modelo descobre novas ferramentas, elas são inseridas no final da janela de contexto.
Na API Responses, apenas o gpt-5.4 e os modelos posteriores oferecem suporte a tool_search.
A configuração e os exemplos a seguir usam a API Responses. Para saber como carregar funções por sessão e descobrir ferramentas MCP automaticamente, consulte a seção Agents API.
Para ativar a busca de ferramentas na API Responses, siga estas duas etapas:
- Adicione
tool_searchcomo ferramenta no arraytools. - Se usar funções, marque com
defer_loading: trueaquelas que deseja carregar sob demanda. Se usar servidores MCP, definadefer_loading: truena definição da ferramenta do servidor MCP.
Use namespaces sempre que possível
Você pode usar a busca de ferramentas com funções, namespaces ou servidores MCP configurados para carregamento sob demanda. Recomendamos usar namespaces ou servidores MCP sempre que possível. Nossos modelos foram treinados principalmente para fazer buscas nesses dois tipos de agrupamento, que costumam proporcionar uma economia maior de tokens.
Nos namespaces, defer_loading se aplica somente às funções contidas no namespace. O objeto que representa o namespace continua disponível desde o início.
No início de uma solicitação, o modelo vê o nome e a descrição de cada item que pode pesquisar. No caso de um namespace ou servidor MCP, o modelo vê inicialmente apenas o nome e a descrição do namespace ou servidor. Os detalhes de cada função só aparecem quando a ferramenta de busca carrega essas funções. No caso de uma função individual com carregamento sob demanda, o modelo já vê o nome e a descrição da função. Na prática, o que a busca de ferramentas adia é principalmente o carregamento do schema dos parâmetros.
Para economizar o máximo de tokens, recomendamos agrupar as funções com carregamento sob demanda em namespaces ou servidores MCP. Escreva descrições gerais que deixem claro quais funções cada grupo contém, para que o modelo consiga encontrar e carregar apenas as funções relevantes. Procure manter menos de 10 funções em cada namespace para usar os tokens com mais eficiência e melhorar o desempenho do 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"
}
]
}Um namespace pode combinar ferramentas disponíveis de imediato e ferramentas com carregamento sob demanda. O modelo pode chamar imediatamente as ferramentas sem defer_loading: true. Para carregar as demais ferramentas do mesmo namespace, ele usa a busca de ferramentas.
Tipos de busca de ferramentas
Escolha entre dois tipos de busca de ferramentas:
- Busca de ferramentas hospedada: a OpenAI pesquisa as ferramentas que você declarou na solicitação para carregamento sob demanda e retorna, na mesma resposta, o subconjunto carregado.
- Busca de ferramentas executada pelo cliente: o modelo emite um
tool_search_call, seu aplicativo faz a busca e você retorna otool_search_outputcorrespondente.
Comece com a busca hospedada se você já souber quais ferramentas podem ser carregadas ao criar a solicitação. Use a busca executada pelo cliente quando a descoberta de ferramentas depender do estado do projeto, do estado do tenant ou de outro sistema controlado pelo seu aplicativo.
Busca de ferramentas hospedada
A busca hospedada é a opção mais simples quando você já conhece o conjunto completo de funções, namespaces ou servidores MCP que deseja disponibilizar para a busca do modelo. Declare esses itens no início, adicione {"type": "tool_search"} e deixe a API decidir o que carregar.
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)Se o modelo decidir que precisa de uma ferramenta com carregamento sob demanda, a resposta incluirá dois itens de saída adicionais antes da chamada de função:
tool_search_call, que registra a etapa de busca hospedada.tool_search_output, que contém o subconjunto de ferramentas carregadas que o modelo passa a poder chamar.
[
{
"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\"}"
}
]No modo hospedado, execution tem o valor server e call_id tem o valor null.
Em tarefas mais complexas, o modelo também pode carregar vários namespaces ou servidores MCP no mesmo tool_search_call. Por exemplo, se precisar de funções de namespaces diferentes para concluir uma tarefa, o modelo pode optar por pesquisar e carregar esses namespaces juntos antes de fazer as chamadas de função subsequentes.
Busca de ferramentas executada pelo cliente
Com a busca executada pelo cliente, seu aplicativo tem controle total sobre como as ferramentas são descobertas. Isso é útil quando as ferramentas disponíveis dependem de informações que seria pouco prático declarar na lista inicial tools.
Configure a ferramenta tool_search com execution: "client" e um schema para os argumentos de busca esperados pelo aplicativo:
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)No primeiro turno, o modelo emite um tool_search_call e encerra o turno:
[
{
"type": "tool_search_call",
"execution": "client",
"call_id": "call_abc123",
"status": "completed",
"arguments": {
"goal": "Find the shipping ETA tool for order_42."
}
}
]Em seguida, seu aplicativo faz a busca e retorna um tool_search_output com as ferramentas que deseja carregar:
[
{
"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
}
}
]
}
]No turno seguinte, o modelo pode chamar a ferramenta carregada como qualquer outra função:
[
{
"type": "function_call",
"name": "get_shipping_eta",
"namespace": "get_shipping_eta",
"call_id": "call_xyz456",
"arguments": "{\"order_id\":\"order_42\"}"
}
]No modo cliente, execution tem o valor client e call_id recebe um valor. Retorne o mesmo call_id do tool_search_call no seu tool_search_output.
Uso avançado
Escreva descrições claras para os namespaces
Descreva com clareza o caso de uso de cada namespace. O modelo usa essa descrição para decidir quando carregar um subconjunto das funções do namespace. Evite descrições muito longas. Inclua mais detalhes nas descrições das funções com carregamento sob demanda, que só são carregadas quando necessário.
Entenda quais ferramentas são carregadas
tool_search_output.tools contém a lista de ferramentas que o modelo carregou dinamicamente. O modelo pode chamar qualquer uma delas nos turnos seguintes. Assim, no modo cliente, você não precisa carregar a mesma ferramenta novamente a cada turno. As ferramentas que não constam nesse array ficam indisponíveis para o modelo. Para desativar uma ferramenta carregada, você pode removê-la do item tool_search_output em que definiu o conjunto de ferramentas carregadas. Essa alteração, porém, invalida o cache do modelo a partir desse ponto.
Formas avançadas de inserir ferramentas
A maioria das integrações declara as ferramentas no parâmetro tools da solicitação. A busca executada pelo cliente também permite que o aplicativo retorne ferramentas que não constavam na solicitação original. Esse é um fluxo de trabalho avançado. Valide cuidadosamente os schemas retornados e disponibilize apenas definições de ferramentas confiáveis.
Busca de ferramentas e cache
Todas as ferramentas são carregadas no final da janela de contexto do modelo. Isso vale tanto para a busca hospedada quanto para a busca executada pelo cliente. Dessa forma, o cache do modelo é preservado de uma solicitação para outra, o que reduz o custo total e acelera o processamento.
Adicione ferramentas em um ponto específico da entrada
Em fluxos de trabalho avançados, use um item de entrada additional_tools para disponibilizar ferramentas em um ponto específico da conversa. Isso é útil quando seu aplicativo carrega ferramentas fora do fluxo normal de busca ou precisa manter a ordem em que as ferramentas foram adicionadas durante uma resposta anterior.
Defina role como developer e inclua as ferramentas a adicionar no array tools do item:
{
"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
}
}
]
}As ferramentas de um item additional_tools só ficam disponíveis depois que esse item aparece na entrada. Ao reenviar manualmente os itens da conversa em uma nova solicitação, mantenha o item na mesma posição para que o modelo veja as mesmas ferramentas no mesmo ponto da conversa.
Agents API
Por padrão, a Agents API carrega as definições das funções de imediato. Para adiar o carregamento de funções específicas, inclua { "type": "tool_search" } em agent.tools e defina defer_loading: true em cada função que o agente deve descobrir sob demanda. Adicionar tool_search não adia automaticamente o carregamento de todas as funções.
A solicitação de sessão continua fornecendo a definição completa da função, com nome, descrição e schema dos argumentos. A busca de ferramentas altera o momento em que essa definição chega ao modelo. Após a descoberta, seu aplicativo processa a chamada de função e retorna o resultado como de costume. Consulte Funções para saber como lidar com os resultados.
Defina OPENAI_API_KEY antes de executar este exemplo:
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);Escolha uma estratégia de carregamento de funções
| Estratégia | Configuração | Quando usar | Limitações |
|---|---|---|---|
| Carregamento imediato | Omita defer_loading ou defina o valor como false. |
Quando há poucas funções ou a maioria das tarefas precisa delas. | Definições não utilizadas ocupam espaço no contexto. Alterar uma definição pode invalidar um prefixo armazenado em cache. |
| Carregamento sob demanda | Defina defer_loading: true e inclua tool_search. |
Quando o catálogo é grande e cada tarefa precisa de poucas funções. | A descoberta acrescenta uma etapa e depende de o modelo encontrar a ferramenta relevante. |
A Agents API permite combinar funções com carregamento imediato e sob demanda na mesma sessão, mas, em geral, não recomendamos essa combinação. Dê nomes e descrições claros às funções com carregamento sob demanda. Antes de escolher a estratégia padrão, use solicitações representativas para comparar a conclusão das tarefas, o consumo de tokens de entrada e a latência.
Ferramentas MCP e de plugins
Na Agents API, as ferramentas MCP usam a descoberta automática quando o modelo e o provedor oferecem suporte à busca de ferramentas. O ambiente de execução adia o carregamento das ferramentas MCP e adiciona a busca de ferramentas quando há ferramentas com carregamento sob demanda disponíveis para pesquisa. Isso se aplica a servidores MCP remotos, servidores MCP de executores e ferramentas MCP fornecidas por plugins.
Você não precisa adicionar { "type": "tool_search" } só para usar ferramentas MCP nem definir a opção defer_loading no nível da função em um servidor MCP. Configure o servidor usando conexões MCP. A configuração da API Responses apresentada anteriormente neste guia não se aplica aos servidores MCP da Agents API.
Guias relacionados
- Use a chamada de função para definir funções que o modelo pode chamar e ferramentas personalizadas.
- Consulte Uso de ferramentas para conhecer as ferramentas disponíveis na API Responses.