Communitygithub.com

Apresentador — apresentar um documento (ou tópico) em uma reuni…

Uma coleção de casos de uso reais construídos com agentcall.dev — cada pasta é um exemplo funcional e autocontido. Por Pattern AI Labs.

O que é Apresentador — apresentar um documento (ou tópico) em uma reuni…?

Esta skill transforma um agente de IA em um apresentador de reuniões completo. O agente pode ingressar em reuniões do Google Meet (e outras plataformas), compartilhar uma apresentação de slides na tela principal e narrá-la com sua própria voz, avançando os slides automaticamente. O fluxo principal é: o usuário fornece um link de reunião e um documento (PDF, PowerPoint, Word) ou mesmo apenas um tópico, e o agente cuida de todo o processo — desde a conversão do documento em uma apresentação de slides, passando pela autoria da narração, até a apresentação ao vivo. A skill suporta dois modos principais: 'show' (para slides existentes, mantendo o design original) e 'generate' (para documentos de texto, onde o agente cria uma apresentação baseada no conteúdo). É uma ferramenta poderosa para automatizar apresentações, permitindo que o usuário configure e monitore tudo via arquivos JSON, com controle por voz e uma página de controle remoto. O agente gerencia a saída da reunião automaticamente, garantindo que não haja custos indevidos.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add pattern-ai-labs/built-with-agentcall

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Apresentador — apresentar um documento (ou um tópico) em uma reunião

Um bot de IA entra em uma reunião e apresenta: por padrão, a apresentação ocupa a tela principal da reunião como compartilhamento de tela, narrada pela voz do bot e avançando automaticamente, com o rosto do bot em um pequeno tile de câmera. (Passe --avatar-mode — ou se o usuário disser "entre no modo avatar" — para, em vez disso, mostrar a apresentação no tile da câmera, o visual original de um único tile.) Sem clicker em nenhum dos casos.

Modos de exibição: compartilhamento de tela é o padrão (slides legíveis em tela cheia + rosto do apresentador); modo avatar (--avatar-mode) coloca a apresentação apenas no tile da câmera. Todo o resto — controle de voz, controle remoto, narração, perguntas e respostas — funciona de forma idêntica em ambos.

O caso de uso principal: o usuário fornece um link de reunião e um documento — PDF, PowerPoint ou Word — e o bot o apresenta. Você também pode começar apenas com um tópico.

Faça isso em ordem (o fluxo completo — sempre o mesmo, sem atalhos)

0 · Pré-voo (uma vez).

  • Chave de API — verifique nesta ordem, e NÃO pergunte se já estiver lá (uma única configuração, o MESMO arquivo que o AgentCall usa; esta é a ordem exata que load_api_key usa):
    1. ~/.agentcall/config.json existe com uma api_key? → pronto.
    2. A variável de ambiente AGENTCALL_API_KEY está definida? → pronto.
    3. Nenhuma das opções? → pergunte ao usuário sua chave (gratuita em agentcall.dev/api-keys) e escreva-a em ~/.agentcall/config.json (veja Configuração) — criando esse arquivo exatamente como o AgentCall faria — e continue.
  • Dependências — pip install -r requirements.txt (rápido; wheels Python puros, sem ferramentas de sistema).

1 · Transforme a entrada em uma apresentação. Você (o agente) sempre é o dono da narração — nunca deixe o bot ler o slide da tela. Execute doc_to_deck.py primeiro, depois veja o que foi produzido:

  • Um .pptx/.ppt, ou um PDF em formato de slide → mostre os slides reais, mas a narração é sua:
    • Se o arquivo tiver notas do apresentador em todos os slides (apenas .pptx — notas de .ppt legado não podem ser lidas; peça um .pptx), elas se tornam a narração — você terminou, é só apresentar. Notas em APENAS ALGUNS slides → a apresentação é sinalizada; crie as notas faltantes.
    • Se não tiver notas, a apresentação volta sinalizada como needs_narration com todas as notes vazias (e um decks/<name>/source.json). Crie uma linha de notes falada por slide (leia source.json + dê uma olhada nas imagens dos slides) antes de apresentar — present.py se recusa a executar uma apresentação convertida não criada, então não há atalho. Criar a narração É apresentar.
  • Um .docx/.doc, um PDF do tipo relatório, ou um tópico → crie uma apresentação: execute doc_to_deck.py --mode generate, leia decks/<name>/source.json (seu texto + figuras extraídas) e escreva decks/<name>/deck.json. NÃO tente abrir ou renderizar o arquivo você mesmo (sem pdftoppm, sem ferramentas de imagem) — source.json é sua entrada. Mantenha a criação concisa: uma ideia por slide, marcadores curtos, narração natural — não exagere no polimento.
  • O trabalho criado é protegido — mas apenas na pasta PADRÃO da apresentação. Executar novamente a conversão (ou present.py --deck <mesmo documento>) com uma fonte inalterada reutiliza o deck.json criado em decks/<name>/ — instantâneo, nada é re-renderizado, sua narração sobrevive. Só re-converte quando o documento em si mudou (então recrie — a sinalização volta). NÃO passe --out <uma pasta diferente> para um documento que você criará e apresentará — uma pasta nova não tem apresentação para reutilizar, então você recebe um rascunho com notas vazias (e a apresentação criada real fica obsoleta). --out é apenas para conversões descartáveis/de inspeção. Crie, apresente e reapresente tudo a partir do padrão decks/<name>/deck.json.
  • Detalhes completos + esquema da apresentação: seções A e B abaixo.

Regras rígidas (cada uma já queimou uma sessão real — o código reforça a maioria, não tente driblar):

  1. Nunca envie um documento bruto diretamente para present.py e vá embora. Converta → verifique needs_narration → crie notes → apresente. A saída com recusa (código 2) é seu sinal para criar, não um erro a ser ignorado.
  2. Nunca sobrescreva um deck.json criado reconvertendo. Fonte inalterada → é reutilizado automaticamente; só exclua a pasta da apresentação se o usuário quiser explicitamente uma conversão nova.
  3. Nunca invente uma apresentação placeholder ou peça desculpas na câmera. Se a conversão falhar, present.py encerra — corrija a entrada (ou instale o LibreOffice) e reinicie. Um bot que nunca entra é melhor do que um que parece quebrado.
  4. Nunca deixe uma chamada em execução. present.py para de cobrar em cada caminho de saída sozinho — mas se VOCÊ o iniciou, confirme se o processo realmente terminou quando a apresentação acabar.

1b · Honre as instruções do usuário — as instruções deles moldam a apresentação E como você a conduz. Quando o usuário disser algo além de "apresente isto", capture e aplique. Isso cai em um de dois lugares:

  • Momento da criação (incorporar em deck.json) — qualquer coisa sobre conteúdo ou entrega:
    • "seja breve / ~5 min / uma linha por slide" → escreva notes mais curtas; a duração do slide é baseada no tamanho, então notes mais curtas = uma fala mais rápida. "vá fundo" → notes mais ricas.
    • "diga ‹X› no slide de preços", "comece com uma piada", "enfatize ‹Y›" → coloque essa linha na notes daquele slide específico para que seja falada exatamente onde pretendido.
    • "pule o slide do roadmap" → descarte/funda-o ao criar.
  • Política de condução ao vivo (você impõe enquanto executa) — qualquer coisa sobre reagir na sala:
    • "não responda perguntas sobre ‹Z› / preços / número de funcionários" → quando tal pergunta chegar por heard.jsonl, NÃO responda: responda com um breve desvio ({"cmd":"say","text":"Boa pergunta — vamos tratar disso depois."}) em vez de uma resposta real. "adie todas as perguntas para o final" → acuse e continue apresentando em vez de responder no meio da apresentação.
    • "pause no slide 3 para discussão", "avance apenas quando eu disser" → ajuste a frequência com que você envia next/present. Mantenha uma breve nota mental dessas regras durante toda a sessão — elas persistem ao longo da chamada, não apenas no primeiro slide. Se um pedido for ambíguo, pergunte ao usuário antes de iniciar.

2 · (opcional) Visualização — present.py --local --deck <deck> imprime uma URL localhost para assistir antes de ir ao ar.

3 · Inicie ao vivo, em segundo plano — python scripts/present.py "<url>" --deck <deck> & (nome/voz vêm de ~/.agentcall/config.json; --name/--voice substituem por execução). O bot leva de 30 a 90 segundos para aparecer, depois cumprimenta e espera.

4 · Conduza — comece a monitorar imediatamente. Acompanhe link/heard.jsonl e responda em link/commands.jsonl (protocolo completo sob Controle de voz). Ele não iniciará até que você responda present a um "pode começar".

5 · Finalize — ele sai automaticamente e para de cobrar quando todos saem, no limite de tempo ou em um comando leave. Se você o iniciou, certifique-se de que o processo termine.

Dois modos (esta é a ideia chave)

ModoO que fazPadrão para
showRenderiza as páginas/slides REAIS do documento como imagens e os mostra inalterados.pptx/.ppt e PDFs em formato de slide
generateAnalisa o documento, então VOCÊ cria uma apresentação significativa (títulos, marcadores, narração falada) e puxa as figuras da fonte.docx/.doc, PDFs densos/relatórios e tópicos

Regra prática: um arquivo que já é uma apresentação de slides → mostre-o. Um documento (prosa) → gere uma apresentação a partir dele. auto (o padrão) decide pelo tipo de arquivo e, para PDFs, pela forma da página (paisagem + texto esparso = uma apresentação → mostrar; retrato + denso = um documento → gerar). Substitua com --mode show|generate. A intenção do usuário sempre vence ("apresente meus slides exatamente" → mostrar; "resuma isso em uma apresentação" → gerar).

A) Mostrar uma apresentação como está (PowerPoint ou PDF estilo slide)

O modo show mantém o design real de cada slide (uma imagem em sangria total do slide real). O que diz depende se o arquivo carrega notas do apresentador:

python scripts/doc_to_deck.py "/caminho/para/apresentacao.pptx"      # renderizar slides + detectar notas
  • Tem notas do apresentador em todos os slides (.pptx) → elas são a narração. Apenas apresente:
    python scripts/present.py "<URL_DA_REUNIAO>" --deck decks/apresentacao/deck.json
    
  • Sem notas — ou notas em APENAS ALGUNS slides → a apresentação é sinalizada needs_narration (os slides sem notas seriam exibidos em silêncio absoluto). Crie uma linha de notes falada para cada slide que não tem uma (de decks/<name>/source.json + as imagens dos slides), depois apresente o deck.json criado. Isso é o que o torna um apresentador e não um leitor de tela.

present.py RECUSA-SE a apresentar uma apresentação needs_narration até que todos os slides tenham notes (ele sai com um erro apontando para source.json). Não há nenhum fallback de "ler o texto do slide em voz alta" — por design. Portanto, nunca entregue um arquivo bruto sem notas para present.py esperando que ele fale: converta, crie as notes, depois apresente o deck.json criado. A recusa é a rede de segurança; criar a narração é o trabalho.

B) Gerar uma apresentação significativa (Word, PDF denso ou um tópico)

Um documento não são slides — mostrar suas páginas resulta em uma fala ruim. Então você constrói a apresentação.

  1. Converta para obter o conteúdo fonte + figuras:
    python scripts/doc_to_deck.py "/caminho/para/arquivo.docx" --mode generate
    # escreve decks/<name>/deck.json — um rascunho mecânico com notes VAZIAS, sinalizado needs_narration;
    #   present.py RECUSA até que você crie as notes (esse é o próximo passo, não opcional)
    #    e decks/<name>/source.json  ← as seções analisadas + imagens extraídas, para você criar a partir
    #    e decks/<name>/img/         ← as próprias figuras do documento, já extraídas
    
  2. Crie deck.json a partir de source.json — esta é a parte importante. Faça bem:
    • Esboce primeiro, depois preencha. Faça um slide por ideia principal. Construa uma lista mental das seções/títulos do documento e certifique-se de que cada ponto-chave apareça em um slide — não deixe coisas de fora.
    • Cada slide: um title curto, ≤6 bullets curtos e notes = narração falada natural (1–4 frases; siglas escritas foneticamente como "A.P.I." para que TTS as pronuncie corretamente).
    • Reutilize as figuras da fonte. source.json lista imagens extraídas do documento (em sections[].images e all_images). Coloque a relevante no campo image de um slide — o slide então mostra seus marcadores ao lado dessa figura real (um layout dividido). Não invente imagens.
    • Abra com um slide de introdução de uma linha; feche com um resumo (o bot sai após o último slide).
  3. Visualize e apresente (seções C e D). Para um tópico sem arquivo, pule a conversão e apenas crie decks/<name>.json diretamente.

Esquema JSON da apresentação (slide de texto, slide de imagem ou ambos juntos):

{
  "title": "Minha Palestra",
  "slides": [
    { "title": "Introdução", "notes": "Introdução falada." },
    { "title": "Um ponto", "bullets": ["frase curta", "outra"], "notes": "Narração." },
    { "title": "Com uma figura", "bullets": ["o que mostra"], "image": "fig1.png", "notes": "Narração." },
    { "image": "slide3.png", "notes": "Um slide real em sangria total (modo show)." }
  ]
}

(bullets/notes/image todos opcionais; aliases points→bullets, say→notes; um slide apenas com título é uma capa.)

C) Visualização (recomendado)

python scripts/present.py --local --deck decks/<nome>/deck.json     # ou decks/<nome>.json, ou um arquivo bruto

Imprime uma URL http://localhost:PORTA/?ws=local — abra-a para assistir os slides renderizarem e avançarem automaticamente, sem reunião.

D) Apresentar ao vivo

python scripts/present.py "<URL_DA_REUNIAO>" --deck <arquivo-ou-apresentacao> [--mode show|generate]

Reuniões ao vivo são interativas por padrão (baseadas em consentimento): o bot entra, se apresenta e espera até que alguém diga para começar. Duas maneiras de controlá-lo:

  • Por voz → roteado para VOCÊ (o cérebro). Não há correspondência de palavras-chave no código. O que quer que um participante diga — uma vez que se dirige ao bot pelo nome, ou durante uma janela curta de acompanhamento — é entregue a você para interpretar, e você responde com um comando. Protocolo abaixo.
  • Pela página de controle remoto (direta). Uma página de celular/navegador (Anterior / Pausar / Próximo / tocar-um-slide / Reiniciar / Dispensar) cujo link o bot coloca no chat da reunião, e TAMBÉM imprime no console (▸ Página de controle: …) — repasse a URL do console diretamente ao usuário; a entrega no chat do Meet pode ser não confiável. Os botões são inequívocos e agem no processo, instantaneamente (não passam por você), então são o fallback confiável e a maneira de conduzir sem agente anexado.

O bot sai automaticamente e para de cobrar quando todos os outros saem, em um limite rígido ou em uma saída limpa — um bot órfão não pode acumular custos. Adicione --auto para apresentar imediatamente sem perguntar; --pace <s> define o intervalo entre os slides.

Controle de voz — VOCÊ é o cérebro (a parte importante)

No modo interativo, o bot encaminha o que ouve para um link de arquivo e executa o comando que você escreve de volta. Sem frases fixas: você entende a solicitação e decide a ação. Execute-o em segundo plano e faça um loop:

  1. Inicie (interativo é o padrão para ao vivo): python scripts/present.py "<url>" --deck <arquivo> & Ele imprime dois caminhos: link/heard.jsonl (bot → você) e link/commands.jsonl (você → bot). Comece a monitorar imediatamente — a saudação toca sozinha, mas a apresentação não iniciará até que você responda ao primeiro "pode começar". Leia apenas linhas NOVAS (controle um deslocamento de byte/linha, ou bloqueie no arquivo — não reprocesse linhas antigas) e responda dentro de ~45s (após isso a apresentação continua sozinha). A maneira eficiente, semelhante a evento, de monitorar, sem polling ocupado:

    tail -n +1 -f link/heard.jsonl     # transmite cada nova fala como uma linha; manipule-a, depois acrescente sua resposta a link/commands.jsonl
    

    (&/tail são POSIX — no Windows use seu recurso de execução em segundo plano e Get-Content link/heard.jsonl -Wait.) present.py executa o que você acrescentar a commands.jsonl em ~0.3s.

  2. Quando o bot for chamado pelo nome ("Apresentador, …") — ou durante o período de acompanhamento após uma resposta — cada fala do participante aparece como uma linha JSON em heard.jsonl. Você a lê, interpreta e escreve uma linha de comando em commands.jsonl dentro do prazo de ~45s. O formato é simples:

    {"cmd": "next"}            // avança para o próximo slide
    {"cmd": "prev"}            // volta um slide
    {"cmd": "goto", "slide": 3}  // vai para o slide 3 (baseado em 0)
    {"cmd": "say", "text": "Isso é importante porque…"}  // fala um texto arbitrário
    {"cmd": "pause"}           // pausa a apresentação
    {"cmd": "resume"}          // retoma a apresentação
    {"cmd": "present"}         // Inicia/finaliza a espera — comece com este comando após a saudação
    {"cmd": "leave"}           // Sai da reunião e interrompe a cobrança (a sala continua, mas o bot sai)
    {"cmd": "finish"}          // Encerra o processo do bot (não use a menos que queira matar o processo)
    

    Nenhum outro comando tem efeito. Se você escrever JSON inválido ou um cmd desconhecido, o bot o ignora.

    "Pode começar" da sala: quando a reunião está pronta, as primeiras linhas em heard.jsonl serão algo como "Pode começar" dito por um participante ou um sinal do sistema. Quando você vir isso, responda com {"cmd": "present"} para iniciar a apresentação real. Antes disso, o bot apenas espera — não precisa se apressar.

    Janela de acompanhamento: por ~5 segundos após o bot terminar de falar (ou após você enviar um comando que faz o bot falar), quaisquer falas de participantes adicionais são enviadas para você — você pode responder com follow-ups rápidos (como {"cmd": "say", "text": "Deixe-me elaborar…"}) ou, se eles disserem algo que pareça um pedido para um slide diferente, mude para ele. Após a janela, o bot avança para o próximo slide (se programado) ou espera até ser chamado novamente pelo nome. Seja rápido nas respostas de acompanhamento ou o bot avançará — dependendo do seu ciclo de resposta, você pode querer usar pause e resume para pausar a apresentação enquanto formula uma resposta complexa.

    Limiar: heard.jsonl recebe apenas falas que o sistema de voz do Google Meet considera como dirigidas ao bot (por nome ou durante a janela de acompanhamento). Sussurros paralelos ou tosse não vão aparecer.

  3. Ciclo de resposta:

    while true; do
      # lê a linha mais recente de heard.jsonl (use seu próprio acompanhamento de estado)
      line=$(tail -1 link/heard.jsonl)
      case "$line" in
        *"pode começar"*|*"iniciar"*)
          echo '{"cmd":"present"}' >> link/commands.jsonl ;;
        *"próximo"*|*"avançar"*)
          echo '{"cmd":"next"}' >> link/commands.jsonl ;;
        *"anterior"*|*"voltar"*)
          echo '{"cmd":"prev"}' >> link/commands.jsonl ;;
        *"saia"*|*"finalizar"*)
          echo '{"cmd":"leave"}' >> link/commands.jsonl
          break ;;
        *)
          # resposta padrão: acuse e continue
          echo '{"cmd":"say","text":"Entendi. Continuando."}' >> link/commands.jsonl ;;
      esac
      sleep 0.5
    done
    

    Este é um exemplo simplificado — seu loop real deve lidar com concorrência, múltiplas falas e uma lógica mais rica.

Configuração

  • Chave de API: obtida em agentcall.dev/api-keys. Armazenada em ~/.agentcall/config.json:
    {"api_key": "ag_..."}
    
  • Dependências Python: pip install -r requirements.txt (apenas Python puro, sem binários de sistema).
  • LibreOffice (opcional, para conversão de formatos legados): necessário apenas para .ppt (PowerPoint 97-2003) e arquivos .doc. Se não estiver instalado, a conversão falhará com uma mensagem clara; instale-o com seu gerenciador de pacotes.

Arquitetura

scripts/
  doc_to_deck.py    # Converte documentos em deck.json + source.json + imagens
  present.py        # Ingressa em reunião, compartilha tela, narra, gerencia comandos
  
link/
  heard.jsonl       # Bot → Você: falas dos participantes
  commands.jsonl     # Você → Bot: comandos de controle

decks/
  <nome>/
    deck.json       # A apresentação a ser apresentada (títulos, marcadores, notes, imagens)
    source.json     # Conteúdo fonte analisado a partir do documento
    img/            # Figuras extraídas do documento

Resolução de Problemas

  • O bot não aparece na reunião: verifique a chave de API e a conectividade de rede. Pode levar até 90 segundos.
  • present.py falha com "nenhuma nota": você precisa criar as notes no deck.json primeiro. Consulte a seção A/B.
  • A narração soa estranha: Verifique se siglas estão escritas foneticamente ("A.P.I." em vez de "API").
  • A apresentação não avança: Verifique se você está monitorando heard.jsonl e respondendo com next ou present.
  • O bot não responde a comandos de voz: Certifique-se de que está se dirigindo a ele pelo nome. A janela de acompanhamento é curta (~5s).

Considerações sobre Custo

  • O bot fatura por minuto de reunião. Sai automaticamente quando não há participantes ou ao final do tempo limite.
  • Chaves de API gratuitas estão disponíveis com um limite de minutos; use --local para testes sem reunião.

Habilidades Relacionadas