wehub-resource-sync
13 KiB
13 KiB
Integrasi Protokol Konteks Model (MCP) dengan Microsoft Foundry
Panduan ini menunjukkan cara mengintegrasikan pelayan Model Context Protocol (MCP) dengan ejen Microsoft Foundry, membolehkan orkestrasi alat yang berkuasa dan keupayaan AI perusahaan.
Pengenalan
Model Context Protocol (MCP) adalah standard terbuka yang membolehkan aplikasi AI untuk berhubung dengan selamat ke sumber data dan alat luaran. Apabila digabungkan dengan Microsoft Foundry, MCP membolehkan ejen mengakses dan berinteraksi dengan pelbagai perkhidmatan luaran, API, dan sumber data dengan cara yang standard.
Integrasi ini menggabungkan fleksibiliti ekosistem alat MCP dengan rangka kerja ejen yang kukuh daripada Microsoft Foundry, menyediakan penyelesaian AI tahap perusahaan dengan kemampuan penyesuaian yang meluas.
Nota: Jika anda ingin menggunakan MCP dalam Perkhidmatan Ejen Microsoft Foundry, buat masa ini hanya wilayah berikut disokong: westus, westus2, uaenorth, southindia dan switzerlandnorth
Objektif Pembelajaran
Pada akhir panduan ini, anda akan dapat:
- Memahami Protokol Konteks Model dan manfaatnya
- Menyediakan pelayan MCP untuk digunakan dengan ejen Microsoft Foundry
- Membuat dan mengkonfigurasi ejen dengan integrasi alat MCP
- Melaksanakan contoh praktikal menggunakan pelayan MCP sebenar
- Mengendalikan respons alat dan sitasi dalam perbualan ejen
Prasyarat
Sebelum memulakan, pastikan anda mempunyai:
- Langganan Azure dengan akses Microsoft Foundry
- Python 3.10+ atau .NET 8.0+
- Azure CLI dipasang dan dikonfigurasi
- Kebenaran yang sesuai untuk membuat sumber AI
Apakah Model Context Protocol (MCP)?
Model Context Protocol adalah cara standard untuk aplikasi AI berhubung dengan sumber data dan alat luaran. Manfaat utama termasuk:
- Integrasi Standard: Antara muka konsisten merentasi pelbagai alat dan perkhidmatan
- Keselamatan: Mekanisme pengesahan dan kebenaran yang selamat
- Fleksibiliti: Sokongan untuk pelbagai sumber data, API, dan alat tersuai
- Kebolehsambungan: Mudah untuk menambah keupayaan dan integrasi baru
Menyediakan MCP dengan Microsoft Foundry
Konfigurasi Persekitaran
Pilih persekitaran pembangunan kegemaran anda:
Pelaksanaan Python
Nota Anda boleh menjalankan notebook ini
1. Pasang Pakej yang Diperlukan
pip install azure-ai-projects -U
pip install azure-ai-agents==1.1.0b4 -U
pip install azure-identity -U
pip install mcp==1.11.0 -U
2. Import Kebergantungan
import os, time
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import McpTool, RequiredMcpToolCall, SubmitToolApprovalAction, ToolApproval
3. Konfigurasikan Tetapan MCP
mcp_server_url = os.environ.get("MCP_SERVER_URL", "https://learn.microsoft.com/api/mcp")
mcp_server_label = os.environ.get("MCP_SERVER_LABEL", "mslearn")
4. Inisialisasi Klien Projek
project_client = AIProjectClient(
endpoint="https://your-project-endpoint.services.ai.azure.com/api/projects/your-project",
credential=DefaultAzureCredential(),
)
5. Cipta Alat MCP
mcp_tool = McpTool(
server_label=mcp_server_label,
server_url=mcp_server_url,
allowed_tools=[], # Pilihan: nyatakan alat yang dibenarkan
)
6. Contoh Python Lengkap
with project_client:
agents_client = project_client.agents
# Cipta ejen baru dengan alat MCP
agent = agents_client.create_agent(
model="Your AOAI Model Deployment",
name="my-mcp-agent",
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.",
tools=mcp_tool.definitions,
)
print(f"Created agent, ID: {agent.id}")
print(f"MCP Server: {mcp_tool.server_label} at {mcp_tool.server_url}")
# Cipta thread untuk komunikasi
thread = agents_client.threads.create()
print(f"Created thread, ID: {thread.id}")
# Cipta mesej ke thread
message = agents_client.messages.create(
thread_id=thread.id,
role="user",
content="What's difference between Azure OpenAI and OpenAI?",
)
print(f"Created message, ID: {message.id}")
# Uruskan kelulusan alat dan jalankan ejen
mcp_tool.update_headers("SuperSecret", "123456")
run = agents_client.runs.create(thread_id=thread.id, agent_id=agent.id, tool_resources=mcp_tool.resources)
print(f"Created run, ID: {run.id}")
while run.status in ["queued", "in_progress", "requires_action"]:
time.sleep(1)
run = agents_client.runs.get(thread_id=thread.id, run_id=run.id)
if run.status == "requires_action" and isinstance(run.required_action, SubmitToolApprovalAction):
tool_calls = run.required_action.submit_tool_approval.tool_calls
if not tool_calls:
print("No tool calls provided - cancelling run")
agents_client.runs.cancel(thread_id=thread.id, run_id=run.id)
break
tool_approvals = []
for tool_call in tool_calls:
if isinstance(tool_call, RequiredMcpToolCall):
try:
print(f"Approving tool call: {tool_call}")
tool_approvals.append(
ToolApproval(
tool_call_id=tool_call.id,
approve=True,
headers=mcp_tool.headers,
)
)
except Exception as e:
print(f"Error approving tool_call {tool_call.id}: {e}")
if tool_approvals:
agents_client.runs.submit_tool_outputs(
thread_id=thread.id, run_id=run.id, tool_approvals=tool_approvals
)
print(f"Current run status: {run.status}")
print(f"Run completed with status: {run.status}")
# Paparkan perbualan
messages = agents_client.messages.list(thread_id=thread.id)
print("\nConversation:")
print("-" * 50)
for msg in messages:
if msg.text_messages:
last_text = msg.text_messages[-1]
print(f"{msg.role.upper()}: {last_text.text.value}")
print("-" * 50)
Pelaksanaan .NET
Nota Anda boleh menjalankan notebook ini
1. Pasang Pakej yang Diperlukan
#r "nuget: Azure.AI.Agents.Persistent, 1.1.0-beta.4"
#r "nuget: Azure.Identity, 1.14.2"
2. Import Kebergantungan
using Azure.AI.Agents.Persistent;
using Azure.Identity;
3. Konfigurasikan Tetapan
var projectEndpoint = "https://your-project-endpoint.services.ai.azure.com/api/projects/your-project";
var modelDeploymentName = "Your AOAI Model Deployment";
var mcpServerUrl = "https://learn.microsoft.com/api/mcp";
var mcpServerLabel = "mslearn";
PersistentAgentsClient agentClient = new(projectEndpoint, new DefaultAzureCredential());
4. Cipta Definisi Alat MCP
MCPToolDefinition mcpTool = new(mcpServerLabel, mcpServerUrl);
5. Cipta Ejen dengan Alat MCP
PersistentAgent agent = await agentClient.Administration.CreateAgentAsync(
model: modelDeploymentName,
name: "my-learn-agent",
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.",
tools: [mcpTool]
);
6. Contoh .NET Lengkap
// Create thread and message
PersistentAgentThread thread = await agentClient.Threads.CreateThreadAsync();
PersistentThreadMessage message = await agentClient.Messages.CreateMessageAsync(
thread.Id,
MessageRole.User,
"What's difference between Azure OpenAI and OpenAI?");
// Configure tool resources with headers
MCPToolResource mcpToolResource = new(mcpServerLabel);
mcpToolResource.UpdateHeader("SuperSecret", "123456");
ToolResources toolResources = mcpToolResource.ToToolResources();
// Create and handle run
ThreadRun run = await agentClient.Runs.CreateRunAsync(thread, agent, toolResources);
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress || run.Status == RunStatus.RequiresAction)
{
await Task.Delay(TimeSpan.FromMilliseconds(1000));
run = await agentClient.Runs.GetRunAsync(thread.Id, run.Id);
if (run.Status == RunStatus.RequiresAction && run.RequiredAction is SubmitToolApprovalAction toolApprovalAction)
{
var toolApprovals = new List<ToolApproval>();
foreach (var toolCall in toolApprovalAction.SubmitToolApproval.ToolCalls)
{
if (toolCall is RequiredMcpToolCall mcpToolCall)
{
Console.WriteLine($"Approving MCP tool call: {mcpToolCall.Name}");
toolApprovals.Add(new ToolApproval(mcpToolCall.Id, approve: true)
{
Headers = { ["SuperSecret"] = "123456" }
});
}
}
if (toolApprovals.Count > 0)
{
run = await agentClient.Runs.SubmitToolOutputsToRunAsync(thread.Id, run.Id, toolApprovals: toolApprovals);
}
}
}
// Display messages
using Azure;
AsyncPageable<PersistentThreadMessage> messages = agentClient.Messages.GetMessagesAsync(
threadId: thread.Id,
order: ListSortOrder.Ascending
);
await foreach (PersistentThreadMessage threadMessage in messages)
{
Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
foreach (MessageContent contentItem in threadMessage.ContentItems)
{
if (contentItem is MessageTextContent textItem)
{
Console.Write(textItem.Text);
}
else if (contentItem is MessageImageFileContent imageFileItem)
{
Console.Write($"<image from ID: {imageFileItem.FileId}>");
}
Console.WriteLine();
}
}
Pilihan Konfigurasi Alat MCP
Apabila mengkonfigurasikan alat MCP untuk ejen anda, anda boleh menetapkan beberapa parameter penting:
Konfigurasi Python
mcp_tool = McpTool(
server_label="unique_server_name", # Pengecam untuk pelayan MCP
server_url="https://api.example.com/mcp", # Titik akhir pelayan MCP
allowed_tools=[], # Pilihan: tetapkan alat yang dibenarkan
)
Konfigurasi .NET
MCPToolDefinition mcpTool = new(
"unique_server_name", // Server label
"https://api.example.com/mcp" // MCP server URL
);
Pengesahan dan Header
Kedua-dua pelaksanaan menyokong header khusus untuk pengesahan:
Python
mcp_tool.update_headers("SuperSecret", "123456")
.NET
MCPToolResource mcpToolResource = new(mcpServerLabel);
mcpToolResource.UpdateHeader("SuperSecret", "123456");
Penyelesaian Masalah Isu Lazim
1. Isu Sambungan
- Sahkan URL pelayan MCP boleh diakses
- Semak kelayakan pengesahan
- Pastikan sambungan rangkaian wujud
2. Kegagalan Panggilan Alat
- Semak argumen dan format panggilan alat
- Semak keperluan khusus pelayan
- Laksanakan penanganan ralat yang sesuai
3. Masalah Prestasi
- Optimumkan kekerapan panggilan alat
- Laksanakan caching apabila sesuai
- Pantau masa tindak balas pelayan
Langkah Seterusnya
Untuk meningkatkan integrasi MCP anda:
- Terokai Pelayan MCP Tersuai: Bina pelayan MCP sendiri untuk sumber data proprietari
- Laksanakan Keselamatan Lanjutan: Tambah OAuth2 atau mekanisme pengesahan tersuai
- Pantau dan Analitik: Laksanakan log dan pemantauan penggunaan alat
- Skalakan Penyelesaian Anda: Pertimbangkan pengimbangan beban dan seni bina pelayan MCP diedarkan
Sumber Tambahan
- Dokumentasi Microsoft Foundry
- Contoh Protokol Konteks Model
- Tinjauan Ejen Microsoft Foundry
- Spesifikasi MCP
Sokongan
Untuk sokongan tambahan dan pertanyaan:
- Semak dokumentasi Microsoft Foundry
- Rujuk sumber komuniti MCP
Apa seterusnya
Penafian: Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI Co-op Translator. Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini.