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 demonštruje, ako používať Azure AI Agents s nástrojmi Model Context Protocol (MCP) v Pythone. Ukazuje, ako vytvoriť inteligentného agenta, ktorý dokáže využívať externé MCP servery (ako Microsoft Learn) na rozšírené funkcie pomocou autentifikácie bez kľúča.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "2e6e4234",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Inštalácia potrebných balíkov Pythonu\n",
|
|
"\n",
|
|
"Najskôr musíme nainštalovať potrebné balíky Pythonu:\n",
|
|
"- **azure-ai-projects**: Základné SDK pre Azure AI Projects\n",
|
|
"- **azure-ai-agents**: SDK pre Azure AI Agents na vytváranie a správu agentov\n",
|
|
"- **azure-identity**: Poskytuje bezkľúčovú autentifikáciu pomocou DefaultAzureCredential\n",
|
|
"- **mcp**: Implementácia Model Context Protocol pre Python\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6a2e9a05",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Výhody autentifikácie bez kľúčov\n",
|
|
"\n",
|
|
"Tento notebook demonštruje **autentifikáciu bez kľúčov**, ktorá prináša niekoľko výhod:\n",
|
|
"- ✅ **Žiadne API kľúče na správu** - Používa autentifikáciu založenú na identite Azure\n",
|
|
"- ✅ **Zvýšená bezpečnosť** - Žiadne tajné údaje uložené v kóde alebo konfiguračných súboroch\n",
|
|
"- ✅ **Automatická rotácia poverení** - Azure sa stará o správu životného cyklu poverení\n",
|
|
"- ✅ **Riadenie prístupu na základe rolí** - Používa Azure RBAC na detailné nastavenie oprávnení\n",
|
|
"- ✅ **Podpora viacerých prostredí** - Funguje bez problémov v prostredí vývoja aj produkcie\n",
|
|
"\n",
|
|
"`DefaultAzureCredential` automaticky vyberá najlepší dostupný zdroj poverení:\n",
|
|
"1. **Spravovaná identita** (pri spustení v Azure)\n",
|
|
"2. **Poverenia Azure CLI** (počas lokálneho vývoja)\n",
|
|
"3. **Poverenia Visual Studio**\n",
|
|
"4. **Premenné prostredia** (ak sú nakonfigurované)\n",
|
|
"5. **Autentifikácia cez interaktívny prehliadač** (ako záložné riešenie)\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "43efa94d",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Nastavenie autentifikácie bez kľúčov\n",
|
|
"\n",
|
|
"**Predpoklady pre autentifikáciu bez kľúčov:**\n",
|
|
"\n",
|
|
"### Pre lokálny vývoj:\n",
|
|
"```bash\n",
|
|
"# Install Azure CLI and login\n",
|
|
"az login\n",
|
|
"# Verify your identity\n",
|
|
"az account show\n",
|
|
"```\n",
|
|
"\n",
|
|
"### Pre prostredia Azure:\n",
|
|
"- Aktivujte **Systémom priradenú spravovanú identitu** na vašom Azure zdroji\n",
|
|
"- Priraďte vhodné **RBAC roly** spravovanej identite:\n",
|
|
" - `Cognitive Services OpenAI User` pre prístup k Azure OpenAI\n",
|
|
" - `AI Developer` pre prístup k projektom Azure AI\n",
|
|
"\n",
|
|
"### Premenné prostredia (voliteľné):\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",
|
|
"**Nie sú potrebné žiadne API kľúče ani reťazce pripojenia!** 🔐\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 potrebné knižnice\n",
|
|
"\n",
|
|
"Importujte potrebné Python moduly:\n",
|
|
"- **os, time**: Štandardné Python knižnice pre premenné prostredia a oneskorenia\n",
|
|
"- **AIProjectClient**: Hlavný klient pre Azure AI Projects\n",
|
|
"- **DefaultAzureCredential**: Bezklúčová autentifikácia pre služby Azure\n",
|
|
"- **MCP-related classes**: Na vytváranie a správu MCP nástrojov a spracovanie 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": [
|
|
"## Konfigurácia nastavení MCP servera\n",
|
|
"\n",
|
|
"Nastavte konfiguráciu MCP servera pomocou environmentálnych premenných s predvolenými hodnotami:\n",
|
|
"- **MCP_SERVER_URL**: URL adresa MCP servera (predvolene Microsoft Learn API)\n",
|
|
"- **MCP_SERVER_LABEL**: Označenie na identifikáciu MCP servera (predvolene \"mslearn\")\n",
|
|
"\n",
|
|
"Tento prístup umožňuje flexibilnú konfiguráciu v rôznych prostrediach.\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": [
|
|
"## Vytvorenie klienta projektu Azure AI (Autentifikácia bez kľúča)\n",
|
|
"\n",
|
|
"Inicializujte klienta projektu Azure AI pomocou **autentifikácie bez kľúča**:\n",
|
|
"- **endpoint**: URL koncového bodu projektu Azure AI Foundry\n",
|
|
"- **credential**: Používa `DefaultAzureCredential()` na bezpečnú autentifikáciu bez kľúča\n",
|
|
"- **Nie sú potrebné API kľúče**: Automaticky vyhľadáva a používa najlepšie dostupné poverenia\n",
|
|
"\n",
|
|
"**Proces autentifikácie:**\n",
|
|
"1. Kontroluje Managed Identity (v prostrediach Azure)\n",
|
|
"2. Ako záložné riešenie používa poverenia Azure CLI (pre lokálny vývoj)\n",
|
|
"3. V prípade potreby využíva ďalšie dostupné zdroje poverení\n",
|
|
"\n",
|
|
"Tento prístup eliminuje potrebu spravovať API kľúče alebo reťazce pripojenia vo vašom kóde.\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": [
|
|
"## Vytvorenie definície nástroja MCP\n",
|
|
"\n",
|
|
"Vytvorte nástroj MCP, ktorý sa pripája k serveru Microsoft Learn MCP:\n",
|
|
"- **server_label**: Identifikátor pre server MCP\n",
|
|
"- **server_url**: URL koncový bod servera MCP\n",
|
|
"- **allowed_tools**: Voliteľný zoznam na obmedzenie, ktoré nástroje môžu byť použité (prázdny zoznam umožňuje všetky nástroje)\n",
|
|
"\n",
|
|
"Tento nástroj umožní agentovi prístup k dokumentácii a zdrojom 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": [
|
|
"## Vytvorenie agenta a vykonanie konverzácie (Práca bez kľúčov)\n",
|
|
"\n",
|
|
"Táto komplexná sekcia demonštruje kompletný **pracovný postup agenta bez kľúčov**:\n",
|
|
"\n",
|
|
"1. **Vytvorenie AI agenta**: Nastavte agenta s modelom GPT-4.1 nano a nástrojmi MCP\n",
|
|
"2. **Vytvorenie vlákna**: Založte konverzačné vlákno pre komunikáciu\n",
|
|
"3. **Odoslanie správy**: Opýtajte sa agenta na rozdiely medzi Azure OpenAI a OpenAI\n",
|
|
"4. **Schvaľovanie nástrojov**: Automaticky schvaľujte volania nástrojov MCP, keď je to potrebné\n",
|
|
"5. **Monitorovanie vykonávania**: Sledujte pokrok agenta a riešte potrebné akcie\n",
|
|
"6. **Zobrazenie výsledkov**: Zobrazte detaily konverzácie a použitia nástrojov\n",
|
|
"\n",
|
|
"**Funkcie bez kľúčov:**\n",
|
|
"- ✅ **Žiadne pevne zakódované tajomstvá** - Všetka autentifikácia je spravovaná identitou Azure\n",
|
|
"- ✅ **Bezpečné ako štandard** - Používa kontrolu prístupu na základe rolí\n",
|
|
"- ✅ **Zjednodušené nasadenie** - Nie je potrebná správa poverení\n",
|
|
"- ✅ **Vhodné na audit** - Všetky prístupy sú sledované prostredníctvom identity Azure\n",
|
|
"\n",
|
|
"Agent bude používať nástroje MCP na prístup k zdrojom Microsoft Learn s plnou bezpečnosťou a bez správy API kľúčov.\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**Upozornenie**: \nTento dokument bol preložený pomocou služby AI prekladu [Co-op Translator](https://github.com/Azure/co-op-translator). Aj keď sa snažíme o presnosť, prosím, berte na vedomie, že automatizované preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho pôvodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za akékoľvek nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu.\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:40:31+00:00",
|
|
"source_file": "05-AdvancedTopics/mcp-foundry-agent-integration/mcp_support_python.ipynb",
|
|
"language_code": "sk"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 5
|
|
} |