Assistants API termina em 26 de agosto: checklist para migrar sem perder conversas e ferramentas

A OpenAI programou a remoção da Assistants API para 26 de agosto de 2026 e indica a Responses API, combinada à Conversations API, como substituta. Em 3 de agosto, data desta revisão, restam 23 dias para eliminar a dependência dos endpoints antigos.

A migração Assistants API não deve ser tratada como uma simples troca de URL. A arquitetura antiga distribui estado e comportamento entre Assistants, Threads, Messages, Runs, Run Steps, arquivos e recursos de ferramentas. No modelo atual, essas responsabilidades passam para configurações mantidas pela aplicação, Conversations, Responses e diferentes tipos de itens.

O risco maior não é uma chamada deixar de funcionar. É uma integração voltar ao ar sem o histórico correto, chamar ferramentas com argumentos diferentes, perder vínculos com arquivos ou não conseguir explicar o que aconteceu durante uma execução.

O que realmente muda em 26 de agosto

A documentação oficial apresenta quatro equivalências conceituais:

• Assistants dão lugar à configuração de comportamento usada nas requisições;
• Threads são substituídas por Conversations;
• Runs passam a ser Responses;
• Run Steps tornam-se diferentes tipos de Items, incluindo mensagens, chamadas de ferramenta e resultados.

Há, porém, uma atualização importante para projetos que começaram a migração seguindo versões anteriores do guia. A documentação ainda mostra a transformação de Assistants em objetos de Prompt, mas os prompts reutilizáveis também foram descontinuados: a criação foi despriorizada em 3 de junho de 2026 e o encerramento de v1/prompts está programado para 30 de novembro de 2026. A recomendação mais recente é manter instruções e demais conteúdos de prompt no código ou na camada de configuração da própria aplicação.

Portanto, migrar hoje de Assistant para um Prompt reutilizável pode apenas trocar um prazo de agosto por outro prazo em novembro.

Matriz: recurso antigo e equivalente atual

A tabela é um ponto de partida. O contrato real da sua aplicação pode incluir comportamentos que não aparecem nos objetos da OpenAI, como permissões, limites por cliente, deduplicação, auditoria e confirmação antes de executar ações.

Faça um inventário antes de alterar o código

Assistants e configurações

Para cada Assistant em uso, registre:

• ID e finalidade;
• instruções completas;
• modelo e parâmetros;
• ferramentas habilitadas;
• schemas das funções;
• arquivos e vector stores associados;
• formatos de saída esperados;
• regras aplicadas no código antes e depois da chamada;
• ambientes, clientes ou produtos que dependem dele.

Não copie apenas o texto de instructions. Um Assistant pode depender de recursos em tool_resources, de um schema estruturado ou de lógica aplicada durante a criação do Run.

Transforme esse conjunto em uma configuração versionada no repositório. Cada alteração deve ter revisão, teste e possibilidade de retorno à versão anterior.

Threads, mensagens e usuários

Crie uma tabela de reconciliação com, no mínimo:

A API de Threads trabalha com a recuperação de objetos por thread_id. Na prática, o banco de dados e os logs da aplicação devem ser tratados como o catálogo dos Threads que precisam ser migrados ou arquivados.

O inventário deve incluir todas as páginas de mensagens, e não apenas o primeiro lote retornado pela API. Registre também:

• ordem cronológica;
• papel do autor;
• textos, imagens e arquivos;
• anexos;
• anotações e citações;
• metadados;
• relações com Runs;
• mensagens incompletas ou com erro.

Ferramentas e recursos persistidos

Liste separadamente:

• funções próprias e seus schemas;
• serviços externos chamados pelas funções;
• efeitos colaterais, como envio, compra ou alteração de registro;
• arquivos carregados;
• vector stores e arquivos contidos neles;
• saídas produzidas pelo Code Interpreter;
• webhooks;
• parsers de streaming;
• políticas de retenção e exclusão.

O inventário é concluído somente quando cada recurso antigo possui um destino, uma decisão de descarte documentada ou uma pendência que bloqueia o corte.

Como preservar as conversas

A Conversations API mantém um objeto durável, reutilizável entre sessões, dispositivos ou tarefas. Uma Conversation armazena itens, que podem representar mensagens, chamadas de ferramentas, resultados e outros dados.

A OpenAI informa que não haverá uma ferramenta automática para converter Threads em Conversations. A orientação oficial é direcionar os novos chats para Conversations e migrar os antigos conforme a necessidade. O guia também apresenta um exemplo de backfill que pagina as mensagens de um Thread em ordem crescente, converte o conteúdo em itens e cria uma Conversation.

Uma estratégia segura possui quatro etapas.

1. Pare de criar dívida nova

Depois que o caminho de Responses estiver validado, encaminhe novas conversas diretamente para a Conversations API. Grave imediatamente a relação entre a identidade interna da sessão e o novo conversation_id.

2. Converta o histórico sob demanda

Ao abrir uma conversa antiga:

1. localize o thread_id;
2. recupere todas as páginas de mensagens;
3. converta os tipos de conteúdo aceitos;
4. crie a Conversation;
5. grave a correspondência entre os dois IDs;
6. confira contagem, ordem e conteúdo antes de liberar a resposta.

Esse processo deve ser idempotente: duas tentativas para o mesmo Thread não podem criar duas conversas independentes.

O exemplo oficial de backfill cobre texto e imagem por URL. Integrações que usam image_file, anexos, anotações, resultados de ferramentas ou formatos próprios precisam ampliar o conversor e testar cada tipo separadamente.

3. Mantenha uma cópia canônica

Não dependa da disponibilidade futura dos endpoints antigos para reconstruir o histórico. Antes do desligamento, preserve em armazenamento próprio o conteúdo necessário para continuidade, auditoria e recuperação, de acordo com sua base legal e política de retenção.

Essa cópia deve registrar a origem e a versão do conversor. Ela não precisa reproduzir cada detalhe interno da OpenAI, mas deve ser suficiente para reconstruir a experiência oferecida ao usuário.

4. Revise retenção e privacidade

Responses armazenadas possuem, por padrão, retenção de estado de aplicação por 30 dias. Já Conversations e seus itens permanecem até serem excluídos e não são elegíveis para Zero Data Retention. Uma Response associada a uma Conversation tem seus itens preservados sem o limite padrão de 30 dias.

A escolha entre Conversations, encadeamento por previous_response_id ou histórico administrado pela própria aplicação deve considerar privacidade, exclusão, residência de dados, auditoria e requisitos contratuais — não apenas conveniência técnica.

Como migrar as ferramentas

Function calling

No modelo antigo, um Run podia entrar em requires_action. Na Responses API, a saída contém itens function_call. A aplicação identifica cada chamada, executa a função correspondente e devolve um item function_call_output com o mesmo call_id. O loop de ferramentas passa a ser responsabilidade explícita da aplicação.

Os testes devem verificar:

• nome da função;
• validade dos argumentos;
• campos ausentes ou inesperados;
• chamadas paralelas;
• timeout;
• repetição da mesma ação;
• tratamento de erro;
• confirmação para operações irreversíveis.

A documentação recomenda schemas em modo estrito. Nesse modo, os objetos precisam declarar additionalProperties: false e marcar os campos definidos como obrigatórios, usando null quando um valor puder ser opcional.

File Search

Os vector stores continuam sendo usados pelo file_search tanto na Assistants API quanto na Responses API. Em vez de depender do vínculo mantido no Assistant ou no Thread, a nova requisição informa os vector_store_ids na configuração da ferramenta.

Antes do corte, teste:

• acesso ao mesmo vector store;
• quantidade e status dos arquivos;
• qualidade das respostas;
• presença das citações;
• filtros por metadados;
• permissões por usuário;
• comportamento quando nenhum resultado é encontrado.

Os resultados completos da pesquisa não são incluídos por padrão. Para observabilidade e depuração, a Responses API permite solicitar file_search_call.results pelo parâmetro include.

Code Interpreter

Na Responses API, o Code Interpreter utiliza um container. Ele pode ser criado automaticamente ou explicitamente, com os arquivos necessários. Os containers devem ser tratados como recursos efêmeros: a documentação informa que expiram após 20 minutos sem uso e que seus dados não podem ser recuperados depois da expiração.

Nunca use o container como armazenamento definitivo. Arquivos produzidos que precisem permanecer disponíveis devem ser copiados para o sistema da aplicação enquanto o container estiver ativo.

Processos longos, polling e streaming

Tarefas curtas podem usar Responses síncronas. Para execuções longas, o modo background permite acompanhar estados como queued e in_progress, recuperar a Response e cancelá-la. Webhooks podem informar eventos como response.completed.

O streaming também mudou. A Responses API emite eventos semânticos tipados, incluindo criação, deltas de texto, chamadas de ferramentas, conclusão e erro. Parsers baseados nos eventos antigos precisam de testes específicos; não basta alterar o endpoint.

Matriz de testes de regressão

Não compare apenas frases literais. Modelos generativos podem produzir textos diferentes e ainda cumprir o mesmo contrato. Avalie fatos, formato, decisões, chamadas de ferramentas, segurança e efeito final.

Corte gradual e plano de reversão

Coloque o novo caminho atrás de uma feature flag por cliente, usuário ou sessão. Comece com tráfego interno, avance para um grupo pequeno e amplie somente quando as métricas permanecerem dentro dos limites definidos.

Durante o período de convivência:

• não grave uma mesma ação externa duas vezes;
• mantenha correlação entre objetos antigos e novos;
• compare falhas, latência, tokens e chamadas de ferramentas;
• monitore conversas sem mapeamento;
• bloqueie a exclusão dos recursos legados;
• preserve a capacidade de desativar o caminho novo rapidamente.

Antes de 26 de agosto, a reversão pode, temporariamente, significar redirecionar o tráfego para a integração legada. Depois do encerramento, isso deixa de ser uma estratégia válida. O plano pós-prazo precisa voltar para uma versão anterior e estável da implementação em Responses, usando o estado canônico armazenado pela aplicação.

Cronograma sugerido para os 23 dias restantes

• 3 a 6 de agosto: inventário, exportação e congelamento de novos recursos legados.
• 7 a 13 de agosto: implementação de Conversations, Responses e adaptadores de ferramentas.
• 14 a 19 de agosto: backfill controlado, testes de regressão e execução paralela sem efeitos.
• 20 a 23 de agosto: corte progressivo e correção de divergências.
• 24 e 25 de agosto: operação integral no novo caminho, com plantão e rollback entre versões de Responses.
• 26 de agosto: nenhuma jornada de produção deve depender de Assistants, Threads, Messages, Runs ou Run Steps.

Esse cronograma é uma recomendação editorial, não um calendário oficial da OpenAI. Equipes com grande volume, requisitos regulatórios ou ferramentas que produzem efeitos externos devem antecipar etapas e exigir aprovação técnica formal.

Checklist final da migração Assistants API

• Todos os Assistants em produção foram identificados.

• Instruções, modelos, ferramentas e schemas estão versionados na aplicação.

• A arquitetura final não depende de prompts reutilizáveis.

• Todos os thread_id conhecidos estão ligados a usuários ou sessões autorizados.

• O histórico necessário foi exportado ou convertido.

• Novas sessões já criam Conversations.

• O backfill é paginado, idempotente e auditável.

• Textos, imagens, anexos e anotações foram testados.

• Funções validam argumentos e evitam efeitos duplicados.

• Vector stores e arquivos foram reconciliados.

• Resultados do File Search mantêm citações e permissões.

• Arquivos do Code Interpreter são preservados fora do container.

• Polling, cancelamento, webhooks e streaming foram atualizados.

• Retenção, exclusão e Zero Data Retention foram reavaliados.

• Há métricas comparáveis entre o caminho antigo e o novo.

• O corte está protegido por feature flag.

• Existe rollback para uma versão estável baseada em Responses.

• Nenhum fluxo de produção dependerá da Assistants API em 26 de agosto.

A migração termina quando o sistema consegue continuar uma conversa, recuperar os recursos corretos, executar ferramentas com segurança e explicar cada etapa sem consultar a API legada. Trocar o endpoint é apenas o começo.

Atualizado em 3 de agosto de 2026. A documentação, os SDKs e os recursos da plataforma podem mudar antes da publicação ou do corte definitivo.