DeepSeek V3.2 com ferramentas: como auditar o estado de raciocínio antes de manter ou migrar um agente

A pergunta operacional: a integração preserva o estado correto?

O DeepSeek V3.2 passou a oferecer suporte a chamadas de ferramentas no modo de pensamento, de acordo com o anúncio do fornecedor e seu guia sobre ferramentas. Esse recurso permite formular uma pergunta concreta de engenharia: quando o assistente solicita uma ferramenta, a aplicação a executa e o resultado retorna ao modelo, o estado exigido pela API é preservado na solicitação seguinte? Não dá para responder a isso apenas pelo nome do modelo ou com uma demonstração isolada. É preciso verificar o contrato de mensagens e as respostas que a aplicação realmente processa.

O foco desta análise é restrito: auditar uma integração existente ou avaliar quais evidências ainda faltam antes de mantê-la ou planejar uma mudança. A intenção não é medir a inteligência geral do modelo, comparar pontuações nem inferir como ele raciocina internamente. Uma chamada de ferramenta que parece correta em um teste manual não demonstra que o serviço lida adequadamente com novas tentativas, streaming, resultados inesperados ou com a próxima mensagem do usuário.

A documentação da DeepSeek informa que, ao usar ferramentas no modo de pensamento, as solicitações posteriores daquele turno devem reenviar o campo `reasoning_content` junto com o estado pertinente. Ela também documenta que, nas condições descritas, omitir esse campo pode resultar em um erro 400. A consequência prática é importante: uma camada intermediária que reconstrua o histórico, filtre campos ou converta formatos pode quebrar a sequência, mesmo que a primeira solicitação funcione.

A disponibilidade de um nome de modelo é uma verificação diferente da correção do fluxo. A DeepSeek oferece um endpoint para consultar os modelos disponíveis; esse resultado precisa ser verificado no ambiente e na data do teste, e não inferido de um exemplo estático ou do nome de uma página. Da mesma forma, uma referência ao V4 no centro de transparência não comprova, por si só, que um identificador específico esteja habilitado para determinada conta nem que uma integração possa migrar para ele sem ajustes.

Reconstrua o ciclo sem perder mensagens

Um teste confiável começa pela representação explícita do fluxo como uma sequência. A aplicação envia mensagens ao modelo; ele pode devolver uma solicitação de ferramenta; a aplicação executa a operação autorizada e acrescenta o resultado como uma mensagem de ferramenta; depois, envia a continuação ao modelo. Em uma interação com modo de pensamento e ferramentas, o guia da DeepSeek acrescenta a exigência de preservar `reasoning_content` nas solicitações posteriores pertinentes. O detalhe exato depende do formato da API e da estrutura da resposta; por isso, vale inspecionar a referência do endpoint usado pela integração.

Não reduza o histórico a uma frase como “o modelo pediu para pesquisar”. Nos registros de teste, preserve a sequência de funções, os identificadores das chamadas, quando existirem, os argumentos emitidos, o resultado associado a cada chamada e os campos que a integração reenviou. Se o produto transformar a resposta antes de armazená-la, registre também essa transformação ou uma impressão digital comparável. Assim, será possível distinguir um erro do modelo de uma mensagem removida pelo middleware, de uma chamada associada incorretamente ou de um resultado que nunca chegou à solicitação seguinte.

Não confunda a API Chat Completions com os outros formatos documentados pela DeepSeek. O guia de ferramentas diferencia como as chamadas são inseridas na Chat Completions, na Anthropic API e na Responses API. Uma integração que muda de formato não deve presumir que basta renomear campos: precisa validar a ordem, a representação das chamadas e a maneira como cada formato expressa a continuação.

A regra de preservação também não significa reenviar indefinidamente tudo o que foi gerado em qualquer turno. A documentação do modo de pensamento diferencia solicitações com ferramentas de conversas sem ferramentas. Portanto, o protocolo deve testar separadamente uma continuação do mesmo turno e um novo turno do usuário. Não se deve apagar nem manter conteúdo por intuição: é preciso seguir o formato documentado e verificá-lo com solicitações controladas.

Um protocolo reproduzível com ferramentas simuladas

Antes de testar com ferramentas reais, crie versões simuladas e controladas que retornem resultados conhecidos. Uma ferramenta simulada reduz o risco de alterar dados, chamar serviços externos ou confundir uma resposta variável com uma regressão. Defina antecipadamente o que será considerado aprovado: por exemplo, que a aplicação execute uma única vez uma chamada válida, associe o resultado a essa chamada e envie a continuação com os campos exigidos. A política exata depende do produto e deve ser registrada antes da execução do teste.

Comece com uma ferramenta e uma solicitação simples. Verifique se a aplicação detecta a chamada, valida o nome e os argumentos, executa a operação simulada e acrescenta a resposta correspondente. Depois, confirme se a solicitação seguinte preserva o estado exigido e se o modelo responde com base no resultado. Não basta ver uma resposta final plausível: compare a sequência capturada com a sequência que a aplicação deveria enviar.

Em seguida, encadeie duas ferramentas: a primeira retorna um dado de que a segunda precisa. Esse caso ajuda a descobrir se a aplicação encerra o turno cedo demais, reenvia um resultado antigo ou interpreta como nova uma chamada que já executou. Não presuma que o modelo sempre escolherá a ordem desejada. O critério é que o orquestrador processe as solicitações recebidas com segurança e mantenha uma relação inequívoca entre cada chamada e seu resultado.

Teste também o modo de streaming. A documentação da DeepSeek inclui exemplos de streaming no modo de pensamento, mas a integração precisa validar o próprio leitor de eventos: uma resposta parcial não equivale necessariamente a uma chamada completa e pronta para execução. Acumule e analise a saída conforme o formato documentado; não execute uma ferramenta antes de receber e validar a estrutura necessária. Registre os fragmentos e o evento final relevante, sem presumir que o texto mostrado na interface do usuário, por si só, reflita o estado do protocolo.

Argumentos malformados devem ser tratados como entrada não confiável, mesmo quando gerados pelo modelo. Teste campos ausentes, tipos inesperados, valores fora do intervalo e nomes de ferramentas desconhecidos. A aplicação deve rejeitar ou encaminhar de maneira controlada o que não atender ao próprio esquema. A saída do modelo não concede permissões: autorizações, limites e validações são responsabilidade da aplicação.

Inclua resultados vazios, erros simulados e respostas contraditórias. O agente não deve inventar que uma operação foi bem-sucedida se a ferramenta informou uma falha, nem repetir uma ação com efeitos colaterais sem uma política de idempotência. Em casos contraditórios, defina qual fonte prevalece e se é preciso pedir esclarecimentos ou intervenção humana. Essas são decisões do produto, não propriedades garantidas pela presença de `reasoning_content`.

Falhas que a aplicação precisa detectar

A primeira falha é omitir o estado exigido ao montar uma continuação. O guia do modo de pensamento documenta um erro 400 no caso de ferramentas quando `reasoning_content` é omitido nas condições descritas. Registre o código de resposta e a solicitação de saída com dados sensíveis removidos; não use a mensagem de erro como justificativa para repetir a solicitação sem alterações. A correção deve ser determinada pela estrutura que o cliente realmente envia e pela especificação vigente.

A segunda falha é executar a mesma operação duas vezes. Isso pode ocorrer se a aplicação repetir uma solicitação após uma interrupção de rede sem saber se a ferramenta já produziu efeitos, ou se interpretar fragmentos de streaming como solicitações independentes. A prevenção depende do tipo de ferramenta: use identificadores de operação, deduplicação ou confirmação humana quando apropriado. Uma ferramenta somente de leitura e uma transferência de dinheiro não necessariamente permitem a mesma política.

Também é preciso procurar loops: o modelo volta a solicitar uma ação equivalente, a ferramenta retorna um resultado que não é incorporado ou o orquestrador mantém um estado obsoleto. Defina limites de iterações e de tempo e ofereça uma saída controlada quando forem atingidos. Um limite não garante uma resposta correta, mas reduz a possibilidade de que um problema de integração resulte em consumo indefinido ou repetição de efeitos.

Uma quarta classe de falhas aparece quando argumentos e resultados só são validados na interface do modelo. O cliente deve verificar o esquema, o nome da ferramenta, as permissões do usuário e o escopo da operação. Também precisa tratar resultados parciais, vazios ou incompatíveis com o formato esperado. O modelo pode ajudar a interpretar as informações, mas a aplicação continua responsável por decidir quais ações serão executadas.

Por fim, diferencie um erro de API de um erro de negócio. Um erro 400 relacionado à estrutura da solicitação exige uma revisão do contrato enviado; uma falha da ferramenta pode ser um problema de permissões, conectividade ou dados. Em ambos os casos, registre a categoria e o ponto da sequência em que ocorreu. Evite apresentar como confirmada uma causa que os registros não permitem distinguir.

O que registrar e o que limitar

Para que outra pessoa consiga reproduzir uma falha, registre a data, o ambiente, o identificador de modelo solicitado, o modo, o formato da API, as opções relevantes e a sequência de mensagens. Acrescente as solicitações e respostas das ferramentas, os erros, a duração e os tokens quando a resposta da API os fornecer. Anote também se houve streaming e como o cliente montou a resposta. Um registro que não mostre o ponto exato em que um campo foi perdido ou transformado pode ocultar justamente o defeito que se pretende localizar.

Minimize dados pessoais e segredos. Oculte credenciais, identificadores sensíveis e conteúdo desnecessário para diagnosticar o fluxo; use ferramentas simuladas para reproduzir casos sempre que possível. Defina controles de acesso e prazos de retenção compatíveis com a política da equipe. Não armazene indiscriminadamente todo o histórico de produção apenas porque isso facilita uma depuração pontual.

Trate `reasoning_content` com cuidado especial. A documentação o identifica como um campo relevante para a troca com a API em determinados fluxos, mas isso não o transforma em prova confiável de que o modelo tenha seguido uma cadeia de raciocínio completa ou verdadeira. Seu conteúdo pode ser sensível e não deve ser exibido, retido ou usado indiscriminadamente para avaliar uma explicação como se fosse uma auditoria do processo interno. Para verificar o comportamento, use entradas controladas, chamadas observáveis, resultados e critérios de aceitação.

Os registros devem separar fatos de interpretações. “A solicitação de continuação enviada não continha o campo” é uma observação verificável quando há um registro correspondente. “O modelo esqueceu o que estava pensando” é uma explicação especulativa e antropomórfica. Manter essa distinção evita que uma hipótese se transforme em diagnóstico operacional sem evidências.

Manter, corrigir ou preparar uma migração

Uma decisão de manutenção deve se basear em evidências do ambiente real. Consulte o endpoint oficial de listagem de modelos usando as credenciais e permissões que a aplicação utilizará; registre o identificador retornado e repita a consulta no ambiente de implantação. A página de especificação descreve o endpoint, mas não substitui uma consulta atual: um exemplo ou uma referência histórica não certifica a disponibilidade em uma conta específica. Verifique também o alias configurado em relação à versão fixada e documente o comportamento esperado pela integração.

A cronologia pública pode orientar a investigação, mas não resolvê-la por si só. O centro de transparência da DeepSeek lista o V3.2 e o V4 com informações de publicação, enquanto o registro de alterações permite conferir mudanças de alias e anúncios de descontinuação. Antes de migrar, verifique nessas fontes qual identificador está disponível e que mudança foi anunciada, e confirme o resultado com a API da sua conta. A documentação fornecida não justifica presumir que exista um caminho de migração automática nem afirmar equivalência funcional entre modelos.

O guia de ferramentas explica as diferenças entre interfaces, portanto uma migração de formato também deve ser tratada como uma mudança de integração. Execute a mesma bateria de regressão no caminho atual e no candidato: uma chamada, uma sequência encadeada, streaming, entradas inválidas, erros de ferramenta e continuação em um novo turno. Compare critérios específicos do produto, não uma impressão geral. Revise permissões, latência, falhas e custo conforme os critérios relevantes para a organização, sem confundir compatibilidade sintática com equivalência de comportamento.

Se a integração passar nos testes e o identificador continuar disponível, mantê-la pode ser razoável, de acordo com a política de suporte e o risco aceitável para a equipe. Se houver falha por perda de estado, corrija-a e execute novamente a bateria antes de decidir sobre o modelo. Se uma migração estiver sendo preparada, mantenha um caminho de reversão testado, limite a implantação inicial e defina quais sinais interromperão a mudança. Essas são recomendações operacionais, não garantias oferecidas pelo fornecedor.

A conclusão útil não é que `reasoning_content` “explique” o agente, mas que faz parte de um contrato que merece um teste explícito nas circunstâncias documentadas. A equipe pode tomar uma decisão mais rigorosa quando dispõe de uma sequência reproduzível, critérios definidos previamente, registros minimizados e uma verificação atual de disponibilidade. Se alguma dessas evidências estiver faltando, a incerteza deve constar da decisão.

Continue a explorar

Correções e transparência

Se encontrar informação incorreta ou desatualizada, envie-nos a página e a fonte que devemos rever.