wehub-resource-sync
404 lines
17 KiB
Plaintext
404 lines
17 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "b8c57858",
|
|
"metadata": {},
|
|
"source": [
|
|
"# Azure AI Agents s podporou Model Context Protocol (MCP) - Python\n",
|
|
"\n",
|
|
"Tento notebook ukazuje, jak používat Azure AI Agents s nástroji Model Context Protocol (MCP) v Pythonu. Demonstruje, jak vytvořit inteligentního agenta, který může využívat externí MCP servery (například Microsoft Learn) pro rozšířené schopnosti pomocí autentizace bez klíče.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "2e6e4234",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Instalace potřebných balíčků Pythonu\n",
|
|
"\n",
|
|
"Nejprve je nutné nainstalovat potřebné balíčky Pythonu:\n",
|
|
"- **azure-ai-projects**: Základní SDK pro Azure AI Projects\n",
|
|
"- **azure-ai-agents**: SDK pro Azure AI Agents pro vytváření a správu agentů\n",
|
|
"- **azure-identity**: Poskytuje bezklíčovou autentizaci pomocí DefaultAzureCredential\n",
|
|
"- **mcp**: Implementace Model Context Protocol pro Python\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6a2e9a05",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Výhody autentizace bez klíčů\n",
|
|
"\n",
|
|
"Tento notebook demonstruje **autentizaci bez klíčů**, která přináší několik výhod:\n",
|
|
"- ✅ **Žádné API klíče k spravování** - Využívá autentizaci založenou na identitě Azure\n",
|
|
"- ✅ **Zvýšená bezpečnost** - Žádná tajemství uložená v kódu nebo konfiguračních souborech\n",
|
|
"- ✅ **Automatická rotace přihlašovacích údajů** - Azure se stará o správu životního cyklu přihlašovacích údajů\n",
|
|
"- ✅ **Řízení přístupu na základě rolí** - Používá Azure RBAC pro detailní nastavení oprávnění\n",
|
|
"- ✅ **Podpora více prostředí** - Funguje bez problémů jak v prostředí vývoje, tak v produkci\n",
|
|
"\n",
|
|
"`DefaultAzureCredential` automaticky vybírá nejlepší dostupný zdroj přihlašovacích údajů:\n",
|
|
"1. **Spravovaná identita** (při běhu v Azure)\n",
|
|
"2. Přihlašovací údaje z **Azure CLI** (během lokálního vývoje)\n",
|
|
"3. Přihlašovací údaje z **Visual Studio**\n",
|
|
"4. **Proměnné prostředí** (pokud jsou nastaveny)\n",
|
|
"5. Autentizace přes **interaktivní prohlížeč** (jako záložní možnost)\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "43efa94d",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Nastavení autentizace bez klíčů\n",
|
|
"\n",
|
|
"**Předpoklady pro autentizaci bez klíčů:**\n",
|
|
"\n",
|
|
"### Pro lokální vývoj:\n",
|
|
"```bash\n",
|
|
"# Install Azure CLI and login\n",
|
|
"az login\n",
|
|
"# Verify your identity\n",
|
|
"az account show\n",
|
|
"```\n",
|
|
"\n",
|
|
"### Pro prostředí Azure:\n",
|
|
"- Aktivujte **System-assigned Managed Identity** na vašem Azure zdroji\n",
|
|
"- Přiřaďte odpovídající **RBAC role** k této identitě:\n",
|
|
" - `Cognitive Services OpenAI User` pro přístup k Azure OpenAI\n",
|
|
" - `AI Developer` pro přístup k projektům Azure AI\n",
|
|
"\n",
|
|
"### Proměnné prostředí (volitelné):\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",
|
|
"**Žádné API klíče ani připojovací řetězce nejsou potřeba!** 🔐\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": [
|
|
"## Importujte potřebné knihovny\n",
|
|
"\n",
|
|
"Importujte nezbytné Python moduly:\n",
|
|
"- **os, time**: Standardní Python knihovny pro proměnné prostředí a zpoždění\n",
|
|
"- **AIProjectClient**: Hlavní klient pro Azure AI Projects\n",
|
|
"- **DefaultAzureCredential**: Bezklíčová autentizace pro Azure služby\n",
|
|
"- **Třídy související s MCP**: Pro vytváření a správu MCP nástrojů a zpracování schválení\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": [
|
|
"## Nastavení konfigurace MCP serveru\n",
|
|
"\n",
|
|
"Nastavte konfiguraci MCP serveru pomocí proměnných prostředí s výchozími hodnotami:\n",
|
|
"- **MCP_SERVER_URL**: URL adresa MCP serveru (výchozí je Microsoft Learn API)\n",
|
|
"- **MCP_SERVER_LABEL**: Označení pro identifikaci MCP serveru (výchozí je \"mslearn\")\n",
|
|
"\n",
|
|
"Tento přístup umožňuje flexibilní konfiguraci napříč různými prostředími.\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": [
|
|
"## Vytvoření klienta Azure AI Project (Autentizace bez klíče)\n",
|
|
"\n",
|
|
"Inicializujte klienta Azure AI Project pomocí **autentizace bez klíče**:\n",
|
|
"- **endpoint**: URL koncového bodu projektu Azure AI Foundry\n",
|
|
"- **credential**: Používá `DefaultAzureCredential()` pro bezpečnou autentizaci bez klíče\n",
|
|
"- **Žádné API klíče nejsou potřeba**: Automaticky vyhledá a použije nejlepší dostupné přihlašovací údaje\n",
|
|
"\n",
|
|
"**Proces autentizace:**\n",
|
|
"1. Kontroluje Managed Identity (v prostředí Azure)\n",
|
|
"2. Přechází na přihlašovací údaje Azure CLI (pro lokální vývoj)\n",
|
|
"3. Používá další dostupné zdroje přihlašovacích údajů podle potřeby\n",
|
|
"\n",
|
|
"Tento přístup eliminuje potřebu spravovat API klíče nebo připojovací řetězce ve vašem kódu.\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": [
|
|
"## Vytvoření definice nástroje MCP\n",
|
|
"\n",
|
|
"Vytvořte nástroj MCP, který se připojuje k serveru Microsoft Learn MCP:\n",
|
|
"- **server_label**: Identifikátor pro server MCP\n",
|
|
"- **server_url**: URL endpoint serveru MCP\n",
|
|
"- **allowed_tools**: Volitelný seznam pro omezení, které nástroje mohou být použity (prázdný seznam umožňuje všechny nástroje)\n",
|
|
"\n",
|
|
"Tento nástroj umožní agentovi přístup k dokumentaci a zdrojům 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": [
|
|
"## Vytvoření agenta a vedení konverzace (bez klíčů)\n",
|
|
"\n",
|
|
"Tato komplexní sekce ukazuje kompletní **workflow agenta bez klíčů**:\n",
|
|
"\n",
|
|
"1. **Vytvoření AI agenta**: Nastavte agenta s modelem GPT-4.1 nano a nástroji MCP\n",
|
|
"2. **Vytvoření vlákna**: Založte konverzační vlákno pro komunikaci\n",
|
|
"3. **Odeslání zprávy**: Zeptejte se agenta na rozdíly mezi Azure OpenAI a OpenAI\n",
|
|
"4. **Schvalování nástrojů**: Automaticky schvalujte volání nástrojů MCP, pokud je to potřeba\n",
|
|
"5. **Sledování průběhu**: Sledujte pokrok agenta a řešte případné požadované akce\n",
|
|
"6. **Zobrazení výsledků**: Zobrazte detaily konverzace a použití nástrojů\n",
|
|
"\n",
|
|
"**Funkce bez klíčů:**\n",
|
|
"- ✅ **Žádná pevně zakódovaná tajemství** - Veškeré ověřování je zajištěno identitou Azure\n",
|
|
"- ✅ **Bezpečné jako standard** - Používá řízení přístupu na základě rolí\n",
|
|
"- ✅ **Zjednodušené nasazení** - Není nutná správa přihlašovacích údajů\n",
|
|
"- ✅ **Přátelské k auditu** - Veškerý přístup je sledován prostřednictvím identity Azure\n",
|
|
"\n",
|
|
"Agent bude používat nástroje MCP k přístupu k Microsoft Learn zdrojům s plnou bezpečností a bez správy API klíčů.\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**Prohlášení**: \nTento dokument byl přeložen pomocí služby pro automatický překlad [Co-op Translator](https://github.com/Azure/co-op-translator). Ačkoli se snažíme o přesnost, mějte prosím na paměti, že automatické překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho původním jazyce by měl být považován za autoritativní zdroj. Pro důležité informace doporučujeme profesionální lidský překlad. Neodpovídáme za žádná nedorozumění nebo nesprávné interpretace vyplývající z použití tohoto překladu.\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:39:58+00:00",
|
|
"source_file": "05-AdvancedTopics/mcp-foundry-agent-integration/mcp_support_python.ipynb",
|
|
"language_code": "cs"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 5
|
|
} |