Partage via

Outil Interpréteur de code pour les agents Microsoft Foundry

L’interpréteur de code permet à un agent Microsoft Foundry d’exécuter Python code dans un environnement d’exécution en bac à sable (sandbox). Utilisez cet outil pour l’analyse des données, la génération de graphiques et les tâches de résolution de problèmes itératives qui bénéficient de l’exécution du code.

Dans cet article, vous allez créer un agent qui utilise l’interpréteur de code, charger un fichier CSV pour l’analyse et télécharger un graphique généré.

Lorsque vous activez l’interpréteur de code, votre agent peut écrire et exécuter du code Python de manière itérative pour résoudre les tâches mathématiques et d’analyse des données et générer des graphiques.

Important

L’interpréteur de code a des frais supplémentaires au-delà des frais basés sur les jetons pour l’utilisation d’Azure OpenAI. Si votre agent appelle l’interpréteur de code simultanément dans deux conversations différentes, il crée deux sessions d’interpréteur de code. Chaque session est active par défaut pendant une heure avec un délai d’inactivité de 30 minutes.

Assistance à l'utilisation

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

Prerequisites

  • Environnement d’agent de base ou standard. Pour plus d’informations, consultez la configuration de l’environnement de l’agent .
  • Package sdk le plus récent installé pour votre langue. Les sdk .NET et Java sont actuellement en préversion. Consultez le guide de démarrage rapide pour connaître les étapes d’installation.
  • Le déploiement du modèle d'Azure IA qui est configuré dans votre projet.
  • Pour les opérations de fichier : CSV ou d’autres fichiers pris en charge à charger pour l’analyse.

Note

L’interpréteur de code n’est pas disponible dans toutes les régions. Consultez Vérifier la disponibilité régionale et de modèle.

Créer un agent avec l’interpréteur de code

Les exemples suivants montrent comment créer un agent avec l’interpréteur de code activé, charger un fichier pour analyse et télécharger la sortie générée.

Exemple d’utilisation de l’agent avec l’outil interpréteur de code dans Python SDK

L’exemple de Python suivant montre comment créer un agent avec l’outil d’interpréteur de code, charger un fichier CSV pour l’analyse et demander un graphique à barres en fonction des données. Il illustre un flux de travail complet : charger un fichier, créer un agent avec l’interpréteur de code activé, demander la visualisation des données et télécharger le graphique généré.

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, CodeInterpreterTool, AutoCodeInterpreterToolParam

# Load the CSV file to be processed
asset_file_path = os.path.abspath(
    os.path.join(os.path.dirname(__file__), "../assets/synthetic_500_quarterly_results.csv")
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

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

# Upload the CSV file for the code interpreter to use
file = openai.files.create(purpose="assistants", file=open(asset_file_path, "rb"))

# Create agent with code interpreter tool
agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant.",
        tools=[CodeInterpreterTool(container=AutoCodeInterpreterToolParam(file_ids=[file.id]))],
    ),
    description="Code interpreter agent for data analysis and visualization.",
)

# Create a conversation for the agent interaction
conversation = openai.conversations.create()

# Send request to create a chart and generate a file
response = openai.responses.create(
    conversation=conversation.id,
    input="Could you please create bar chart in TRANSPORTATION sector for the operating profit from the uploaded csv file and provide file to me?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

# Extract file information from response annotations
file_id = ""
filename = ""
container_id = ""

# Get the last message which should contain file citations
last_message = response.output[-1]  # ResponseOutputMessage
if (
    last_message.type == "message"
    and last_message.content
    and last_message.content[-1].type == "output_text"
    and last_message.content[-1].annotations
):
    file_citation = last_message.content[-1].annotations[-1]  # AnnotationContainerFileCitation
    if file_citation.type == "container_file_citation":
        file_id = file_citation.file_id
        filename = file_citation.filename
        container_id = file_citation.container_id
        print(f"Found generated file: {filename} (ID: {file_id})")

# Clean up resources
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

# Download the generated file if available
if file_id and filename:
    file_content = openai.containers.files.content.retrieve(file_id=file_id, container_id=container_id)
    print(f"File ready for download: {filename}")
    file_path = os.path.join(os.path.dirname(__file__), filename)
    with open(file_path, "wb") as f:
        f.write(file_content.read())
    print(f"File downloaded successfully: {file_path}")
else:
    print("No file generated in response")

Sortie attendue

L’exemple de code produit une sortie similaire à l’exemple suivant :

Found generated file: transportation_operating_profit_bar_chart.png (ID: file-xxxxxxxxxxxxxxxxxxxx)
File ready for download: transportation_operating_profit_bar_chart.png
File downloaded successfully: transportation_operating_profit_bar_chart.png

L’agent charge votre fichier CSV dans Azure stockage, crée un environnement de Python en bac à sable( sandbox), analyse les données pour filtrer les enregistrements du secteur des transports, génère un graphique à barres PNG affichant le bénéfice d’exploitation par trimestre et télécharge le graphique dans votre répertoire local. Les annotations de fichier dans la réponse fournissent l’ID de fichier et les informations de conteneur nécessaires pour récupérer le graphique généré.

Créer un graphique avec l’interpréteur de code en C#

L’exemple C# suivant montre comment créer un agent avec l’outil interpréteur de code et l’utiliser pour générer un graphique à barres. L’agent écrit et exécute Python code (à l’aide de matplotlib) dans un conteneur en bac à sable (sandbox). Pour une utilisation asynchrone, consultez l’exemple de code dans le référentiel .NET du Kit de développement logiciel (SDK) Azure pour .NET sur GitHub.

using System;
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";

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

// Create an agent with Code Interpreter enabled.
PromptAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a data visualization assistant. When asked to create charts, write and run Python code using matplotlib to generate them.",
    Tools = {
        ResponseTool.CreateCodeInterpreterTool(
            new CodeInterpreterToolContainer(
                CodeInterpreterToolContainerConfiguration.CreateAutomaticContainerConfiguration(
                    fileIds: []
                )
            )
        ),
    }
};
AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
    agentName: "myChartAgent",
    options: new(agentDefinition));

// Ask the agent to create a bar chart from inline data.
AgentReference agentReference = new(name: agentVersion.Name, version: agentVersion.Version);
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentReference);

ResponseResult response = responseClient.CreateResponse(
    "Create a bar chart showing quarterly revenue for 2025: Q1=$2.1M, Q2=$2.8M, Q3=$3.2M, Q4=$2.9M. " +
    "Use a blue color scheme, add data labels on each bar, and title the chart 'Quarterly Revenue 2025'. " +
    "Save the chart as a PNG file.");

Console.WriteLine(response.GetOutputText());

// Clean up
projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Sortie attendue

L’exemple de code produit une sortie similaire à l’exemple suivant :

Here is the bar chart showing quarterly revenue for 2025. The chart displays Q1 ($2.1M), Q2 ($2.8M), Q3 ($3.2M), and Q4 ($2.9M) with a blue color scheme, data labels on each bar, and the title "Quarterly Revenue 2025".

L’agent crée une session Interpréteur de code, écrit du code Python à l’aide de matplotlib pour générer le graphique à barres, exécute le code dans un environnement bac à sable et retourne le graphique en tant que fichier généré. Pour obtenir un exemple qui charge un fichier CSV et télécharge le graphique généré, sélectionnez Python ou TypeScript dans le sélecteur de langue en haut de cet article.

Exemple d’utilisation de l’agent avec l’outil interpréteur de code dans le Kit de développement logiciel (SDK) TypeScript

L’exemple TypeScript suivant montre comment créer un agent avec l’outil d’interpréteur de code, charger un fichier CSV pour l’analyse et demander un graphique à barres en fonction des données. Pour obtenir une version JavaScript, consultez l'exemple JavaScript dans l'Azure SDK du dépôt JavaScript sur GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";
import { fileURLToPath } from "url";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";

// Helper to resolve asset file path
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

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

  // Load and upload CSV file
  const assetFilePath = path.resolve(
    __dirname,
    "../assets/synthetic_500_quarterly_results.csv",
  );
  const fileStream = fs.createReadStream(assetFilePath);

  // Upload CSV file
  const uploadedFile = await openai.files.create({
    file: fileStream,
    purpose: "assistants",
  });

  // Create agent with Code Interpreter tool
  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "You are a helpful assistant.",
    tools: [
      {
        type: "code_interpreter",
        container: {
          type: "auto",
          file_ids: [uploadedFile.id],
        },
      },
    ],
  });

  // Create a conversation
  const conversation = await openai.conversations.create();

  // Request chart generation
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input:
        "Could you please create bar chart in TRANSPORTATION sector for the operating profit from the uploaded csv file and provide file to me?",
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );

  // Extract file information from response annotations
  let fileId = "";
  let filename = "";
  let containerId = "";

  // Get the last message which should contain file citations
  const lastMessage = response.output?.[response.output.length - 1];
  if (lastMessage && lastMessage.type === "message") {
    // Get the last content item
    const textContent = lastMessage.content?.[lastMessage.content.length - 1];
    if (textContent && textContent.type === "output_text" && textContent.annotations) {
      // Get the last annotation (most recent file)
      const fileCitation = textContent.annotations[textContent.annotations.length - 1];
      if (fileCitation && fileCitation.type === "container_file_citation") {
        fileId = fileCitation.file_id;
        filename = fileCitation.filename;
        containerId = fileCitation.container_id;
        console.log(`Found generated file: ${filename} (ID: ${fileId})`);
      }
    }
  }

  // Download the generated file if available
  if (fileId && filename) {
    const safeFilename = path.basename(filename);
    const fileContent = await openai.containers.files.content.retrieve({
      file_id: fileId,
      container_id: containerId,
    });

    // Read the readable stream into a buffer
    const chunks: Buffer[] = [];
    for await (const chunk of fileContent.body) {
      chunks.push(Buffer.from(chunk));
    }
    const buffer = Buffer.concat(chunks);

    fs.writeFileSync(safeFilename, buffer);
    console.log(`File ${safeFilename} downloaded successfully.`);
    console.log(`File ready for download: ${safeFilename}`);
  } else {
    console.log("No file generated in response");
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
}

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

Sortie attendue

L’exemple de code produit une sortie similaire à l’exemple suivant :

Found generated file: transportation_operating_profit_bar_chart.png (ID: file-xxxxxxxxxxxxxxxxxxxx)
File transportation_operating_profit_bar_chart.png downloaded successfully.
File ready for download: transportation_operating_profit_bar_chart.png

L’agent charge votre fichier CSV dans Azure stockage, crée un environnement de Python en bac à sable( sandbox), analyse les données pour filtrer les enregistrements du secteur des transports, génère un graphique à barres PNG affichant le bénéfice d’exploitation par trimestre et télécharge le graphique dans votre répertoire local. Les annotations de fichier dans la réponse fournissent l’ID de fichier et les informations de conteneur nécessaires pour récupérer le graphique généré.

Créer un graphique avec l’interpréteur de code dans Java

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>

Créer un agent et générer un graphique

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.CodeInterpreterTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Collections;

public class CodeInterpreterChartExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

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

        // Create code interpreter tool
        CodeInterpreterTool codeInterpreter = new CodeInterpreterTool();

        // Create agent with code interpreter for data visualization
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini")
            .setInstructions("You are a data visualization assistant. When asked to create charts, "
                + "write and run Python code using matplotlib to generate them.")
            .setTools(Collections.singletonList(codeInterpreter));

        AgentVersionDetails agent = agentsClient.createAgentVersion("chart-agent", agentDefinition);

        // Request a bar chart with inline data
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createWithAgent(
            agentReference,
            ResponseCreateParams.builder()
                .input("Create a bar chart showing quarterly revenue for 2025: "
                    + "Q1=$2.1M, Q2=$2.8M, Q3=$3.2M, Q4=$2.9M. "
                    + "Use a blue color scheme, add data labels on each bar, "
                    + "and title the chart 'Quarterly Revenue 2025'. "
                    + "Save the chart as a PNG file."));

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

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}

Sortie attendue

Response: Here is the bar chart showing quarterly revenue for 2025 with Q1 ($2.1M), Q2 ($2.8M), Q3 ($3.2M), and Q4 ($2.9M) displayed in blue with data labels.

L’agent crée une session Interpréteur de code, écrit du code Python à l’aide de matplotlib pour générer le graphique et exécute le code dans un environnement bac à sable (sandbox). Pour obtenir un exemple qui charge un fichier CSV et télécharge le graphique généré, sélectionnez Python ou TypeScript dans le sélecteur de langue en haut de cet article. Pour plus d’exemples, consultez les exemples Java SDK pour les agents Azure AI.

Créer un graphique avec l’interpréteur de code à l’aide de l’API REST

L’exemple suivant montre comment charger un fichier CSV, créer un agent avec l’interpréteur de code, demander un graphique et télécharger le fichier généré.

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)

1. Charger un fichier CSV

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/files" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -F "purpose=assistants" \
  -F "file=@quarterly_results.csv"

Enregistrez le id de la réponse (par exemple, file-abc123).

2. Créer un agent avec l’interpréteur de code

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "chart-agent",
    "definition": {
      "kind": "prompt",
      "model": "<MODEL_DEPLOYMENT>",
      "instructions": "You are a data visualization assistant. When asked to create charts, write and run Python code using matplotlib to generate them.",
      "tools": [
        {
          "type": "code_interpreter",
          "container": {
            "type": "auto",
            "file_ids": ["<FILE_ID>"]
          }
        }
      ]
    }
  }'

3. Générer un graphique

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": "chart-agent"},
    "input": "Create a bar chart of operating profit by quarter from the uploaded CSV file. Use a blue color scheme and add data labels."
  }'

La réponse inclut container_file_citation des annotations avec les détails du fichier généré. Enregistrez les valeurs container_id et file_id de l’annotation.

4. Télécharger le graphique généré

curl -X GET "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/containers/<CONTAINER_ID>/files/<FILE_ID>/content" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  --output chart.png

5. Nettoyage

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

Vérifier la disponibilité des régions et des modèles

La disponibilité des outils varie selon la région et le modèle.

Pour obtenir la liste actuelle des régions et modèles pris en charge pour l’interpréteur de code, consultez les meilleures pratiques pour l’utilisation d’outils dans le service Microsoft Foundry Agent.

Types de fichiers pris en charge

Format de fichier MIME type
.c text/x-c
.cpp text/x-c++
.csv application/csv
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html text/html
.java text/x-java
.json application/json
.md text/markdown
.pdf application/pdf
.php text/x-php
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.py text/x-python
.py text/x-script.python
.rb text/x-ruby
.tex text/x-tex
.txt text/plain
.css text/css
.jpeg image/jpeg
.jpg image/jpeg
.js text/javascript
.gif image/gif
.png image/png
.tar application/x-tar
.ts application/typescript
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml ou text/xml
.zip application/zip

Résolution des problèmes

Problème Cause probable Résolution
L’interpréteur de code ne s’exécute pas. L'outil n'est pas activé ou le modèle ne le prend pas en charge dans votre zone géographique. Vérifiez que l’interpréteur de code est activé sur l’agent. Vérifiez que votre déploiement de modèle prend en charge l’outil dans votre région. Consultez Vérifier la disponibilité régionale et de modèle.
Aucun fichier n’est généré. L’agent a retourné une réponse texte seule sans annotation de fichier. Vérifiez les annotations de réponse pour container_file_citation. S’il n’existe aucun fichier, l’agent n’a pas généré de fichier. Réécrire la demande pour demander explicitement la sortie du fichier.
Échec du chargement du fichier. Type de fichier non pris en charge ou objectif incorrect. Vérifiez que le type de fichier figure dans la liste des types de fichiers pris en charge . Charger avec purpose="assistants".
Le fichier généré est endommagé ou vide. Erreur d’exécution du code ou traitement incomplet. Vérifiez la réponse de l’agent pour les messages d’erreur. Vérifiez que les données d’entrée sont valides. Essayez d’abord une demande plus simple.
Délai d’expiration de session ou latence élevée. Les sessions Interpréteur de code ont des limites de temps. Les sessions ont un délai d’expiration actif de 1 heure et un délai d’inactivité de 30 minutes. Réduisez la complexité des opérations ou fractionnez-les en tâches plus petites.
Frais de facturation inattendus. Plusieurs sessions simultanées créées. Chaque conversation crée une session distincte. Surveillez l’utilisation de la session et consolidez les opérations le cas échéant.
Python package non disponible. L’interpréteur de code a un ensemble fixe de packages. L’interpréteur de code inclut des packages de science des données courants. Pour les packages personnalisés, utilisez l’interpréteur de code personnalisé.
Échec du téléchargement du fichier. ID de conteneur ou ID de fichier incorrect. Vérifiez que vous utilisez les bons container_id et file_id à partir des annotations de réponse.

Nettoyer les ressources

Supprimez les ressources que vous avez créées dans cet exemple lorsque vous n’en avez plus besoin pour éviter les coûts en cours :

  • Supprimez la version de l’agent.
  • Supprimez la conversation.
  • Supprimez les fichiers chargés.

Pour obtenir des exemples de modèles de nettoyage de conversation et de fichier, consultez l’outil de recherche web (préversion) et l’outil de recherche de fichiers pour les agents.

Environnement d’exécution en bac à sable

L’interpréteur de code exécute du code Python dans un bac à sable géré par Microsoft. Le bac à sable est conçu pour exécuter du code non approuvé et utilise des sessions dynamiques (sessions d’interpréteur de code) dans Azure Container Apps. Chaque session est isolée par une limite de Hyper-V.

Comportements clés à planifier :

  • Région : le bac à sable de l’interpréteur de code s’exécute dans la même région Azure que votre projet Foundry.
  • Durée de vie de la session : une session Interpréteur de code est active pendant une heure maximum, avec un délai d’inactivité (voir la note importante au début de cet article).
  • Isolation : chaque session s’exécute dans un environnement isolé. Si votre agent appelle l’interpréteur de code simultanément dans différentes conversations, des sessions distinctes sont créées.
  • Isolation réseau et accès Internet : le bac à sable n’hérite pas de la configuration de votre sous-réseau d’agent, et les sessions dynamiques ne peuvent pas effectuer de requêtes réseau sortantes.
  • Fichiers dans le bac à sable : le runtime Python en bac à sable a accès aux fichiers que vous attachez pour analyse. L’interpréteur de code peut également générer des fichiers, tels que des graphiques, et les retourner sous forme de sorties téléchargeables.

Si vous avez besoin de plus de contrôle sur l'environnement d'exécution de la sandbox ou si vous avez besoin d'un modèle d’isolation différent, référez-vous à l’outil d’interpréteur de code personnalisé pour les agents.

Contenu connexe

  • Last updated on