Web Search Tool

A Agentic Web Search Tool permite que seu Agente pesquise na web pública quando precisa de informações que não estão disponíveis em seu contexto ou fontes de conhecimento existentes. Isso é útil para obter informações externas atualizadas, validar fatos ou reunir referências de sites específicos.

---

🔎 Visão geral

Essa tool dá ao seu Agente uma forma agêntica de pesquisar na web.

O Agente envia uma descrição textual do que precisa encontrar. A busca é executada usando o OpenAI web search.

A tool retorna:

• Um texto consolidado com os achados mais relevantes
• Uma lista de URLs de origem encontradas durante a busca

---

⚙️ Campos de configuração

1. Name — Um nome claro que identifica o propósito da tool.
   Exemplo: Product Documentation Search
2. Description — Informa ao Agente quando e por que ele deve usar a tool.
   Mantenha específica para que o Agente possa escolher a tool no momento certo.
3. Allowed Domains — Restringe opcionalmente os resultados de busca a sites específicos.
   Use isso quando você quiser respostas apenas de fontes confiáveis ou oficiais.
   Digite os domínios sem https://.
   Exemplo: openai.com, e não https://openai.com/.
   Um domínio raiz também cobre seus subdomínios.
   Exemplo: openai.com também cobre subdomínios.
   A OpenAI suporta até 100 domínios permitidos para web_search.
4. Effort — Define o esforço de raciocínio usado durante a busca.
   Opções disponíveis: low, medium, high
5. Execution — Define se a tool é opcional ou obrigatória.
   Opções disponíveis:
   • eligible — O Agente decide quando usar a tool
   • compulsory — A tool deve ser executada
6. Prompt — Instrução extra opcional que orienta como a busca deve ser conduzida.
   Use-a para orientações curtas que melhoram a qualidade da busca.
7. LLM Provider — Substituição opcional de provedor para essa tool.
   Apenas provedores OpenAI são suportados.

---

🧠 Como funciona

1. O Agente decide usar a tool com base em sua configuração.
2. O Agente envia uma descrição textual da busca que precisa.
3. A tool realiza a busca usando o OpenAI web search.
4. Se Allowed Domains estiver configurado, os resultados ficam limitados a esses domínios.
5. Effort controla quanto raciocínio a busca aplica.
6. Execution controla se o uso da tool é opcional ou obrigatório.

Isso torna a tool útil para consultas externas que exigem informações atualizadas ou referências verificáveis.

Nota

A filtragem de domínio segue o comportamento do web_search da OpenAI na Responses API. A OpenAI suporta até 100 entradas em allowed_domains ou blocked_domains, mas esta tool atualmente expõe apenas Allowed Domains. Esses filtros não são suportados pela tool legada web_search_preview nem pelos modelos de busca do Chat Completions. Veja Filtragem de domínio do OpenAI Web Search.

---

📘 Exemplo de configuração

• Name: Product Documentation Search
• Description: Use esta tool quando precisar encontrar informações confiáveis nos sites oficiais de documentação do produto.
• Allowed Domains: docs.example.com, help.example.com
• Effort: medium
• Execution: eligible
• Prompt: Priorize a documentação oficial e resuma os achados mais relevantes.
• LLM Provider: provedor OpenAI padrão

Essa configuração ajuda o Agente a pesquisar em fontes de documentação confiáveis e retornar respostas concisas e embasadas.

---

💡 Boas práticas

• Mantenha a Description específica para que o Agente saiba quando usar a tool.
• Use Allowed Domains quando quiser restringir as buscas a fontes confiáveis.
• Liste os domínios em forma simples, sem prefixos de protocolo.
• Escolha um Effort mais alto apenas quando a tarefa exigir raciocínio mais profundo.
• Use a execução compulsory apenas quando toda interação relevante precisar incluir uma busca na web.
• Use o campo Prompt para orientações concisas, não instruções procedurais longas.