Como Criar um AI Agent com OpenAI Assistants (Agora a Responses API)
Turn this article into takeaways for your work.
Each assistant summarizes the article only for you and suggests best practices for your work.
A Assistants API da OpenAI permitia que desenvolvedores criassem aplicações no estilo agent, com threads de conversa persistentes, recuperação de arquivos, execução de código e function calling, sem precisar gerenciar todo esse estado manualmente. Ela teve sua importância e, para integrações existentes, ainda funciona hoje. Mas a OpenAI anunciou sua descontinuação em 26 de agosto de 2025, com data final de encerramento em 26 de agosto de 2026, e direcionou todo o desenvolvimento novo para a Responses API e o Agents SDK. Se você está começando um projeto novo, crie-o lá. Este guia explica o que a Assistants API fazia, o que a substitui e como criar de fato um agent com as ferramentas atuais da OpenAI.
O que Era a Assistants API e Por que Ela Está Saindo de Cena
Lançada na conferência de desenvolvedores da OpenAI em 2023, a Assistants API oferecia aos desenvolvedores quatro primitivas centrais: um Assistant (o agent configurado, com instruções e ferramentas), uma Thread (uma conversa persistente), um Run (uma execução do assistant sobre uma thread) e Run Steps (as ações individuais realizadas durante um run). Ela incluía recuperação sobre arquivos enviados, um code interpreter e function calling, o que, por um tempo, a tornou a forma mais rápida de colocar de pé um agent com estado e uso de ferramentas sem construir essa infraestrutura por conta própria.
O problema, nas palavras da própria OpenAI, era a complexidade. Quando a empresa lançou a Responses API em março de 2025, disse com clareza que planejava levar todos os recursos da Assistants para a API mais simples e encerrar a original, e cumpriu o combinado: o aviso de descontinuação foi enviado aos desenvolvedores em 26 de agosto de 2025, com a remoção da API exatamente um ano depois. O guia de migração da OpenAI confirma que nenhuma funcionalidade se perde na mudança: os recursos são reorganizados, não eliminados.
O que a Substitui: a Responses API e o Agents SDK
A Responses API não é uma simples mudança de nome, é um modelo genuinamente mais simples: você envia itens de entrada e recebe itens de saída diretamente, sem ficar consultando um objeto Run até o status mudar. Quatro conceitos da Assistants correspondem a quatro conceitos da Responses.
| Assistants API | Equivalente na Responses API | O que mudou |
|---|---|---|
| Assistants | Prompts | A configuração agora fica no dashboard, com versionamento integrado, em vez de ser gerenciada inteiramente por chamadas de API |
| Threads | Conversations | Ampliadas para armazenar mais do que mensagens: chamadas de ferramentas, saídas e outros tipos de item |
| Runs | Responses | Você envia a entrada e recebe a saída diretamente; sem loop de consulta |
| Run steps | Items | Objetos generalizados que cobrem a variedade de dados que uma resposta pode conter |
A Responses API também traz cinco ferramentas nativas que você não precisa construir: web search, file search, code interpreter, computer use e conexões com servidores MCP remotos. O file search é o sucessor direto do recurso de recuperação da Assistants API, o mesmo padrão de ancoragem em documentos abordado em RAG para AI agents e, no nível de padrão, no padrão de assistente RAG.
Para qualquer coisa além de um único agent, a OpenAI também oferece o Agents SDK, um sucessor pronto para produção do seu antigo framework experimental "Swarm". Enquanto a Responses API entrega o bloco básico, uma chamada de entrada, uma resposta de saída, o Agents SDK entrega a orquestração em torno dele: Agents (um modelo mais instruções e ferramentas), Handoffs (permitir que um agent delegue uma tarefa a outro) e Guardrails (validar o que entra e o que sai). O enquadramento da própria OpenAI é direto: use a Responses API quando quiser ser dono do loop do agent, e use o Agents SDK quando quiser que o SDK execute esse loop por você. As novidades do SDK em 2026 incluem integração nativa com a Realtime API para voice agents e suporte de primeira classe a servidores Model Context Protocol, de modo que qualquer ferramenta que fale MCP vira uma capacidade conectável sem código de ligação personalizado.
O Passo a Passo da Criação
- Decida quem é dono do loop. Para um único agent relativamente simples, chame a Responses API diretamente e trate o ciclo de entrada, saída e chamada de função no seu próprio código. Para vários agents que se coordenam, ou se você prefere não escrever esse loop, comece pelo Agents SDK.
- Escreva as instruções do agent. São os blocos de papel e regras de como criar um AI agent, declarados como um system prompt: o que o agent assume como responsabilidade e o que ele nunca deve fazer.
- Anexe ferramentas nativas conforme necessário. File search se ele precisar responder a partir dos seus próprios documentos, web search se precisar de informações atuais, code interpreter para cálculos e computer use apenas se ele realmente precisar operar uma interface.
- Conecte ferramentas personalizadas de function calling para os seus próprios sistemas. Defina um JSON schema para cada função (nome, parâmetros, descrição); o modelo solicita uma chamada com argumentos específicos, o código da sua aplicação a executa de fato no seu CRM, banco de dados ou API e devolve o resultado para o modelo continuar raciocinando. É a mesma mecânica de chamada de ferramentas explicada em detalhes em como os AI agents usam ferramentas.
- Use Conversations para tudo que precisa persistir entre sessões, o sucessor direto das Threads da Assistants.
- Adicione Handoffs se o trabalho se dividir de forma limpa entre agents especializados, o mesmo padrão de orquestração abordado em sistemas multi-agent.
- Adicione Guardrails para validar entradas e saídas, e adicione tracing (a integração nativa do SDK com o Sentry ou o seu próprio log) para ver exatamente quais ferramentas rodaram e por quê, antes de confiar ao agent um volume real.
- Faça o deploy atrás do seu próprio backend. Aqui não há host visual; o servidor, a autenticação e a lógica de novas tentativas são responsabilidade sua.
A implementação avança da propriedade do loop e das instruções, passando por ferramentas, estado persistente, handoffs, guardrails e tracing.
Um Exemplo Prático: um Agent de Knowledge Base com IA
Um agent de knowledge base é uma escolha natural para a Responses API, já que se apoia diretamente na ferramenta nativa de file search, em vez de código de recuperação personalizado.
Um usuário faz uma pergunta. As instruções do agent o restringem a responder apenas a partir de um conjunto de documentos da empresa enviados e indexados, conectado por meio da ferramenta de file search. Ele pesquisa, encontra os trechos relevantes e responde com uma citação do documento de origem, e não com uma afirmação solta. Se o file search não retornar uma correspondência confiável, as instruções mandam dizê-lo explicitamente em vez de adivinhar, e uma ferramenta personalizada de function calling permite escalar a pergunta para uma fila humana quando ele não consegue responder.
É a mesma estrutura de regras e guardrails que o blueprint do AI Knowledge Base Agent especifica por completo: restringir-se a fontes aprovadas, citar de onde veio a resposta e escalar em vez de adivinhar. Criá-lo na Responses API significa, em grande parte, conectar a ferramenta de file search e a função de escalonamento e deixar que o próprio raciocínio do modelo decida quando cada uma se aplica.
Custo e Limites
A API da OpenAI cobra por tokens (entrada e saída com preços separados, variando conforme o modelo), e cada ferramenta nativa tem a sua própria medição: web search e file search cobram por chamada ou pelo volume de documentos armazenados, e code interpreter e computer use cobram pelo tempo de computação que usam. As tarifas mudam com frequência suficiente para que valha consultar diretamente a página de preços da OpenAI, em vez de tratar qualquer número aqui como atual. O que importa para o planejamento é o formato do custo, baseado em uso e distribuído por vários medidores separados, e não um preço fixo único, então leia custo total de propriedade de IA antes de estimar um agent pesado e sempre ativo a partir da fatura de um piloto leve.
O limite maior para a maioria das equipes não é o custo, é que esse caminho não oferece nenhum construtor visual. Tudo o que n8n, Make ou Lindy resolvem por você (hospedagem, novas tentativas, uma interface para que quem não é engenheiro ajuste o agent) passa a ser trabalho da sua equipe. Esse é o trade-off que vale nomear sem rodeios: você tem acesso de primeira mão aos modelos e às ferramentas da OpenAI, com o mínimo de abstração entre você e a API, em troca de assumir todo o runtime. E, se você tem uma integração existente com a Assistants API, a migração não é opcional. Ela precisa acontecer antes de 26 de agosto de 2026, usando o mapeamento acima, ou a integração simplesmente para de funcionar.
Quando Escolher Este Caminho e Quando Escolher Alternativas
| Se você quer... | Escolha |
|---|---|
| Controle total via código diretamente sobre os modelos da OpenAI, abstração mínima, e sua equipe já escreve software | Responses API e Agents SDK da OpenAI |
| O caminho mais rápido até um agent funcionando, sem nenhum código | Lindy |
| O catálogo de apps pré-construídos mais amplo, com um construtor visual | Make |
| Self-hosting com um canvas visual e uma saída de emergência para código | n8n |
Essas não são escolhas estritamente excludentes. n8n, Make e Lindy podem chamar os modelos da OpenAI como o motor de raciocínio de um agent criado em suas plataformas; você está escolhendo uma camada de orquestração, não necessariamente abrindo mão dos modelos da OpenAI. Crie diretamente na Responses API e no Agents SDK quando sua equipe já entrega código e quer o menor número de camadas entre a aplicação e o modelo. Recorra a uma plataforma visual quando preferir trocar um pouco de controle de baixo nível por iteração mais rápida e por um construtor que quem não é engenheiro também possa usar. A urgência por trás dessa escolha é real: o Gartner prevê que 40% dos aplicativos corporativos terão AI agents específicos para tarefas até o fim de 2026, contra menos de 5% em 2025, exatamente o tipo de curva de adoção que faz de construir sobre uma plataforma que a OpenAI está ativamente aposentando a aposta errada neste momento.
Key Facts
- A OpenAI anunciou a descontinuação da Assistants API em 26 de agosto de 2025, com data final de encerramento em 26 de agosto de 2026. Projetos novos devem ser criados na Responses API.
- A Responses API substitui quatro conceitos da Assistants: Assistants viram Prompts, Threads viram Conversations, Runs viram Responses e Run steps viram Items.
- A Responses API traz cinco ferramentas nativas: web search, file search, code interpreter, computer use e conexões com servidores MCP remotos.
- O Agents SDK, sucessor de nível de produção do framework experimental Swarm da OpenAI, adiciona Agents, Handoffs e Guardrails para coordenar mais de um agent.
- O Gartner prevê que 40% dos aplicativos corporativos terão AI agents específicos para tarefas até o fim de 2026, contra menos de 5% em 2025.
Perguntas Frequentes sobre Como Criar um AI Agent com OpenAI Assistants
A Assistants API da OpenAI ainda pode ser usada em 2026?
Sim, até a data de encerramento de 26 de agosto de 2026, quando ela é removida da API por completo. As integrações existentes continuam funcionando até lá, mas a OpenAI direcionou todo o desenvolvimento novo para a Responses API e o Agents SDK desde que anunciou a descontinuação em 26 de agosto de 2025.
O que substitui a Assistants API?
A Responses API, que unifica e simplifica as mesmas capacidades (estado persistente, recuperação, execução de código, function calling) em um modelo no qual você envia itens de entrada e recebe itens de saída diretamente, sem consultar um objeto Run. Para coordenar vários agents, o Agents SDK da OpenAI fica sobre a Responses API e acrescenta handoffs e guardrails.
Preciso migrar a minha integração existente com a Assistants API?
Sim, antes de 26 de agosto de 2026. O guia de migração da OpenAI mapeia cada conceito da Assistants para o seu equivalente na Responses API (Assistants para Prompts, Threads para Conversations, Runs para Responses, Run steps para Items) e confirma que nenhuma funcionalidade se perde, apenas é reorganizada.
Qual é a diferença entre a Responses API e o Agents SDK?
A Responses API é a primitiva básica: você envia uma requisição e recebe uma resposta, e é você quem cuida do loop de chamá-la repetidamente, executar as chamadas de função e devolver os resultados. O Agents SDK é construído sobre ela e executa o loop por você, acrescentando handoffs entre vários agents e guardrails de entrada e saída, úteis quando a lógica de um único agent fica complexa o bastante para pedir essa estrutura.
Posso criar um AI agent com os modelos da OpenAI sem escrever código?
Não diretamente pelas APIs da própria OpenAI, já que não há construtor visual. Plataformas como n8n, Make e Lindy podem chamar os modelos da OpenAI como o motor de raciocínio de um agent criado de forma visual, que é o caminho mais acessível se sua equipe não quer escrever e hospedar o código de orquestração.
Para Onde Ir Agora
Se a sua equipe já escreve software e quer o menor número de camadas entre o seu código e os modelos da OpenAI, a Responses API e o Agents SDK são o ponto de partida certo, basta criar por lá em vez de usar a API que está sendo aposentada. Se prefere criar de forma visual, veja como criar um AI agent com o n8n, como criar um AI agent com o Make ou como criar um AI agent com o Lindy, conforme o quanto de controle e de velocidade você precisa. O panorama de ferramentas para desenvolvedores e o guia como escolher uma plataforma de chatbot com IA são boas próximas paradas se você ainda está comparando as ferramentas da própria OpenAI com uma plataforma hospedada.
