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_keyusa):~/.agentcall/config.jsonexiste com umaapi_key? → pronto.- A variável de ambiente
AGENTCALL_API_KEYestá definida? → pronto. - 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.pptlegado 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_narrationcom todas asnotesvazias (e umdecks/<name>/source.json). Crie uma linha denotesfalada por slide (leiasource.json+ dê uma olhada nas imagens dos slides) antes de apresentar —present.pyse recusa a executar uma apresentação convertida não criada, então não há atalho. Criar a narração É apresentar.
- Se o arquivo tiver notas do apresentador em todos os slides (apenas
- Um
.docx/.doc, um PDF do tipo relatório, ou um tópico → crie uma apresentação: executedoc_to_deck.py --mode generate, leiadecks/<name>/source.json(seu texto + figuras extraídas) e escrevadecks/<name>/deck.json. NÃO tente abrir ou renderizar o arquivo você mesmo (sempdftoppm, 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 odeck.jsoncriado emdecks/<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ãodecks/<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):
- Nunca envie um documento bruto diretamente para
present.pye vá embora. Converta → verifiqueneeds_narration→ crienotes→ apresente. A saída com recusa (código 2) é seu sinal para criar, não um erro a ser ignorado. - Nunca sobrescreva um
deck.jsoncriado reconvertendo. Fonte inalterada → é reutilizado automaticamente; só exclua a pasta da apresentação se o usuário quiser explicitamente uma conversão nova. - 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.
- 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
notesmais curtas; a duração do slide é baseada no tamanho, então notes mais curtas = uma fala mais rápida. "vá fundo" →notesmais ricas. - "diga ‹X› no slide de preços", "comece com uma piada", "enfatize ‹Y›" → coloque essa linha na
notesdaquele slide específico para que seja falada exatamente onde pretendido. - "pule o slide do roadmap" → descarte/funda-o ao criar.
- "seja breve / ~5 min / uma linha por slide" → escreva
- 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.
- "não responda perguntas sobre ‹Z› / preços / número de funcionários" → quando tal pergunta chegar por
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)
| Modo | O que faz | Padrão para |
|---|---|---|
| show | Renderiza as páginas/slides REAIS do documento como imagens e os mostra inalterados | .pptx/.ppt e PDFs em formato de slide |
| generate | Analisa 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 denotesfalada para cada slide que não tem uma (dedecks/<name>/source.json+ as imagens dos slides), depois apresente odeck.jsoncriado. 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.
- 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 - Crie
deck.jsona partir desource.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
titlecurto, ≤6bulletscurtos enotes= 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.jsonlista imagens extraídas do documento (emsections[].imageseall_images). Coloque a relevante no campoimagede 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).
- Visualize e apresente (seções C e D). Para um tópico sem arquivo, pule a conversão e apenas crie
decks/<name>.jsondiretamente.
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:
-
Inicie (interativo é o padrão para ao vivo):
python scripts/present.py "<url>" --deck <arquivo> &Ele imprime dois caminhos:link/heard.jsonl(bot → você) elink/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(
&/tailsão POSIX — no Windows use seu recurso de execução em segundo plano eGet-Content link/heard.jsonl -Wait.) present.py executa o que você acrescentar acommands.jsonlem ~0.3s. -
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 emcommands.jsonldentro 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.jsonlserã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 usarpauseeresumepara pausar a apresentação enquanto formula uma resposta complexa.Limiar:
heard.jsonlrecebe 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. -
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 doneEste é 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
notesnodeck.jsonprimeiro. 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.jsonle respondendo comnextoupresent. - 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
--localpara testes sem reunião.