wehub-resource-sync
404 lines
17 KiB
Plaintext
404 lines
17 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "b8c57858",
|
|
"metadata": {},
|
|
"source": [
|
|
"# Azure AI -agentit Model Context Protocol (MCP) -tuen kanssa - Python\n",
|
|
"\n",
|
|
"Tämä muistikirja esittelee, kuinka käyttää Azure AI -agentteja Model Context Protocol (MCP) -työkalujen kanssa Pythonissa. Se näyttää, kuinka luoda älykäs agentti, joka voi hyödyntää ulkoisia MCP-palvelimia (kuten Microsoft Learn) parannettujen ominaisuuksien saavuttamiseksi käyttämällä avaimetonta autentikointia.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "2e6e4234",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Asenna tarvittavat Python-paketit\n",
|
|
"\n",
|
|
"Ensiksi meidän täytyy asentaa tarvittavat Python-paketit:\n",
|
|
"- **azure-ai-projects**: Azure AI Projects SDK:n ydin\n",
|
|
"- **azure-ai-agents**: Azure AI Agents SDK agenttien luomiseen ja hallintaan\n",
|
|
"- **azure-identity**: Tarjoaa avaimettoman autentikoinnin käyttämällä DefaultAzureCredentialia\n",
|
|
"- **mcp**: Model Context Protocol -toteutus Pythonille\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6a2e9a05",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Avaimeton todennus - Edut\n",
|
|
"\n",
|
|
"Tämä muistikirja esittelee **avaimettoman todennuksen**, joka tarjoaa useita etuja:\n",
|
|
"- ✅ **Ei API-avaimia hallittavana** - Käyttää Azureen perustuvaa identiteettitodennusta\n",
|
|
"- ✅ **Parannettu turvallisuus** - Ei salaisuuksia tallennettuna koodiin tai konfiguraatiotiedostoihin\n",
|
|
"- ✅ **Automaattinen tunnistetietojen kierto** - Azure hallitsee tunnistetietojen elinkaaren\n",
|
|
"- ✅ **Roolipohjainen käyttöoikeuksien hallinta** - Käyttää Azuren RBAC:ia tarkkoihin käyttöoikeuksiin\n",
|
|
"- ✅ **Moniympäristötuki** - Toimii saumattomasti kehitys- ja tuotantoympäristöissä\n",
|
|
"\n",
|
|
"`DefaultAzureCredential` valitsee automaattisesti parhaan saatavilla olevan tunnistetietolähteen:\n",
|
|
"1. **Hallinnoitu identiteetti** (kun suoritetaan Azuren sisällä)\n",
|
|
"2. **Azure CLI** -tunnistetiedot (paikallisen kehityksen aikana)\n",
|
|
"3. **Visual Studio** -tunnistetiedot\n",
|
|
"4. **Ympäristömuuttujat** (jos määritetty)\n",
|
|
"5. **Interaktiivinen selain** -todennus (varavaihtoehtona)\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "43efa94d",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Avaimeton todennusasetukset\n",
|
|
"\n",
|
|
"**Edellytykset avaimettomalle todennukselle:**\n",
|
|
"\n",
|
|
"### Paikallista kehitystä varten:\n",
|
|
"```bash\n",
|
|
"# Install Azure CLI and login\n",
|
|
"az login\n",
|
|
"# Verify your identity\n",
|
|
"az account show\n",
|
|
"```\n",
|
|
"\n",
|
|
"### Azure-ympäristöissä:\n",
|
|
"- Ota käyttöön **järjestelmän määrittämä hallinnoitu identiteetti** Azure-resurssissasi\n",
|
|
"- Määritä hallinnoidulle identiteetille sopivat **RBAC-roolit**:\n",
|
|
" - `Cognitive Services OpenAI User` Azure OpenAI -käyttöä varten\n",
|
|
" - `AI Developer` Azure AI -projektien käyttöä varten\n",
|
|
"\n",
|
|
"### Ympäristömuuttujat (valinnainen):\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",
|
|
"**Ei API-avaimia tai yhteysmerkkijonoja tarvitaan!** 🔐\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": [
|
|
"## Tuo tarvittavat kirjastot\n",
|
|
"\n",
|
|
"Tuo tarvittavat Python-moduulit:\n",
|
|
"- **os, time**: Pythonin vakiokirjastot ympäristömuuttujille ja viiveille\n",
|
|
"- **AIProjectClient**: Pääasiakas Azure AI -projekteille\n",
|
|
"- **DefaultAzureCredential**: Avaimeton todennus Azure-palveluille\n",
|
|
"- **MCP-liittyvät luokat**: MCP-työkalujen luomiseen ja hallintaan sekä hyväksyntöjen käsittelyyn\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": [
|
|
"## Määritä MCP-palvelimen asetukset\n",
|
|
"\n",
|
|
"Määritä MCP-palvelimen kokoonpano käyttämällä ympäristömuuttujia, joilla on oletusarvot:\n",
|
|
"- **MCP_SERVER_URL**: MCP-palvelimen URL-osoite (oletuksena Microsoft Learn API)\n",
|
|
"- **MCP_SERVER_LABEL**: Tunniste MCP-palvelimen tunnistamiseen (oletuksena \"mslearn\")\n",
|
|
"\n",
|
|
"Tämä lähestymistapa mahdollistaa joustavan kokoonpanon eri ympäristöissä.\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": [
|
|
"## Luo Azure AI Project -asiakas (avaimeton todennus)\n",
|
|
"\n",
|
|
"Alusta Azure AI Project -asiakas käyttäen **avaimetonta todennusta**:\n",
|
|
"- **endpoint**: Azure AI Foundry -projektin päätepisteen URL-osoite\n",
|
|
"- **credential**: Käyttää `DefaultAzureCredential()` turvalliseen, avaimettomaan todennukseen\n",
|
|
"- **Ei API-avaimia vaadita**: Löytää ja käyttää automaattisesti parasta saatavilla olevaa tunnistetta\n",
|
|
"\n",
|
|
"**Todennusprosessi:**\n",
|
|
"1. Tarkistaa hallitun identiteetin (Azure-ympäristöissä)\n",
|
|
"2. Siirtyy Azure CLI -tunnisteisiin (paikallista kehitystä varten)\n",
|
|
"3. Käyttää muita saatavilla olevia tunnistuslähteitä tarpeen mukaan\n",
|
|
"\n",
|
|
"Tämä lähestymistapa poistaa tarpeen hallita API-avaimia tai yhteysmerkkijonoja koodissasi.\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": [
|
|
"## Luo MCP-työkalumääritelmä\n",
|
|
"\n",
|
|
"Luo MCP-työkalu, joka yhdistyy Microsoft Learn MCP-palvelimeen:\n",
|
|
"- **server_label**: Tunniste MCP-palvelimelle\n",
|
|
"- **server_url**: MCP-palvelimen URL-päätepiste\n",
|
|
"- **allowed_tools**: Valinnainen lista, jolla rajoitetaan käytettävissä olevia työkaluja (tyhjä lista sallii kaikki työkalut)\n",
|
|
"\n",
|
|
"Tämä työkalu mahdollistaa agentin pääsyn Microsoft Learn -dokumentaatioon ja -resursseihin.\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": [
|
|
"## Luo agentti ja suorita keskustelu (avaimeton työnkulku)\n",
|
|
"\n",
|
|
"Tämä kattava osio esittelee täydellisen **avaimettoman agentin työnkulun**:\n",
|
|
"\n",
|
|
"1. **Luo AI-agentti**: Määritä agentti GPT-4.1 nano -mallilla ja MCP-työkaluilla\n",
|
|
"2. **Luo keskusteluketju**: Perusta keskusteluketju viestintää varten\n",
|
|
"3. **Lähetä viesti**: Kysy agentilta Azure OpenAI:n ja OpenAI:n eroista\n",
|
|
"4. **Käsittele työkalujen hyväksynnät**: Hyväksy MCP-työkalujen kutsut automaattisesti tarvittaessa\n",
|
|
"5. **Seuraa suoritusta**: Tarkkaile agentin etenemistä ja hoida tarvittavat toimenpiteet\n",
|
|
"6. **Näytä tulokset**: Esitä keskustelun ja työkalujen käytön yksityiskohdat\n",
|
|
"\n",
|
|
"**Avaimettomat ominaisuudet:**\n",
|
|
"- ✅ **Ei kovakoodattuja salaisuuksia** - Kaikki autentikointi hoidetaan Azure-identiteetillä\n",
|
|
"- ✅ **Turvallinen oletuksena** - Käyttää roolipohjaista käyttöoikeuksien hallintaa\n",
|
|
"- ✅ **Yksinkertaistettu käyttöönotto** - Ei vaadi tunnistetietojen hallintaa\n",
|
|
"- ✅ **Auditointia tukeva** - Kaikki käyttö kirjataan Azure-identiteetin kautta\n",
|
|
"\n",
|
|
"Agentti käyttää MCP-työkaluja Microsoft Learn -resurssien hyödyntämiseen täysin turvallisesti ilman API-avainten hallintaa.\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**Vastuuvapauslauseke**: \nTämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, huomioithan, että automaattiset käännökset voivat sisältää virheitä tai epätarkkuuksia. Alkuperäistä asiakirjaa sen alkuperäisellä kielellä tulisi pitää ensisijaisena lähteenä. Kriittisen tiedon osalta suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa väärinkäsityksistä tai virhetulkinnoista, jotka johtuvat tämän käännöksen käytöstä.\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:35:13+00:00",
|
|
"source_file": "05-AdvancedTopics/mcp-foundry-agent-integration/mcp_support_python.ipynb",
|
|
"language_code": "fi"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 5
|
|
} |