Connetti e usa il server MCP linguistico con un agente

Dopo aver compreso le funzionalità del server MCP del linguaggio di Azure, il passaggio successivo consiste nel connetterlo a un agente e iniziare a usarlo. Ciò comporta la creazione di un agente in Microsoft Foundry, la connessione dello strumento MCP language, il test nel playground dell'agente e, facoltativamente, la creazione di un'applicazione client per interagire con l'agente a livello di codice.

Creare un progetto e un agente Foundry

Per usare il server MCP del linguaggio di Azure, è necessario innanzitutto 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 assists users by helping them analyze and summarize text.
   

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

Connettere il server MCP del linguaggio di Azure

È possibile connettere il server MCP del linguaggio di Azure 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 Language in Strumenti Fonderia dal catalogo.

3. Configurare la connessione con le impostazioni seguenti:

   • Nome della risorsa Foundry: nome della risorsa Foundry , ad esempio myproject-resource.
   • Autenticazione: basata su chiave.
   • Credenziale (Ocp-Apim-Subscription-Key): la chiave per il progetto Fonderia.

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

L'agente ha ora accesso a tutti gli strumenti di analisi del testo esposti dal server MCP di Linguaggio di Azure.

Aggiornare le istruzioni dell'agente

Dopo aver connesso lo strumento McP del linguaggio, aggiornare le istruzioni dell'agente per indirizzarlo all'uso dello strumento:

You are an AI agent that assists users by helping them analyze and summarize text. Use the Azure Language tool to perform text analysis tasks.

Questa istruzione consente all'agente di comprendere che deve usare lo strumento connesso durante l'elaborazione delle richieste di analisi del testo.

Testare nel playground dell'agente

Il playground dell'agente nel portale foundry fornisce un ambiente interattivo per testare l'agente prima di distribuirlo in un'applicazione.

Quando si invia un prompt che richiede l'analisi del testo, l'agente:

1. Identifica le attività necessarie, ad esempio il riepilogo e il riconoscimento delle entità.
2. Chiama gli strumenti MCP del linguaggio di Azure appropriati.
3. Restituisce una risposta combinata.

La prima volta che l'agente usa uno strumento MCP, viene richiesto di approvare l'utilizzo dello strumento. È possibile approvare lo strumento per un singolo uso oppure selezionare Approva sempre tutto il linguaggio di Azure negli strumenti foundry per ignorare le richieste di approvazione future.

Dopo la risposta dell'agente, è possibile esaminare il riquadro Log per verificare quali strumenti sono stati usati. I log mostrano ogni chiamata allo strumento MCP, l'input inviato e il risultato restituito.

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": "Text-Analysis-Agent",
            "type": "agent_reference"
        }
    },
)

print(response.output_text)

L'agente elabora il prompt, chiama gli strumenti MCP appropriati e restituisce il risultato in output_text. È anche possibile esaminare il codice JSON di risposta completo (usando response.model_dump_json()) per visualizzare gli strumenti chiamati dall'agente, ad esempio o extract_named_entities_from_text , detect_sentiment_from_text insieme agli argomenti e ai risultati per ogni chiamata allo strumento.

Connettere il server MCP nel codice

Anziché connettere il server MCP del linguaggio di Azure tramite il portale foundry, è anche possibile definire la connessione dello strumento MCP direttamente nel codice quando si crea un agente. Usare la MCPTool classe dell'SDK azure-ai-projects per specificare l'etichetta del server, l'URL e gli strumenti consentiti:

from azure.ai.projects.models import MCPTool

mcp_tool = MCPTool(
    server_label="azure-language",
    server_url="https://{foundry-resource-name}.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview",
    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. È anche possibile usare la allowed_tools proprietà su MCPTool per limitare gli strumenti specifici del linguaggio che l'agente può chiamare.

Selezione degli strumenti con richieste di più attività

Quando la richiesta di un utente prevede più attività di analisi del testo, l'agente può chiamare più strumenti in un unico turno. Ad esempio, il prompt:

"Dimmi quali entità e date sono menzionate in questa recensione e se è positivo o negativo".

Questa richiesta richiede sia il riconoscimento delle entità che l'analisi del sentiment. L'agente identifica entrambe le attività, chiama gli strumenti appropriati (extract_named_entities_from_text e detect_sentiment_from_text) e combina i risultati in una singola risposta.

Ogni chiamata allo strumento passa attraverso il server MCP in modo indipendente e l'agente sintetizza gli output in una risposta coerente per l'utente.