Agente de IA e Google Calendar: como agendar sem conflito de horário

Agente de IA e Google Calendar: como agendar sem conflito de horário

Para um agente de IA agendar no Google Calendar sem conflito, a IA não deve decidir sozinha se um horário está livre. Ela entende o pedido e propõe opções, uma ferramenta determinística consulta a disponibilidade real, uma trava reserva o horário por pouco tempo e o evento só é criado depois da confirmação da pessoa, com uma nova checagem imediatamente antes.

Isso vale para qualquer negócio que marca visitas, consultas, reuniões ou atendimentos por WhatsApp, e-mail ou site. O ponto central é separar o que a IA faz bem (conversar, interpretar datas, resumir) do que precisa de regra fixa (conferir agenda, bloquear, criar).

Principais pontos

• A agenda é a fonte da verdade: o agente nunca deve afirmar que um horário está livre com base na memória da conversa.
• Checar disponibilidade logo antes de criar o evento é obrigatório, porque o estado da agenda muda entre a proposta e a confirmação.
• Uma trava temporária impede que duas conversas simultâneas reservem o mesmo horário.
• A confirmação explícita da pessoa, com data, hora, fuso e local, evita eventos criados por engano.
• Criação, remarcação e cancelamento precisam ser operações idempotentes e registradas em log, para que repetir uma tentativa não gere duplicidade.

Por que agentes de IA criam horários duplicados?

O Google Calendar permite que eventos se sobreponham. Ele é uma agenda, não um sistema de reservas com regra de exclusividade. Se o agente chamar a criação de evento sem checar nada, o evento será criado mesmo que já exista outro no mesmo intervalo.

As causas mais comuns de duplicidade são previsíveis:

• O agente confia no que foi dito antes na conversa e oferece um horário que já foi ocupado por outra pessoa.
• Duas conversas acontecem ao mesmo tempo e ambas enxergam o mesmo horário livre.
• O fluxo tenta de novo após um erro de rede e cria um segundo evento igual.
• A pessoa muda de ideia no meio do caminho e o evento antigo continua na agenda.
• Eventos marcados como disponíveis, eventos de dia inteiro ou agendas secundárias não são considerados na checagem.

Nenhuma dessas falhas é um problema de inteligência do modelo. São falhas de desenho do fluxo, e por isso a correção está na arquitetura, não em um prompt mais rigoroso.

Como o agente deve checar a disponibilidade?

O agente precisa de uma ferramenta própria de consulta, com entrada e saída bem definidas. A API do Google Calendar oferece uma consulta de disponibilidade (freeBusy) que devolve os intervalos ocupados das agendas informadas. Também é possível listar eventos de um período. Em ambos os casos, o resultado vem da agenda, não do modelo.

Algumas decisões de desenho evitam surpresas:

• Quais agendas contam: a agenda principal, as de cada profissional, a de uma sala ou equipamento. Defina isso por escrito antes de integrar.
• Eventos que não bloqueiam: no Google Calendar, um evento marcado como disponível não aparece como ocupado na consulta de disponibilidade. Decida se isso é aceitável para o seu caso.
• Fuso horário explícito: envie e receba sempre datas completas com fuso, nunca apenas «amanhã às três».
• Regras do negócio fora da agenda: duração por tipo de serviço, intervalo entre atendimentos, tempo de deslocamento e horário de funcionamento. O Calendar não conhece essas regras, então elas ficam em código ou em configuração.
• Janela de antecedência: por exemplo, não oferecer horários que começam em minutos, para dar tempo de preparo.

A ferramenta deve devolver ao agente uma lista curta de opções válidas, já filtradas pelas regras. O modelo apenas apresenta essas opções em linguagem natural. Se ele inventar um horário fora da lista, a etapa de criação precisa recusar.

Outro cuidado: a entrada vem de texto livre de um cliente. Trate o conteúdo da conversa como dado não confiável, e não como instrução, como explicamos em prompt injection em agentes de IA.

Como usar travas para evitar corrida entre dois pedidos?

Mesmo com checagem, dois clientes podem receber o mesmo horário livre no mesmo minuto. A solução é uma pré-reserva, ou trava, com prazo curto.

O funcionamento básico é este:

• Quando o agente oferece um horário, a ferramenta grava uma reserva temporária em um banco de dados ou cache próprio, com identificador da conversa, recurso, início, fim e prazo de expiração.
• Uma regra de unicidade impede duas reservas ativas para o mesmo recurso e intervalo. Quem tentar depois recebe uma recusa e o agente oferece outra opção.
• Se a pessoa confirmar dentro do prazo, a reserva é convertida em evento. Se não confirmar, a reserva expira e o horário volta a ficar livre.
• A consulta de disponibilidade passa a considerar tanto os eventos do Calendar quanto as reservas temporárias ativas.

O prazo da trava é uma decisão de negócio. Muito curto frustra quem demora a responder no WhatsApp. Muito longo esconde horários que poderiam ser vendidos. Comece com um prazo conservador e ajuste com base no que o piloto mostrar.

Há ainda a questão de repetição. A API do Google Calendar permite informar um identificador próprio ao criar o evento, e uma segunda tentativa com o mesmo identificador é recusada como conflito (confira o formato aceito na documentação oficial). Derivar esse identificador da reserva dá a você uma criação idempotente: repetir a chamada não gera dois eventos. O princípio é o mesmo descrito na documentação de requisições idempotentes da Stripe, que serve como exemplo de como um provedor define essa garantia. Para fluxos com retentativas, vale ler também sobre erros e retentativas no n8n.

Por que confirmar antes de criar o evento?

Criar um evento é uma ação com efeito externo: convida pessoas, dispara notificações e ocupa a agenda de alguém. Por isso a confirmação não deve ser implícita.

Uma boa mensagem de confirmação traz tudo o que precisa ser verificado:

• Serviço ou motivo do compromisso.
• Data, hora de início e duração, com o dia da semana escrito.
• Profissional ou recurso responsável.
• Local ou link da reunião.
• Aviso de que o horário está reservado por um tempo limitado e o que acontece se a pessoa não responder.

A resposta deve ser inequívoca. Um «pode ser» ou um «talvez» não confirma. Defina quais respostas contam como sim e peça de novo quando houver dúvida.

Depois da confirmação, e antes de gravar, a ferramenta repete a checagem de disponibilidade. Entre a proposta e o sim, alguém da equipe pode ter colocado um compromisso direto no Calendar. Se o horário deixou de estar livre, o agente explica com clareza e oferece alternativas, em vez de criar um conflito silencioso.

Se o agendamento acontece pelo WhatsApp, o fluxo completo de conversa merece cuidado próprio. Explicamos o funcionamento geral em agendamento automático no WhatsApp com IA.

Passo a passo para montar o fluxo

Este é um roteiro de implementação que pode ser seguido por uma equipe técnica ou por um fornecedor:

• Passo um: liste os recursos que podem ser agendados (pessoas, salas, equipamentos) e a agenda correspondente a cada um.
• Passo dois: escreva as regras do negócio: horários de funcionamento, duração por serviço, intervalos, antecedência mínima e limite de remarcações.
• Passo três: crie uma conta de serviço ou uma autorização com o menor escopo possível, usando o fluxo OAuth 2.0 descrito na documentação do Google.
• Passo quatro: construa a ferramenta de consulta, que recebe serviço e período e devolve apenas horários válidos.
• Passo cinco: construa a ferramenta de reserva temporária, com expiração e regra de unicidade.
• Passo seis: construa a ferramenta de criação, que exige uma reserva válida, repete a checagem e usa um identificador idempotente.
• Passo sete: construa as ferramentas de remarcação e cancelamento, que verificam se o evento pertence à pessoa que está pedindo.
• Passo oito: registre em log cada decisão: opções oferecidas, reserva criada, confirmação recebida, resultado da criação e erros.
• Passo nove: teste com agenda de sandbox e cenários de conflito antes de tocar na agenda real.
• Passo dez: defina o que o agente faz quando algo falha: avisar a pessoa e transferir para um humano.

Sobre o desenho das ferramentas, a Anthropic publica orientações úteis em como escrever ferramentas eficazes para agentes: nomes claros, respostas enxutas e mensagens de erro que ajudam o agente a se corrigir. Para validar tudo sem risco, veja como testar agente de IA com mocks e sandbox.

Cenário ilustrativo: duas pessoas, um horário

Cenário ilustrativo: uma clínica fictícia atende por WhatsApp e tem uma única sala de avaliação. Duas pessoas pedem «quinta à tarde» quase ao mesmo tempo.

O agente consulta a ferramenta de disponibilidade e recebe três horários livres. Para a primeira pessoa, oferece o das catorze horas, e a ferramenta grava uma reserva temporária. Quando o agente consulta de novo para a segunda pessoa, o horário das catorze já aparece como indisponível, porque a reserva conta como ocupação. Ela recebe os outros dois.

A primeira pessoa confirma. A ferramenta repete a checagem, encontra o horário ainda livre, cria o evento com identificador derivado da reserva e converte a reserva em agendamento. Se a rede falhar e a chamada for repetida, o identificador igual impede um segundo evento.

A segunda pessoa demora a responder. A reserva dela expira, o horário volta a ficar livre e, se ela confirmar depois, o agente refaz a consulta e explica a mudança antes de oferecer novas opções. Em nenhum momento o modelo decidiu sozinho o que estava livre.

Permissões, LGPD e como aplicar o método

O agente só deve ter acesso ao que precisa. Se a tarefa é marcar horários, não há motivo para ler o conteúdo de todos os eventos da agenda pessoal de alguém. Prefira consultar apenas ocupado ou livre, use agendas dedicadas ao atendimento e restrinja escopos de acesso. O guia de autorização da OWASP reforça o princípio do menor privilégio e a verificação de autorização em cada operação.

Em relação à LGPD, o evento costuma conter nome, telefone, motivo do atendimento e, em alguns setores, informação sensível, como dados de saúde. Registre só o necessário na descrição do evento, defina por quanto tempo os logs de conversa ficam guardados e saiba onde os dados são processados. Se o modelo ou o serviço de agenda estiver fora do país, leia sobre transferência internacional de dados com IA. Em caso de dúvida sobre base legal, procure orientação jurídica.

No método que aplicamos, o trabalho segue quatro etapas. Mapear: entender como a agenda é usada hoje, quem marca, quem remarca e onde os conflitos aparecem. Limitar: definir quais agendas, quais ações e quais dados o agente pode tocar, com aprovação humana para exceções. Pilotar: escolher um fluxo real, como marcar a primeira visita, com logs e uma métrica combinada, por exemplo a quantidade de conflitos detectados e evitados. Transferir: entregar a operação com documentação e decidir em conjunto se expande, ajusta ou para.

Perguntas frequentes

O agente de IA pode ler e escrever direto no Google Calendar? Pode, por meio da API e de uma autorização OAuth, mas o ideal é que ele passe por ferramentas intermediárias que aplicam as regras do negócio. Assim, o modelo não tem acesso irrestrito à agenda e cada ação fica registrada.

O Google Calendar impede dois eventos no mesmo horário? Não, ele aceita eventos sobrepostos. A prevenção de conflito precisa vir da sua lógica: consulta de disponibilidade, trava temporária, checagem final e criação idempotente.

O que fazer quando o horário some entre a proposta e a confirmação? O agente deve avisar que o horário não está mais disponível e apresentar novas opções válidas. Nunca crie o evento mesmo assim para depois resolver manualmente, porque isso transfere o problema para a equipe e para o cliente.

Quando um humano deve assumir o agendamento? Quando houver pedido fora das regras, remarcações repetidas, falha técnica na agenda ou qualquer ambiguidade sobre quem é a pessoa ou qual compromisso ela quer alterar. Defina esses gatilhos desde o início e envie ao atendente o resumo da conversa para que ninguém precise repetir tudo.

Fontes

• Google: OAuth 2.0 authorization
• Stripe: an example of provider-defined idempotency
• OWASP: authorization guidance
• Anthropic: Writing effective tools for agents