AgendaIA

O AgendaIA é um bot para Telegram desenvolvido como um estudo de integração entre inteligência artificial, processamento de linguagem natural e APIs externas.

Em vez de exigir comandos rígidos, o usuário pode enviar mensagens em linguagem natural, como:

"agende uma reunião amanhã às 17h"

O sistema interpreta a intenção da mensagem e transforma o pedido em uma estrutura que pode ser processada pela integração com o Google Calendar.

O fluxo começa com uma mensagem enviada pelo usuário no Telegram.

1. O bot recebe a mensagem através do Telegram.
2. A mensagem é enviada ao Gemini 2.5 Flash.
3. O modelo identifica a intenção da solicitação.
4. A resposta do modelo é estruturada em campos como ação, data, horário, título e duração.
5. O resultado é validado através de Zod.
6. A aplicação verifica conflitos no Google Calendar quando necessário.
7. A operação correspondente é executada através da API do Google Calendar.
8. O bot retorna o resultado ao usuário.

As intenções suportadas incluem criação, consulta e cancelamento de reuniões.

A aplicação é organizada em módulos com responsabilidades específicas:

Telegram
   │
   ▼
Bot
   │
   ▼
Gemini
   │
   ▼
Intent estruturada
   │
   ▼
Zod
   │
   ▼
Google Calendar

Bot

Responsável por receber mensagens, direcioná-las para o processamento e enviar as respostas ao usuário.

IA

O módulo de IA utiliza o Gemini para transformar linguagem natural em uma intenção estruturada.

Validação

O resultado produzido pelo modelo passa por um schema Zod antes de ser utilizado pela aplicação.

Google Calendar

A integração utiliza OAuth2 e a API do Google Calendar para consultar, criar e cancelar eventos, incluindo verificação de disponibilidade antes de novos agendamentos.

• Criação de reuniões através de linguagem natural.
• Consulta de compromissos de um determinado dia.
• Cancelamento de reuniões por data e horário.
• Detecção de conflitos antes de criar eventos.
• Interpretação de intenções através do Gemini.
• Saída estruturada validada com Zod.
• Integração OAuth2 com o Google Calendar.
• Interface conversacional através do Telegram.

Linguagem natural em vez de comandos rígidos

O usuário não precisa conhecer uma sintaxe específica para interagir com o bot. A aplicação recebe mensagens comuns e utiliza o modelo para identificar a intenção.

Saída estruturada

Em vez de utilizar a resposta textual do modelo diretamente, a aplicação trabalha com uma estrutura contendo a ação e os dados necessários para executar a operação.

Isso permite separar a interpretação feita pela IA da lógica responsável por alterar o calendário.

Zod como camada de validação

A resposta gerada pelo modelo é validada antes de chegar à integração com o Google Calendar.

Verificação de conflitos

A criação de eventos passa por uma verificação de disponibilidade antes da confirmação do agendamento.

O AgendaIA funciona principalmente como um estudo de caso sobre integração de IA em uma aplicação tradicional.

Os principais conceitos explorados foram:

• processamento de linguagem natural;
• structured output;
• validação de respostas de modelos;
• integração com APIs externas;
• OAuth2;
• interpretação de intenções;
• transformação de linguagem natural em operações determinísticas;
• integração de um LLM com uma interface conversacional.