Utilisation des outils MCP avec les agents Foundry

Vous pouvez étendre les fonctionnalités de votre agent Azure AI Foundry en la connectant à des outils hébergés sur des serveurs MCP (Remote Model Context Protocol) ( apportez votre propre point de terminaison de serveur MCP).

Comment utiliser l’outil Model Context Protocol

Cette section explique comment créer un agent IA à l’aide d’Azure Foundry (Azure AI) avec une intégration de serveur MCP (Model Context Protocol) hébergée. L’agent peut utiliser des outils MCP gérés et exécutés par le service Azure Foundry, ce qui permet un accès sécurisé et contrôlé aux ressources externes.

Principales fonctionnalités

Serveur MCP hébergé : le serveur MCP est hébergé et géré par Azure AI Foundry, ce qui élimine la nécessité de gérer l’infrastructure du serveur
Agents persistants : les agents sont créés et stockés côté serveur, ce qui permet des conversations avec état
Flux de travail d’approbation des outils : mécanismes d’approbation configurables pour les appels d’outils MCP

Fonctionnement

1. Configuration de l’environnement

L’exemple nécessite deux variables d’environnement :

AZURE_FOUNDRY_PROJECT_ENDPOINT: URL du point de terminaison de projet Azure AI Foundry
AZURE_FOUNDRY_PROJECT_MODEL_ID: Nom du déploiement du modèle (par défaut « 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. Configuration de l’agent

L’agent est configuré avec des instructions et des métadonnées spécifiques :

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

Cela crée un agent spécialisé pour répondre aux questions à l’aide de la documentation Microsoft Learn.

3. Définition de l’outil MCP

L’exemple crée une définition d’outil MCP qui pointe vers un serveur MCP hébergé :

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

Composants clés :

serverLabel : identificateur unique pour l’instance de serveur MCP
serverUrl : URL du serveur MCP hébergé
AllowedTools : spécifie les outils du serveur MCP que l’agent peut utiliser

4. Création d’un agent persistant

L’agent est créé côté serveur à l’aide du Kit de développement logiciel (SDK) Des agents persistants Azure AI Foundry :

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

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

Avertissement

DefaultAzureCredential est pratique pour le développement, mais nécessite une considération minutieuse en production. En production, envisagez d’utiliser des informations d’identification spécifiques (par exemple ManagedIdentityCredential) pour éviter les problèmes de latence, la détection involontaire des informations d’identification et les risques de sécurité potentiels liés aux mécanismes de secours.

Cela crée un agent persistant qui :

Vit sur le service Azure AI Foundry
A accès aux outils MCP spécifiés
Peut maintenir l’état de conversation entre plusieurs interactions

5. Récupération et exécution de l’agent

L’agent créé est récupéré en tant qu’instance AIAgent :

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

6. Configuration des ressources de l’outil

L’exemple configure les ressources de l’outil avec les paramètres d’approbation :

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

Configuration de clé :

MCPToolResource : Lie l’instance de serveur MCP à l’exécution de l’agent
RequireApproval : contrôles lorsque l’approbation de l’utilisateur est nécessaire pour les appels d’outils
- "never": les outils s’exécutent automatiquement sans approbation
- "always": Tous les appels d’outils nécessitent l’approbation de l’utilisateur
- Les règles d’approbation personnalisées peuvent également être configurées

7. Exécution de l’agent

L’agent est appelé avec une question et s’exécute à l’aide des outils MCP configurés :

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

8. Nettoyage

L’exemple illustre le nettoyage des ressources approprié :

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

Conseil / Astuce

Consultez les exemples .NET pour obtenir des exemples exécutables complets.

Azure AI Foundry fournit une intégration transparente avec les serveurs MCP (Model Context Protocol) via Python Agent Framework. Le service gère l’hébergement et l’exécution du serveur MCP, éliminant ainsi la gestion de l’infrastructure tout en fournissant un accès sécurisé et contrôlé aux outils externes.

Configuration de l’environnement

Configurez vos informations d’identification de projet Azure AI Foundry via des variables d’environnement :

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

Intégration MCP de base

Créez un agent Azure AI Foundry avec les outils MCP hébergés :

import asyncio
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 client,
    ):
        # Create a hosted MCP tool using the client method
        learn_mcp = client.get_mcp_tool(
            name="Microsoft Learn MCP",
            url="https://learn.microsoft.com/api/mcp",
        )

        # Create agent with hosted MCP tool
        agent = client.as_agent(
            name="MicrosoftLearnAgent", 
            instructions="You answer questions by searching Microsoft Learn content only.",
            tools=learn_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())

Configuration MCP multi-outil

Utilisez plusieurs outils MCP hébergés avec un seul agent :

async def multi_tool_mcp_example():
    """Example using multiple hosted MCP tools."""
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(async_credential=credential) as client,
    ):
        # Create multiple MCP tools using the client method
        learn_mcp = client.get_mcp_tool(
            name="Microsoft Learn MCP",
            url="https://learn.microsoft.com/api/mcp",
            approval_mode="never_require",  # Auto-approve documentation searches
        )
        github_mcp = client.get_mcp_tool(
            name="GitHub MCP", 
            url="https://api.github.com/mcp",
            approval_mode="always_require",  # Require approval for GitHub operations
            headers={"Authorization": "Bearer github-token"},
        )

        # Create agent with multiple MCP tools
        agent = client.as_agent(
            name="MultiToolAgent",
            instructions="You can search documentation and access GitHub repositories.",
            tools=[learn_mcp, github_mcp],
        )

        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())

Python Agent Framework fournit une intégration transparente avec les fonctionnalités MCP hébergées d’Azure AI Foundry, ce qui permet un accès sécurisé et évolutif aux outils externes tout en conservant la flexibilité et le contrôle nécessaires pour les applications de production.

Exemple complet

# Copyright (c) Microsoft. All rights reserved.

import asyncio
import os

from agent_framework import Agent
from agent_framework.openai import OpenAIResponsesClient
from dotenv import load_dotenv

"""
MCP GitHub Integration with Personal Access Token (PAT)

This example demonstrates how to connect to GitHub's remote MCP server using a Personal Access
Token (PAT) for authentication. The agent can use GitHub operations like searching repositories,
reading files, creating issues, and more depending on how you scope your token.

Prerequisites:
1. A GitHub Personal Access Token with appropriate scopes
   - Create one at: https://github.com/settings/tokens
   - For read-only operations, you can use more restrictive scopes
2. Environment variables:
   - GITHUB_PAT: Your GitHub Personal Access Token (required)
   - OPENAI_API_KEY: Your OpenAI API key (required)
   - OPENAI_RESPONSES_MODEL_ID: Your OpenAI model ID (required)
"""


async def github_mcp_example() -> None:
    """Example of using GitHub MCP server with PAT authentication."""
    # 1. Load environment variables from .env file if present
    load_dotenv()

    # 2. Get configuration from environment
    github_pat = os.getenv("GITHUB_PAT")
    if not github_pat:
        raise ValueError(
            "GITHUB_PAT environment variable must be set. Create a token at https://github.com/settings/tokens"
        )

    # 3. Create authentication headers with GitHub PAT
    auth_headers = {
        "Authorization": f"Bearer {github_pat}",
    }

    # 4. Create agent with the GitHub MCP tool using instance method
    # The MCP tool manages the connection to the MCP server and makes its tools available
    # Set approval_mode="never_require" to allow the MCP tool to execute without approval
    client = OpenAIResponsesClient()
    github_mcp_tool = client.get_mcp_tool(
        name="GitHub",
        url="https://api.githubcopilot.com/mcp/",
        headers=auth_headers,
        approval_mode="never_require",
    )

    # 5. Create agent with the GitHub MCP tool
    async with Agent(
        client=client,
        name="GitHubAgent",
        instructions=(
            "You are a helpful assistant that can help users interact with GitHub. "
            "You can search for repositories, read file contents, check issues, and more. "
            "Always be clear about what operations you're performing."
        ),
        tools=github_mcp_tool,
    ) as agent:
        # Example 1: Get authenticated user information
        query1 = "What is my GitHub username and tell me about my account?"
        print(f"\nUser: {query1}")
        result1 = await agent.run(query1)
        print(f"Agent: {result1.text}")

        # Example 2: List my repositories
        query2 = "List all the repositories I own on GitHub"
        print(f"\nUser: {query2}")
        result2 = await agent.run(query2)
        print(f"Agent: {result2.text}")


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

Prochaines étapes

Utilisation de flux de travail en tant qu’agents

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-02-13