wehub-resource-sync
404 lines
19 KiB
Plaintext
404 lines
19 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "b8c57858",
|
|
"metadata": {},
|
|
"source": [
|
|
"# عوامل هوش مصنوعی Azure با پشتیبانی از پروتکل زمینه مدل (MCP) - پایتون\n",
|
|
"\n",
|
|
"این دفترچه نشان میدهد که چگونه میتوان از عوامل هوش مصنوعی Azure با ابزارهای پروتکل زمینه مدل (MCP) در پایتون استفاده کرد. این مثال نحوه ایجاد یک عامل هوشمند را نشان میدهد که میتواند از سرورهای خارجی MCP (مانند Microsoft Learn) برای قابلیتهای پیشرفته با استفاده از احراز هویت بدون کلید بهرهمند شود.\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "2e6e4234",
|
|
"metadata": {},
|
|
"source": [
|
|
"## نصب بستههای مورد نیاز پایتون\n",
|
|
"\n",
|
|
"ابتدا باید بستههای ضروری پایتون را نصب کنیم:\n",
|
|
"- **azure-ai-projects**: هسته SDK پروژههای Azure AI\n",
|
|
"- **azure-ai-agents**: SDK عوامل Azure AI برای ایجاد و مدیریت عوامل\n",
|
|
"- **azure-identity**: احراز هویت بدون کلید با استفاده از DefaultAzureCredential\n",
|
|
"- **mcp**: پیادهسازی پروتکل Model Context برای پایتون\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "6a2e9a05",
|
|
"metadata": {},
|
|
"source": [
|
|
"## مزایای احراز هویت بدون کلید\n",
|
|
"\n",
|
|
"این دفترچه **احراز هویت بدون کلید** را نشان میدهد که چندین مزیت ارائه میدهد:\n",
|
|
"- ✅ **بدون نیاز به مدیریت کلیدهای API** - از احراز هویت مبتنی بر هویت Azure استفاده میکند\n",
|
|
"- ✅ **امنیت بیشتر** - هیچ راز یا اطلاعات حساسی در کد یا فایلهای پیکربندی ذخیره نمیشود\n",
|
|
"- ✅ **چرخش خودکار اعتبارنامهها** - Azure مدیریت چرخه عمر اعتبارنامهها را بر عهده دارد\n",
|
|
"- ✅ **کنترل دسترسی مبتنی بر نقش** - از RBAC Azure برای تنظیم دقیق مجوزها استفاده میکند\n",
|
|
"- ✅ **پشتیبانی از چند محیط** - بهطور یکپارچه در محیطهای توسعه و تولید کار میکند\n",
|
|
"\n",
|
|
"`DefaultAzureCredential` بهطور خودکار بهترین منبع اعتبارنامه موجود را انتخاب میکند:\n",
|
|
"1. **Managed Identity** (زمان اجرا در Azure)\n",
|
|
"2. اعتبارنامههای **Azure CLI** (در طول توسعه محلی)\n",
|
|
"3. اعتبارنامههای **Visual Studio**\n",
|
|
"4. **متغیرهای محیطی** (در صورت پیکربندی)\n",
|
|
"5. احراز هویت **مرورگر تعاملی** (بهعنوان گزینه جایگزین)\n"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "43efa94d",
|
|
"metadata": {},
|
|
"source": [
|
|
"## تنظیم احراز هویت بدون کلید\n",
|
|
"\n",
|
|
"**پیشنیازهای احراز هویت بدون کلید:**\n",
|
|
"\n",
|
|
"### برای توسعه محلی:\n",
|
|
"```bash\n",
|
|
"# Install Azure CLI and login\n",
|
|
"az login\n",
|
|
"# Verify your identity\n",
|
|
"az account show\n",
|
|
"```\n",
|
|
"\n",
|
|
"### برای محیطهای Azure:\n",
|
|
"- فعال کردن **System-assigned Managed Identity** روی منبع Azure خود\n",
|
|
"- اختصاص **نقشهای RBAC** مناسب به هویت مدیریتشده:\n",
|
|
" - `Cognitive Services OpenAI User` برای دسترسی به Azure OpenAI\n",
|
|
" - `AI Developer` برای دسترسی به پروژههای Azure AI\n",
|
|
"\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",
|
|
"**نیازی به کلیدهای API یا رشتههای اتصال نیست!** 🔐\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": [
|
|
"## وارد کردن کتابخانههای مورد نیاز\n",
|
|
"\n",
|
|
"ماژولهای پایتون مورد نیاز را وارد کنید:\n",
|
|
"- **os, time**: کتابخانههای استاندارد پایتون برای متغیرهای محیطی و تأخیرها\n",
|
|
"- **AIProjectClient**: کلاینت اصلی برای پروژههای هوش مصنوعی Azure\n",
|
|
"- **DefaultAzureCredential**: احراز هویت بدون کلید برای خدمات Azure\n",
|
|
"- **کلاسهای مرتبط با MCP**: برای ایجاد و مدیریت ابزارهای MCP و رسیدگی به تأییدیهها\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": [
|
|
"## تنظیمات سرور MCP را پیکربندی کنید\n",
|
|
"\n",
|
|
"پیکربندی سرور MCP را با استفاده از متغیرهای محیطی و مقادیر پیشفرض انجام دهید:\n",
|
|
"- **MCP_SERVER_URL**: آدرس URL سرور MCP (بهصورت پیشفرض API Microsoft Learn)\n",
|
|
"- **MCP_SERVER_LABEL**: یک برچسب برای شناسایی سرور MCP (بهصورت پیشفرض \"mslearn\")\n",
|
|
"\n",
|
|
"این روش امکان پیکربندی انعطافپذیر در محیطهای مختلف را فراهم میکند.\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": [
|
|
"## ایجاد کلاینت پروژه Azure AI (احراز هویت بدون کلید)\n",
|
|
"\n",
|
|
"کلاینت پروژه Azure AI را با استفاده از **احراز هویت بدون کلید** مقداردهی اولیه کنید:\n",
|
|
"- **endpoint**: آدرس URL نقطه پایانی پروژه Azure AI Foundry\n",
|
|
"- **credential**: از `DefaultAzureCredential()` برای احراز هویت امن و بدون کلید استفاده میکند\n",
|
|
"- **بدون نیاز به کلیدهای API**: بهطور خودکار بهترین اعتبار موجود را کشف و استفاده میکند\n",
|
|
"\n",
|
|
"**جریان احراز هویت:**\n",
|
|
"1. بررسی هویت مدیریتشده (در محیطهای Azure)\n",
|
|
"2. استفاده از اعتبارنامههای Azure CLI (برای توسعه محلی)\n",
|
|
"3. استفاده از سایر منابع اعتبارنامه موجود در صورت نیاز\n",
|
|
"\n",
|
|
"این روش نیاز به مدیریت کلیدهای API یا رشتههای اتصال در کد شما را از بین میبرد.\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": [
|
|
"## ایجاد تعریف ابزار MCP\n",
|
|
"\n",
|
|
"یک ابزار MCP ایجاد کنید که به سرور MCP مایکروسافت لرن متصل شود:\n",
|
|
"- **server_label**: شناسهای برای سرور MCP\n",
|
|
"- **server_url**: نقطه پایانی URL سرور MCP\n",
|
|
"- **allowed_tools**: لیست اختیاری برای محدود کردن ابزارهایی که میتوانند استفاده شوند (لیست خالی به همه ابزارها اجازه میدهد)\n",
|
|
"\n",
|
|
"این ابزار به عامل اجازه میدهد به مستندات و منابع مایکروسافت لرن دسترسی پیدا کند.\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": [
|
|
"## ایجاد عامل و اجرای مکالمه (جریان کاری بدون کلید)\n",
|
|
"\n",
|
|
"این بخش جامع، **جریان کاری عامل بدون کلید** را به طور کامل توضیح میدهد:\n",
|
|
"\n",
|
|
"1. **ایجاد عامل هوش مصنوعی**: تنظیم یک عامل با مدل GPT-4.1 nano و ابزارهای MCP \n",
|
|
"2. **ایجاد رشته مکالمه**: برقراری یک رشته مکالمه برای ارتباط \n",
|
|
"3. **ارسال پیام**: از عامل درباره تفاوتهای Azure OpenAI و OpenAI سؤال کنید \n",
|
|
"4. **مدیریت تأیید ابزارها**: تأیید خودکار فراخوانی ابزارهای MCP در صورت نیاز \n",
|
|
"5. **نظارت بر اجرا**: پیگیری پیشرفت عامل و مدیریت اقدامات مورد نیاز \n",
|
|
"6. **نمایش نتایج**: نمایش جزئیات مکالمه و استفاده از ابزارها \n",
|
|
"\n",
|
|
"**ویژگیهای بدون کلید:**\n",
|
|
"- ✅ **بدون اسرار سختکد شده** - تمام احراز هویت از طریق هویت Azure مدیریت میشود \n",
|
|
"- ✅ **امنیت پیشفرض** - از کنترل دسترسی مبتنی بر نقش استفاده میکند \n",
|
|
"- ✅ **استقرار سادهشده** - نیازی به مدیریت اعتبارنامه نیست \n",
|
|
"- ✅ **مناسب برای ممیزی** - تمام دسترسیها از طریق هویت Azure ردیابی میشود \n",
|
|
"\n",
|
|
"عامل از ابزارهای MCP برای دسترسی به منابع Microsoft Learn با امنیت کامل و بدون نیاز به مدیریت کلید 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**سلب مسئولیت**: \nاین سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما تلاش میکنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمههای خودکار ممکن است شامل خطاها یا نادرستیها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، توصیه میشود از ترجمه حرفهای انسانی استفاده کنید. ما مسئولیتی در قبال سوء تفاهمها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.\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:22:34+00:00",
|
|
"source_file": "05-AdvancedTopics/mcp-foundry-agent-integration/mcp_support_python.ipynb",
|
|
"language_code": "fa"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 5
|
|
} |