0Pricing
AI Agents · Lezione

Workflow per agenti audio e testo

Pipeline end-to-end di trascrizione → ragionamento → risposta audio.

Workflow per agenti audio e testo è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

Panoramica della pipeline per agenti audio-testo

Una pipeline per agenti audio-testo converte i contenuti tra il mondo parlato e quello scritto. Il flusso canonico è: audio in ingresso → trascrizione Whisper → agente testuale → audio TTS in uscita. Questo consente di creare assistenti vocali, analizzare chiamate, sintetizzare riunioni e realizzare interfacce a mani libere.

Formati audio supportati

OpenAI Whisper accetta: mp3, mp4, mpeg, mpga, m4a, wav, webm. La dimensione massima del file è 25 MB. Per i file più grandi, è necessario suddividere o comprimere l'audio prima di inviarlo.

Registri o converta sempre l'audio in mono a 16 kHz per ottenere la migliore qualità di trascrizione e le dimensioni più ridotte.

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)

Trascrizione dell'audio con Whisper

L'endpoint audio.transcriptions.create di OpenAI funge da wrapper per Whisper. Passi l'oggetto file, il nome del modello e, facoltativamente, un suggerimento sulla lingua (più rapido e utile per evitare rilevamenti errati) e un prompt (che prepara il vocabolario per i termini specifici del dominio).

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)

Trascrizione con timestamp

Per l'analisi di riunioni o la diarizzazione dei parlanti, richieda il formato verbose_json. In questo modo vengono restituiti timestamp a livello di parola o di segmento, che consentono di individuare i momenti esatti dell'audio da citare o ritagliare.

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'}]}

Elaborazione del testo da parte dell'agente

Dopo la trascrizione, il testo passa all'agente LLM come un normale messaggio di testo. Inserisca un prompt di sistema che imposti il contesto: questo testo proviene da un enunciato parlato, quindi preveda parole riempitive e frasi incomplete.

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

Sintesi vocale con OpenAI TTS

Converta la risposta testuale dell'agente in parlato utilizzando l'API TTS di OpenAI. Scelga una voce (alloy, echo, fable, onyx, nova, shimmer) e un modello (tts-1 per la velocità, tts-1-hd per la qualità). Salvi il risultato come file mp3 oppure lo trasmetta direttamente.

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'
)

Streaming dell'output audio

Per risposte vocali in tempo reale, trasmetta l'audio TTS in blocchi invece di attendere il file completo. L'helper stream_to_file di OpenAI o l'iterazione manuale sui blocchi consentono di iniziare a riprodurre l'audio mentre il resto viene ancora generato.

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

Suddivisione dei file audio lunghi

I file audio più grandi di 25 MB devono essere suddivisi prima di essere inviati a Whisper. Utilizzi la libreria pydub per suddividere l'audio in base a intervalli temporali ed elabori ogni blocco indipendentemente, quindi concateni le trascrizioni.

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)

Pipeline audio in tempo reale

Una pipeline in tempo reale acquisisce l'audio del microfono in blocchi, invia ogni blocco a Whisper appena arriva e trasmette l'output TTS in risposta, creando un ciclo di conversazione vocale quasi in tempo reale. La sfida principale consiste nel gestire la latenza in ogni fase.

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)

Rilevamento della lingua e instradamento automatico

Whisper rileva automaticamente la lingua parlata. Utilizzi la lingua rilevata per instradare la conversazione verso la persona corretta dell'agente oppure per impostare la lingua TTS della risposta.

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)

Gestione del rumore di fondo e dell'audio di scarsa qualità

L'audio di scarsa qualità riduce la precisione della trascrizione. Possibili rimedi pratici: pre-elaborare l'audio con la riduzione del rumore (libreria noisereduce), aggiungere il vocabolario del dominio al prompt di Whisper, verificare il livello di confidenza della trascrizione e chiedere chiarimenti quando il livello di confidenza è basso.

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 delle conoscenze

Che cosa fa il parametro prompt di Whisper?

Riepilogo: flussi di lavoro agente audio-testo

Ottimo lavoro! Punti chiave:

  • Whisper: supporta mp3/wav/m4a ecc., con un limite massimo di 25 MB; divida i file grandi con pydub
  • Timestamp: utilizzi verbose_json con timestamp_granularities per la temporizzazione dei segmenti
  • TTS: OpenAI TTS offre diverse voci; trasmetta i blocchi in streaming per ridurre la latenza
  • Rilevamento della lingua: Whisper rileva automaticamente la lingua; instradi verso la voce o l'agente corretti in base alla lingua rilevata
  • Pipeline in tempo reale: buffer dei blocchi audio → trascrizione → agente → streaming TTS

Prossimo argomento: comprensione dei video negli agenti — estrazione dei fotogrammi e ragionamento temporale.

Domande Frequenti

La lezione «Workflow per agenti audio e testo» è gratuita?

Sì — il testo completo di «Workflow per agenti audio e testo» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Workflow per agenti audio e testo»?

Pipeline end-to-end di trascrizione → ragionamento → risposta audio. Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Agents?

Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Workflow per agenti audio e testo»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Agents?

Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Agenti multimodali di immagini e testo con Claude Vision e GPT-4V
  2. Workflow per agenti audio e testo
  3. Comprensione dei video negli agenti
  4. Pattern di ragionamento cross-modale
← Torna a AI Agents