Como criar um assistente de IA com Python e a API Responses da OpenAI

Neste tutorial, você vai criar um assistente de texto simples em Python usando a API oficial da OpenAI. Ele recebe uma pergunta e devolve uma resposta, mantendo o contexto das mensagens anteriores durante a execução. O exemplo é um primeiro passo para aprender a integrar um modelo; ainda não é um agente autônomo, porque não escolhe nem executa ferramentas externas.

O que você precisa

Python 3.10 ou superior instalado;
uma chave de API criada na plataforma OpenAI, com acesso e cobrança configurados;
acesso à internet e um terminal.

Uma chave da API é diferente de uma assinatura do ChatGPT. Mantenha-a no seu computador ou servidor como variável de ambiente. Não a coloque no código, em um repositório público ou em um aplicativo que roda diretamente no navegador.

1. Instale a biblioteca oficial

Crie uma pasta para o projeto e, se possível, um ambiente virtual do Python. No terminal, instale o SDK oficial:

python -m pip install --upgrade openai

Configure a chave no terminal que vai executar o programa. No macOS ou Linux:

export OPENAI_API_KEY="sua-chave-da-api"

No PowerShell do Windows:

$env:OPENAI_API_KEY="sua-chave-da-api"

Substitua o texto de exemplo pela sua chave. Não compartilhe capturas de tela que a revelem. A variável configurada no PowerShell vale para aquela janela; abra outra sessão e repita o comando se necessário.

2. Crie o assistente

Salve o código abaixo em um arquivo chamado assistente.py. Ele usa a Responses API, indicada na documentação atual da OpenAI para novas integrações. O ID do modelo pode variar conforme o acesso e o catálogo disponível na sua conta; confira a página oficial de modelos se receber um erro de modelo indisponível.

from openai import OpenAI

client = OpenAI()
modelo = "gpt-6-luna"
instrucoes = (
    "Você é um assistente didático. Responda em português claro, "
    "explique termos técnicos e admita quando não souber algo."
)
resposta_anterior = None

print("Assistente iniciado. Digite 'sair' para encerrar ou 'novo' para limpar o contexto.")

while True:
    pergunta = input("Você: ").strip()

    if pergunta.lower() == "sair":
        break
    if pergunta.lower() == "novo":
        resposta_anterior = None
        print("Contexto reiniciado.")
        continue
    if not pergunta:
        continue

    parametros = {
        "model": modelo,
        "instructions": instrucoes,
        "input": pergunta,
    }
    if resposta_anterior:
        parametros["previous_response_id"] = resposta_anterior

    try:
        resposta = client.responses.create(**parametros)
        print(f"Assistente: {resposta.output_text}\n")
        resposta_anterior = resposta.id
    except Exception as erro:
        print(f"Não foi possível gerar a resposta: {erro}")

Execute no terminal com python assistente.py. Faça uma pergunta, depois envie outra que dependa do contexto anterior. Digite novo para começar uma conversa sem o histórico encadeado, ou sair para encerrar.

3. O que o código está fazendo

O SDK lê a chave da variável de ambiente e envia a pergunta ao endpoint responses. O campo instructions define o comportamento esperado. A cada resposta, o programa guarda o identificador retornado pela API e o envia como previous_response_id na próxima solicitação. Assim, a API consegue relacionar os turnos sem que o programa mantenha uma lista manual de mensagens.

Esse exemplo usa o armazenamento padrão de respostas da API. Consulte a documentação de estado de conversa e as configurações atuais de retenção antes de enviar dados pessoais, confidenciais ou de clientes. A resposta também pode consumir créditos; acompanhe o uso e os preços na plataforma.

Assistente ou agente: qual é a diferença?

O programa deste guia conversa com uma pessoa, mas não executa ações fora da conversa. Em geral, chamamos de agente uma aplicação que recebe um objetivo, decide quando usar ferramentas e executa ações por meio de funções ou serviços conectados. Para dar esse próximo passo, é preciso declarar as ferramentas disponíveis na API, executar no próprio Python somente as funções autorizadas e devolver o resultado ao modelo. Nunca permita que uma resposta do modelo execute comandos arbitrários no computador ou acesse arquivos sem validação e limites.

Erros comuns e cuidados

Chave inválida ou ausente: confira se a variável OPENAI_API_KEY está definida no mesmo terminal usado para rodar o programa.
Modelo indisponível: verifique o catálogo e o acesso habilitado para sua conta; altere a variável modelo para um ID disponível.
Limite ou cobrança: consulte o painel de uso, faturamento e limites da API antes de repetir solicitações.
Resposta incorreta: modelos podem errar. Confira informações importantes e teste qualquer código gerado antes de usá-lo.
Dados sensíveis: envie apenas o que é necessário e revise as regras de privacidade e retenção aplicáveis à sua integração.

Próximos passos

Depois de testar o exemplo, você pode criar uma interface simples, registrar conversas em um banco de dados ou adicionar uma ferramenta específica, como consultar o status de um chamado. Faça cada integração com uma função limitada, validação dos parâmetros, autenticação adequada e confirmação humana para ações importantes.

Conclusão

Com poucas linhas de Python, você integrou uma aplicação à API Responses e criou uma conversa com contexto entre turnos. O exemplo ensina o fundamento sem chamar um chatbot de agente. Para avançar com segurança, adicione ferramentas aos poucos, teste falhas e mantenha controle humano sobre ações com impacto.