Python + IA: Fundamentos e Projetos Práticos
Uma aplicação de inteligência artificial que responde sobre preços, notícias, normas, lançamentos ou qualquer informação recente não pode depender apenas do conhecimento interno do modelo. Ela precisa buscar dados no momento da pergunta, selecionar fontes e mostrar de onde cada afirmação veio. É exatamente esse o papel do Web Search na Responses API.
Neste tutorial, você vai criar em Python uma pesquisa assistida por IA que consulta a Web, restringe domínios quando necessário, recupera a lista completa de fontes e preserva citações clicáveis. O objetivo não é construir mais um “chat que pesquisa”, mas uma base auditável para relatórios, atendimento, monitoramento e automações.
Quando usar Web Search, File Search ou uma função própria
Escolha a ferramenta pela origem da verdade. Use Web Search quando a resposta depende de conteúdo público e atual: documentação que muda, comunicados, notícias, indicadores ou páginas institucionais. Use File Search quando a informação está nos seus PDFs, manuais, contratos ou documentos internos. Já o function calling é mais adequado quando o modelo precisa consultar ou alterar um sistema controlado por você.
Em muitos projetos, as três abordagens convivem. Um assistente de compras pode pesquisar informações públicas do produto, consultar a política interna da empresa e chamar uma função para registrar a solicitação. A separação importa porque cada fonte exige regras diferentes de segurança, atualização e autorização.
Princípio prático: a Web fornece evidências externas; seus arquivos fornecem contexto privado; suas funções executam ações. Não trate essas responsabilidades como se fossem equivalentes.
Prepare o projeto e faça a primeira pesquisa
Crie um projeto Python, instale o SDK oficial e mantenha a chave apenas no ambiente do servidor. Se você acompanhou a aula sobre ambientes com uv, pode iniciar assim:
uv init pesquisa-web
cd pesquisa-web
uv add openai
Defina OPENAI_API_KEY no ambiente e crie main.py:
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.6",
tools=[{"type": "web_search"}],
input=(
"Pesquise as mudanças mais recentes na documentação oficial "
"do Python sobre ambientes virtuais. Resuma em tópicos e cite as fontes."
),
)
print(response.output_text)
O item {"type": "web_search"} disponibiliza a pesquisa hospedada para o modelo. Com tool_choice="auto", que é o comportamento padrão, o modelo decide se precisa pesquisar. Se a atualização for requisito obrigatório do seu fluxo, use tool_choice="required" e registre no log se um item web_search_call realmente apareceu na resposta.
A documentação atual recomenda web_search para novas integrações. O antigo web_search_preview permanece apenas para compatibilidade e não oferece todos os controles novos.
Restrinja domínios e informe a localização do usuário
Uma pesquisa ampla pode encontrar material útil, mas também páginas secundárias, agregadores ou conteúdo sem responsabilidade editorial. Em temas técnicos, financeiros ou regulatórios, prefira limitar a busca a fontes primárias. O filtro aceita domínios sem https:// e inclui seus subdomínios.
response = client.responses.create(
model="gpt-5.6",
reasoning={"effort": "low"},
tools=[
{
"type": "web_search",
"filters": {
"allowed_domains": [
"docs.python.org",
"peps.python.org",
],
"blocked_domains": [
"reddit.com",
"quora.com",
],
},
}
],
tool_choice="required",
input="Quais mudanças recentes afetam a criação de ambientes virtuais?",
)
Para perguntas locais, acrescente uma localização aproximada. Isso é útil para legislação regional, eventos, serviços e recomendações geográficas:
tool = {
"type": "web_search",
"user_location": {
"type": "approximate",
"country": "BR",
"city": "São Paulo",
"region": "São Paulo",
},
}
Envie apenas a precisão necessária. Para uma pesquisa estadual, não há motivo para coletar endereço. Localização é contexto, não prova de que o resultado está correto; valide datas, jurisdição e fonte antes de automatizar uma decisão.
Recupere todas as fontes consultadas
O texto final inclui as citações mais relevantes, mas elas não representam necessariamente tudo o que foi consultado. Para auditoria, solicite também web_search_call.action.sources:
response = client.responses.create(
model="gpt-5.6",
tools=[{"type": "web_search"}],
include=["web_search_call.action.sources"],
tool_choice="required",
input="Pesquise a situação atual do suporte ao Python 3.13.",
)
data = response.model_dump()
for item in data.get("output", []):
if item.get("type") != "web_search_call":
continue
action = item.get("action") or {}
for source in action.get("sources", []):
print(source.get("url"))
Armazene a consulta, o horário, o modelo, os domínios permitidos e as URLs retornadas. Isso permite reproduzir uma decisão, investigar uma resposta ruim e detectar quando uma fonte mudou. Não salve páginas inteiras indiscriminadamente: registre somente o necessário e respeite sua política de retenção.
Transforme as anotações em citações clicáveis
Quando a pesquisa é usada, a saída contém um item message. Dentro do trecho output_text, o campo annotations informa o título, a URL e a posição da citação no texto. A interface precisa apresentar essas referências de forma visível e clicável — não esconda as fontes em um log técnico.
def extrair_citacoes(response):
citacoes = []
data = response.model_dump()
for item in data.get("output", []):
if item.get("type") != "message":
continue
for part in item.get("content", []):
if part.get("type") != "output_text":
continue
for annotation in part.get("annotations", []):
if annotation.get("type") == "url_citation":
citacoes.append({
"titulo": annotation.get("title"),
"url": annotation.get("url"),
"inicio": annotation.get("start_index"),
"fim": annotation.get("end_index"),
})
return citacoes
No front-end, valide o protocolo da URL, escape título e endereço e abra links externos com rel="noopener noreferrer". Se você gerar HTML, não aceite marcação arbitrária produzida pelo modelo. Uma alternativa segura é renderizar o texto como conteúdo comum e criar a lista de referências usando somente os objetos estruturados de anotação.
Proteja custo, qualidade e comportamento em produção
Pesquisa na Web adiciona latência e custo de ferramenta. Não a acione em perguntas atemporais que seu sistema já responde com segurança. Defina um orçamento por requisição, limite tentativas e use cache por consulta quando a necessidade de atualização permitir. Em caso de timeout, mostre que a pesquisa falhou; não transforme uma resposta sem fonte em uma resposta “atual”.
Também trate o conteúdo recuperado como dado não confiável. Uma página pode conter instruções maliciosas, publicidade disfarçada ou afirmações sem evidência. Diga explicitamente ao modelo para usar as páginas como fontes, nunca como instruções; filtre domínios em fluxos sensíveis; e exija confirmação humana antes de pagamentos, exclusões ou mudanças de permissão.
Monitore pelo menos: taxa de pesquisas acionadas, tempo total, número de fontes, domínios mais citados, respostas sem citação e feedback do usuário. Qualidade não é “a resposta parece boa”; é a capacidade de verificar o caminho entre pergunta, fonte e conclusão.
Checklist antes de colocar a pesquisa no ar
- A chave da API permanece somente no servidor.
- O projeto usa
web_search, e não a variante preview em uma integração nova. tool_choicecorresponde ao requisito: automático ou obrigatório.- Domínios primários são priorizados nos fluxos sensíveis.
- Citações aparecem visíveis e clicáveis para o usuário.
- A lista completa de fontes é registrada quando auditoria é necessária.
- URLs e textos são escapados antes de entrar no HTML.
- Timeout, cache, custo máximo e fallback estão definidos.
- Conteúdo recuperado nunca recebe autorização para executar ações.
Próximo passo: transforme pesquisa em evidência auditável
Comece com uma única consulta real do seu produto. Force a pesquisa, restrinja as fontes a domínios confiáveis, exiba as citações e registre as URLs consultadas. Depois compare a resposta com uma revisão humana. Esse ciclo simples revela problemas de consulta, cobertura e apresentação antes que a ferramenta seja conectada a decisões importantes.
O Web Search resolve a atualização da informação; ele não elimina sua responsabilidade sobre a qualidade. Quando combinado com saídas estruturadas, validação e observabilidade, torna-se uma peça sólida para construir aplicações que explicam não apenas o que responderam, mas em quais fontes se apoiaram.
Fontes oficiais: guia de Web Search da OpenAI e visão geral de ferramentas da Responses API.
