Para um agente de IA agendar no horário certo, transforme a conversa em uma proposta explícita: data local, hora, zona IANA, duração e participantes. Depois valide essa proposta com código, converta o instante para UTC e só então consulte disponibilidade e grave o compromisso. O modelo interpreta a intenção; a biblioteca de datas resolve a conversão.
Guardar apenas “15h” ou somar três horas manualmente não sustenta uma operação com clientes em cidades diferentes. Também não basta salvar tudo em UTC: reuniões recorrentes precisam preservar a intenção de horário local. O desenho abaixo separa essas duas necessidades e evita que uma resposta convincente do agente esconda uma agenda errada.
Resumo rápido
- Use identificadores como
America/Sao_Paulo, além da data e hora locais.- Resolva “amanhã” a partir do instante da mensagem e do fuso confirmado do solicitante.
- Valide horários inexistentes e ambíguos antes de criar eventos.
- Preserve a zona e a regra local em recorrências; UTC sozinho não descreve essa intenção.
- Mostre a proposta completa e registre o identificador retornado pelo calendário.
Por que o agente precisa de um contrato de tempo
“Marca amanhã às nove” parece um pedido completo. Faltam, porém, o lugar de referência, a duração, a agenda de destino e o significado de amanhã se a mensagem ficou numa fila. Um agente que preenche esses campos pela localização do servidor consegue criar um evento válido na API e errado para a pessoa.
Defina um contrato para a ferramenta de agendamento. Ela recebe campos separados: data local, hora local, zona, duração, calendário autorizado e identificação da solicitação. O texto original serve de evidência para revisão. A ferramenta recusa entradas incompletas; o agente volta à conversa para resolver a dúvida. Essa separação segue a lógica de function calling e saídas estruturadas: ter um JSON bem formado é o começo da validação, não a prova de que seu significado está correto.
Adote uma ordem de confiança para o fuso: confirmação explícita no pedido, preferência verificada do usuário e, por último, pergunta. O telefone, o idioma português e o endereço IP podem sugerir uma opção de interface, mas não devem autorizar uma reserva. Uma pessoa de Manaus pode estar pedindo uma reunião pelo horário do escritório de São Paulo.
Registre a origem dessa escolha. “Fuso confirmado na conversa” é diferente de “fuso herdado do cadastro”. Ao alterar uma preferência, não reinterprete silenciosamente eventos já aceitos. A decisão afeta o que o usuário quis dizer naquele pedido, e precisa sobreviver a retomadas do agente.
Instante, horário local e zona são dados diferentes
Um instante identifica um ponto na linha do tempo. Uma data e hora locais são o que aparece no relógio de uma região. A zona contém regras para relacionar esses conceitos. Já o deslocamento, como -03:00, informa a diferença em relação a UTC em um instante específico; ele não contém as regras completas da região.
| Dado | Para que serve | Erro ao usar sozinho |
|---|---|---|
| 2027-02-10 às 09:00 | Expressar intenção local | Não identifica um instante sem contexto |
| America/Sao_Paulo | Identificar regras regionais | Não informa qual reunião foi pedida |
| Instante em UTC | Comparar reservas e disparar tarefas | Não preserva sozinho a intenção de recorrência local |
| Deslocamento UTC | Documentar uma conversão concreta | Não representa futuras mudanças de regra |
A base de fusos da IANA mantém regras históricas e recebe atualizações quando autoridades mudam limites ou horários. Portanto, trate a base usada pela aplicação como uma dependência de produção. Não fixe no prompt uma afirmação permanente sobre horário de verão no Brasil ou em qualquer outro país.
Como recomendação de armazenamento, mantenha o instante UTC do evento pontual, a zona escolhida, a representação local aprovada e a versão operacional da dependência de fusos quando disponível. Isso ajuda a explicar diferenças após atualizações. Para datas distantes, estabeleça uma revisão quando regras mudarem, antes de enviar novos lembretes.
Valide a proposta antes de consultar a agenda
O pipeline deve ter etapas observáveis: interpretar, validar, resolver a zona, calcular candidatos, consultar disponibilidade, confirmar e criar. Não entregue ao modelo uma ferramenta que aceite um texto livre e faça tudo sem devolver a interpretação intermediária. Esse desenho dificulta detectar o ponto em que a data mudou.
Expressões relativas e passagem de dia
Salve o instante de recebimento da mensagem e converta-o para a zona de referência. Use essa data local para resolver “hoje”, “amanhã” e “sexta que vem”, aplicando uma convenção explícita para expressões ambíguas. Se a execução ocorrer no dia seguinte, mantenha a interpretação ligada à mensagem original ou peça nova confirmação quando a proposta já estiver vencida.
Também separe o horário de atendimento da equipe do horário do cliente. Para oferecer uma janela, construa os intervalos de trabalho de cada participante em sua própria zona e compare os instantes. Verifique feriados e pausas por regras do negócio; um conversor de fusos não conhece o expediente de uma filial.
Horários inexistentes e repetidos
Transições de relógio podem pular um horário local ou fazê-lo ocorrer duas vezes. A biblioteca deve revelar os candidatos, e a política do produto decide o que fazer: rejeitar um horário inexistente e pedir alternativa; diante de duas ocorrências, apresentar as opções com seus deslocamentos. Evite deslocar a reserva para a próxima hora sem avisar.
Em Python, zoneinfo trabalha com zonas IANA e o atributo fold distingue ocorrências em transições ambíguas. A documentação também explica a dependência de dados do sistema ou do pacote tzdata. Instalar Python não substitui verificar os dados de fusos do ambiente.
Uma estratégia de validação é gerar candidatos com as duas possibilidades de fold, convertê-los para UTC e voltar para a zona original. Descarte os que não reproduzem a data e hora pedidas e remova instantes duplicados. Zero candidatos exige correção; dois exigem desambiguação. Teste essa rotina separadamente, pois apenas anexar uma zona a um objeto não demonstra que o horário local existiu.
Integre calendários sem perder a intenção
No Google Calendar, a representação de um evento distingue dateTime de date. O primeiro atende compromissos com hora; o segundo, eventos de dia inteiro. O campo timeZone usa nomes IANA e participa da expansão de recorrências. Consulte a referência oficial de eventos ao montar o adaptador.
Para uma reunião semanal às nove de uma cidade, guarde a regra junto da zona regional e deixe a implementação de calendário expandir suas ocorrências. Somar sete períodos de 24 horas em UTC pode preservar o intervalo absoluto e alterar a hora local após uma mudança de regra. O requisito precisa dizer se a prioridade é a hora local ou a duração absoluta entre execuções.
O término do evento na API é exclusivo. Um evento de dia inteiro deve ter limites de datas apropriados, sem inventar meia-noite UTC para simular a ausência de horário. Inclua esses casos nos testes do adaptador. A documentação de calendários e recorrências ajuda a separar a regra da série e suas ocorrências.
Após consultar disponibilidade, outra pessoa ainda pode ocupar a janela. Revalide perto da gravação e trate o conflito conforme a capacidade do provedor e da aplicação. Use uma chave de solicitação no seu banco para impedir que a retomada do agente repita uma criação já confirmada. Guarde o identificador do evento remoto e consulte o resultado antes de repetir uma chamada cujo retorno se perdeu.
Se o projeto usa serviços Google, a página de integrações do ecossistema Google oferece contexto adicional. A responsabilidade pela conversão e pela validação continua sendo do código da aplicação, independentemente do modelo que interpreta a conversa.
Exemplo: agência de Recife atendendo clientes em Manaus
Imagine uma agência de marketing em Recife com um agente que organiza reuniões de implantação. Um cliente escreve: “Pode ser terça às dez, no meu horário”. O cadastro indica Manaus, mas o pedido não confirma se ele está viajando. O agente apresenta a referência proposta e pede a informação que falta antes de reservar.
Depois da confirmação, a aplicação usa America/Manaus para o cliente e America/Recife para a equipe. A biblioteca calcula a correspondência na data escolhida. A mensagem final mostra data por extenso, dia da semana, horário do cliente e horário da agência, com os nomes das cidades. Nenhuma diferença fixa fica escondida no prompt.
- O agente gera uma proposta com duração de 45 minutos e o calendário da equipe responsável.
- A aplicação valida o pedido e consulta o intervalo convertido, incluindo o tempo de preparação definido pela agência.
- O cliente confirma a proposta completa, associada a uma versão do pedido.
- O adaptador cria o evento e grava seu identificador antes de responder que a reserva foi concluída.
- Um lembrete usa o instante armazenado e exibe novamente a zona de referência do cliente.
Se o cliente responde “agora marque toda terça”, nasce uma série com regra local, não uma cópia infinita de instantes. Se depois ele viaja, a equipe pergunta se deseja manter o horário de Manaus ou alterar a série. O exemplo é ilustrativo e não pressupõe ganho de produtividade medido.
Para avaliar o piloto, acompanhe reservas corrigidas por fuso, solicitações que precisaram de esclarecimento e eventos duplicados após retentativa. Relacione esses indicadores às métricas de agentes de IA, preservando uma categoria específica para erro temporal. A média de tempo de resposta pode melhorar enquanto a agenda piora.
Erros comuns
- Usar o fuso do servidor. Exija a zona da proposta, mesmo que toda a equipe esteja hoje na mesma cidade.
- Confundir conversão com rotulagem. Trocar o rótulo de zona não equivale a preservar o instante em outra zona.
- Aceitar abreviações ambíguas. Resolva a cidade ou a zona completa antes de chamar ferramentas.
- Atualizar dados sem revisão. Verifique eventos futuros relevantes quando a dependência de fusos mudar.
- Confirmar apenas “terça às dez”. Mostre também a data e o lugar de referência.
- Testar só datas comuns. Inclua virada de mês, ano, meia-noite, transições e retomada de execução.
Monte uma pequena matriz de aceitação com resultados conhecidos. Inclua um pedido recebido perto da meia-noite, participantes em dias locais diferentes, evento de dia inteiro, série recorrente e cancelamento de uma única ocorrência. Rode os casos no ambiente de produção antes de liberar novas versões do adaptador.
Perguntas frequentes
Salvar tudo em UTC resolve o problema?
Resolve a comparação de instantes, mas não toda a intenção. Preserve também zona e regra local para séries e para explicar o que foi confirmado na conversa.
Posso pedir ao modelo para calcular a diferença?
Use o modelo para identificar o pedido. Faça a conversão com biblioteca e dados atualizados, devolvendo o resultado à conversa para confirmação quando necessário.
O que fazer quando o fuso não foi informado?
Proponha a preferência verificada do cadastro e indique sua origem. Sem uma referência confiável, pergunte antes de criar o compromisso; não deduza pelo idioma.
Como tratar uma execução que ficou parada?
Retome a proposta com o instante original da mensagem, confira se ela ainda vale e consulte o estado remoto. Não recalcule “amanhã” usando o relógio da retomada.
Uma mudança na base deve alterar todos os eventos?
Não automaticamente. Diferencie histórico de compromissos futuros e avalie a intenção local da série. Defina uma política de revisão e comunique alterações relevantes aos envolvidos.
