wehub-resource-sync
404 lines
17 KiB
Plaintext
404 lines
17 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "b8c57858",
|
|
"metadata": {},
|
|
"source": [
|
|
"# Azure AI Agenti s podporo za Model Context Protocol (MCP) - Python\n",
|
|
"\n",
|
|
"Ta zvezek prikazuje, kako uporabljati Azure AI agente z orodji Model Context Protocol (MCP) v Pythonu. Prikazuje, kako ustvariti inteligentnega agenta, ki lahko izkorišča zunanje MCP strežnike (kot je Microsoft Learn) za izboljšane zmogljivosti z uporabo avtentikacije brez ključev.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "2e6e4234",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Namestitev potrebnih Python paketov\n",
|
|
"\n",
|
|
"Najprej moramo namestiti potrebne Python pakete:\n",
|
|
"- **azure-ai-projects**: Osnovni SDK za Azure AI Projects\n",
|
|
"- **azure-ai-agents**: Azure AI Agents SDK za ustvarjanje in upravljanje agentov\n",
|
|
"- **azure-identity**: Omogoča avtentikacijo brez ključev z uporabo DefaultAzureCredential\n",
|
|
"- **mcp**: Implementacija protokola Model Context Protocol za Python\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6a2e9a05",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Prednosti avtentikacije brez ključev\n",
|
|
"\n",
|
|
"Ta zvezek prikazuje **avtentikacijo brez ključev**, ki ponuja več prednosti:\n",
|
|
"- ✅ **Ni API ključev za upravljanje** - Uporablja avtentikacijo na podlagi identitete Azure\n",
|
|
"- ✅ **Izboljšana varnost** - Brez shranjevanja skrivnosti v kodi ali konfiguracijskih datotekah\n",
|
|
"- ✅ **Samodejna rotacija poverilnic** - Azure upravlja življenjski cikel poverilnic\n",
|
|
"- ✅ **Nadzor dostopa na podlagi vlog** - Uporablja Azure RBAC za natančno določene pravice\n",
|
|
"- ✅ **Podpora za več okolij** - Deluje brez težav v razvojnem in produkcijskem okolju\n",
|
|
"\n",
|
|
"`DefaultAzureCredential` samodejno izbere najboljši razpoložljivi vir poverilnic:\n",
|
|
"1. **Upravljana identiteta** (pri izvajanju v Azure)\n",
|
|
"2. **Poverilnice Azure CLI** (med lokalnim razvojem)\n",
|
|
"3. **Poverilnice Visual Studio**\n",
|
|
"4. **Okoljske spremenljivke** (če so konfigurirane)\n",
|
|
"5. **Avtentikacija prek interaktivnega brskalnika** (kot zadnja možnost)\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "43efa94d",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Nastavitev avtentikacije brez ključev\n",
|
|
"\n",
|
|
"**Predpogoji za avtentikacijo brez ključev:**\n",
|
|
"\n",
|
|
"### Za lokalni razvoj:\n",
|
|
"```bash\n",
|
|
"# Install Azure CLI and login\n",
|
|
"az login\n",
|
|
"# Verify your identity\n",
|
|
"az account show\n",
|
|
"```\n",
|
|
"\n",
|
|
"### Za Azure okolja:\n",
|
|
"- Omogočite **sistemsko dodeljeno upravljano identiteto** na vašem Azure viru\n",
|
|
"- Dodelite ustrezne **RBAC vloge** upravljani identiteti:\n",
|
|
" - `Cognitive Services OpenAI User` za dostop do Azure OpenAI\n",
|
|
" - `AI Developer` za dostop do projektov Azure AI\n",
|
|
"\n",
|
|
"### Spremenljivke okolja (neobvezno):\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",
|
|
"**Ni potrebnih API ključev ali povezovalnih nizov!** 🔐\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": [
|
|
"## Uvoz potrebnih knjižnic\n",
|
|
"\n",
|
|
"Uvozite potrebne Python module:\n",
|
|
"- **os, time**: Standardne Python knjižnice za okoljske spremenljivke in zamike\n",
|
|
"- **AIProjectClient**: Glavni odjemalec za Azure AI Projects\n",
|
|
"- **DefaultAzureCredential**: Brezključna avtentikacija za Azure storitve\n",
|
|
"- **Razredi, povezani z MCP**: Za ustvarjanje in upravljanje MCP orodij ter obravnavo odobritev\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": [
|
|
"## Konfigurirajte nastavitve strežnika MCP\n",
|
|
"\n",
|
|
"Nastavite konfiguracijo strežnika MCP z uporabo okoljskih spremenljivk in privzetih vrednosti:\n",
|
|
"- **MCP_SERVER_URL**: URL strežnika MCP (privzeto Microsoft Learn API)\n",
|
|
"- **MCP_SERVER_LABEL**: Oznaka za identifikacijo strežnika MCP (privzeto \"mslearn\")\n",
|
|
"\n",
|
|
"Ta pristop omogoča prilagodljivo konfiguracijo v različnih okoljih.\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": [
|
|
"## Ustvarite odjemalca projekta Azure AI (avtentikacija brez ključa)\n",
|
|
"\n",
|
|
"Inicializirajte odjemalca projekta Azure AI z uporabo **avtentikacije brez ključa**:\n",
|
|
"- **endpoint**: URL končne točke projekta Azure AI Foundry\n",
|
|
"- **credential**: Uporablja `DefaultAzureCredential()` za varno avtentikacijo brez ključa\n",
|
|
"- **Brez potrebnih API ključev**: Samodejno zazna in uporabi najbolj razpoložljive poverilnice\n",
|
|
"\n",
|
|
"**Potek avtentikacije:**\n",
|
|
"1. Preveri identiteto, upravljano s strani Azure (v Azure okoljih)\n",
|
|
"2. Preklopi na poverilnice Azure CLI (za lokalni razvoj)\n",
|
|
"3. Po potrebi uporabi druge razpoložljive vire poverilnic\n",
|
|
"\n",
|
|
"Ta pristop odpravlja potrebo po upravljanju API ključev ali povezovalnih nizov v vaši kodi.\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": [
|
|
"## Ustvari definicijo orodja MCP\n",
|
|
"\n",
|
|
"Ustvari orodje MCP, ki se povezuje z Microsoft Learn MCP strežnikom:\n",
|
|
"- **server_label**: Identifikator za MCP strežnik\n",
|
|
"- **server_url**: URL končna točka MCP strežnika\n",
|
|
"- **allowed_tools**: Izbirni seznam za omejitev, katera orodja se lahko uporabljajo (prazni seznam omogoča vsa orodja)\n",
|
|
"\n",
|
|
"To orodje bo agentu omogočilo dostop do dokumentacije in virov 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": [
|
|
"## Ustvarjanje agenta in izvedba pogovora (brez ključev)\n",
|
|
"\n",
|
|
"Ta obsežen razdelek prikazuje celoten **potek dela agenta brez ključev**:\n",
|
|
"\n",
|
|
"1. **Ustvarite AI agenta**: Nastavite agenta z modelom GPT-4.1 nano in orodji MCP\n",
|
|
"2. **Ustvarite nit**: Vzpostavite pogovorno nit za komunikacijo\n",
|
|
"3. **Pošljite sporočilo**: Vprašajte agenta o razlikah med Azure OpenAI in OpenAI\n",
|
|
"4. **Upravljajte odobritve orodij**: Samodejno odobrite klice orodij MCP, ko je to potrebno\n",
|
|
"5. **Spremljajte izvedbo**: Spremljajte napredek agenta in upravljajte potrebne ukrepe\n",
|
|
"6. **Prikažite rezultate**: Prikaz pogovora in podrobnosti uporabe orodij\n",
|
|
"\n",
|
|
"**Funkcije brez ključev:**\n",
|
|
"- ✅ **Brez vgrajenih skrivnosti** - Vsa avtentikacija se izvaja prek identitete Azure\n",
|
|
"- ✅ **Privzeto varno** - Uporablja nadzor dostopa na podlagi vlog\n",
|
|
"- ✅ **Poenostavljena uvedba** - Brez potrebe po upravljanju poverilnic\n",
|
|
"- ✅ **Prijazno za revizije** - Vsi dostopi so sledljivi prek identitete Azure\n",
|
|
"\n",
|
|
"Agent bo uporabljal orodja MCP za dostop do virov Microsoft Learn z največjo varnostjo in brez upravljanja API ključev.\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**Omejitev odgovornosti**: \nTa dokument je bil preveden z uporabo storitve za prevajanje z umetno inteligenco [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da lahko avtomatizirani prevodi vsebujejo napake ali netočnosti. Izvirni dokument v njegovem maternem jeziku je treba obravnavati kot avtoritativni vir. Za ključne informacije priporočamo profesionalni človeški prevod. Ne prevzemamo odgovornosti za morebitna nesporazumevanja ali napačne razlage, ki bi nastale zaradi uporabe tega prevoda.\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:43:19+00:00",
|
|
"source_file": "05-AdvancedTopics/mcp-foundry-agent-integration/mcp_support_python.ipynb",
|
|
"language_code": "sl"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 5
|
|
} |