Google Workspace Calendar Agenda

ANÁLISE EDITORIAL

Em resumo: Google Workspace Calendar Agenda orienta um agente a reunir os próximos compromissos dos calendários acessíveis por uma conta Google. A Skill usa o comando gws calendar +agenda, trabalha com permissão somente de leitura e organiza os eventos por horário. Ela não cria, altera ou remove reuniões.

A utilidade aparece quando a agenda está distribuída entre calendário principal, projetos, equipes e calendários compartilhados. Em vez de pedir uma síntese vaga, o usuário pode escolher hoje, amanhã, a semana, um número de dias ou um calendário específico. O cuidado central é outro: leitura não significa ausência de sensibilidade. Título, horário, calendário e local podem revelar clientes, rotinas, viagens e reuniões internas.

Uma agenda consolidada, com escopo visível

O arquivo oficial define uma tarefa estreita: mostrar eventos futuros em todos os calendários ou aplicar um filtro por nome ou identificador. Os controles documentados são --today, --tomorrow, --week, --days, --calendar e --timezone. A Skill oficial no commit auditado também informa que, sem filtro, a consulta percorre todos os calendários disponíveis para a conta.

Há uma diferença útil entre --today e o comando sem período. No código da versão revisada, --today usa o intervalo entre meia-noite e meia-noite no fuso resolvido. Sem essa opção, a busca parte do momento atual e avança um dia por padrão. --tomorrow cobre o próximo dia civil e --week avança sete dias a partir do horário atual.

O que a versão auditada realmente consulta

A implementação da release v0.22.5 solicita o escopo OAuth calendar.readonly. Primeiro consulta a lista de calendários da conta. Depois chama a listagem de eventos em cada calendário selecionado, transforma recorrências em ocorrências individuais, ordena por início e devolve cinco campos por item: início, fim, título, nome do calendário e local. A saída também inclui a quantidade de eventos e o intervalo consultado.

Isso ajuda a separar a Skill de um assistente completo de reuniões. Ela não devolve descrição, lista de convidados ou conteúdo de anexos no resultado preparado pelo helper. Também não prepara reunião, não resume mensagens e não envia lembrete. Sua função é montar uma visão cronológica enxuta a partir do Google Calendar.

Para quem ela serve

A Skill pode ser útil para profissionais com vários calendários, equipes de atendimento, operações, consultorias e pessoas que organizam o dia por blocos. Um uso responsável é gerar uma pauta pessoal com horários e nomes de calendário, sem enviar o resultado a serviços adicionais. Outro é filtrar um calendário de projeto e identificar conflitos de horário antes de uma reunião de planejamento.

Ela não é indicada como prova de disponibilidade absoluta. Um calendário pode não estar compartilhado com a conta autenticada, a API pode falhar em uma das consultas e a versão auditada limita o retorno a 50 eventos por calendário no intervalo. Para escala maior, auditoria formal ou cálculo de capacidade, use diretamente a API com paginação, logs de erro e critérios próprios.

Compatibilidade e pré-requisitos

O projeto é mantido na organização oficial googleworkspace no GitHub. O README documenta uma extensão para Gemini CLI e fornece Skills em formato SKILL.md. Outros agentes podem carregar esse formato quando permitem instruções locais e execução do binário gws, mas o diretório de instalação e as permissões variam por cliente. Não trate a presença do arquivo como suporte oficial para qualquer agente.

• O executável gws disponível no PATH.
• Uma conta Google com acesso apenas aos calendários necessários.
• Um projeto do Google Cloud e credenciais OAuth conforme o fluxo oficial.
• A Skill gws-shared, exigida para autenticação, opções globais e regras de segurança.
• Um cliente capaz de carregar as duas pastas de Skill como irmãs.

Instale a ferramenta e as instruções separadamente

A documentação oficial de instalação do gws recomenda os binários publicados em Releases e também apresenta npm, Cargo e Homebrew. O caminho por npm requer Node.js 18 ou superior e usa npm install -g @googleworkspace/cli. Em ambiente corporativo, prefira o método aprovado pela equipe e confira a versão com gws --version.

O ZIP do Bastidores não instala a CLI. Ele preserva gws-calendar-agenda/SKILL.md e o pré-requisito gws-shared/SKILL.md. Extraia as duas pastas no diretório de Skills aceito pelo seu cliente e leia os arquivos antes de permitir terminal ou rede. Se o cliente não documentar Agent Skills, use os Markdown apenas como referência auditável, sem inventar um comando de instalação.

Autenticação com o menor alcance possível

O README oferece gws auth login para o fluxo OAuth interativo. Também documenta gws auth setup, que pode preparar projeto, APIs e login com auxílio do Google Cloud CLI. Essa segunda opção não é apenas leitura: pode configurar recursos no Google Cloud. Confirme a conta, o projeto e as políticas da organização antes de executá-la.

A documentação oficial de autorização do Google Calendar recomenda escolher o escopo mais restrito necessário. Nesta versão, a agenda pede https://www.googleapis.com/auth/calendar.readonly. Esse escopo impede escrita pela API, mas permite ler calendários e eventos acessíveis. Não cole token, arquivo de credenciais ou chave de conta de serviço no prompt, no ZIP ou no repositório.

Primeiro uso sem alterar eventos

Depois de validar gws --version e concluir o OAuth com a conta correta, um primeiro teste explícito para o Brasil é:

gws calendar +agenda --today --timezone America/Sao_Paulo --format table

O resultado esperado é uma tabela com início, fim, título, calendário e local dos eventos encontrados hoje, além do intervalo consultado. Nenhum evento deve ser criado ou modificado. Para reduzir exposição, teste primeiro com um calendário sem dados sensíveis ou aplique --calendar ao nome ou ID de um calendário específico.

Quando a conta tiver calendários em fusos diferentes, informe um identificador IANA, como America/Sao_Paulo. Sem substituição, o helper tenta usar o fuso configurado na conta Google. Evite assumir que o fuso do computador será adotado.

Permissões, privacidade e limites que precisam aparecer

A Skill é Markdown, mas conduz um agente a autenticar e chamar uma API externa. O comando envia um token OAuth ao Google Calendar e pode colocar títulos e locais na saída do terminal. Antes de permitir que outra ferramenta processe essa saída, classifique os dados e remova o que não deveria sair do ambiente autorizado.

O código auditado consulta até 50 eventos por calendário e não pagina além disso no helper de agenda. Ele também trata a falha de uma consulta individual retornando uma lista vazia para aquele calendário, sem apresentar o erro no resultado consolidado. Portanto, uma agenda curta não prova que todos os calendários foram lidos. Se a completude for crítica, compare calendários esperados, valide a conta e use a referência oficial de events.list para implementar paginação e tratamento de erro explícito.

Erros comuns e como isolar a causa

• gws não encontrado: a Skill está presente, mas a CLI não foi instalada ou não está no PATH. Teste gws --version fora do agente.
• OAuth recusado: confirme projeto, tela de consentimento, usuário de teste e escopo. Não amplie permissões apenas para eliminar o erro.
• Agenda vazia: verifique o fuso, o intervalo, a conta autenticada e o calendário filtrado antes de concluir que não há eventos.
• Eventos faltando: confira o limite de 50 por calendário e considere que uma chamada individual pode ter falhado.
• Calendário errado: use o ID quando houver nomes parecidos. O filtro aceita correspondência parcial pelo resumo ou igualdade pelo ID.
• Horário deslocado: informe --timezone America/Sao_Paulo e compare com o fuso configurado na conta.

Versão auditada, licença e download local

A curadoria consultou googleworkspace/cli em 12 de agosto de 2026, quando o repositório registrava 30.338 estrelas. O pacote está fixado no commit 705fb0ecac6f4249679958f6325b809b63fdde17 e na release v0.22.5. O repositório declara licença Apache-2.0, que permite redistribuição com preservação dos avisos aplicáveis.

O ZIP local contém somente as duas Skills Markdown, LICENSE e ORIGEM.md. Não inclui binário, instalador, dependência, token, credencial ou dado de calendário. O SHA-256 do pacote é b4734a31da092512c78a8ce7d2c53bf8c868ddfb7ffef01f25d1e3406225e64e. O botão do repositório oficial permanece separado para acompanhar correções e releases futuras.

Imagem editorial exclusiva do Bastidores da IA. Não é captura de tela, interface real nem prova de acesso a uma agenda.

Referências primárias

• Google Workspace Calendar Agenda no commit auditado
• Pré-requisito oficial gws-shared
• Release oficial v0.22.5
• Licença Apache-2.0 do repositório
• Autorização e escopos do Google Calendar
• Referência oficial de events.list