Partage via

Outil d’interpréteur de code personnalisé pour les agents (préversion)

Important

Les éléments marqués (aperçu) dans cet article sont actuellement en aperçu public. Cette version préliminaire est fournie sans contrat de niveau de service, et nous la déconseillons pour les charges de travail en production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d'utilisation supplémentaires pour les aperçus Microsoft Azure.

Un interpréteur de code personnalisé vous donne un contrôle total sur l’environnement d’exécution pour le code Python généré par l’agent. Vous pouvez configurer des packages Python personnalisés, des ressources de calcul et un environnement Azure Container Apps. Le conteneur d’interpréteur de code expose un serveur MCP (Model Context Protocol).

Utilisez un interpréteur de code personnalisé lorsque l'outil interpréteur de code intégré Code pour les agents ne répond pas à vos besoins, par exemple lorsque vous avez besoin de packages Python spécifiques, d'images conteneur personnalisées ou de ressources de calcul dédiées.

Pour plus d’informations sur MCP et sur la façon dont les agents se connectent aux outils MCP, consultez Se connecter aux serveurs Model Context Protocol (préversion).

Assistance à l'utilisation

Cet article utilise les Azure CLI et un exemple de projet exécutable.

✔️ (GA) indique une disponibilité générale, ✔️ (préversion) indique un aperçu public et un tiret (-) indique que la fonctionnalité n’est pas disponible.

Support de Microsoft Foundry SDK Python Kit de développement logiciel (SDK) C# Kit de développement logiciel (SDK) JavaScript Kit de développement logiciel (SDK) Java API REST Configuration d’agent de base Configuration d’agent standard
✔️ ✔️ (GA) ✔️ (Préversion) ✔️ (GA) ✔️ (Préversion) ✔️ (GA) - ✔️

Pour connaître la dernière prise en charge du SDK et de l’API pour les outils d’agents, consultez les meilleures pratiques pour l’utilisation d’outils dans le service Microsoft Foundry Agent.

Prise en charge des Kits de développement logiciel (SDK)

L’interpréteur de code personnalisé utilise le type d’outil MCP. Tous les SDK qui prennent en charge les outils MCP peuvent créer un agent d’interpréteur de code personnalisé. Les sdk .NET et Java sont actuellement en préversion. Pour connaître les étapes d’approvisionnement d’infrastructure (Azure CLI, Bicep), consultez Créer un agent avec un interpréteur de code personnalisé.

Prerequisites

Avant de commencer

Cette procédure provisionne l’infrastructure Azure, y compris les ressources Azure Container Apps. Examinez les exigences de coût et de gouvernance Azure de votre organisation avant le déploiement.

Créer un agent avec un interpréteur de code personnalisé

Les étapes suivantes montrent comment approvisionner l’infrastructure et créer un agent qui utilise un serveur MCP d’interpréteur de code personnalisé. La configuration de l’infrastructure s’applique à toutes les langues. Les exemples de code spécifiques à la langue suivent.

Inscrire la fonctionnalité d’aperçu

Inscrivez la fonctionnalité de serveur MCP pour Azure Container Apps sessions dynamiques :

az feature register --namespace Microsoft.App --name SessionPoolsSupportMCP
az provider register -n Microsoft.App

Obtenir l’exemple de code

Clonez le code sample dans le référentiel GitHub et accédez au dossier samples/python/prompt-agents/code-interpreter-custom de votre terminal.

Provisionner l’infrastructure

Pour approvisionner l’infrastructure, exécutez la commande suivante à l’aide du Azure CLI (az) :

az deployment group create \
    --name custom-code-interpreter \
    --subscription <your_subscription> \
    --resource-group <your_resource_group> \
    --template-file ./infra.bicep

Note

Le déploiement peut prendre jusqu’à une heure, en fonction du nombre d’instances de secours que vous demandez. L’allocation de pool de sessions dynamiques est l’étape la plus longue.

Configurer et exécuter l’agent

Copiez le fichier .env.sample du référentiel vers .env et renseignez les valeurs à partir du résultat de votre déploiement. Vous trouverez ces valeurs dans le portail Azure sous le groupe de ressources.

Installez les dépendances Python à l’aide de uv sync ou pip install. Enfin, exécutez ./main.py.

Exemple de code

L’exemple de Python suivant montre comment créer un agent avec un outil MCP de l’interpréteur de code personnalisé :

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, MCPTool

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
MCP_SERVER_URL = "https://your-mcp-server-url"
# Optional: set to your project connection ID if your MCP server requires authentication
MCP_CONNECTION_ID = "your-mcp-connection-id"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Configure the custom code interpreter MCP tool
custom_code_interpreter = MCPTool(
    server_label="custom-code-interpreter",
    server_url=MCP_SERVER_URL,
    project_connection_id=MCP_CONNECTION_ID,
)

# Create an agent with the custom code interpreter
agent = project.agents.create_version(
    agent_name="CustomCodeInterpreterAgent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can run Python code to analyze data and solve problems.",
        tools=[custom_code_interpreter],
    ),
    description="Agent with custom code interpreter for data analysis.",
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

# Test the agent with a simple calculation
response = openai.responses.create(
    input="Calculate the factorial of 10 using Python.",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(f"Response: {response.output_text}")

# Clean up
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")

Sortie attendue

Lorsque vous exécutez l’exemple, vous voyez une sortie similaire à :

Agent created (id: agent-xxxxxxxxxxxx, name: CustomCodeInterpreterAgent, version: 1)
Response: The factorial of 10 is 3,628,800. I calculated this using Python's math.factorial() function.
Agent deleted

Exemple de code

L’exemple C# suivant montre comment créer un agent avec un outil MCP de l’interpréteur de code personnalisé. Pour plus d’informations sur l’utilisation des outils MCP dans .NET, consultez l’exemple d’outil MCP dans le Azure SDK pour .NET référentiel sur GitHub.

using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var mcpServerUrl = "https://your-mcp-server-url";
// Optional: set to your project connection ID if your MCP server requires authentication
var mcpConnectionId = "your-mcp-connection-id";

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create agent with custom code interpreter MCP tool
// Code runs in a sandboxed Azure Container Apps session
McpTool tool = ResponseTool.CreateMcpTool(
    serverLabel: "custom-code-interpreter",
    serverUri: new Uri(mcpServerUrl));
tool.ProjectConnectionId = mcpConnectionId;

PromptAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant that can run Python code to analyze data and solve problems.",
    Tools = { tool }
};

AgentVersion agent = projectClient.Agents.CreateAgentVersion(
    agentName: "CustomCodeInterpreterAgent",
    options: new(agentDefinition));

Console.WriteLine($"Agent created: {agent.Name} (version {agent.Version})");

// Create a response using the agent
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agent.Name);

ResponseResult response = responseClient.CreateResponse(
    new([ResponseItem.CreateUserMessageItem("Calculate the factorial of 10 using Python.")]));

Console.WriteLine(response.GetOutputText());

// Clean up
projectClient.Agents.DeleteAgentVersion(
    agentName: agent.Name,
    agentVersion: agent.Version);
Console.WriteLine("Agent deleted");

Sortie attendue

Agent created: CustomCodeInterpreterAgent (version 1)
The factorial of 10 is 3,628,800.
Agent deleted

Exemple de code

L’exemple TypeScript suivant montre comment créer un agent avec un outil MCP de l’interpréteur de code personnalisé. Pour obtenir une version javaScript, consultez l’exemple d’outil MCP dans le Azure SDK du référentiel JavaScript sur GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const MCP_SERVER_URL = "https://your-mcp-server-url";

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create agent with custom code interpreter MCP tool
  // The custom code interpreter uses require_approval: "never" because code
  // runs in a sandboxed Azure Container Apps session
  const agent = await project.agents.createVersion("CustomCodeInterpreterAgent", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions:
      "You are a helpful assistant that can run Python code to analyze data and solve problems.",
    tools: [
      {
        type: "mcp",
        server_label: "custom-code-interpreter",
        server_url: MCP_SERVER_URL,
        require_approval: "never",
      },
    ],
  });
  console.log(`Agent created (name: ${agent.name}, version: ${agent.version})`);

  // Send a request to the agent
  const response = await openai.responses.create(
    {
      input: "Calculate the factorial of 10 using Python.",
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );
  console.log(`Response: ${response.output_text}`);

  // Clean up
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Sortie attendue

Agent created (name: CustomCodeInterpreterAgent, version: 1)
Response: The factorial of 10 is 3,628,800. I calculated this using Python's math.factorial() function.
Agent deleted

Ajoutez la dépendance à votre pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.0.0-beta.1</version>
</dependency>

Exemple de code

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.McpTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.core.util.BinaryData;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Collections;

public class CustomCodeInterpreterExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";
        String mcpServerUrl = "https://your-mcp-server-url";
        // Optional: set to your project connection ID if your MCP server requires authentication
        String mcpConnectionId = "your-mcp-connection-id";

        // Create clients to call Foundry API
        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // Create custom code interpreter MCP tool
        // Uses require_approval: "never" because code runs in a sandboxed Container Apps session
        McpTool customCodeInterpreter = new McpTool("custom-code-interpreter")
            .setServerUrl(mcpServerUrl)
            .setProjectConnectionId(mcpConnectionId)
            .setRequireApproval(BinaryData.fromString("\"never\""));

        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini")
            .setInstructions("You are a helpful assistant that can run Python code to analyze data and solve problems.")
            .setTools(Collections.singletonList(customCodeInterpreter));

        AgentVersionDetails agent = agentsClient.createAgentVersion(
            "CustomCodeInterpreterAgent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createWithAgent(
            agentReference,
            ResponseCreateParams.builder()
                .input("Calculate the factorial of 10 using Python."));

        System.out.println("Response: " + response.output());

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
        System.out.println("Agent deleted");
    }
}

Sortie attendue

Agent created: CustomCodeInterpreterAgent (version 1)
Response: The factorial of 10 is 3,628,800.
Agent deleted

Prerequisites

Définissez ces variables d’environnement :

  • FOUNDRY_PROJECT_ENDPOINT: URL du point de terminaison de votre projet.
  • AGENT_TOKEN : jeton du porteur pour Foundry.

Obtenez un jeton d’accès :

export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

Exemple de code

1. Créer un agent avec un interpréteur de code personnalisé

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "CustomCodeInterpreterAgent",
    "definition": {
      "kind": "prompt",
      "model": "<MODEL_DEPLOYMENT>",
      "instructions": "You are a helpful assistant that can run Python code to analyze data and solve problems.",
      "tools": [
        {
          "type": "mcp",
          "server_label": "custom-code-interpreter",
          "server_url": "<MCP_SERVER_URL>",
          "project_connection_id": "<MCP_PROJECT_CONNECTION_ID>",
          "require_approval": "never"
        }
      ]
    }
  }'

2. Créer une réponse

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "agent_reference": {"type": "agent_reference", "name": "CustomCodeInterpreterAgent"},
    "input": "Calculate the factorial of 10 using Python."
  }'

3. Nettoyer

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/CustomCodeInterpreterAgent?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Sortie attendue

{
  "id": "resp_xxxxxxxxxxxx",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The factorial of 10 is 3,628,800."
        }
      ]
    }
  ]
}

Vérifier votre configuration

Après avoir provisionné l’infrastructure et exécuté l’exemple :

  1. Vérifiez que le déploiement Azure s’est terminé avec succès.
  2. Confirmez que l’exemple se connecte en utilisant les valeurs de votre fichier .env.
  3. Dans Microsoft Foundry, vérifiez que votre agent appelle l’outil à l’aide du traçage. Pour plus d’informations, consultez les meilleures pratiques pour l’utilisation d’outils dans le service Microsoft Foundry Agent.

Résolution des problèmes

Problème Cause probable Résolution
L'enregistrement des fonctionnalités est toujours en cours La commande az feature register renvoie l’état Registering. Attendez que l’inscription soit terminée (peut prendre 15 à 30 minutes). Vérifiez l’état avec az feature show --namespace Microsoft.App --name SessionPoolsSupportMCP. Ensuite, réexécutez az provider register -n Microsoft.App .
Le déploiement échoue avec une erreur d’autorisation Les attributions de rôles requises sont manquantes. Vérifiez que vous avez les rôles Azure AI Owner et Container Apps ManagedEnvironment Contributor sur l’abonnement ou le groupe de ressources.
Échec du déploiement avec une erreur de région La région sélectionnée ne prend pas en charge Azure Container Apps sessions dynamiques. Essayez une autre région. Consultez Azure Container Apps régions pour les régions prises en charge.
L’agent n’appelle pas l’outil La connexion MCP n’est pas configurée correctement, ou les instructions de l’agent n’invitent pas l’outil à utiliser. Utilisez le suivi dans Microsoft Foundry pour confirmer l’appel de l’outil. Vérifiez que MCP_SERVER_URL correspond à votre point de terminaison de Container Apps déployé. Consultez Bonnes pratiques.
Délai d’expiration de la connexion au serveur MCP Le pool de sessions Container Apps n’est pas en cours d’exécution ou n’a pas d’instances de secours. Vérifiez l’état du pool de sessions dans le portail Azure. Augmentez standbyInstanceCount dans votre modèle de Bicep si nécessaire.
Échec de l’exécution du code dans le conteneur Packages Python manquants dans le conteneur personnalisé. Mettez à jour votre image conteneur pour inclure les packages requis. Regénérer et redéployer le conteneur.
Erreur d’authentification lors de la connexion au serveur MCP Les informations d’identification de connexion du projet ne sont pas valides ou expirées. Régénérez les informations d’identification de connexion et mettez à jour le .env fichier. Vérifiez le MCP_PROJECT_CONNECTION_ID format.

Limites

Les API ne prennent pas directement en charge l’entrée ou la sortie de fichier, ou l’utilisation de magasins de fichiers. Pour transférer des données, vous devez utiliser des URL, par exemple des URL de données pour des petits fichiers et des URLs de service Blob Azure à signature d'accès partagé (SAP) pour des fichiers de grande taille.

Sécurité

Si vous utilisez des URL SAS pour transmettre des données dans ou hors du runtime :

  • Utilisez des jetons SAP de courte durée.
  • Ne consignez pas les URL SAP ni stockez-les dans le contrôle de code source.
  • Définir les autorisations au minimum requis (par exemple, lecture seule ou écriture seule).

Nettoyage

Pour arrêter la facturation des ressources approvisionnées, supprimez les ressources créées par l’exemple de déploiement. Si vous avez utilisé un groupe de ressources dédié pour cet article, supprimez le groupe de ressources.

Contenu connexe

  • Last updated on