wehub-resource-sync
404 lines
17 KiB
Plaintext
404 lines
17 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "b8c57858",
|
|
"metadata": {},
|
|
"source": [
|
|
"# Agenti Azure AI con supporto per il Model Context Protocol (MCP) - Python\n",
|
|
"\n",
|
|
"Questo notebook dimostra come utilizzare gli agenti Azure AI con gli strumenti del Model Context Protocol (MCP) in Python. Mostra come creare un agente intelligente che può sfruttare server MCP esterni (come Microsoft Learn) per capacità avanzate utilizzando l'autenticazione senza chiavi.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "2e6e4234",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Installare i Pacchetti Python Necessari\n",
|
|
"\n",
|
|
"Per prima cosa, dobbiamo installare i pacchetti Python necessari:\n",
|
|
"- **azure-ai-projects**: SDK principale per Azure AI Projects\n",
|
|
"- **azure-ai-agents**: SDK di Azure AI Agents per creare e gestire agenti\n",
|
|
"- **azure-identity**: Fornisce l'autenticazione senza chiavi utilizzando DefaultAzureCredential\n",
|
|
"- **mcp**: Implementazione del Model Context Protocol per Python\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6a2e9a05",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Vantaggi dell'Autenticazione Senza Chiavi\n",
|
|
"\n",
|
|
"Questo notebook dimostra l'**autenticazione senza chiavi**, che offre diversi vantaggi:\n",
|
|
"- ✅ **Nessuna gestione di chiavi API** - Utilizza l'autenticazione basata sull'identità di Azure\n",
|
|
"- ✅ **Maggiore sicurezza** - Nessun segreto memorizzato nel codice o nei file di configurazione\n",
|
|
"- ✅ **Rotazione automatica delle credenziali** - Azure gestisce il ciclo di vita delle credenziali\n",
|
|
"- ✅ **Controllo degli accessi basato sui ruoli** - Utilizza Azure RBAC per permessi dettagliati\n",
|
|
"- ✅ **Supporto multi-ambiente** - Funziona senza problemi sia in sviluppo che in produzione\n",
|
|
"\n",
|
|
"Il `DefaultAzureCredential` seleziona automaticamente la migliore fonte di credenziali disponibile:\n",
|
|
"1. **Managed Identity** (quando eseguito in Azure)\n",
|
|
"2. Credenziali di **Azure CLI** (durante lo sviluppo locale)\n",
|
|
"3. Credenziali di **Visual Studio**\n",
|
|
"4. **Variabili d'ambiente** (se configurate)\n",
|
|
"5. Autenticazione tramite **browser interattivo** (come ultima risorsa)\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "43efa94d",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Configurazione dell'autenticazione senza chiavi\n",
|
|
"\n",
|
|
"**Prerequisiti per l'autenticazione senza chiavi:**\n",
|
|
"\n",
|
|
"### Per lo sviluppo locale:\n",
|
|
"```bash\n",
|
|
"# Install Azure CLI and login\n",
|
|
"az login\n",
|
|
"# Verify your identity\n",
|
|
"az account show\n",
|
|
"```\n",
|
|
"\n",
|
|
"### Per gli ambienti Azure:\n",
|
|
"- Abilita l'**Identità Gestita Assegnata dal Sistema** sulla tua risorsa Azure\n",
|
|
"- Assegna i ruoli **RBAC** appropriati all'identità gestita:\n",
|
|
" - `Cognitive Services OpenAI User` per l'accesso ad Azure OpenAI\n",
|
|
" - `AI Developer` per l'accesso ai progetti Azure AI\n",
|
|
"\n",
|
|
"### Variabili d'ambiente (Opzionale):\n",
|
|
"```python\n",
|
|
"# These are automatically detected by DefaultAzureCredential\n",
|
|
"# AZURE_CLIENT_ID=<your-client-id>\n",
|
|
"# AZURE_CLIENT_SECRET=<your-client-secret>\n",
|
|
"# AZURE_TENANT_ID=<your-tenant-id>\n",
|
|
"```\n",
|
|
"\n",
|
|
"**Nessuna chiave API o stringa di connessione necessaria!** 🔐\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"id": "2e21387d",
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"! pip install azure-ai-projects -U\n",
|
|
"! pip install azure-ai-agents==1.1.0b4 -U\n",
|
|
"! pip install azure-identity -U\n",
|
|
"! pip install mcp==1.11.0 -U"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "b31c8873",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Importa le Librerie Necessarie\n",
|
|
"\n",
|
|
"Importa i moduli Python necessari:\n",
|
|
"- **os, time**: Librerie standard di Python per variabili d'ambiente e ritardi\n",
|
|
"- **AIProjectClient**: Client principale per i progetti Azure AI\n",
|
|
"- **DefaultAzureCredential**: Autenticazione senza chiavi per i servizi Azure\n",
|
|
"- **Classi relative a MCP**: Per creare e gestire strumenti MCP e gestire approvazioni\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"id": "43667b32",
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"import os, time\n",
|
|
"from azure.ai.projects import AIProjectClient\n",
|
|
"from azure.identity import DefaultAzureCredential\n",
|
|
"from azure.ai.agents.models import McpTool, RequiredMcpToolCall, SubmitToolApprovalAction, ToolApproval\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "721355e5",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Configurare le Impostazioni del Server MCP\n",
|
|
"\n",
|
|
"Configura il server MCP utilizzando variabili di ambiente con valori predefiniti di fallback:\n",
|
|
"- **MCP_SERVER_URL**: L'URL del server MCP (predefinito: Microsoft Learn API)\n",
|
|
"- **MCP_SERVER_LABEL**: Un'etichetta per identificare il server MCP (predefinito: \"mslearn\")\n",
|
|
"\n",
|
|
"Questo approccio consente una configurazione flessibile in diversi ambienti.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"id": "189f3d55",
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"mcp_server_url = os.environ.get(\"MCP_SERVER_URL\", \"https://learn.microsoft.com/api/mcp\")\n",
|
|
"mcp_server_label = os.environ.get(\"MCP_SERVER_LABEL\", \"mslearn\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "20612d9a",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Creare un Client per Progetto Azure AI (Autenticazione Senza Chiave)\n",
|
|
"\n",
|
|
"Inizializza il client per il progetto Azure AI utilizzando **l'autenticazione senza chiave**:\n",
|
|
"- **endpoint**: L'URL dell'endpoint del progetto Azure AI Foundry\n",
|
|
"- **credential**: Utilizza `DefaultAzureCredential()` per un'autenticazione sicura e senza chiave\n",
|
|
"- **Nessuna chiave API richiesta**: Rileva e utilizza automaticamente la credenziale migliore disponibile\n",
|
|
"\n",
|
|
"**Flusso di Autenticazione:**\n",
|
|
"1. Verifica l'identità gestita (in ambienti Azure)\n",
|
|
"2. Passa alle credenziali di Azure CLI (per lo sviluppo locale)\n",
|
|
"3. Utilizza altre fonti di credenziali disponibili, se necessario\n",
|
|
"\n",
|
|
"Questo approccio elimina la necessità di gestire chiavi API o stringhe di connessione nel codice.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"id": "36b1dbd8",
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"project_client = AIProjectClient(\n",
|
|
" endpoint=\"Your Azure AI Foundry Endpoint\",\n",
|
|
" credential=DefaultAzureCredential(),\n",
|
|
")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "cdb6ab8c",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Creare la Definizione dello Strumento MCP\n",
|
|
"\n",
|
|
"Crea uno strumento MCP che si connette al server MCP di Microsoft Learn:\n",
|
|
"- **server_label**: Identificatore per il server MCP\n",
|
|
"- **server_url**: Endpoint URL del server MCP\n",
|
|
"- **allowed_tools**: Elenco opzionale per limitare quali strumenti possono essere utilizzati (un elenco vuoto consente tutti gli strumenti)\n",
|
|
"\n",
|
|
"Questo strumento permetterà all'agente di accedere alla documentazione e alle risorse di Microsoft Learn.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"id": "51e7e136",
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"mcp_tool = McpTool(\n",
|
|
" server_label=mcp_server_label,\n",
|
|
" server_url=mcp_server_url,\n",
|
|
" allowed_tools=[], # Optional: specify allowed tools\n",
|
|
")\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6e894b0b",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Creare un Agente e Eseguire una Conversazione (Flusso Senza Chiavi)\n",
|
|
"\n",
|
|
"Questa sezione completa illustra il flusso di lavoro **senza chiavi** per un agente:\n",
|
|
"\n",
|
|
"1. **Creare un Agente AI**: Configura un agente con il modello GPT-4.1 nano e strumenti MCP\n",
|
|
"2. **Creare un Thread**: Stabilisci un thread di conversazione per la comunicazione\n",
|
|
"3. **Inviare un Messaggio**: Chiedi all'agente le differenze tra Azure OpenAI e OpenAI\n",
|
|
"4. **Gestire le Approvazioni degli Strumenti**: Approva automaticamente le chiamate agli strumenti MCP quando necessario\n",
|
|
"5. **Monitorare l'Esecuzione**: Tieni traccia dei progressi dell'agente e gestisci eventuali azioni richieste\n",
|
|
"6. **Mostrare i Risultati**: Visualizza i dettagli della conversazione e dell'utilizzo degli strumenti\n",
|
|
"\n",
|
|
"**Caratteristiche Senza Chiavi:**\n",
|
|
"- ✅ **Nessun segreto hardcoded** - Tutta l'autenticazione gestita tramite identità Azure\n",
|
|
"- ✅ **Sicuro per impostazione predefinita** - Utilizza il controllo degli accessi basato sui ruoli\n",
|
|
"- ✅ **Distribuzione semplificata** - Non è richiesta la gestione delle credenziali\n",
|
|
"- ✅ **Audit-friendly** - Tutti gli accessi sono tracciati tramite identità Azure\n",
|
|
"\n",
|
|
"L'agente utilizzerà gli strumenti MCP per accedere alle risorse di Microsoft Learn con piena sicurezza e senza gestione di chiavi API.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"id": "68c49af5",
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"with project_client:\n",
|
|
" agents_client = project_client.agents\n",
|
|
"\n",
|
|
" # Create a new agent with keyless authentication\n",
|
|
" # NOTE: To reuse existing agent, fetch it with get_agent(agent_id)\n",
|
|
" agent = agents_client.create_agent(\n",
|
|
" model=\"Your Azure OpenAI Model Deployment Name\",\n",
|
|
" name=\"my-mcp-agent\",\n",
|
|
" instructions=\"You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.\",\n",
|
|
" tools=mcp_tool.definitions,\n",
|
|
" )\n",
|
|
" print(f\"Created agent, ID: {agent.id}\")\n",
|
|
" print(f\"MCP Server: {mcp_tool.server_label} at {mcp_tool.server_url}\")\n",
|
|
"\n",
|
|
" # Create thread for communication\n",
|
|
" thread = agents_client.threads.create()\n",
|
|
" print(f\"Created thread, ID: {thread.id}\")\n",
|
|
"\n",
|
|
" # Create message to thread\n",
|
|
" message = agents_client.messages.create(\n",
|
|
" thread_id=thread.id,\n",
|
|
" role=\"user\",\n",
|
|
" content=\"What's difference between Azure OpenAI and OpenAI?\",\n",
|
|
" )\n",
|
|
" print(f\"Created message, ID: {message.id}\")\n",
|
|
"\n",
|
|
" # KEYLESS APPROACH: Handle tool approvals without hardcoded secrets\n",
|
|
" \n",
|
|
" # Option 1: Completely keyless (recommended for Azure identity-enabled MCP servers)\n",
|
|
" # run = agents_client.runs.create(thread_id=thread.id, agent_id=agent.id, tool_resources=mcp_tool.resources)\n",
|
|
" \n",
|
|
" # Option 2: With minimal headers (if MCP server requires specific headers)\n",
|
|
" # For demonstration purposes, using a placeholder header\n",
|
|
" mcp_tool.update_headers(\"SuperSecret\", \"123456\") # Replace with actual auth if needed\n",
|
|
" \n",
|
|
" # Set approval mode - uncomment next line to disable approval requirement completely\n",
|
|
" # mcp_tool.set_approval_mode(\"never\") # Fully automated, no approval needed\n",
|
|
" \n",
|
|
" run = agents_client.runs.create(thread_id=thread.id, agent_id=agent.id, tool_resources=mcp_tool.resources)\n",
|
|
" print(f\"Created run, ID: {run.id}\")\n",
|
|
"\n",
|
|
" while run.status in [\"queued\", \"in_progress\", \"requires_action\"]:\n",
|
|
" time.sleep(1)\n",
|
|
" run = agents_client.runs.get(thread_id=thread.id, run_id=run.id)\n",
|
|
"\n",
|
|
" if run.status == \"requires_action\" and isinstance(run.required_action, SubmitToolApprovalAction):\n",
|
|
" tool_calls = run.required_action.submit_tool_approval.tool_calls\n",
|
|
" if not tool_calls:\n",
|
|
" print(\"No tool calls provided - cancelling run\")\n",
|
|
" agents_client.runs.cancel(thread_id=thread.id, run_id=run.id)\n",
|
|
" break\n",
|
|
"\n",
|
|
" tool_approvals = []\n",
|
|
" for tool_call in tool_calls:\n",
|
|
" if isinstance(tool_call, RequiredMcpToolCall):\n",
|
|
" try:\n",
|
|
" print(f\"Approving tool call: {tool_call}\")\n",
|
|
" \n",
|
|
" # KEYLESS APPROVAL OPTIONS:\n",
|
|
" \n",
|
|
" # Option 1: No headers (fully keyless)\n",
|
|
" # tool_approvals.append(\n",
|
|
" # ToolApproval(\n",
|
|
" # tool_call_id=tool_call.id,\n",
|
|
" # approve=True,\n",
|
|
" # headers={} # No headers needed for keyless\n",
|
|
" # )\n",
|
|
" # )\n",
|
|
" \n",
|
|
" # Option 2: With headers (if MCP server requires them)\n",
|
|
" tool_approvals.append(\n",
|
|
" ToolApproval(\n",
|
|
" tool_call_id=tool_call.id,\n",
|
|
" approve=True,\n",
|
|
" headers=mcp_tool.headers, # Uses configured headers if needed\n",
|
|
" )\n",
|
|
" )\n",
|
|
" except Exception as e:\n",
|
|
" print(f\"Error approving tool_call {tool_call.id}: {e}\")\n",
|
|
"\n",
|
|
" print(f\"tool_approvals: {tool_approvals}\")\n",
|
|
" if tool_approvals:\n",
|
|
" agents_client.runs.submit_tool_outputs(\n",
|
|
" thread_id=thread.id, run_id=run.id, tool_approvals=tool_approvals\n",
|
|
" )\n",
|
|
"\n",
|
|
" print(f\"Current run status: {run.status}\")\n",
|
|
"\n",
|
|
" print(f\"Run completed with status: {run.status}\")\n",
|
|
" if run.status == \"failed\":\n",
|
|
" print(f\"Run failed: {run.last_error}\")\n",
|
|
"\n",
|
|
" # Display run steps and tool calls\n",
|
|
" run_steps = agents_client.run_steps.list(thread_id=thread.id, run_id=run.id)\n",
|
|
"\n",
|
|
" # Loop through each step\n",
|
|
" for step in run_steps:\n",
|
|
" print(f\"Step {step['id']} status: {step['status']}\")\n",
|
|
"\n",
|
|
" # Check if there are tool calls in the step details\n",
|
|
" step_details = step.get(\"step_details\", {})\n",
|
|
" tool_calls = step_details.get(\"tool_calls\", [])\n",
|
|
"\n",
|
|
" if tool_calls:\n",
|
|
" print(\" MCP Tool calls:\")\n",
|
|
" for call in tool_calls:\n",
|
|
" print(f\" Tool Call ID: {call.get('id')}\")\n",
|
|
" print(f\" Type: {call.get('type')}\")\n",
|
|
"\n",
|
|
" print() # add an extra newline between steps\n",
|
|
"\n",
|
|
" # Fetch and log all messages\n",
|
|
" messages = agents_client.messages.list(thread_id=thread.id)\n",
|
|
" print(\"\\nConversation:\")\n",
|
|
" print(\"-\" * 50)\n",
|
|
" for msg in messages:\n",
|
|
" if msg.text_messages:\n",
|
|
" last_text = msg.text_messages[-1]\n",
|
|
" print(f\"{msg.role.upper()}: {last_text.text.value}\")\n",
|
|
" print(\"-\" * 50)\n",
|
|
"\n",
|
|
" # Example of dynamic tool management (keyless)\n",
|
|
" print(f\"\\nDemonstrating keyless dynamic tool management:\")\n",
|
|
" print(f\"Current allowed tools: {mcp_tool.allowed_tools}\")\n",
|
|
" print(\"✅ All operations completed using keyless authentication!\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"\n---\n\n**Disclaimer**: \nQuesto documento è stato tradotto utilizzando il servizio di traduzione automatica [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire l'accuratezza, si prega di notare che le traduzioni automatiche possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa dovrebbe essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un traduttore umano. Non siamo responsabili per eventuali incomprensioni o interpretazioni errate derivanti dall'uso di questa traduzione.\n"
|
|
]
|
|
}
|
|
],
|
|
"metadata": {
|
|
"kernelspec": {
|
|
"display_name": "demo",
|
|
"language": "python",
|
|
"name": "python3"
|
|
},
|
|
"language_info": {
|
|
"codemirror_mode": {
|
|
"name": "ipython",
|
|
"version": 3
|
|
},
|
|
"file_extension": ".py",
|
|
"mimetype": "text/x-python",
|
|
"name": "python",
|
|
"nbconvert_exporter": "python",
|
|
"pygments_lexer": "ipython3",
|
|
"version": "3.10.15"
|
|
},
|
|
"coopTranslator": {
|
|
"original_hash": "39a035fea0d10767dfcb0662bd3528fa",
|
|
"translation_date": "2025-08-26T21:30:48+00:00",
|
|
"source_file": "05-AdvancedTopics/mcp-foundry-agent-integration/mcp_support_python.ipynb",
|
|
"language_code": "it"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 5
|
|
} |