Korzystanie z narzędzi MCP z agentami foundry

1. Konfiguracja środowiska

Przykład wymaga dwóch zmiennych środowiskowych:

• AZURE_FOUNDRY_PROJECT_ENDPOINT: Adres URL punktu końcowego projektu usługi Azure AI Foundry
• AZURE_FOUNDRY_PROJECT_MODEL_ID: Nazwa wdrożenia modelu (domyślnie to "gpt-4.1-mini")

var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") 
    ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_MODEL_ID") ?? "gpt-4.1-mini";

2. Konfiguracja agenta

Agent jest skonfigurowany przy użyciu określonych instrukcji i metadanych:

const string AgentName = "MicrosoftLearnAgent";
const string AgentInstructions = "You answer questions by searching the Microsoft Learn content only.";

Spowoduje to utworzenie agenta wyspecjalizowanego do odpowiadania na pytania przy użyciu dokumentacji platformy Microsoft Learn.

3. Definicja narzędzia MCP

Przykład tworzy definicję narzędzia MCP wskazującą hostowany serwer MCP:

var mcpTool = new MCPToolDefinition(
    serverLabel: "microsoft_learn",
    serverUrl: "https://learn.microsoft.com/api/mcp");
mcpTool.AllowedTools.Add("microsoft_docs_search");

Kluczowe składniki:

• serverLabel: unikatowy identyfikator wystąpienia serwera MCP
• serverUrl: adres URL hostowanego serwera MCP
• AllowedTools: określa narzędzia z serwera MCP, których agent może używać

4. Trwałe tworzenie agenta

Agent jest tworzony po stronie serwera przy użyciu zestawu SDK agentów trwałych usługi Azure AI Foundry:

var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());

var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
    model: model,
    name: AgentName,
    instructions: AgentInstructions,
    tools: [mcpTool]);

Spowoduje to utworzenie agenta trwałego, który:

• Mieszka w usłudze Azure AI Foundry
• Ma dostęp do określonych narzędzi MCP
• Może zachować stan konwersacji w wielu interakcjach

5. Pobieranie i wykonywanie agenta

Utworzony agent jest pobierany jako AIAgent wystąpienie:

AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);

6. Konfiguracja zasobów narzędzi

Przykład konfiguruje zasoby narzędzi z ustawieniami zatwierdzania:

var runOptions = new ChatClientAgentRunOptions()
{
    ChatOptions = new()
    {
        RawRepresentationFactory = (_) => new ThreadAndRunOptions()
        {
            ToolResources = new MCPToolResource(serverLabel: "microsoft_learn")
            {
                RequireApproval = new MCPApproval("never"),
            }.ToToolResources()
        }
    }
};

Konfiguracja klucza:

• MCPToolResource: Łączy wystąpienie serwera MCP z wykonaniem agenta
• RequireApproval: określa, kiedy jest wymagane zatwierdzenie przez użytkownika w przypadku wywołań narzędzi
  • "never": Narzędzia są wykonywane automatycznie bez zatwierdzenia
  • "always": Wszystkie wywołania narzędzi wymagają zatwierdzenia przez użytkownika
  • Niestandardowe reguły zatwierdzania można również skonfigurować

7. Wykonywanie agenta

Agent jest wywoływany z pytaniem i wykonywany przy użyciu skonfigurowanych narzędzi MCP:

AgentThread thread = agent.GetNewThread();
var response = await agent.RunAsync(
    "Please summarize the Azure AI Agent documentation related to MCP Tool calling?", 
    thread, 
    runOptions);
Console.WriteLine(response);

8. Oczyszczanie

W przykładzie pokazano prawidłowe czyszczenie zasobów:

await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);

Integracja z platformą Azure AI Foundry MCP w języku Python

Usługa Azure AI Foundry zapewnia bezproblemową integrację z serwerami protokołu MCP (Model Context Protocol) za pośrednictwem platformy Agent Framework języka Python. Usługa zarządza hostowaniem i wykonywaniem serwera MCP, eliminując zarządzanie infrastrukturą przy jednoczesnym zapewnieniu bezpiecznego, kontrolowanego dostępu do narzędzi zewnętrznych.

Konfiguracja środowiska

Skonfiguruj poświadczenia projektu usługi Azure AI Foundry za pomocą zmiennych środowiskowych:

import os
from azure.identity.aio import AzureCliCredential
from agent_framework.azure import AzureAIAgentClient

# Required environment variables
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = "https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"] = "gpt-4o-mini"  # Optional, defaults to this

Podstawowa integracja mcp

Utwórz agenta usługi Azure AI Foundry z hostowanymi narzędziami MCP:

import asyncio
from agent_framework import HostedMCPTool
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def basic_foundry_mcp_example():
    """Basic example of Azure AI Foundry agent with hosted MCP tools."""
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential) as chat_client,
    ):
        # Enable Azure AI observability (optional but recommended)
        await chat_client.setup_azure_ai_observability()

        # Create agent with hosted MCP tool
        agent = chat_client.create_agent(
            name="MicrosoftLearnAgent", 
            instructions="You answer questions by searching Microsoft Learn content only.",
            tools=HostedMCPTool(
                name="Microsoft Learn MCP",
                url="https://learn.microsoft.com/api/mcp",
            ),
        )

        # Simple query without approval workflow
        result = await agent.run(
            "Please summarize the Azure AI Agent documentation related to MCP tool calling?"
        )
        print(result)

if __name__ == "__main__":
    asyncio.run(basic_foundry_mcp_example())

Konfiguracja mcp z wieloma narzędziami

Użyj wielu hostowanych narzędzi MCP z jednym agentem:

async def multi_tool_mcp_example():
    """Example using multiple hosted MCP tools."""
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential) as chat_client,
    ):
        await chat_client.setup_azure_ai_observability()

        # Create agent with multiple MCP tools
        agent = chat_client.create_agent(
            name="MultiToolAgent",
            instructions="You can search documentation and access GitHub repositories.",
            tools=[
                HostedMCPTool(
                    name="Microsoft Learn MCP",
                    url="https://learn.microsoft.com/api/mcp",
                    approval_mode="never_require",  # Auto-approve documentation searches
                ),
                HostedMCPTool(
                    name="GitHub MCP", 
                    url="https://api.github.com/mcp",
                    approval_mode="always_require",  # Require approval for GitHub operations
                    headers={"Authorization": "Bearer github-token"},
                ),
            ],
        )

        result = await agent.run(
            "Find Azure documentation and also check the latest commits in microsoft/semantic-kernel"
        )
        print(result)

if __name__ == "__main__":
    asyncio.run(multi_tool_mcp_example())

Struktura agentów języka Python zapewnia bezproblemową integrację z hostowanymi funkcjami MCP usługi Azure AI Foundry, umożliwiając bezpieczny i skalowalny dostęp do narzędzi zewnętrznych przy zachowaniu elastyczności i kontroli wymaganej dla aplikacji produkcyjnych.