Utilisation des outils MCP avec les agents Foundry

Vous pouvez étendre les fonctionnalités de votre agent Microsoft 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 Python soutenu par Microsoft Foundry 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 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 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 votre projet 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 de l’agent

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

var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());

var agentVersion = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
    AgentName,
    new ProjectsAgentVersionCreationOptions(
        new DeclarativeAgentDefinition(model)
        {
            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 avec version qui :

Vit sur le service 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 = aiProjectClient.AsAIAgent(agentVersion);

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 aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(agent.Id);

Conseil / Astuce

Consultez l’exemple MCP hébergé par l’agent .NET Foundry pour obtenir un exemple exécutable complet.

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 les informations d’identification de votre projet Foundry via des variables d’environnement :

import os
from azure.identity.aio import AzureCliCredential
from agent_framework.foundry import FoundryChatClient

# Required environment variables
os.environ["FOUNDRY_PROJECT_ENDPOINT"] = "https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
os.environ["FOUNDRY_MODEL"] = "gpt-4o-mini"

Intégration MCP de base

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

import asyncio
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async def basic_foundry_mcp_example():
    """Basic example of Foundry agent with hosted MCP tools."""
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(credential=credential)
        # 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
        async with Agent(
            client=client,
            name="MicrosoftLearnAgent",
            instructions="You answer questions by searching Microsoft Learn content only.",
            tools=[learn_mcp],
        ) as agent:
            # Simple query without approval workflow
            result = await agent.run(
                "Please summarize the Azure AI Agent documentation related to MCP tool calling?"
            )
            print(result.text)

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:
        client = FoundryChatClient(credential=credential)
        # 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.githubcopilot.com/mcp/",
            approval_mode="always_require",  # Require approval for GitHub operations
            headers={"Authorization": "Bearer github-token"},
        )

        # Create agent with multiple MCP tools
        async with Agent(
            client=client,
            name="MultiToolAgent",
            instructions="You can search documentation and access GitHub repositories.",
            tools=[learn_mcp, github_mcp],
        ) as agent:
            result = await agent.run(
                "Find Azure documentation and also check the latest commits in microsoft/semantic-kernel"
            )
            print(result.text)

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

Python Agent Framework offre une intégration transparente avec les fonctionnalités MCP hébergées de 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 aux applications de production.

Exemple complet

# Copyright (c) Microsoft. All rights reserved.

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
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)
   - FOUNDRY_PROJECT_ENDPOINT: Your Foundry project endpoint (required)
   - FOUNDRY_MODEL: Your Foundry model deployment name (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 = FoundryChatClient(credential=AzureCliCredential())
    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

Outils MCP locaux

Commentaires

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

Last updated on 2026-04-02