0Pricing
AI Agents · Aula

Fluxos de trabalho de agentes de áudio + texto

Transcrição → raciocínio → resposta em áudio, de ponta a ponta.

Fluxos de trabalho de agentes de áudio + texto é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

Visão geral do fluxo de agente de áudio e texto

Um fluxo de agente de áudio e texto faz conversões entre os mundos falado e escrito. O fluxo padrão é: entrada de áudio → transcrição pelo Whisper → agente de texto → saída de áudio em TTS. Isso permite criar assistentes de voz, analisar chamadas, resumir reuniões e oferecer interfaces sem uso das mãos.

Formatos de áudio compatíveis

O OpenAI Whisper aceita: mp3, mp4, mpeg, mpga, m4a, wav, webm. O tamanho máximo do arquivo é 25 MB. Para arquivos maiores, é necessário dividir ou comprimir o áudio antes de enviá-lo.

Para obter a melhor qualidade de transcrição e o menor tamanho de arquivo, sempre grave ou converta o áudio para mono a 16 kHz.

import os

SUPPORTED_FORMATS = {'.mp3', '.mp4', '.mpeg', '.mpga', '.m4a', '.wav', '.webm'}
MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024  # 25 MB

def validate_audio_file(path: str) -> dict:
    ext = os.path.splitext(path)[1].lower()
    size = os.path.getsize(path) if os.path.exists(path) else 0
    return {
        'path': path,
        'format_ok': ext in SUPPORTED_FORMATS,
        'size_ok': size <= MAX_FILE_SIZE_BYTES,
        'size_mb': round(size / 1024 / 1024, 2),
        'extension': ext
    }

# Usage:
info = validate_audio_file('meeting.wav')
print(info)

Transcrição de áudio com Whisper

O ponto de acesso audio.transcriptions.create da OpenAI encapsula o Whisper. Passe o objeto de arquivo, o nome do modelo e, opcionalmente, uma indicação de idioma (mais rápido e evita detecções incorretas) e uma instrução inicial (prepara o vocabulário para termos específicos da área).

from openai import OpenAI

client = OpenAI(api_key='YOUR_OPENAI_API_KEY')

def transcribe_audio(
    audio_path: str,
    language: str = 'en',
    prompt: str = ''
) -> str:
    with open(audio_path, 'rb') as audio_file:
        transcript = client.audio.transcriptions.create(
            model='whisper-1',
            file=audio_file,
            language=language,
            prompt=prompt,  # e.g. 'Python, NestJS, TypeScript, API'
            response_format='text'
        )
    return transcript

text = transcribe_audio('user_query.mp3', language='en',
                        prompt='Kubernetes, microservices, Docker')
print('Transcription:', text)

Transcrição com marcações de tempo

Para análise de reuniões ou diarização de oradores, solicite o formato verbose_json. Ele retorna marcações de tempo no nível das palavras ou dos segmentos, permitindo localizar momentos exatos no áudio para referência ou recorte.

def transcribe_with_timestamps(audio_path: str) -> dict:
    from openai import OpenAI
    client = OpenAI(api_key='YOUR_OPENAI_API_KEY')
    with open(audio_path, 'rb') as f:
        result = client.audio.transcriptions.create(
            model='whisper-1',
            file=f,
            response_format='verbose_json',
            timestamp_granularities=['segment']
        )
    # result.segments: list of {start, end, text}
    segments = [
        {'start': s.start, 'end': s.end, 'text': s.text}
        for s in result.segments
    ]
    return {'full_text': result.text, 'segments': segments}

# Example output structure:
# {'full_text': 'Hello team...', 'segments': [{'start': 0.0, 'end': 2.3, 'text': 'Hello team'}]}

Processamento pelo agente de texto

Após a transcrição, o texto passa pelo agente LLM como uma mensagem de texto normal. Inclua uma instrução de sistema que estabeleça o contexto: esse texto veio de uma fala, portanto espere palavras de preenchimento e frases incompletas.

import anthropic

VOICE_AGENT_SYSTEM = (
    'You are a helpful voice assistant. The user\'s message was transcribed from speech '
    'and may contain filler words ("um", "uh"), false starts, or incomplete sentences. '
    'Interpret the intent charitably and respond concisely in 1-3 sentences. '
    'Your response will be converted to speech, so avoid markdown, lists, or code blocks.'
)

def voice_agent_respond(transcription: str) -> str:
    client = anthropic.Anthropic(api_key='YOUR_ANTHROPIC_API_KEY')
    response = client.messages.create(
        model='claude-opus-4-5',
        max_tokens=256,
        system=VOICE_AGENT_SYSTEM,
        messages=[{'role': 'user', 'content': transcription}]
    )
    return response.content[0].text

Síntese de fala com OpenAI TTS

Converta a resposta de texto do agente novamente em fala usando a API TTS da OpenAI. Escolha uma voz (alloy, echo, fable, onyx, nova, shimmer) e um modelo (tts-1 para velocidade, tts-1-hd para qualidade). Salve o resultado como um arquivo mp3 ou transmita-o diretamente.

from openai import OpenAI
from pathlib import Path

client = OpenAI(api_key='YOUR_OPENAI_API_KEY')

def text_to_speech(
    text: str,
    output_path: str = 'response.mp3',
    voice: str = 'nova',
    model: str = 'tts-1'
) -> str:
    response = client.audio.speech.create(
        model=model,
        voice=voice,
        input=text,
        response_format='mp3'
    )
    Path(output_path).write_bytes(response.content)
    print(f'TTS audio saved to {output_path}')
    return output_path

# Full pipeline:
tts_file = text_to_speech(
    'The weather in London is currently 15 degrees and partly cloudy.',
    voice='nova'
)

Transmissão da saída de áudio

Para respostas de voz em tempo real, transmita o áudio TTS em blocos em vez de esperar pelo arquivo completo. O auxiliar stream_to_file da OpenAI ou a iteração manual pelos blocos permite começar a reproduzir o áudio enquanto o restante ainda está sendo gerado.

from openai import OpenAI

client = OpenAI(api_key='YOUR_OPENAI_API_KEY')

def stream_tts_to_file(text: str, output_path: str):
    # OpenAI SDK streams the audio response
    with client.audio.speech.with_streaming_response.create(
        model='tts-1',
        voice='nova',
        input=text,
        response_format='mp3'
    ) as response:
        response.stream_to_file(output_path)
    print(f'Streamed to {output_path}')

def stream_tts_chunks(text: str):
    """Yield raw audio bytes for piping to an audio player."""
    with client.audio.speech.with_streaming_response.create(
        model='tts-1',
        voice='nova',
        input=text
    ) as response:
        for chunk in response.iter_bytes(chunk_size=4096):
            yield chunk  # pipe to audio player or WebSocket

Divisão de arquivos de áudio longos

Arquivos de áudio maiores que 25 MB precisam ser divididos antes de serem enviados ao Whisper. Use a biblioteca pydub para dividi-los por intervalos de tempo e processe cada bloco de forma independente; depois, concatene as transcrições.

from pydub import AudioSegment
import os

def split_audio(
    path: str,
    chunk_minutes: int = 10
) -> list:
    audio = AudioSegment.from_file(path)
    chunk_ms = chunk_minutes * 60 * 1000
    chunks = []
    os.makedirs('audio_chunks', exist_ok=True)
    for i, start in enumerate(range(0, len(audio), chunk_ms)):
        chunk = audio[start:start + chunk_ms]
        chunk_path = f'audio_chunks/chunk_{i:03d}.mp3'
        chunk.export(chunk_path, format='mp3')
        chunks.append(chunk_path)
    return chunks

def transcribe_long_audio(path: str) -> str:
    chunks = split_audio(path, chunk_minutes=10)
    transcripts = []
    for chunk_path in chunks:
        text = transcribe_audio(chunk_path)
        transcripts.append(text)
    # Clean up chunks
    for chunk_path in chunks:
        os.remove(chunk_path)
    return ' '.join(transcripts)

Fluxo de áudio em tempo real

Um fluxo em tempo real captura a entrada do microfone em blocos, envia cada bloco ao Whisper assim que ele chega e transmite a saída TTS de volta, criando um ciclo de conversa por voz quase em tempo real. O principal desafio é gerenciar a latência em cada etapa.

import asyncio
import time

async def realtime_voice_loop(mic_stream, speaker_stream, client):
    """
    mic_stream: async generator yielding audio bytes
    speaker_stream: async callable accepting audio bytes
    """
    buffer = b''
    BUFFER_THRESHOLD = 50 * 1024  # ~3 seconds at 16kHz mono mp3

    async for audio_chunk in mic_stream:
        buffer += audio_chunk

        if len(buffer) >= BUFFER_THRESHOLD:
            t0 = time.time()
            # Save buffer to temp file
            with open('/tmp/voice_chunk.mp3', 'wb') as f:
                f.write(buffer)
            buffer = b''

            # Transcribe
            text = transcribe_audio('/tmp/voice_chunk.mp3')
            print(f'Transcribed ({time.time()-t0:.1f}s): {text}')

            # Agent response
            reply = voice_agent_respond(text)

            # TTS and stream to speaker
            for audio_bytes in stream_tts_chunks(reply):
                await speaker_stream(audio_bytes)

Detecção de idioma e encaminhamento automático

O Whisper detecta automaticamente o idioma falado. Use o idioma detectado para encaminhar a conversa à persona correta do agente ou para definir o idioma TTS da resposta.

def transcribe_and_detect_language(audio_path: str) -> dict:
    from openai import OpenAI
    client = OpenAI(api_key='YOUR_OPENAI_API_KEY')
    with open(audio_path, 'rb') as f:
        result = client.audio.transcriptions.create(
            model='whisper-1',
            file=f,
            response_format='verbose_json'
        )
    return {
        'text': result.text,
        'language': result.language,  # e.g. 'english', 'spanish'
        'duration': result.duration
    }

LANGUAGE_VOICE_MAP = {
    'english': 'nova',
    'spanish': 'alloy',
    'french': 'echo',
    'german': 'fable'
}

def respond_in_detected_language(audio_path: str) -> str:
    info = transcribe_and_detect_language(audio_path)
    voice = LANGUAGE_VOICE_MAP.get(info['language'], 'nova')
    reply = voice_agent_respond(info['text'])
    return text_to_speech(reply, voice=voice)

Como lidar com ruído de fundo e áudio de baixa qualidade

Áudio de baixa qualidade reduz a precisão da transcrição. Medidas práticas: faça um pré-processamento com redução de ruído usando a biblioteca noisereduce, adicione o vocabulário da área à prompt do Whisper, valide a confiança da transcrição e peça esclarecimentos quando a confiança for baixa.

def transcribe_with_quality_check(
    audio_path: str,
    min_confidence_words: int = 3
) -> dict:
    from openai import OpenAI
    import string
    client = OpenAI(api_key='YOUR_OPENAI_API_KEY')
    with open(audio_path, 'rb') as f:
        result = client.audio.transcriptions.create(
            model='whisper-1',
            file=f,
            response_format='verbose_json',
            timestamp_granularities=['word']
        )
    # Word count as a basic quality proxy
    words = result.text.translate(
        str.maketrans('', '', string.punctuation)
    ).split()
    quality_ok = len(words) >= min_confidence_words
    return {
        'text': result.text,
        'word_count': len(words),
        'quality_ok': quality_ok,
        'fallback_message': None if quality_ok else 'I could not hear you clearly. Please repeat.'
    }

Verificação de conhecimento

O que o parâmetro prompt do Whisper faz?

Recapitulação: fluxos de trabalho de agentes de áudio e texto

Excelente! Principais aprendizados:

  • Whisper: aceita mp3/wav/m4a etc., com limite de 25 MB; divida arquivos grandes com pydub
  • Marcações de tempo: use verbose_json com timestamp_granularities para obter a temporização dos segmentos
  • TTS: TTS da OpenAI com opções de voz; transmita blocos para obter baixa latência
  • Detecção de idioma: o Whisper detecta automaticamente; encaminhe para a voz ou o agente correto com base no idioma detectado
  • Fluxo em tempo real: armazene blocos de áudio em buffer → transcreva → agente → transmita TTS

Próximo: compreensão de vídeo em agentes — extração de quadros e raciocínio temporal.

Perguntas Frequentes

A aula “Fluxos de trabalho de agentes de áudio + texto” é grátis?

Sim — o texto completo de “Fluxos de trabalho de agentes de áudio + texto” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Fluxos de trabalho de agentes de áudio + texto”?

Transcrição → raciocínio → resposta em áudio, de ponta a ponta. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Fluxos de trabalho de agentes de áudio + texto”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Agentes de imagem + texto com Claude Vision e GPT-4V
  2. Fluxos de trabalho de agentes de áudio + texto
  3. Compreensão de vídeo em agentes
  4. Padrões de raciocínio entre modalidades
← Voltar para AI Agents