Partager via

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

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

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 :

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. Nettoyage

L’exemple illustre le nettoyage des ressources approprié :

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

Intégration MCP Azure AI Foundry Python

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

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

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.

Étapes suivantes

Utilisation de flux de travail en tant qu’agents

  • Last updated on