O HEALTHCHECK acrescenta um sinal objetivo: o Docker executa um teste dentro do container e registra os estados starting, healthy ou unhealthy. Com o Docker Compose, esse sinal também pode coordenar a inicialização de serviços dependentes e permitir que um deploy espere o ambiente ficar realmente pronto.

Nesta aula 8 da série Docker do Zero ao Profissional, vamos evoluir o projeto apresentado em Docker Compose: organizando múltiplos serviços. O exemplo usa uma API Python e PostgreSQL, mas o raciocínio vale para qualquer aplicação composta por vários containers.

Processo ativo não significa aplicação saudável

O Docker já sabe se o processo principal terminou. O healthcheck responde a outra pergunta: o serviço ainda consegue cumprir sua função mínima? Para uma API, isso costuma significar aceitar uma conexão HTTP e responder rapidamente. Para um banco, pode significar aceitar conexões. Para um worker, pode ser confirmar acesso à fila e a recursos essenciais.

Uma verificação útil deve ser:

• rápida, para não consumir recursos nem acumular processos;
• determinística, retornando sucesso ou falha sem ambiguidade;
• local, testando o serviço pelo ponto de vista do próprio container;
• representativa, sem executar uma operação pesada ou destrutiva;
• segura, sem expor dados sensíveis na resposta.

Evite usar apenas a existência do processo, porque isso repete o que o runtime já observa. Também evite chamar serviços externos desnecessários: se a API de um terceiro ficar fora do ar, todos os seus containers podem parecer doentes ao mesmo tempo.

A documentação do Docker informa que o comando do healthcheck sinaliza o resultado pelo código de saída. Na prática, 0 representa sucesso e 1 indica falha. Após o número configurado de falhas consecutivas, o status passa a unhealthy.

Crie endpoints de vida e prontidão

Em aplicações profissionais, é útil separar dois conceitos. Liveness confirma que o processo responde. Readiness confirma que ele está pronto para receber tráfego e acessar dependências indispensáveis.

Em uma API Flask, a estrutura pode começar assim:

from flask import Flask, jsonify
from sqlalchemy import text
from database import engine

app = Flask(__name__)

@app.get("/health/live")
def live():
    return jsonify(status="ok"), 200

@app.get("/health/ready")
def ready():
    try:
        with engine.connect() as connection:
            connection.execute(text("SELECT 1"))
        return jsonify(status="ready"), 200
    except Exception:
        return jsonify(status="not_ready"), 503

O endpoint de vida não consulta o banco; ele apenas prova que a aplicação responde. O de prontidão executa uma consulta mínima e devolve 503 quando a dependência essencial não está disponível. Não retorne stack traces, credenciais ou detalhes internos da infraestrutura.

Para um projeto pequeno, o healthcheck do container pode chamar /health/ready. Em ambientes maiores, a separação permite que a plataforma reinicie um processo que deixou de responder sem tratar uma indisponibilidade temporária do banco como falha fatal da aplicação.

Configure o HEALTHCHECK no Dockerfile

O teste pode fazer parte da imagem, seguindo a mesma evolução iniciada na aula Criando sua primeira imagem com Dockerfile. Como a imagem do exemplo já possui Python, podemos usar a biblioteca padrão e evitar instalar curl apenas para a verificação:

FROM python:3.13-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

HEALTHCHECK --interval=30s --timeout=5s \
  --start-period=20s --retries=3 \
  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health/ready', timeout=3)"]

CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app:app"]

Cada parâmetro controla uma parte do comportamento:

• interval: intervalo entre verificações;
• timeout: tempo máximo permitido para cada tentativa;
• start-period: período de tolerância para a aplicação inicializar;
• retries: quantidade de falhas consecutivas antes de marcar como não saudável.

Os valores precisam refletir o comportamento real do serviço. Um start-period curto demais gera falsos negativos durante migrações ou aquecimento. Um intervalo muito longo demora a revelar falhas. Um timeout exagerado mantém verificações presas e reduz a utilidade do sinal.

Há apenas um HEALTHCHECK efetivo por Dockerfile; se a instrução aparecer mais de uma vez, somente a última vale. Você também pode usar HEALTHCHECK NONE para desativar uma verificação herdada da imagem base.

Coordene banco e API no Docker Compose

O Compose permite definir ou sobrescrever o healthcheck de cada serviço. A forma longa de depends_on adiciona a condição service_healthy, fazendo a API esperar o banco ficar saudável antes de ser criada:

services:
  db:
    image: postgres:18
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    restart: unless-stopped

  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://app:${POSTGRES_PASSWORD}@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres_data:

A sintaxe curta depends_on: [db] garante a ordem de criação, mas não espera o banco aceitar conexões. service_healthy usa o resultado do healthcheck para fechar essa lacuna. Isso reduz erros de inicialização, mas a aplicação ainda deve implementar tentativas com espera progressiva: dependências podem cair depois que o ambiente já iniciou.

Mantenha a senha em um arquivo .env fora do Git ou, em produção, em um gerenciador de segredos. O healthcheck do PostgreSQL não precisa repetir a senha porque pg_isready apenas verifica o estado de aceitação de conexões.

Entenda o limite das políticas de reinício

restart: unless-stopped e HEALTHCHECK resolvem problemas diferentes. A política de reinício atua quando o processo do container termina; o healthcheck registra se um processo ainda ativo consegue atender ao teste. Um container marcado como unhealthy não é reiniciado automaticamente pelo Docker Engine apenas por causa desse estado.

As políticas mais comuns são:

• no: não reinicia automaticamente;
• on-failure: reinicia quando o processo termina com código diferente de zero;
• always: reinicia sempre, respeitando as regras de parada manual do Docker;
• unless-stopped: reinicia, exceto quando o container foi interrompido explicitamente.

Se a aplicação detectar uma condição irrecuperável, encerrar o processo com erro permite que on-failure ou unless-stopped atue. Para decisões mais sofisticadas — substituir instâncias doentes, limitar tentativas e distribuir tráfego — use um orquestrador compatível com essas necessidades. Não instale um supervisor dentro do container apenas para mascarar falhas; a documentação do Docker recomenda usar as políticas do runtime.

Valide o ambiente e provoque uma falha controlada

Antes de considerar o trabalho concluído, valide a configuração e espere os serviços ficarem saudáveis:

docker compose config
docker compose up --build --wait --wait-timeout 90
docker compose ps

A opção --wait aguarda os serviços atingirem o estado running ou healthy e implica modo destacado. Isso é especialmente útil em scripts de deploy e integração contínua, pois o comando falha em vez de seguir adiante com um ambiente incompleto.

Para inspecionar o histórico de uma verificação:

docker inspect --format '{{json .State.Health}}' projeto-api-1
docker compose logs --tail=100 api db

Em um ambiente local, pare o banco por alguns segundos e observe a API mudar de estado. Depois, inicie o banco novamente e confirme a recuperação. Esse teste revela se timeouts, tentativas e endpoints representam o comportamento real, sem esperar a primeira falha em produção.

Use este checklist antes do deploy:

• [ ] O teste verifica uma capacidade real do serviço, não apenas o processo?
• [ ] O endpoint responde rápido e não revela informações sensíveis?
• [ ] interval, timeout, start_period e retries foram ajustados ao tempo real de inicialização?
• [ ] Dependências críticas usam condition: service_healthy?
• [ ] A aplicação tolera a queda de uma dependência depois da inicialização?
• [ ] A política de reinício escolhida corresponde ao comportamento esperado?
• [ ] docker compose up --wait termina com sucesso no pipeline?
• [ ] Uma falha controlada foi observada nos estados e nos logs?

Com healthchecks bem definidos, o Docker deixa de informar apenas que processos existem e passa a mostrar se os serviços entregam a capacidade esperada. O próximo passo é levar essa confiabilidade ao processo de entrega: automatizar build, testes e publicação da imagem sem perder rastreabilidade. Enquanto isso, revise também as boas práticas de performance, segurança e organização no Docker para consolidar a base da aplicação.

O post Docker Healthcheck: containers confiáveis com Compose apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.

Esse é o ponto em que muitos negócios digitais travam. O empreendedor sai das entrevistas cheio de boas ideias, mas tenta transformar tudo em produto completo. Acrescenta funcionalidades, integrações, automações e promessas antes de descobrir se alguém aceita pagar por uma primeira versão do resultado.

Na aula 5 da série Negócios Digitais na Prática, vamos seguir o passo iniciado em Proposta de valor: transforme entrevistas em uma oferta clara. O objetivo agora é criar uma oferta piloto paga: pequena o bastante para ser entregue com controle e valiosa o bastante para produzir evidência real de compra e resultado.

O piloto não é desconto nem produto incompleto

Um piloto é um acordo limitado de aprendizado. Você atende um perfil específico, resolve uma parte bem definida do problema e acompanha o resultado de perto. O cliente sabe que está entrando em uma etapa inicial; você sabe exatamente quais hipóteses quer testar.

Isso é diferente de vender barato tudo o que imagina construir. Quando o escopo continua aberto, o preço reduzido apenas piora a operação: você recebe menos, assume mais risco e ainda termina sem saber qual parte gerou valor.

A Strategyzer recomenda que experimentos iniciais sejam baratos e rápidos, adiando construções caras quando existe uma forma mais simples de aprender. Também diferencia descoberta de validação: conversar ajuda a entender o problema; uma troca real de valor produz evidência mais forte. A oferta piloto cria essa passagem.

Ela deve responder a cinco perguntas:

1. Para quem é esta primeira versão?
2. Qual resultado específico será perseguido?
3. O que está incluído e o que está fora?
4. Quanto custa e quando será pago?
5. Qual evidência permitirá continuar, ajustar ou encerrar?

Se uma dessas respostas estiver vaga, a venda pode até acontecer, mas o aprendizado ficará confuso.

Escolha um cliente e um resultado estreitos

Comece pelas evidências reunidas na entrevista de problema. Não escolha “pequenas empresas” ou “criadores de conteúdo”. Escolha um grupo que compartilhe contexto, dor e urgência.

Compare:

Ajudo empresas a automatizar atendimento.

com:

Em 14 dias, organizo o atendimento inicial de clínicas pequenas que perdem contatos vindos do WhatsApp, implantando triagem, registro e acompanhamento dos novos pedidos.

A segunda formulação não promete transformar toda a operação. Ela define público, situação, prazo e resultado observável. Isso facilita a conversa comercial e reduz a quantidade de variáveis no piloto.

Use este modelo:

Para [perfil específico]
que hoje enfrenta [situação observável],
o piloto entrega [resultado limitado]
em [prazo],
sem exigir [barreira relevante].

O resultado deve ser importante para o cliente e possível de verificar. “Melhorar a presença digital” é abstrato. “Publicar uma página de oferta e captar dez conversas qualificadas” é mensurável. “Aumentar vendas” pode depender de fatores demais; “reduzir o tempo de resposta aos contatos” pode ser acompanhado diretamente.

Converta o resultado em um escopo protegido

O escopo existe para impedir que o piloto vire um projeto infinito. Organize-o em quatro blocos: entradas, atividades, entregáveis e limites.

Evite apresentar uma lista enorme de funcionalidades. O cliente compra progresso, não volume de tarefas. Três entregáveis ligados ao resultado costumam comunicar melhor que vinte itens técnicos.

Inclua também uma regra de mudança. Se surgir uma necessidade fora do combinado, registre-a como hipótese para uma próxima fase, em vez de absorvê-la silenciosamente. Essa disciplina protege margem, prazo e qualidade da evidência.

O MVP concierge é especialmente útil aqui. Você pode executar manualmente etapas que mais tarde serão automatizadas, desde que a experiência e os limites estejam claros. O piloto deve testar o valor do resultado antes de financiar uma infraestrutura complexa.

Defina um preço que teste compromisso e sustentabilidade

Preço zero mede interesse, disponibilidade e talvez uso. Não mede disposição de pagar. Se a hipótese central envolve um negócio sustentável, algum compromisso financeiro precisa entrar no teste.

O preço inicial não precisa ser perfeito, mas precisa ser explicável. Considere três referências:

• custo de entrega: horas, ferramentas, suporte e risco assumido;
• valor percebido: economia, receita, velocidade ou risco evitado pelo cliente;
• alternativas: quanto custa continuar como está ou contratar outra solução.

Para um piloto de serviço ou implantação, um valor fechado simplifica a decisão. Para software, o modelo deve acompanhar como o cliente recebe valor. A orientação atual da Stripe sobre precificação e empacotamento destaca que cobrança por usuário, faixa, consumo ou formato híbrido funciona melhor quando a métrica escolhida acompanha o benefício entregue.

Não use desconto sem contrapartida. Se o primeiro cliente receber uma condição especial, peça algo concreto: participação nas reuniões de revisão, dados de uso, autorização para um caso anonimizado ou depoimento condicionado a resultado. O desconto deixa de ser concessão aleatória e vira parte explícita do experimento.

Uma estrutura simples pode ser:

Investimento: R$ X
Pagamento: 50% no início e 50% na entrega
Prazo: 14 dias
Vagas do piloto: 3
Inclui: entregáveis A, B e C
Não inclui: itens D e E

O meio de pagamento não precisa atrasar a validação. A documentação da Stripe mostra que Payment Links permite criar uma página hospedada e compartilhável para produto ou assinatura sem desenvolver um checkout próprio. Use a solução compatível com seu negócio e sua região, mas mantenha a experiência profissional: descrição clara, recibo, confirmação e próximos passos.

Escreva critérios de sucesso antes de começar

Sem critérios definidos antecipadamente, qualquer resultado pode ser reinterpretado como vitória. Um experimento forte começa com uma hipótese precisa, participantes relevantes e evidências que realmente respondam à pergunta, como orienta a Strategyzer ao tratar do desenho de experimentos.

Defina critérios em três níveis:

Evidência comercial

• quantas pessoas do perfil receberam a oferta;
• quantas avançaram para conversa;
• quantas aceitaram o preço e pagaram;
• quais objeções apareceram repetidamente.

Evidência de entrega

• o piloto foi concluído dentro do prazo e do escopo;
• quantas horas e custos foram consumidos;
• onde houve dependência excessiva do fundador;
• quais etapas poderiam ser padronizadas.

Evidência de resultado

• qual indicador mudou para o cliente;
• em quanto tempo o primeiro valor apareceu;
• o cliente continuaria, renovaria ou indicaria;
• qual parte da solução ele considerou indispensável.

Estabeleça uma regra de decisão. Exemplo: “Se dois de cinco clientes qualificados comprarem, os três pilotos forem entregues em até 16 horas cada e pelo menos dois clientes atingirem o indicador combinado, criaremos a segunda versão.” Os números devem refletir sua realidade; o valor está em defini-los antes de conhecer o resultado.

Conduza o piloto como ciclo de aprendizado

Uma venda não encerra a validação. Ela inicia um ciclo curto de observação. Faça uma reunião de entrada, registre o estado inicial, entregue em marcos e marque uma revisão final.

Durante a execução, mantenha um diário simples:

Hipótese testada:
O que aconteceu:
Evidência observada:
Surpresa ou objeção:
Mudança proposta:
Decisão:

Evite mudar a oferta para cada cliente no meio do teste. Pequenas adaptações são naturais, mas alterações profundas impedem a comparação. Se três pessoas pedem a mesma mudança, isso é um sinal. Se apenas uma pede algo muito específico, pode ser exceção.

Ao final, separe satisfação de resultado. O cliente pode gostar do atendimento e ainda não obter valor econômico. Também pode atingir o objetivo com uma experiência operacional ruim. As duas dimensões importam para decidir o que padronizar.

Checklist para colocar a oferta na rua

Antes de convidar o primeiro cliente, confirme:

• [ ] o perfil do piloto está descrito de forma específica;
• [ ] o problema foi observado em entrevistas reais;
• [ ] existe um resultado limitado e mensurável;
• [ ] prazo, entradas e entregáveis estão claros;
• [ ] o documento informa explicitamente o que não está incluído;
• [ ] o preço cobre o aprendizado sem tornar a entrega inviável;
• [ ] a condição especial exige uma contrapartida definida;
• [ ] o pagamento e a confirmação estão preparados;
• [ ] os critérios de sucesso foram escritos antes da venda;
• [ ] existe uma reunião final para medir resultado e decidir o próximo passo.

A oferta piloto é a ponte entre “as pessoas disseram que gostaram” e “alguém assumiu um compromisso para obter o resultado”. Ela não precisa parecer uma empresa pronta. Precisa ser clara, honesta, entregável e capaz de gerar evidência.

Escolha hoje um único perfil, transforme sua proposta de valor em um resultado de curto prazo e escreva uma página com escopo, preço, limites e critérios de sucesso. Depois apresente-a a cinco pessoas qualificadas. A próxima versão do negócio deve nascer das respostas, das compras e da experiência de entrega — não de mais semanas planejando funcionalidades em isolamento.

O post Oferta piloto: defina escopo, preço e critérios de sucesso apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.

Nesta continuação da série Python + IA, vamos implementar esse fluxo com a Responses API, o SDK oficial para Python e Server-Sent Events (SSE). O objetivo não é somente imprimir fragmentos no terminal. Vamos organizar os eventos, preservar a resposta final e criar um endpoint que uma interface web possa consumir.

O streaming complementa recursos vistos nas aulas sobre saídas estruturadas, function calling e Web Search. Ele não muda o que o modelo é capaz de fazer; muda como a aplicação apresenta e controla a execução.

Por que streaming muda a experiência, mas não reduz o trabalho do modelo

Sem streaming, o fluxo é simples: seu código envia uma requisição, aguarda a conclusão e recebe um objeto pronto. Com streaming, a conexão permanece aberta e o servidor envia uma sequência de eventos. O SDK oficial implementa esse transporte sobre SSE quando stream=True é usado na criação da resposta.

Na prática, isso reduz a latência percebida. Uma geração que leva oito segundos pode começar a exibir conteúdo no primeiro ou segundo segundo. O tempo total e a quantidade de tokens, porém, podem continuar praticamente iguais. Portanto, streaming é uma melhoria de experiência e de arquitetura de entrega, não um desconto automático de custo.

Ele faz sentido em:

• chats e copilotos;
• geração de textos mais longos;
• explicações de código;
• pesquisas com várias etapas;
• interfaces nas quais o usuário precisa perceber progresso.

Para respostas curtas, tarefas em segundo plano ou automações que só podem agir depois de validar o resultado completo, uma chamada comum pode ser mais simples. Também é importante separar duas ideias: o fluxo pode exibir texto parcial, mas decisões críticas devem aguardar o evento de conclusão e as validações necessárias.

Prepare o projeto sem colocar a chave no código

Crie um ambiente isolado e instale o SDK. Se você acompanhou a aula sobre ambientes com uv, pode usar o mesmo padrão:

uv init streaming-ia
cd streaming-ia
uv add openai python-dotenv fastapi uvicorn

Guarde a credencial em uma variável de ambiente. Um arquivo .env local é conveniente durante o desenvolvimento, desde que esteja no .gitignore:

OPENAI_API_KEY=sua_chave_aqui
OPENAI_MODEL=gpt-5.5

O modelo fica configurável porque nomes e opções disponíveis podem variar entre projetos. O código não precisa ser alterado quando você troca o valor no ambiente.

import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")

Nunca envie a chave ao navegador nem a inclua em JavaScript público. A interface deve conversar com seu backend; somente o backend chama o provedor de IA.

Faça o primeiro streaming e filtre os eventos úteis

A implementação mínima usa stream=True e percorre o objeto retornado. O fluxo contém eventos de tipos diferentes: início, deltas de texto, conclusão de itens, término da resposta e possíveis falhas. Para mostrar texto, o evento mais importante é response.output_text.delta.

from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model=MODEL,
    input="Explique em cinco passos como revisar um pull request.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n\nResposta concluída.")
    elif event.type == "response.failed":
        print("\nA geração falhou.")

O flush=True evita que o terminal retenha pequenos fragmentos em um buffer. Em uma interface web, o equivalente é encaminhar cada delta imediatamente pela conexão aberta.

Evite imprimir todos os eventos para o usuário. Eles são úteis durante a depuração, mas podem incluir detalhes internos que poluem a interface. Trate explicitamente os tipos necessários e registre o restante de forma controlada.

Acumule o texto e diferencie parcial de concluído

Uma resposta parcial é ótima para leitura, mas não deve ser confundida com o resultado definitivo. A conexão pode cair, o usuário pode cancelar ou a geração pode terminar com erro. Por isso, acumule os deltas enquanto transmite e marque o resultado como concluído somente após receber o evento terminal esperado.

def gerar_resposta(pergunta: str) -> str:
    partes: list[str] = []
    concluida = False

    stream = client.responses.create(
        model=MODEL,
        input=pergunta,
        stream=True,
    )

    for event in stream:
        if event.type == "response.output_text.delta":
            partes.append(event.delta)
            print(event.delta, end="", flush=True)
        elif event.type == "response.completed":
            concluida = True
        elif event.type == "response.failed":
            raise RuntimeError("A API informou falha na resposta")

    if not concluida:
        raise RuntimeError("O fluxo terminou sem confirmação de conclusão")

    return "".join(partes)

Esse cuidado é especialmente importante quando o texto será salvo, enviado por e-mail ou usado como entrada de outra automação. Você pode mostrar o conteúdo enquanto chega, mas só persiste a versão final depois da confirmação.

Também registre informações operacionais sem armazenar conteúdo sensível: duração, tipo do evento terminal, modelo configurado e um identificador interno da requisição. Logs devem ajudar a diagnosticar falhas, não criar uma cópia desnecessária dos dados do usuário.

Exponha o fluxo para uma interface com FastAPI e SSE

O navegador pode consumir eventos enviados pelo seu backend. Neste exemplo, o FastAPI recebe a pergunta, abre o streaming com o SDK e encaminha apenas deltas sanitizados. StreamingResponse mantém a conexão HTTP aberta com o tipo text/event-stream.

import json
import os

from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from openai import AsyncOpenAI
from pydantic import BaseModel, Field

app = FastAPI()
client = AsyncOpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")


class Mensagem(BaseModel):
    pergunta: str = Field(min_length=2, max_length=4000)


@app.post("/chat/stream")
async def chat_stream(payload: Mensagem, request: Request):
    async def eventos():
        stream = await client.responses.create(
            model=MODEL,
            input=payload.pergunta,
            stream=True,
        )

        async for event in stream:
            if await request.is_disconnected():
                break

            if event.type == "response.output_text.delta":
                data = json.dumps(
                    {"tipo": "delta", "texto": event.delta},
                    ensure_ascii=False,
                )
                yield f"data: {data}\n\n"

            elif event.type == "response.completed":
                yield 'data: {"tipo":"concluida"}\n\n'

            elif event.type == "response.failed":
                yield 'data: {"tipo":"erro"}\n\n'

    return StreamingResponse(
        eventos(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",
        },
    )

Inicie o servidor com uv run uvicorn main:app --reload. O cabeçalho X-Accel-Buffering: no ajuda quando há um proxy compatível, mas a configuração real depende da sua infraestrutura. Teste o caminho completo em produção: aplicação, proxy, CDN e navegador. Um intermediário que acumula a resposta em buffer elimina o benefício do streaming.

Para uma aplicação pública, acrescente autenticação, limite por usuário, timeout, moderação adequada ao caso e proteção contra abuso. Também limite o tamanho da pergunta antes de iniciar uma chamada que gera custo.

Checklist de produção e próximos passos

Antes de liberar o recurso, verifique:

• [ ] a chave existe somente no backend e no gerenciador de segredos;
• [ ] a entrada tem limite de tamanho e validação;
• [ ] o frontend diferencia delta, conclusão e erro;
• [ ] texto parcial não dispara ações irreversíveis;
• [ ] desconexões interrompem o trabalho quando possível;
• [ ] proxy e CDN não acumulam o fluxo em buffer;
• [ ] timeouts e tentativas não duplicam uma operação;
• [ ] logs evitam dados pessoais e segredos;
• [ ] métricas acompanham tempo até o primeiro delta e tempo total;
• [ ] a interface oferece cancelar e tentar novamente.

Duas métricas ajudam bastante. Tempo até o primeiro delta mede a sensação de resposta. Tempo até a conclusão mede a duração real. Se o primeiro está baixo e o segundo alto, a interface parece ágil, mas talvez o prompt ou a tarefa ainda precisem ser otimizados.

O próximo passo natural é combinar streaming com ferramentas. Nesse caso, a interface precisa comunicar estados além do texto, como “consultando documentos” ou “verificando pedido”, sem expor argumentos internos nem fingir que uma ação terminou antes da validação.

Comece pelo script de terminal, confirme os eventos que sua aplicação realmente recebe e só então adicione FastAPI e frontend. Essa progressão torna os erros mais fáceis de localizar. Com o fluxo bem tratado, o streaming deixa de ser um efeito visual e vira uma camada confiável de entrega para produtos de IA mais responsivos.

O post Streaming com IA em Python: respostas em tempo real na prática apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.

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_choice corresponde 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.

O post Web Search com IA em Python: respostas atuais com fontes verificáveis apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.

Nesta aula, vamos partir das evidências coletadas na entrevista de problema e construir uma proposta de valor que possa ser explicada, entregue e testada. O objetivo não é encontrar uma frase bonita. É criar uma hipótese de valor específica o bastante para orientar produto, marketing e venda.

Transforme entrevistas em um perfil de cliente

Comece reunindo somente evidências de um segmento. A estrutura do Value Proposition Canvas organiza o perfil em três partes: os trabalhos que o cliente tenta realizar, as dores que dificultam esse progresso e os ganhos que ele deseja obter. “Trabalho” não significa apenas uma tarefa operacional; pode existir uma dimensão funcional, social ou emocional.

Um dono de pequeno e-commerce, por exemplo, pode querer responder clientes rapidamente — trabalho funcional —, manter a reputação da loja — trabalho social — e terminar o dia sem a sensação de que esqueceu uma reclamação — trabalho emocional. A mesma solução pode contribuir para as três dimensões, mas a pesquisa deve revelar qual delas realmente move a decisão.

Revise as entrevistas e converta cada trecho relevante em uma nota curta:

• Trabalho: o que a pessoa tenta concluir ou melhorar?
• Dor: qual obstáculo, custo, risco ou frustração aparece?
• Ganho: qual resultado ela espera, valoriza ou considera superior?
• Evidência: qual comportamento, situação ou consequência sustenta a nota?

Prefira fatos como “perde duas horas por dia copiando respostas” a rótulos vagos como “quer produtividade”. Preserve as palavras usadas pelo cliente em um campo separado; elas serão úteis para a comunicação. Não converta um elogio à sua ideia em evidência de compra.

Escolha um segmento e priorize o que realmente importa

Uma proposta para “empreendedores que querem crescer” é ampla demais para orientar qualquer decisão. Separe perfis com contexto, urgência e critérios de compra diferentes. Usuário e pagador também podem precisar de mapas distintos. A própria Strategyzer aponta que misturar vários segmentos no mesmo perfil dificulta identificar as prioridades e desenhar uma proposta convincente.

Depois de agrupar notas semelhantes, ordene cada trabalho, dor e ganho. Use quatro perguntas práticas:

1. Com que frequência essa situação aparece nas entrevistas?
2. Qual é a intensidade da consequência em tempo, dinheiro, risco ou estresse?
3. O cliente já tenta resolver o problema? Como?
4. Existe orçamento, autoridade e urgência para mudar agora?

Frequência sem intensidade pode indicar uma irritação pequena. Intensidade sem comportamento pode revelar um problema raro ou ainda não prioritário. Procure a combinação de recorrência, consequência e tentativa real de solução. Registre também evidências contrárias: elas impedem que a equipe selecione apenas falas que confirmam a ideia inicial.

Para o exemplo do e-commerce, imagine que as entrevistas mostrem três sinais repetidos: perguntas chegam por canais diferentes, respostas dependem do dono e atrasos geram cancelamentos. Esse conjunto é mais útil que a afirmação genérica “atendimento dá trabalho”.

Conecte dores e ganhos ao que sua oferta entrega

Agora construa o mapa de valor. Liste os produtos e serviços da oferta, como eles aliviam dores específicas e como criam ganhos relevantes. O ponto central é o encaixe: cada componente importante deve responder a uma prioridade observada no perfil do cliente.

Uma automação de atendimento poderia incluir triagem das mensagens, base de respostas aprovadas e encaminhamento para uma pessoa quando houver exceção. Esses componentes não são valiosos por existirem; são valiosos quando:

• reduzem o tempo gasto copiando respostas;
• diminuem o risco de uma reclamação ficar sem retorno;
• mantêm consistência entre canais;
• liberam o dono para tratar apenas casos que exigem decisão.

Não tente ligar a oferta a todas as dores e ganhos do mapa. A recomendação oficial do Value Proposition Canvas é concentrar-se no que é mais importante para o cliente. Uma proposta forte escolhe; uma proposta que promete resolver tudo geralmente fica genérica e difícil de comprovar.

Escreva uma proposta de valor que possa ser entendida

Com as prioridades definidas, transforme o mapa em uma frase de trabalho. Use o modelo abaixo como diagnóstico, não como slogan obrigatório:

Para [segmento em uma situação específica] que precisa [trabalho prioritário], nossa oferta ajuda a [resultado relevante] ao [mecanismo concreto], sem [dor ou risco da alternativa atual].

No exemplo:

Para pequenos e-commerces cujo atendimento ainda depende do dono, implementamos uma operação assistida que organiza mensagens e sugere respostas aprovadas, reduzindo atrasos sem deixar casos sensíveis nas mãos de uma automação sem supervisão.

A frase identifica segmento, situação, resultado, mecanismo e limite. Ela é mais confiável que “revolucione seu atendimento com inteligência artificial”, porque mostra o que muda e como. Evite números que ainda não foram medidos. Quando houver prova, substitua adjetivos por resultados verificáveis.

Teste a clareza com três perguntas: alguém do segmento reconhece o próprio contexto? Entende o resultado sem uma explicação adicional? Consegue perceber por que essa abordagem é diferente da alternativa atual? Se a resposta for não, volte ao mapa — trocar palavras no título não corrige uma hipótese de valor difusa.

Converta a proposta em mensagem e oferta

A proposta de valor orienta a comunicação, mas não precisa aparecer inteira como manchete. Em uma página simples, distribua seus elementos em uma sequência:

1. Contexto: mostre a situação que o cliente reconhece.
2. Resultado: descreva a mudança desejada com linguagem concreta.
3. Mecanismo: explique como a entrega produz essa mudança.
4. Prova: apresente demonstração, caso, amostra ou evidência disponível.
5. Próximo passo: convide para uma ação proporcional ao estágio da oferta.

Se o produto ainda está em validação, a prova pode ser uma demonstração manual, um protótipo ou a transparência de um MVP concierge. Não invente depoimentos nem apresente estimativas como resultados garantidos. Credibilidade nasce do alinhamento entre promessa, mecanismo e evidência.

A oferta também inclui escopo, prazo, participação do cliente, preço e redução de risco. Uma mensagem atraente sem uma entrega delimitada gera expectativas incompatíveis. Antes de anunciar, escreva claramente o que está incluído, o que não está e qual condição define sucesso.

Teste a proposta antes de ampliar o investimento

O canvas e a frase representam hipóteses. A Strategyzer recomenda testar a proposta porque o encaixe desenhado ainda não prova que o cliente se importa o suficiente para comprar. Use um experimento pequeno e defina antecipadamente qual comportamento contará como evidência.

Você pode criar duas versões de uma página, variar apenas a prioridade da mensagem e levar cada uma ao mesmo segmento. Outra opção é apresentar a proposta em conversas de venda e observar perguntas, objeções e avanço para o próximo passo. Para uma oferta nova, uma reserva, diagnóstico pago ou piloto fornece sinal mais forte que curtidas e elogios.

Registre uma hipótese no formato: “Acreditamos que [segmento] avançará para [ação] quando apresentarmos [proposta], porque [evidência].” Em seguida, defina volume, prazo e critério de decisão. Se o teste falhar, descubra qual parte está errada: segmento, prioridade, mecanismo, prova, preço ou canal.

Esse processo continua o trabalho de validar a oferta antes de construir. A meta não é defender a primeira frase, mas aprender qual promessa sustentável merece virar produto e campanha.

Checklist para sair do mapa e chegar ao mercado

• Use evidências de um segmento por vez.
• Separe trabalhos, dores, ganhos e fatos observados.
• Priorize recorrência, intensidade, comportamento e urgência.
• Conecte cada componente da oferta a uma prioridade real.
• Escolha o que não será resolvido nesta versão.
• Escreva segmento, resultado, mecanismo e risco evitado.
• Transforme a proposta em mensagem, prova e próximo passo.
• Defina o comportamento que validará ou rejeitará a hipótese.
• Atualize o mapa com evidências novas, inclusive as contrárias.

Uma boa proposta de valor não nasce de criatividade isolada. Ela é a síntese entre o progresso que um segmento busca, as dificuldades que enfrenta e uma entrega capaz de produzir um resultado relevante. Quando essa conexão está clara, produto, conteúdo e venda passam a contar a mesma história.

Na próxima etapa, transforme a proposta priorizada em uma página de teste e uma oferta-piloto. Continue a série Negócios Digitais na Prática: da Ideia às Primeiras Vendas para avançar da evidência à primeira venda com menos desperdício.

Referências: Value Proposition Canvas oficial, erros comuns no uso do canvas e teste de proposta de valor.

O post Proposta de valor: transforme entrevistas em uma oferta clara apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.

Nesta aula, você vai criar uma pequena central de suporte em Python. O sistema receberá um manual, localizará os trechos relevantes e responderá com referências ao arquivo consultado. É uma evolução natural depois de aprender function calling em Python: em vez de executar uma função externa, o modelo usará uma ferramenta hospedada para recuperar conhecimento.

O que o File Search faz — e quando vale a pena usar

O File Search é uma ferramenta da Responses API que combina busca semântica e busca por palavras-chave. Os arquivos são organizados em um vector store, processados e recuperados conforme a pergunta. A ferramenta é hospedada pela OpenAI, portanto você não precisa implementar manualmente geração de embeddings, indexação, comparação vetorial e montagem do contexto.

Use esse recurso quando a resposta depender de uma coleção de documentos: central de ajuda, políticas comerciais, procedimentos operacionais, catálogo técnico, contratos padronizados ou documentação de produto. Ele é diferente de enviar um arquivo isolado em toda requisição: o vector store cria uma base reutilizável e evita reenviar o mesmo conteúdo a cada pergunta.

Também não é o mesmo que function calling. File Search consulta conhecimento; function calling executa uma ação, como buscar um pedido no banco ou abrir um chamado. Em uma aplicação real, as duas ferramentas podem trabalhar juntas.

Prepare o projeto e um documento de teste

Crie uma pasta vazia, configure um ambiente virtual e instale o SDK oficial. Se você ainda organiza dependências manualmente, veja também o guia de Python com uv e pyproject.toml.

uv init suporte-file-search
cd suporte-file-search
uv add openai python-dotenv

Salve sua chave em um arquivo .env que não será enviado ao Git:

OPENAI_API_KEY=sua_chave_aqui

Agora crie manual-suporte.txt. Em produção, o conteúdo virá de documentos reais; aqui usaremos regras simples para conseguir verificar a qualidade da recuperação.

POLÍTICA DE TROCAS — versão 3, agosto de 2026

Produtos físicos podem ser trocados em até 30 dias após o recebimento.
O item deve estar sem sinais de uso e acompanhado da nota fiscal.
Produtos digitais não são reembolsáveis após o primeiro acesso.
Casos de cobrança duplicada devem ser analisados em até 2 dias úteis.
O atendimento humano funciona de segunda a sexta, das 9h às 18h.

Documentos com títulos claros, datas, seções curtas e linguagem consistente costumam produzir buscas melhores. Evite misturar versões conflitantes no mesmo arquivo sem identificar qual regra está vigente.

Envie o arquivo e crie o vector store

O primeiro script envia o documento pela Files API, cria o vector store e associa o arquivo à base. A documentação atual utiliza purpose="assistants" no upload. Depois da associação, aguarde o processamento antes de liberar perguntas na aplicação.

import os
import time
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

with open("manual-suporte.txt", "rb") as documento:
    arquivo = client.files.create(
        file=documento,
        purpose="assistants",
    )

base = client.vector_stores.create(name="Manual de suporte")

vinculo = client.vector_stores.files.create(
    vector_store_id=base.id,
    file_id=arquivo.id,
)

while vinculo.status == "in_progress":
    time.sleep(2)
    vinculo = client.vector_stores.files.retrieve(
        vector_store_id=base.id,
        file_id=arquivo.id,
    )

if vinculo.status != "completed":
    raise RuntimeError(f"Falha ao indexar: {vinculo.status}")

print("VECTOR_STORE_ID=", base.id)

Guarde o identificador da base em uma variável de ambiente. Não recrie o vector store em toda execução: além de duplicar conteúdo, isso dificulta controle de versões e custos. Em um fluxo de implantação, a indexação deve ser uma etapa separada da aplicação que responde aos usuários.

Faça uma pergunta com a Responses API

Com a base pronta, inclua a ferramenta file_search e informe os vector stores permitidos. O parâmetro max_num_results limita quantos resultados serão recuperados; valores menores podem reduzir latência e tokens, mas um limite agressivo pode retirar contexto importante.

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    input=(
        "Responda somente com base no manual. "
        "Qual é o prazo para troca de um produto físico e "
        "quais condições precisam ser atendidas?"
    ),
    tools=[{
        "type": "file_search",
        "vector_store_ids": [os.environ["VECTOR_STORE_ID"]],
        "max_num_results": 3,
    }],
    include=["file_search_call.results"],
)

print(response.output_text)

A resposta deverá mencionar os 30 dias, a ausência de sinais de uso e a nota fiscal. A saída também contém uma chamada file_search_call e uma mensagem com anotações do tipo file_citation. O parâmetro include acrescenta os resultados recuperados ao objeto retornado, algo útil para depuração, auditoria e avaliação.

Não confunda “há citação” com “a resposta está correta”. Exiba a fonte para o usuário e compare a afirmação com o trecho recuperado. Se sua automação precisa devolver dados estruturados para outro sistema, combine esta etapa com Structured Outputs e JSON validado.

Melhore relevância, escopo e segurança

A maior parte dos problemas de busca nasce na organização da base, não no prompt. Separe documentação por produto ou cliente, remova duplicatas e mantenha apenas versões vigentes. Em aplicações multiempresa, nunca dependa do texto da pergunta para isolar dados: use vector stores separados por tenant ou filtros de metadados controlados pelo servidor.

Os filtros permitem restringir resultados por atributos como categoria, região, versão ou status. Isso evita que uma pergunta sobre a política brasileira recupere uma regra de outro país. A escolha do filtro deve vir da identidade autenticada e das permissões da aplicação, e não de parâmetros livres enviados pelo navegador.

tools=[{
    "type": "file_search",
    "vector_store_ids": [os.environ["VECTOR_STORE_ID"]],
    "filters": {
        "type": "in",
        "key": "categoria",
        "value": ["suporte", "politicas_vigentes"],
    },
}]

Trate os documentos como dados sensíveis. Não faça upload de segredos, chaves, senhas ou informações pessoais sem necessidade e base legal. Defina responsáveis pela atualização, política de retenção e processo de exclusão. Registre qual versão do arquivo sustentou cada resposta importante.

Teste a qualidade antes de colocar em produção

Monte um conjunto de perguntas com respostas esperadas. Inclua casos fáceis, ambiguidades, informação inexistente e perguntas que deveriam ser recusadas. Avalie separadamente recuperação e geração: primeiro confirme se o trecho correto apareceu nos resultados; depois verifique se o modelo o interpretou sem inventar condições.

Um teste útil para este exemplo contém pelo menos estas perguntas:

• Qual é o prazo de troca para produto físico?
• Um produto digital acessado pode ser reembolsado?
• Em quanto tempo a cobrança duplicada é analisada?
• O suporte funciona no sábado?
• Qual é o prazo de garantia estendida? — a base não informa isso.

Para perguntas sem resposta documental, instrua o modelo a declarar a ausência da informação e encaminhar o caso. Monitore latência, quantidade de resultados, taxa de respostas fundamentadas e dúvidas que chegam ao atendimento humano. Ajuste max_num_results com dados reais, não por intuição.

Checklist de implementação e próximo passo

• Crie um vector store por domínio de conhecimento ou limite de acesso.
• Envie documentos limpos, versionados e com títulos descritivos.
• Aguarde a indexação terminar antes de aceitar consultas.
• Defina explicitamente os vector stores e filtros permitidos no servidor.
• Inclua os resultados durante testes para inspecionar a recuperação.
• Mostre citações e ofereça escalonamento quando a base não responder.
• Teste perguntas conhecidas, negativas, ambíguas e adversariais.
• Revise retenção, exclusão, custos e permissões periodicamente.

O File Search transforma uma coleção de documentos em uma fonte consultável pela IA sem exigir que você construa toda a infraestrutura de recuperação. O ganho real, porém, vem da disciplina: base bem governada, acesso restrito, perguntas de avaliação e fontes visíveis.

Como próximo passo, adapte o exemplo a um manual real e crie dez perguntas de teste antes de conectá-lo a uma interface. Continue acompanhando a série Python + IA: Fundamentos e Projetos Práticos para integrar essa busca a fluxos mais completos.

Referências oficiais: File Search na Responses API e Retrieval e vector stores.

O post File Search com IA em Python: consulte seus documentos na prática apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.

Nesta aula 33 da série Python + IA: Fundamentos e Projetos Práticos, vamos construir um assistente que consulta o status de um pedido. O exemplo usa a Responses API, esquema estrito, lista de funções permitidas e validação antes da execução. A implementação segue o fluxo atual da documentação oficial de function calling da OpenAI.

Do JSON estruturado para uma ação controlada

Na aula anterior, vimos como gerar JSON confiável com saídas estruturadas. Ali, o formato organiza a resposta final do modelo. No function calling, o JSON tem outra função: descrever uma solicitação para que a sua aplicação execute uma ferramenta.

Essa diferença é fundamental. O modelo não chama diretamente o banco de dados e não executa uma função Python por conta própria. Ele pode responder algo equivalente a “use a ferramenta consultar_pedido com o número AM-1042”. Seu programa recebe a solicitação, verifica o nome, valida os argumentos, executa a função permitida e devolve o resultado ao modelo.

O fluxo completo tem cinco etapas:

1. seu código oferece uma lista de ferramentas e seus esquemas;
2. o usuário faz uma pergunta;
3. o modelo produz uma chamada de ferramenta quando necessário;
4. a aplicação valida e executa a função;
5. o resultado volta ao modelo, que redige a resposta final.

A separação mantém a aplicação no controle. O modelo propõe; o código autoriza e executa.

Prepare o projeto e crie a função local

Você pode continuar o ambiente organizado com uv e pyproject.toml. No terminal, crie um projeto e instale o SDK:

uv init assistente-pedidos
cd assistente-pedidos
uv add openai

Configure OPENAI_API_KEY no ambiente, sem gravar a chave no arquivo Python. Em seguida, crie uma fonte de dados local para o tutorial:

PEDIDOS = {
    "AM-1042": {"status": "em transporte", "previsao": "12/08/2026"},
    "AM-1057": {"status": "separando itens", "previsao": "13/08/2026"},
}


def consultar_pedido(numero: str) -> dict:
    pedido = PEDIDOS.get(numero)
    if pedido is None:
        return {"encontrado": False, "numero": numero}

    return {
        "encontrado": True,
        "numero": numero,
        **pedido,
    }

Em produção, essa função poderia consultar uma API interna. Para aprender o fluxo, o dicionário em memória elimina dependências e deixa claro onde termina a IA e começa a regra de negócio.

Descreva a ferramenta com um esquema estrito

O modelo precisa conhecer o nome da função, sua finalidade e os argumentos aceitos. Na Responses API, a ferramenta pode ser descrita assim:

tools = [
    {
        "type": "function",
        "name": "consultar_pedido",
        "description": "Consulta o status de um pedido pelo número.",
        "strict": True,
        "parameters": {
            "type": "object",
            "properties": {
                "numero": {
                    "type": "string",
                    "description": "Identificador no formato AM-1234",
                }
            },
            "required": ["numero"],
            "additionalProperties": False,
        },
    }
]

Com strict: True, a chamada deve respeitar o esquema. A documentação oficial recomenda o modo estrito e exige que os campos sejam declarados em required e que objetos usem additionalProperties: false. Isso reduz argumentos inesperados, mas não substitui a validação da sua aplicação.

Uma string pode estar correta para o JSON Schema e ainda ser inválida para o negócio. AM-1042 atende ao formato esperado; qualquer-coisa continua sendo uma string. Por isso, vamos verificar o padrão antes de consultar os dados.

Detecte, valide e execute a chamada

Agora envie a pergunta junto com a definição da ferramenta. Desativaremos chamadas paralelas para que este exemplo aceite no máximo uma função por rodada:

import json
import re

from openai import OpenAI

client = OpenAI()

funcoes_permitidas = {
    "consultar_pedido": consultar_pedido,
}

input_list = [
    {"role": "user", "content": "Onde está o pedido AM-1042?"}
]

response = client.responses.create(
    model="gpt-5.6",
    input=input_list,
    tools=tools,
    parallel_tool_calls=False,
)

input_list += response.output

for item in response.output:
    if item.type != "function_call":
        continue

    if item.name not in funcoes_permitidas:
        resultado = {"erro": "ferramenta_nao_permitida"}
    else:
        try:
            argumentos = json.loads(item.arguments)
            numero = argumentos["numero"].strip().upper()

            if not re.fullmatch(r"AM-\d{4}", numero):
                raise ValueError("Número de pedido inválido")

            resultado = funcoes_permitidas[item.name](numero=numero)
        except (KeyError, ValueError, json.JSONDecodeError) as erro:
            resultado = {"erro": str(erro)}

    input_list.append(
        {
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps(resultado, ensure_ascii=False),
        }
    )

Nunca use eval() para executar o nome ou os argumentos enviados pelo modelo. O dicionário funcoes_permitidas é uma lista explícita de capacidades. Se aparecer outro nome, a aplicação recusa. O call_id liga o resultado à solicitação correta.

Devolva o resultado e gere a resposta final

O retorno de uma ferramenta deve ser uma string; JSON serializado funciona bem porque preserva campos e erros. Depois de adicionar function_call_output à lista, faça uma segunda chamada:

final = client.responses.create(
    model="gpt-5.6",
    input=input_list,
    tools=tools,
    instructions=(
        "Responda em português, de forma objetiva. "
        "Não invente status ou previsão ausentes no resultado da ferramenta."
    ),
)

print(final.output_text)

Para o pedido do exemplo, a resposta poderá informar que ele está em transporte e apresentar a previsão. Se o número não existir, o modelo recebe encontrado: false e deve explicar isso, sem criar dados. A qualidade depende tanto das instruções quanto da clareza do resultado devolvido pela função.

Em uma aplicação real, encapsule esse ciclo em uma função ou serviço. Também trate falhas temporárias da API interna, tempo limite e respostas sem chamada de ferramenta. O modelo pode responder diretamente quando não precisa consultar nada.

Proteja ferramentas com efeitos reais

Consultar um pedido é uma operação de leitura e oferece um bom primeiro projeto. Cancelar compra, enviar e-mail, emitir reembolso ou alterar cadastro exige controles adicionais. Um argumento bem formatado não prova que o usuário tem permissão para a ação.

Adote estas regras antes de disponibilizar ferramentas de escrita:

• Autorização fora do modelo: valide usuário, conta e escopo no backend.
• Confirmação explícita: mostre o efeito, o destinatário e o valor antes de uma ação irreversível.
• Idempotência: use uma chave para impedir reembolsos ou envios duplicados.
• Limites: defina valores máximos, formatos, tempo de execução e quantidade de chamadas.
• Logs seguros: registre ferramenta, resultado e duração, removendo chaves e dados sensíveis.
• Privilégio mínimo: cada ferramenta deve acessar apenas os dados necessários.

Também separe ferramentas de leitura das que causam efeitos. Comece com consultas, observe erros reais e só depois adicione ações. Function calling não transforma o modelo em autoridade; ele cria uma interface estruturada entre a intenção do usuário e uma capacidade controlada pelo sistema.

Checklist prático e próximo passo

Antes de colocar o fluxo em produção, confirme:

• o nome e a descrição da ferramenta são específicos;
• o esquema usa modo estrito, campos obrigatórios e bloqueio de propriedades extras;
• os argumentos passam por validação de formato e regra de negócio;
• apenas funções presentes na lista permitida podem ser executadas;
• o resultado referencia o call_id recebido;
• erros viram respostas controladas, sem expor segredos;
• ações sensíveis exigem autorização, confirmação e idempotência;
• logs e métricas permitem investigar o fluxo.

Execute o exemplo, troque o número do pedido e teste três cenários: pedido existente, identificador inválido e pedido não encontrado. Depois, substitua o dicionário por uma função de leitura do seu próprio sistema. Na próxima evolução, você poderá oferecer mais de uma ferramenta e criar um roteador seguro, mantendo validação e observabilidade em cada chamada.

O post Function calling em Python: conecte a IA a ferramentas com segurança apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.

Esta é a terceira aula da série Negócios Digitais na Prática. Depois de aprender a validar uma oferta antes de criar o produto e testar a entrega com um MVP concierge, agora vamos melhorar a qualidade do aprendizado: entrevistar clientes sem induzir respostas e transformar conversas em decisões.

Por que a entrevista vem antes da solução

Quando alguém se apaixona pela própria ideia, a tendência é procurar confirmação. Perguntas como “você usaria este aplicativo?” ou “pagaria por uma plataforma que economiza tempo?” parecem úteis, mas produzem respostas frágeis. A pessoa pode querer ser gentil, imaginar uma versão perfeita da solução ou dizer que compraria sem enfrentar a decisão real de compra.

A entrevista de problema muda o foco do futuro hipotético para o comportamento passado. Em vez de perguntar se o cliente gostaria de algo, você investiga a última vez em que o problema aconteceu, o que ele fez, quanto tempo perdeu, quais alternativas tentou e o que o impediu de resolver melhor.

O objetivo não é sair da conversa com elogios. É descobrir três pontos: se o problema acontece com frequência, se provoca uma consequência relevante e se a pessoa já investe algum recurso para contorná-lo. Esse recurso pode ser dinheiro, tempo, trabalho manual, risco assumido ou dependência de outra pessoa.

Escolha quem entrevistar e defina uma hipótese

Entrevistar “qualquer pessoa” mistura contextos e dificulta enxergar padrões. Comece com um perfil específico e uma situação observável. Por exemplo: “profissionais autônomos que recebem pelo menos dez pedidos de orçamento por mês e ainda organizam o acompanhamento em mensagens e planilhas”.

Antes da primeira conversa, escreva uma hipótese em uma frase:

Acredito que profissionais autônomos perdem oportunidades porque não conseguem acompanhar propostas e retornos com consistência.

Em seguida, liste o que precisaria ser verdade para essa hipótese merecer um experimento. Talvez o problema tenha ocorrido nas últimas duas semanas, causado perda de receita ou horas de retrabalho e levado o profissional a criar algum controle improvisado. Esses critérios evitam que uma história isolada pareça validação.

Procure pessoas que viveram a situação recentemente. Clientes atendidos manualmente no MVP concierge são ótimos candidatos, assim como contatos indicados por eles. Cinco entrevistas com o perfil correto ensinam mais do que cinquenta respostas de um público genérico.

Um roteiro de perguntas que busca comportamento real

Use um roteiro curto, mas trate a conversa como investigação, não como questionário. Estas sete perguntas funcionam bem em diferentes negócios:

1. Conte sobre a última vez em que isso aconteceu. Peça uma situação concreta, com começo, meio e fim.
2. O que desencadeou o problema? Descubra o evento que torna a necessidade urgente.
3. Como você resolveu naquele momento? A solução atual é seu concorrente real, mesmo que seja uma planilha ou trabalho manual.
4. Qual foi a parte mais difícil? Explore o custo emocional, operacional ou financeiro.
5. Quanto tempo ou dinheiro isso consumiu? Busque uma ordem de grandeza, sem exigir precisão artificial.
6. O que você já tentou fazer diferente? Tentativas anteriores revelam prioridade e barreiras.
7. Quem mais participa da decisão ou é afetado? Identifique usuários, compradores, influenciadores e bloqueadores.

Depois de cada resposta ampla, use perguntas de aprofundamento: “o que aconteceu depois?”, “pode me dar um exemplo?” e “por que isso foi importante?”. O detalhe costuma aparecer na segunda ou terceira camada.

Como conduzir sem vender sua ideia

Abra a conversa explicando que você está pesquisando o processo atual e que não há resposta certa. Peça autorização para anotar. Se quiser gravar, solicite consentimento explícito e informe como o arquivo será usado. Uma entrevista de 20 a 30 minutos costuma ser suficiente quando o recorte é claro.

Durante a conversa, fale pouco. Não complete frases, não defenda uma funcionalidade e não transforme cada dor em promessa. Se a pessoa perguntar sobre sua solução, diga que você contará no final, mas que primeiro precisa compreender como ela trabalha hoje.

Evite três armadilhas comuns:

• Pergunta que contém a resposta: “Seria melhor receber lembretes automáticos, certo?” Troque por “como você se lembra de fazer o retorno?”.
• Pedido de opinião sobre uma ideia: “o que achou do meu produto?” Troque por perguntas sobre o último episódio do problema.
• Excesso de explicação: se você fala por dez minutos, está apresentando, não entrevistando.

Observe contradições sem confrontar. Alguém pode dizer que o problema é urgente e, ao mesmo tempo, nunca ter tentado resolvê-lo. Registre as duas informações. A ausência de ação também é evidência.

Transforme respostas em evidências comparáveis

Não confie apenas na memória ou na sensação de que “a conversa foi ótima”. Logo após cada entrevista, registre os mesmos campos: perfil, contexto, episódio recente, solução atual, frequência, impacto, tentativa anterior, barreira, frase marcante e próximo contato.

Separe fatos de interpretações. “Perdeu duas propostas no último mês porque esqueceu o retorno” é fato relatado. “Precisa de um CRM com inteligência artificial” é interpretação. A primeira informação ajuda a decidir; a segunda pode limitar prematuramente as alternativas.

Crie uma matriz simples com as entrevistas nas linhas e os sinais nas colunas. Marque a presença de quatro evidências:

• o problema ocorreu recentemente;
• há impacto mensurável ou consequência relevante;
• existe um método atual, ainda que improvisado;
• a pessoa aceitou avançar para uma ação concreta.

A ação concreta vale mais do que entusiasmo. Pode ser apresentar você a outro profissional, compartilhar um exemplo real, testar um protótipo, reservar horário para uma demonstração ou aceitar uma proposta paga. “Parece interessante” não tem o mesmo peso.

Decida o próximo experimento

Depois de cinco a oito entrevistas do mesmo perfil, procure padrões. Se a mesma situação, impacto e solução improvisada aparecem repetidamente, transforme o aprendizado em um experimento pequeno. Você pode oferecer uma entrega manual, criar uma página com uma promessa específica ou testar uma pré-venda com escopo limitado.

Se as dores forem diferentes, não force uma média. Talvez o segmento esteja amplo demais. Recorte por contexto, frequência ou maturidade. Um autônomo com dois orçamentos por mês vive uma realidade diferente de uma pequena agência com cinquenta oportunidades abertas.

Se ninguém tomou qualquer iniciativa para resolver o problema, reavalie a prioridade. Isso não significa que o tema seja irrelevante, mas indica que talvez não sustente uma oferta agora. Voltar à hipótese custa menos do que construir algo que dependerá de muita persuasão para ser usado.

O resultado ideal da entrevista não é uma lista de funcionalidades. É uma decisão mais nítida: aprofundar o mesmo problema, mudar o segmento, testar uma promessa ou abandonar uma hipótese fraca.

Checklist prático e próximo passo

Antes de entrevistar, confirme:

• defini um perfil específico e uma situação recente;
• escrevi a hipótese e os sinais que poderiam confirmá-la ou enfraquecê-la;
• preparei perguntas sobre fatos passados, não intenções futuras;
• reservei mais tempo para ouvir do que para explicar;
• criei um modelo único para registrar todas as conversas;
• defini uma ação concreta que pode indicar interesse real;
• vou comparar padrões antes de escolher funcionalidades.

Seu próximo passo é simples: selecione cinco pessoas do mesmo perfil, convide-as para uma conversa de 25 minutos e conduza as entrevistas ao longo de uma semana. Ao final, escolha apenas uma hipótese para testar. Na próxima etapa da série, vamos converter essas evidências em uma proposta de valor específica, compreensível e difícil de confundir com promessas genéricas.

O post Entrevista de problema: como descobrir dores reais sem vender a solução apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.

O MVP concierge resolve esse problema de maneira direta. Em vez de automatizar tudo desde o início, você entrega manualmente uma versão pequena da solução para poucos clientes, acompanha o uso de perto e transforma o aprendizado em um processo repetível. O cliente compra o resultado; a operação, nos bastidores, ainda pode usar planilhas, mensagens e trabalho especializado.

Esta é a parte 2 da série Negócios Digitais na Prática: da Ideia às Primeiras Vendas. Se ainda não confirmou a demanda, comece pela aula sobre como validar uma oferta antes de criar o produto. Aqui, vamos avançar do sinal de interesse para uma entrega real, paga e controlada.

O que é um MVP concierge e quando usar

Um MVP concierge é uma versão inicial em que parte relevante da entrega acontece manualmente, embora a experiência do cliente seja organizada como um produto. Você não finge que existe uma tecnologia pronta. Explica o escopo, o prazo e como o serviço funciona, mas evita investir em software antes de entender o trabalho que merece ser automatizado.

Imagine uma solução que cria um plano editorial para pequenos negócios. A visão final pode incluir painel, integrações, geração com IA e calendário automático. No MVP concierge, o cliente responde a um formulário, você analisa o posicionamento, monta o plano com ferramentas existentes e apresenta as recomendações em uma reunião curta. A promessa é a mesma — sair com um plano aplicável —, mas o mecanismo inicial é humano.

Esse formato é útil quando o problema exige descoberta, julgamento ou personalização; quando você ainda não conhece todas as exceções; e quando construir a automação custaria mais do que executar alguns ciclos manualmente. Não é uma desculpa para entregar de qualquer jeito. É um método para aprender com proximidade sem confundir atividade com produto validado.

Defina uma promessa pequena e verificável

O MVP precisa de uma transformação clara. “Ajudar empresas a crescer” é amplo demais. “Entregar em 48 horas um diagnóstico de conteúdo com três prioridades e um plano de 14 dias” estabelece resultado, prazo e limite.

Escreva a oferta em uma frase usando esta estrutura:

Eu ajudo [perfil específico] a alcançar [resultado observável] por meio de [entrega principal], em [prazo], sem [objeção relevante].

Depois, descreva o que está incluído e o que não está. No exemplo do plano editorial, a primeira versão pode incluir diagnóstico, três pilares, dez ideias e uma revisão. Não inclui publicação, criação de artes, gestão de anúncios nem suporte ilimitado. Esses limites protegem a margem, reduzem mal-entendidos e tornam os ciclos comparáveis.

Escolha também um critério de conclusão. A entrega termina quando o cliente recebe o plano e participa da revisão? Quando aprova as prioridades? Sem esse marco, cada cliente transforma o MVP em um projeto diferente, e você perde a capacidade de aprender sobre um processo comum.

Desenhe o fluxo manual de ponta a ponta

Mapeie a experiência antes de vender. Um fluxo simples pode ter seis etapas:

1. Qualificação: confirme perfil, problema, urgência e capacidade de decisão.
2. Pagamento: use um meio confiável e registre condições, prazo e política de cancelamento.
3. Onboarding: colete apenas as informações necessárias para começar.
4. Produção: execute uma lista de tarefas com responsável e prazo.
5. Entrega: apresente o resultado em um formato consistente.
6. Aprendizado: registre dúvidas, ajustes, tempo gasto e próximo passo.

Para cada etapa, defina entrada, ação e saída. Se o onboarding começa com um formulário, a saída pode ser um briefing completo ou uma solicitação automática de complemento. Se a produção depende de uma entrevista, determine quem agenda, quanto dura e quais perguntas são obrigatórias.

Use ferramentas simples: formulário, agenda, documento, planilha e um quadro de tarefas. A sofisticação agora deve estar na clareza, não na quantidade de aplicativos. O fluxo precisa ser visível para que você descubra onde há espera, retrabalho ou informação faltando.

Venda o primeiro ciclo com escopo claro

O objetivo não é distribuir uma amostra indefinidamente. Uma cobrança real testa prioridade, expectativa e disposição para assumir compromisso. O valor pode ser introdutório, desde que cubra a entrega combinada e seja apresentado como condição daquela fase.

Comece com poucos clientes que compartilhem um perfil semelhante. Misturar um profissional autônomo, uma loja local e uma empresa grande pode produzir pedidos incompatíveis e esconder o padrão. Convide pessoas que já demonstraram o problema durante a validação e descreva a proposta sem prometer recursos futuros.

Uma mensagem direta pode seguir este roteiro:

Estou abrindo poucas vagas para uma primeira versão acompanhada de [solução]. Em [prazo], você recebe [entregáveis]. Como esta fase é próxima e manual, vou pedir feedback em dois momentos. O investimento é [valor] e o escopo inclui [limites].

Registre a concordância com entregáveis, datas e responsabilidades. Se sua oferta envolve um trabalho técnico, o guia sobre como transformar um projeto em proposta para o primeiro cliente ajuda a estruturar esse compromisso sem criar uma apresentação excessiva.

Aprenda com comportamento, não apenas com elogios

Uma conversa final é útil, mas o comportamento durante a entrega revela mais. Observe quais perguntas aparecem antes do pagamento, onde o cliente demora a responder, quais partes da entrega ele usa primeiro e quais recomendações viram ação.

Mantenha um diário operacional por ciclo com cinco registros:

• tempo gasto em cada etapa;
• dúvidas e objeções repetidas;
• informações que faltaram no onboarding;
• ajustes solicitados e sua causa;
• resultado ou decisão tomada pelo cliente após a entrega.

Faça perguntas específicas. Em vez de “você gostou?”, pergunte: “qual parte você aplicaria amanhã?”, “o que quase fez você desistir?” e “qual etapa ainda depende de explicação?”. Separe pedidos isolados de padrões. Uma sugestão pode ser interessante, mas só deve alterar o produto quando reforçar a promessa central ou se repetir no público escolhido.

A cada ciclo, atualize um documento de decisões: o que permanece, o que muda, o que foi recusado e por quê. Essa memória impede que a operação seja redesenhada pela última conversa.

Padronize antes de automatizar

Automatizar um fluxo instável apenas acelera confusão. Primeiro, transforme as partes recorrentes em padrões: roteiro de qualificação, formulário, checklist de produção, modelo de entrega, mensagens de acompanhamento e critérios de qualidade.

Classifique cada atividade em três grupos:

• Manter humana: exige julgamento, negociação, empatia ou decisão sensível.
• Padronizar: repete-se, mas ainda está amadurecendo e precisa de checklist.
• Automatizar: possui entrada previsível, regra clara, saída verificável e volume suficiente para justificar o esforço.

Por exemplo, enviar confirmação de pagamento e criar uma tarefa são bons candidatos à automação. Interpretar uma objeção complexa ou aprovar uma recomendação estratégica pode continuar humano. Quando chegar a hora de conectar sistemas, consulte o comparativo sobre quando usar n8n ou programação.

Antes de automatizar, calcule o benefício concreto: horas poupadas, redução de erro, menor tempo de resposta ou capacidade adicional. Se uma integração leva semanas para economizar poucos minutos em uma etapa rara, ela não é prioridade.

Checklist para executar seu MVP concierge

• Validei que o problema é frequente e relevante para um público específico.
• Defini uma promessa observável, prazo, entregáveis e exclusões.
• Estabeleci pagamento, capacidade máxima e critério de conclusão.
• Mapeei qualificação, onboarding, produção, entrega e feedback.
• Preparei modelos simples sem construir uma plataforma antecipadamente.
• Selecionei poucos clientes com perfil semelhante.
• Registrei tempo, objeções, ajustes e uso real da entrega.
• Separei exceções individuais de padrões recorrentes.
• Padronizei o processo antes de escolher automações.
• Defini o que continuará humano por segurança ou qualidade.

O MVP concierge não é o produto final, mas também não é improvisação. Ele é uma operação pequena, transparente e desenhada para produzir duas coisas ao mesmo tempo: valor para o cliente e evidência para o negócio.

Seu próximo passo é escolher uma promessa que possa ser entregue em poucos dias, mapear o fluxo em uma página e convidar os primeiros clientes validados. Execute três ciclos sem adicionar funcionalidades no meio. Ao final, compare o que se repetiu. Essa repetição — e não a ansiedade por parecer escalável — mostrará o que merece virar produto, processo ou automação.

O post MVP concierge: como vender e aprender antes de automatizar apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.

Nesta aula da série Python + IA: Fundamentos e Projetos Práticos, vamos usar Structured Outputs, Pydantic e a Responses API da OpenAI para transformar uma solicitação de suporte em dados tipados. O resultado poderá alimentar uma fila, um banco de dados, um webhook ou uma automação no n8n sem depender de expressões regulares frágeis.

O objetivo não é apenas obter um JSON válido. É garantir que os campos esperados existam, que os valores respeitem o schema e que o código Python saiba o que fazer quando a resposta não puder ser processada.

Por que “responda em JSON” não basta

Pedir JSON no prompt ajuda, mas não cria um contrato. O modelo ainda pode devolver uma chave diferente, omitir um campo obrigatório ou escolher um valor que sua aplicação não reconhece. O modo JSON resolve parte do problema porque produz JSON sintaticamente válido, mas não garante aderência ao formato de negócio.

Structured Outputs acrescenta essa garantia de schema. Segundo a documentação oficial da OpenAI, a resposta segue o JSON Schema fornecido, incluindo chaves obrigatórias e enumerações compatíveis com os recursos suportados. No SDK Python, podemos declarar o formato com um modelo Pydantic e receber o objeto já analisado.

Essa distinção muda a arquitetura. Em vez de extrair texto e tentar corrigi-lo depois, definimos primeiro o que a aplicação aceita. A IA passa a preencher esse contrato. Ainda precisamos validar regras de negócio e tratar falhas operacionais, mas eliminamos uma grande classe de erros de formatação.

Prepare o projeto e proteja a chave

Crie um ambiente isolado e instale o SDK da OpenAI e o Pydantic. Se você acompanhou a aula anterior sobre ambientes reproduzíveis com uv e pyproject.toml, pode continuar no mesmo padrão:

uv init triagem-ia
cd triagem-ia
uv add openai pydantic

A introdução oficial da API orienta configurar OPENAI_API_KEY como variável de ambiente; o SDK a lê automaticamente. Não coloque a chave no arquivo Python, no repositório ou em uma captura de tela. Em produção, use o gerenciador de segredos da sua infraestrutura e conceda acesso apenas ao serviço que executa a automação.

O projeto deste tutorial terá um arquivo main.py. A entrada será uma mensagem livre enviada por um cliente. A saída deverá conter categoria, prioridade, resumo, indicação de atendimento humano e tags.

Modele o contrato com Pydantic

Comece pelos valores que não podem variar livremente. A prioridade será uma enumeração, enquanto o restante será descrito em um modelo Pydantic:

from enum import Enum
from pydantic import BaseModel, Field


class Prioridade(str, Enum):
    baixa = "baixa"
    media = "media"
    alta = "alta"


class Triagem(BaseModel):
    categoria: str = Field(
        description="Fila curta: financeiro, acesso, suporte ou comercial"
    )
    prioridade: Prioridade
    resumo: str = Field(
        description="Resumo objetivo da solicitação em até duas frases"
    )
    requer_humano: bool
    tags: list[str]

O schema é a fronteira entre o modelo e o restante do sistema. Quanto mais previsível ele for, mais simples será integrar. Uma enumeração é melhor que instruções como “use baixa, média ou alta”, pois impede variações inesperadas. Para categoria, poderíamos criar outra enumeração; deixamos como texto neste exemplo para demonstrar uma validação de negócio posterior.

Evite transformar o schema em um espelho de toda a sua base. Inclua somente os dados necessários para a próxima decisão. Campos demais aumentam complexidade, manutenção e risco de armazenar informações que não deveriam circular.

Gere a resposta estruturada com a Responses API

Agora crie o cliente e use responses.parse. A documentação atual recomenda começar novos projetos com a Responses API e mostra o parâmetro text_format para informar o modelo Pydantic:

from openai import OpenAI

client = OpenAI()

solicitacao = """
Não consigo acessar minha conta desde ontem.
Já redefini a senha duas vezes e preciso emitir uma nota hoje.
"""

response = client.responses.parse(
    model="gpt-5.6",
    input=[
        {
            "role": "system",
            "content": (
                "Classifique solicitações de suporte. "
                "Não invente dados. Marque requer_humano como verdadeiro "
                "quando houver urgência, bloqueio de acesso ou ambiguidade."
            ),
        },
        {"role": "user", "content": solicitacao},
    ],
    text_format=Triagem,
)

triagem = response.output_parsed

if triagem is None:
    raise RuntimeError("A resposta não pôde ser convertida para o schema.")

print(triagem.model_dump_json(indent=2))

O atributo output_parsed entrega uma instância de Triagem, não uma string para ser decodificada manualmente. O editor, os testes e o analisador de tipos passam a conhecer os campos disponíveis. Se o schema mudar, o ponto de integração fica explícito.

O prompt de sistema continua importante. Structured Outputs garante a forma, mas não torna verdadeira uma classificação ruim. Descreva critérios objetivos, forneça contexto suficiente e teste exemplos reais antes de automatizar uma consequência relevante.

Transforme o resultado em uma decisão de automação

Com o objeto validado, a aplicação pode decidir a fila sem interpretar linguagem natural novamente:

CATEGORIAS_PERMITIDAS = {
    "financeiro",
    "acesso",
    "suporte",
    "comercial",
}


def decidir_fila(triagem: Triagem) -> str:
    categoria = triagem.categoria.strip().lower()

    if categoria not in CATEGORIAS_PERMITIDAS:
        return "revisao-manual"

    if triagem.requer_humano or triagem.prioridade is Prioridade.alta:
        return "atendimento-humano"

    return f"fila-{categoria}"


fila = decidir_fila(triagem)
print({"fila": fila, "dados": triagem.model_dump()})

Observe que ainda validamos as categorias permitidas. O schema resolve o formato; a função protege uma regra local. Essa separação é saudável: o modelo organiza e classifica, enquanto o código controla quais ações podem acontecer.

O dicionário retornado pode ser enviado a um endpoint, gravado em uma tabela ou passado a uma ferramenta de automação. Se você estiver decidindo entre um fluxo visual e código, veja também quando usar n8n ou programação para automatizar processos. Uma arquitetura comum usa Python para a classificação tipada e n8n para orquestrar notificações, CRM e filas.

Trate recusas, falhas e validações operacionais

Uma resposta estruturada não elimina indisponibilidade de rede, limites da API, recusa do modelo ou entrada maliciosa. Em produção, trate esses casos como estados esperados, nunca como exceções impossíveis.

• Ausência de resultado analisado: não execute a ação. Envie o item para revisão ou uma fila de retentativa.
• Falha temporária: aplique tentativas limitadas com espera progressiva. Não crie um ciclo infinito.
• Regra sensível: pagamentos, bloqueios, decisões legais e alterações irreversíveis exigem confirmação humana.
• Dados pessoais: envie apenas o mínimo necessário e evite registrar a mensagem completa em logs.
• Observabilidade: registre identificador, duração, versão do schema, fila escolhida e tipo de falha, sem expor segredos.
• Testes: mantenha exemplos de mensagens urgentes, vagas, contraditórias e fora de escopo.

Também defina um limite de tamanho para a entrada e normalize o texto antes do envio. Em vez de aceitar qualquer categoria produzida, use enumerações sempre que o domínio for estável. Quando o objetivo for chamar funções ou ferramentas durante a resposta, use function calling; quando o objetivo for estruturar a resposta do próprio modelo, use Structured Outputs em text.format. Essa é a separação recomendada na documentação.

Checklist prático e próximo passo

• Criei um ambiente isolado e instalei openai e pydantic.
• Configurei OPENAI_API_KEY fora do código.
• Defini um modelo Pydantic pequeno e orientado à próxima decisão.
• Usei responses.parse com text_format.
• Verifiquei se output_parsed existe antes de agir.
• Separei aderência ao schema de validação das regras de negócio.
• Criei uma rota segura para falhas, recusas e categorias desconhecidas.
• Adicionei logs mínimos, testes e revisão humana para ações sensíveis.

O salto de qualidade acontece quando a IA deixa de entregar “um texto que parece certo” e passa a participar de um sistema com contratos, limites e rotas de segurança. Structured Outputs torna a integração mais previsível; Pydantic aproxima o schema do código; e a função de decisão mantém a autoridade final na aplicação.

Como exercício, adapte Triagem ao seu contexto: leads, pedidos, currículos ou tickets internos. Separe dez entradas reais, defina a saída mínima que o próximo passo exige e teste os casos ambíguos. Na próxima evolução, esse mesmo objeto poderá alimentar uma API ou um fluxo completo de automação sem perder a rastreabilidade.

O post Saídas estruturadas com IA: JSON confiável para automações em Python apareceu primeiro em Asllan Maciel | Tecnologia, IA e Produtos Digitais.