Pular para conteúdo

CALENDAR_LIST_EVENTS - Listar Eventos do Google Calendar

O que é esta Tool?

A CALENDAR_LIST_EVENTS é a tool responsável por buscar múltiplos eventos de uma agenda com filtros por data, quantidade máxima de resultados e termos de busca.

Por que esta Tool existe?

Consultar lista de compromissos é fundamental. A CALENDAR_LIST_EVENTS existe para:

  1. Visualizar Agenda: Exibir próximos compromissos do usuário
  2. Filtrar por Período: Listar eventos de uma semana ou mês específico
  3. Integração com Chatbots: "Quais minhas reuniões de amanhã?"
  4. Dashboards: Exibir calendário em interfaces web

Como funciona internamente?

Quando a CALENDAR_LIST_EVENTS é executada, o sistema:

  1. Valida Autenticação: Verifica tokens OAuth2
  2. Monta Filtros: timeMin, timeMax, maxResults, query
  3. Busca Eventos: GET /calendar/v3/calendars/{calendarId}/events
  4. Ordena Resultados: Por data de início (startTime)
  5. Retorna Lista: Array de eventos com dados resumidos
  6. Se vazio: Retorna array vazio (não é erro)

Código interno (google-executors.service.ts:389-401): 

case 'listEvents':
  const listResult = await calendar.events.list({
    calendarId: data.calendarId || 'primary',
    timeMin: data.timeMin || new Date().toISOString(),
    maxResults: data.maxResults || 10,
    singleEvents: true,
    orderBy: 'startTime',
  });

  return {
    success: true,
    events: listResult.data.items || [],
  };

Quando você DEVE usar esta Tool?

Use CALENDAR_LIST_EVENTS sempre que precisar listar múltiplos eventos:

Casos de uso

  1. Agenda do Dia: "Mostrar compromissos de hoje"
  2. Próximas Reuniões: "Listar 5 próximas reuniões"
  3. Eventos da Semana: "Compromissos desta semana"
  4. Buscar por Título: "Encontrar todas reuniões com palavra 'cliente'"

Quando NÃO usar CALENDAR_LIST_EVENTS

  • Buscar evento específico por ID: Use CALENDAR_GET_EVENT
  • Criar novo evento: Use CALENDAR_CREATE_EVENT
  • Verificar disponibilidade: Use CALENDAR_GET_FREE_BUSY

Parâmetros Detalhados

calendarId (string, opcional)

O que é: ID da agenda a consultar.

Padrão: "primary" (agenda principal)

timeMin (string RFC3339, opcional)

O que é: Data/hora mínima (eventos a partir de...)

Padrão: Agora (new Date().toISOString())

timeMax (string RFC3339, opcional)

O que é: Data/hora máxima (eventos até...)

Padrão: Sem limite

maxResults (number, opcional)

O que é: Quantidade máxima de eventos a retornar.

Padrão: 10

Limite: 2500

query (string, opcional)

O que é: Termo de busca para filtrar eventos.

Padrão: "" (sem filtro)

Flow completo para testar:

{
  "name": "Listar Próximos 5 Eventos",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "calendar_1",
      "type": "google_calendar",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Listar Eventos",
        "operation": "listEvents",
        "oauth2": {
          "clientId": "{{GOOGLE_CLIENT_ID}}",
          "clientSecret": "{{GOOGLE_CLIENT_SECRET}}",
          "refreshToken": "{{GOOGLE_REFRESH_TOKEN}}"
        },
        "calendarId": "primary",
        "maxResults": 5
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Exibir Lista",
        "parameters": {
          "message": "Próximos 5 eventos:\n\n{{calendar_1.events}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "calendar_1" },
    { "source": "calendar_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: O sistema retornará os 5 próximos eventos da agenda principal.

Parâmetros

Campo Tipo Obrigatório Descrição
calendarId string Não ID da agenda (padrão: primary)
timeMin string (RFC3339) Não Data/hora inicial (padrão: agora)
timeMax string (RFC3339) Não Data/hora final (padrão: sem limite)
maxResults number Não Quantidade máxima (padrão: 10, máx: 2500)
query string Não Termo de busca (padrão: sem filtro)

Exemplo 1: Agenda do Dia

Objetivo: Listar todos compromissos de hoje

JSON para Importar

{
  "name": "Compromissos de Hoje",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "calendar_1",
      "type": "google_calendar",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Eventos de Hoje",
        "operation": "listEvents",
        "oauth2": {
          "clientId": "{{GOOGLE_CLIENT_ID}}",
          "clientSecret": "{{GOOGLE_CLIENT_SECRET}}",
          "refreshToken": "{{GOOGLE_REFRESH_TOKEN}}"
        },
        "calendarId": "primary",
        "timeMin": "2025-10-12T00:00:00-03:00",
        "timeMax": "2025-10-12T23:59:59-03:00",
        "maxResults": 50
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Agenda",
        "parameters": {
          "message": "Sua agenda de hoje ({{calendar_1.events.length}} eventos):\n\n{{calendar_1.events}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "calendar_1" },
    { "source": "calendar_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Sua agenda de hoje (3 eventos):

1. 09:00 - Reunião de Equipe
2. 14:00 - Apresentação Cliente
3. 16:30 - Review Semanal

Exemplo 2: Buscar Reuniões com Cliente

Objetivo: Filtrar eventos por termo de busca

JSON para Importar

{
  "name": "Buscar Reuniões com Cliente",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Termo de Busca",
        "parameters": {
          "message": "Digite o termo para buscar (ex: cliente, reunião, etc):",
          "variableName": "searchTerm"
        }
      }
    },
    {
      "id": "calendar_1",
      "type": "google_calendar",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Eventos",
        "operation": "listEvents",
        "oauth2": {
          "clientId": "{{GOOGLE_CLIENT_ID}}",
          "clientSecret": "{{GOOGLE_CLIENT_SECRET}}",
          "refreshToken": "{{GOOGLE_REFRESH_TOKEN}}"
        },
        "calendarId": "primary",
        "query": "{{searchTerm}}",
        "maxResults": 20
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Exibir Resultados",
        "parameters": {
          "message": "Encontrados {{calendar_1.events.length}} eventos com '{{searchTerm}}':\n\n{{calendar_1.events}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "calendar_1" },
    { "source": "calendar_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Digite o termo para buscar:
Usuário: cliente
Sistema: Encontrados 4 eventos com 'cliente':

1. 15/10 - Reunião com Cliente A
2. 18/10 - Apresentação Cliente B
3. 22/10 - Follow-up Cliente A
4. 25/10 - Proposta Cliente C

Resposta da Tool

{
  "success": true,
  "action": "calendar_list_events",
  "events": [
    {
      "id": "abc123",
      "summary": "Reunião de Equipe",
      "start": {"dateTime": "2025-10-12T09:00:00-03:00"},
      "end": {"dateTime": "2025-10-12T10:00:00-03:00"},
      "status": "confirmed"
    },
    {
      "id": "xyz789",
      "summary": "Apresentação Cliente",
      "start": {"dateTime": "2025-10-12T14:00:00-03:00"},
      "end": {"dateTime": "2025-10-12T15:00:00-03:00"},
      "status": "confirmed"
    }
  ],
  "count": 2,
  "timestamp": "2025-10-12T08:00:00.000Z"
}

Boas Práticas

SIM:

  • Use timeMin para evitar buscar eventos passados desnecessariamente
  • Limite maxResults para melhor performance (padrão 10 é bom)
  • Use query para filtrar por termos específicos
  • Ordene por startTime (padrão da API)

NÃO:

  • Não busque todos eventos sem limite (use timeMax)
  • Não ignore eventos com status "cancelled"
  • Não esqueça que retorna array vazio se não houver eventos

Dicas

Formato de datas: Use RFC3339 para timeMin/timeMax: 2025-10-12T00:00:00-03:00.

Performance: Quanto menor o maxResults, mais rápida a resposta.

Busca inteligente: O parâmetro query busca em título, descrição e local do evento.

Eventos recorrentes: Por padrão, singleEvents=true expande eventos recorrentes em instâncias individuais.

Próximos Nodes

→ CALENDAR_GET_EVENT - Buscar detalhes de evento específico → CALENDAR_SEARCH_EVENTS - Busca avançada com filtros → CALENDAR_CREATE_EVENT - Criar novo evento