Quando um agente de IA recebe um erro de upload, a primeira ação deve ser descobrir se o servidor recebeu o arquivo. Um tempo de espera esgotado não prova que o envio falhou. Repetir a criação imediatamente pode produzir duas cópias, duas notificações e duas etapas de processamento para o mesmo documento.
A solução combina identificação estável da operação, consulta do estado remoto e uma política de repetição definida no código. O modelo pode explicar o problema e organizar a exceção, mas a integração deve decidir quando reenviar. A proposta abaixo trata de uploads feitos por ferramentas de agentes, usando o Google Drive como exemplo concreto.
Resumo rápido
- Erro de comunicação pode deixar o resultado desconhecido.
- Uma operação mantém a mesma identidade durante todas as tentativas.
- Consulta e retomada vêm antes de uma nova criação.
- Falha de permissão exige correção, não repetição infinita.
- O envio termina depois da confirmação do arquivo e do registro local.
O problema está entre enviar e receber a confirmação
Há três momentos diferentes: preparar o documento, transmitir os bytes e receber a confirmação. A conexão pode cair depois que o servidor gravou o arquivo, mas antes de o agente receber a resposta. Nesse intervalo, a tela mostra erro enquanto a pasta já contém o documento. Se a ferramenta interpretar qualquer exceção como autorização para criar novamente, o sistema perde a ligação entre intenção e resultado.
Idempotência é a propriedade de repetir uma operação sem multiplicar seu efeito pretendido. Ela precisa existir no contrato da ferramenta ou ser construída pela aplicação. Escrever no prompt “não duplique arquivos” ajuda a explicar o objetivo, porém não cria uma transação no servidor nem impede dois trabalhadores de executar o mesmo envio simultaneamente.
Defina primeiro o que significa duplicata no seu processo. Dois PDFs com bytes iguais podem ser entregas legítimas para clientes diferentes. Dois documentos com o mesmo nome podem representar versões diferentes. Uma identidade útil combina contexto de negócio, destino e versão da entrega. O resumo criptográfico do conteúdo, chamado hash, ajuda a conferir bytes, mas sozinho não determina se uma segunda entrega foi autorizada.
Essa distinção deve aparecer na descrição da ferramenta. O agente precisa saber se está criando um documento novo, retomando uma operação existente ou substituindo uma versão. Para estruturar os argumentos dessas ações, consulte o guia de function calling e saídas estruturadas.
Monte um registro antes do primeiro envio
Crie um registro durável antes de acessar a rede. Ele deve conter identificador da operação, referência interna do cliente, destino esperado, nome de apresentação, tamanho, hash local quando aplicável e estado atual. Armazene também a referência remota assim que ela existir. Um processo reiniciado precisa conseguir continuar a mesma entrega sem depender do histórico de conversa do modelo.
Uma sequência de estados simples é: preparado, enviando, resultado desconhecido, confirmado ou bloqueado. “Resultado desconhecido” merece um estado próprio: significa que uma investigação é necessária. Não o transforme automaticamente em “não enviado”. Registre horário, número de tentativas e próximo passo permitido, evitando guardar o conteúdo integral do arquivo no log.
Na aplicação, use uma restrição de unicidade ou mecanismo equivalente para impedir duas execuções ativas da mesma operação. A verificação “existe registro?” seguida de “criar registro” em comandos separados pode sofrer uma corrida: duas instâncias consultam antes que qualquer uma grave. O armazenamento deve resolver essa disputa de forma atômica.
Também defina quando uma operação nova pode ser aberta. Uma revisão autorizada do documento pode gerar outra versão, ligada à anterior. A ausência de resposta de rede não pode gerar essa autorização. Assim, o identificador expressa a intenção do usuário e não muda apenas porque uma tentativa demorou.
| Situação observada | Próxima ação | O que evitar |
|---|---|---|
| Servidor confirma arquivo e identificador | Conferir destino e registrar conclusão | Criar outra cópia por precaução |
| Conexão cai sem resposta final | Consultar operação ou sessão remota | Declarar que nada foi recebido |
| Permissão insuficiente | Encaminhar para correção de acesso | Trocar credenciais por conta própria |
| Limitação temporária de chamadas | Aplicar política de espera limitada | Repetir em laço rápido |
| Arquivo local mudou | Interromper e pedir decisão sobre versão | Misturar bytes de versões distintas |
Use os mecanismos reais oferecidos pelo destino
O Google Drive documenta uploads retomáveis, que permitem consultar uma sessão e continuar uma transferência interrompida. Preserve a referência dessa sessão e siga o procedimento oficial de consulta do estado. A posição confirmada pelo servidor orienta a retomada; a quantidade que o programa tentou enviar não comprova o que foi recebido.
O Drive também documenta IDs previamente gerados para determinados arquivos. Em uploads compatíveis, reutilizar o mesmo ID permite repetir uma criação após um erro de resultado incerto sem gerar outra cópia. A documentação descreve retorno de conflito quando a criação anterior ocorreu. Há restrições para arquivos nativos do Google Workspace e conversões; não aplique essa estratégia a qualquer documento.
Esses mecanismos resolvem partes diferentes do problema. A sessão retomável ajuda a continuar os bytes. O ID estável ajuda a identificar o recurso. O registro de negócio impede que a mesma intenção abra várias operações. Confirme o comportamento da combinação utilizada no seu conector e evite presumir que uma função chamada “upload” expõe todas essas opções.
Quando uma ferramenta visual não apresenta ID nem estado de transferência, reduza a autonomia. O agente pode consultar a pasta, comparar os dados disponíveis e encaminhar o caso a uma pessoa. Uma pesquisa por nome é apenas evidência auxiliar, pois nomes podem se repetir. A página de integrações do ecossistema Google contextualiza conexões, mas as garantias técnicas vêm da API específica.
Separe falhas recuperáveis de pedidos de intervenção
A documentação do Drive diferencia códigos HTTP e motivos detalhados no corpo da resposta. Use ambos. Um erro de autenticação pede a recuperação prevista pelo fluxo de credenciais; uma proibição pode decorrer de acesso ou de limite. Repetir tudo sob a mesma regra desperdiça chamadas e pode esconder a causa real.
Para falhas transitórias, defina espera crescente, alguma variação aleatória e um teto de tentativas. Esses limites são escolhas da sua aplicação, não números universais. Considere o prazo do trabalho: um envio que só é útil antes da reunião não deve continuar escondido depois dela. Quando o teto for atingido, mantenha o registro e entregue um diagnóstico verificável.
Evite multiplicar políticas de repetição. Se o SDK repete uma chamada e a ferramenta repete o SDK, enquanto o agente repete a ferramenta, o total pode crescer muito além do esperado. Escolha quem controla o ciclo, exponha contadores e faça os outros níveis respeitarem essa decisão.
A confirmação do arquivo não implica confirmação de todas as ações seguintes. Indexação, leitura pela IA e notificação ao cliente devem ter registros próprios. Se a análise falhar, repita a análise sobre o ID confirmado; não envie outra cópia. O cuidado com evidências aparece no artigo sobre downloads parciais e conferência de integridade.
Exemplo: uma gráfica em Campinas recebe artes
Considere uma gráfica de Campinas que usa um agente para organizar PDFs enviados por um formulário. Este é um cenário ilustrativo, sem resultados medidos. O formulário produz uma referência de atendimento, e cada arte aprovada para transferência ganha uma operação ligada a essa referência e à pasta do pedido.
O agente prepara o registro e aciona a ferramenta. A rede cai antes da resposta final. Em vez de anunciar falha definitiva ou reenviar a arte, a ferramenta marca resultado desconhecido e consulta a sessão. Se o servidor confirmar o envio completo, ela salva o ID remoto e compara os metadados previstos. Se houver uma parte pendente, continua conforme o protocolo suportado.
Imagine que o cliente troca o arquivo enquanto a transferência está suspensa. A ferramenta detecta que a origem mudou e para. O atendente decide qual versão usar; o agente não junta o começo da arte antiga com o restante da nova. A nova entrega recebe uma versão própria, preservando a relação com o pedido.
O comprovante interno informa operação, arquivo confirmado, pasta e horário da conferência. A mensagem ao atendente distingue “arquivo recebido” de “arte aprovada para impressão”. Aprovar a qualidade gráfica é outra etapa. A separação evita que uma confirmação técnica seja interpretada como autorização de produção.
Erros comuns
- Gerar um novo identificador em cada tentativa. Isso apaga a relação entre reenvio e operação original.
- Excluir a cópia suspeita automaticamente. O arquivo encontrado pode ser a entrega válida de outro processo.
- Tratar barra de progresso como conclusão. O que importa é a confirmação persistida pelo destino.
- Reutilizar arquivo modificado. A retomada precisa manter a mesma versão de origem.
- Registrar segredos no log. Referências de sessão e credenciais exigem acesso restrito; o modelo não precisa recebê-las.
- Encerrar sem explicar a pendência. Informe qual resultado está desconhecido, o que foi consultado e quem deve decidir.
Antes de liberar, simule queda antes da transmissão, durante os bytes e depois da gravação remota. Execute duas instâncias ao mesmo tempo. A aceitação deve observar uma única entrega para a mesma intenção, retomada rastreável e nenhuma notificação prematura. Use o guia de testes de agentes antes da produção para organizar os casos.
Perguntas frequentes
Um hash impede qualquer duplicata?
Não. Ele ajuda a comparar conteúdo, mas não decide contexto, versão ou destino. A mesma arte pode precisar estar em dois pedidos diferentes. Use o hash como evidência e mantenha uma identidade de operação ligada à entrega autorizada.
Posso mandar o agente clicar em reenviar?
Somente quando o procedimento da aplicação determinar que isso é seguro. Se o resultado anterior está desconhecido, o clique pode criar outra cópia. Sem uma forma confiável de consultar o envio, encaminhe a exceção para conferência.
Um conflito significa que o arquivo está correto?
Não necessariamente. Ele pode indicar que o identificador já existe. Consulte o recurso e confira sua relação com a operação, o destino e os dados disponíveis. A regra precisa considerar o comportamento documentado daquele endpoint.
Preciso usar IA para fazer retentativas?
Não. Controle de estado, espera e repetição pertencem ao código. A IA pode interpretar solicitações e explicar problemas, enquanto a ferramenta preserva as garantias de transferência. Essa divisão facilita auditar o resultado.
