Agente F.R.I.D.A.Y. do Pipecat

Visão Geral

Esta habilidade fornece um modelo para construir F.R.I.D.A.Y. (Replacement Integrated Digital Assistant Youth - Jovem Assistente Digital Integrado de Substituição), um assistente de voz local inspirado na IA tática dos filmes do Homem de Ferro. Ele usa o framework Pipecat para orquestrar um pipeline de baixa latência:

• STT: OpenAI Whisper (whisper-1) ou gpt-4o-transcribe
• LLM: Google Gemini 2.5 Flash (via um "shim" de compatibilidade)
• TTS: OpenAI TTS (voz nova)
• Transporte: Áudio Local (Microfone/Alto-falantes de Hardware)

Quando Usar Esta Habilidade

• Use quando quiser construir um agente de voz conversacional em tempo real.
• Use ao trabalhar com o framework Pipecat para IA baseada em pipeline.
• Use quando precisar integrar múltiplos provedores (Google e OpenAI) em um único loop de voz.
• Use ao construir aplicações de voz com tema Homem de Ferro ou tático.

Como Funciona

Passo 1: Instalar Dependências

Você precisará do framework Pipecat e seus provedores de serviço instalados:

pip install pipecat-ai[openai,google,silero] python-dotenv

Passo 2: Configurar Ambiente

Crie um arquivo .env com suas chaves de API:

OPENAI_API_KEY=your_openai_key
GOOGLE_API_KEY=your_google_key

Passo 3: Executar o Agente

Execute o script Python fornecido para iniciar a interface:

python scripts/friday_agent.py

Conceitos Principais

Arquitetura de Pipeline

O agente segue um pipeline linear: Mic -> VAD -> STT -> LLM -> TTS -> Speaker. Isso permite um controle granular sobre cada estágio, ao contrário de modelos de fala-para-fala de ponta a ponta.

Shim de Compatibilidade Google

Como a API Gemini do Google tem um formato de mensagem diferente do padrão da OpenAI (que os agregadores do Pipecat esperam), o script inclui uma classe GoogleSafeContext e GoogleSafeMessage para preencher essa lacuna.

Melhores Práticas

• ✅ Use Silero VAD: É robusto para hardware local e impede que ruídos de fundo ativem o LLM.
• ✅ Prompts Concisos: Agentes táticos devem fornecer respostas curtas e densas em dados para minimizar a latência.
• ✅ Taxa de Amostragem Correspondente: O OpenAI TTS gera áudio em 24kHz; certifique-se de que seu audio_out_sample_rate corresponda para evitar áudio agudo ou lento.
• ❌ Sem Preenchimentos Polidos: Evite "Olá, como posso ajudar hoje?". Em vez disso, use "Sistemas nominais. Pronto para comandos."

Solução de Problemas

• Problema: O áudio está picotado ou atrasado.
  • Solução: Verifique seu índice de OUTPUT_DEVICE. Execute um script como test_audio_output.py para encontrar o índice de hardware correto para o seu sistema operacional.
• Problema: "Erro de validação" para o formato da mensagem.
  • Solução: Certifique-se de que o shim GoogleSafeContext está traduzindo corretamente dicionários no estilo OpenAI para o esquema no estilo Gemini.

Habilidades Relacionadas

• @voice-agents - Princípios gerais de IA de voz.
• @agent-tool-builder - Adicione ferramentas (Pesquisa, Luzes, etc.) ao seu agente Friday.
• @llm-architect - Otimizando a camada LLM.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se as entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.