Collegarsi e utilizzare il server Speech MCP con un agente

  • 8 minuti

Dopo aver compreso le funzionalità del server MCP di Riconoscimento vocale di Azure, il passaggio successivo consiste nel connetterlo a un agente e iniziare a usarlo. Ciò comporta la configurazione dell'archiviazione, la creazione di un agente in Microsoft Foundry, la connessione dello strumento Speech MCP, il test nel playground dell'agente e, facoltativamente, la creazione di un'applicazione client.

Configurare l'archiviazione blob di Azure

Il server MCP di Riconoscimento vocale di Azure richiede un account di archiviazione di Azure per archiviare i file audio. È necessario creare un account di archiviazione e un contenitore BLOB prima di connettere lo strumento.

  1. Nel portale di Azure creare un nuovo account di archiviazione di Azure (o usarne uno esistente).
  2. Nell'account di archiviazione espandere Archiviazione dati e selezionare Contenitori.
  3. Creare un nuovo contenitore (ad esempio, file denominati) per archiviare i file audio generati e letti dall'agente.
  4. Generare un token SAS per il contenitore con i seguenti permessi: Lettura, Aggiunta, Creazione, Scrittura ed Elenco. Impostare l'ora di scadenza sulla durata pratica più breve.

Importante

Copiare l'URL SAS generato e archiviarlo in modo sicuro, che sarà necessario quando ci si connette al server MCP di sintesi vocale.

Creare un progetto e un agente Foundry

Per usare il server MCP di Riconoscimento vocale di Azure, è necessario un progetto Microsoft Foundry con un modello distribuito.

  1. Nel portale di Microsoft Foundry creare un nuovo progetto (o usarne uno esistente).

  2. Distribuire un modello ,ad esempio gpt-4.1, che verrà usato dall'agente per il ragionamento e la generazione di risposte.

  3. Creare un agente e fornire istruzioni che ne descrivono lo scopo. Per esempio:

    You are an AI agent that uses the Azure AI Speech tool to transcribe and generate speech.

L'agente è ora pronto per ricevere le connessioni degli strumenti.

Connettere il server MCP voce di Azure

Il server MCP di Riconoscimento vocale di Azure viene connesso all'agente tramite la pagina Strumenti nel portale foundry.

  1. Nel riquadro di spostamento selezionare la pagina Strumenti .

  2. Selezionare Connetti uno strumento e scegliere Azure Speech in Foundry Tools dal catalogo.

  3. Configurare la connessione con le impostazioni seguenti:

    • Nome della risorsa Foundry: nome della risorsa Foundry , ad esempio myproject-resource.
    • Bearer (Ocp-Apim-Subscription-Key): chiave per il progetto Foundry.
    • X-Blob-Container-Url: URL della firma di accesso condiviso per il contenitore BLOB.

  4. Attendere la creazione della connessione, quindi selezionare Usa in un agente e scegliere l'agente.

Screenshot del catalogo degli Strumenti nel portale Fonderia che mostra la configurazione della connessione di Voce di Azure in Strumenti Fonderia.

L'agente ha ora accesso agli strumenti di speech-to-text e text-to-speech esposti dal server Azure Speech MCP.

Suggerimento

È possibile trovare la chiave del progetto nella home page del progetto nel portale foundry.

Testare nel playground dell'agente

L'area di test dell'agente nel portale Foundry fornisce un ambiente interattivo per il test dell'agente.

Testare la sintesi vocale

Inserire un prompt che chiede all'agente di generare un discorso

Generate "To be or not to be, that is the question." as speech

La prima volta che l'agente usa lo strumento Speech MCP, viene richiesto di approvare l'utilizzo dello strumento. È possibile selezionare Approva sempre tutti gli strumenti del server MCP di Riconoscimento vocale di Azure per ignorare le richieste di approvazione future.

La risposta include un collegamento al file audio generato salvato nel contenitore BLOB. Selezionare il collegamento per ascoltare il parlato sintetizzato.

Testare il riconoscimento vocale

Immettere un prompt che chiede all'agente di trascrivere un file audio. È possibile usare un URL accessibile o un URL SAS che punta a un file nel contenitore BLOB pubblicamente:

Transcribe the file at https://example.com/audio/meeting-recording.wav

L'agente chiama lo strumento riconoscimento vocale e restituisce il testo trascritto.

Personalizzazione dell'output vocale

Gli strumenti mcp voce supportano diverse opzioni che è possibile specificare nei prompt:

  • Selezione vocale: specificare una voce neurale, ad esempio en-GB-SoniaNeural o en-US-JennyNeural.
  • Lingua: specificare la lingua per il riconoscimento o la sintesi (ad esempio, es-ES per lo spagnolo).
  • Hint di frase: fornire termini specifici del dominio per migliorare l'accuratezza della trascrizione(ad esempio, "Azure, OpenAI, Servizi cognitivi").
  • Filtro di volgarità: richiedere masked, removed o raw gestione del linguaggio volgare durante la trascrizione.

Per esempio:

Synthesize "Better a witty fool, than a foolish wit!" as speech using the voice "en-GB-SoniaNeural".

Creare un'applicazione client

Anche se il playground dell'agente è utile per i test, in genere si vuole creare un'applicazione client che usa l'agente a livello di codice. Microsoft Foundry SDK supporta questa funzionalità tramite l'API Risposte OpenAI.

Per compilare un'applicazione client, usare i azure-ai-projects pacchetti e azure-identity . Il modello generale è:

  1. Creare un oggetto AIProjectClient usando l'endpoint del progetto Fonderia e DefaultAzureCredential (che usa le credenziali dell'interfaccia della riga di comando di Azure in fase di sviluppo).
  2. Ottenere un client OpenAI dal client del progetto chiamando get_openai_client().
  3. Chiamare responses.create() per inviare una richiesta dell'utente all'agente.

La parte chiave è il modo in cui si fa riferimento all'agente, specificandolo in base al nome nel extra_body parametro :

response = openai_client.responses.create(
    input=[{"role": "user", "content": user_prompt}],
    extra_body={
        "agent_reference": {
            "name": "Speech-Agent",
            "type": "agent_reference"
        }
    },
)

print(response.output_text)

L'agente elabora il prompt, chiama lo strumento di elaborazione vocale MCP appropriato e restituisce il risultato in output_text. Per le richieste di sintesi vocale, l'output include un collegamento al file audio generato nel contenitore Blob.

Connettere il server MCP nel codice

Invece di connettere il server MCP di Riconoscimento vocale di Azure tramite il portale foundry, è possibile definire la connessione allo strumento MCP direttamente nel codice quando si crea un agente. Usare la MCPTool classe dell'SDK azure-ai-projects :

from azure.ai.projects.models import MCPTool

mcp_tool = MCPTool(
    server_label="azure-speech",
    server_url="https://{foundry-resource-name}.cognitiveservices.azure.com/speech/mcp",
    require_approval="always",
)

Si passa quindi il mcp_tool quando si crea l'agente tramite l'SDK. Questo approccio è utile quando si vogliono gestire le connessioni degli strumenti come parte del codice dell'applicazione anziché configurarle manualmente nel portale.