Interpréteur de code Azure AI Agent Service

Article
02/27/2025

L’interpréteur de code permet aux agents d’écrire et d’exécuter du code Python dans un environnement d’exécution en mode sandbox (bac à sable). Une fois l’interpréteur de code activé, votre agent peut exécuter du code de manière itérative pour résoudre des problèmes de code, de mathématiques et d’analyse de données plus complexes. Quand votre agent écrit du code qui ne s’exécute pas, il peut itérer au sein de ce code en modifiant et en exécutant un code distinct jusqu’à la réussite de l’exécution du code.

Important

L’Interpréteur de code comporte des frais supplémentaires au-delà des frais basés sur le jeton pour l’utilisation d’Azure OpenAI. Si votre agent appelle l’interpréteur de code simultanément dans deux threads distincts, deux sessions d’interpréteur de code sont créées. Chaque session est active pendant une heure par défaut.

Modèles pris en charge

La page des modèles contient les informations les plus récentes sur les régions/modèles où les agents et l’interpréteur de code sont pris en charge.

Nous vous recommandons d’utiliser des agents avec les derniers modèles pour tirer parti des nouvelles fonctionnalités, des fenêtres de contexte plus grandes et des données d’apprentissage plus à jour.

Prise en charge de l’utilisation

Prise en charge d’Azure AI Foundry	Kit de développement logiciel (SDK) Python	Kit de développement logiciel (SDK) C#	Kit de développement logiciel (SDK) JavaScript	API REST	Configuration d’agent de base	Configuration d’agent standard
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Utilisation de l’outil d’interpréteur de code avec un agent

Vous pouvez ajouter l’outil d’interpréteur de code à un agent de façon programmatique à l’aide des exemples de code répertoriés en haut de cet article ou proposés dans le portail Azure AI Foundry. Si vous souhaitez utiliser le portail :

Dans l’écran Créer et déboguer de votre agent, faites défiler vers le bas le volet Configuration à droite jusqu’à action. Sélectionnez ensuite Ajouter.
Sélectionnez Interpréteur de code et suivez les invites pour ajouter l’outil.
Si vous le souhaitez, vous pouvez charger des fichiers pour que votre agent puisse lire et interpréter des informations à partir de jeux de données, générer du code et créer des graphiques et des diagrammes à l’aide de vos données.

Créer un client de projet

Pour utiliser l’interpréteur de code, ajoutez d’abord les instructions import présentées dans l’exemple, puis créez un client de projet, qui contiendra une chaîne de connexion à votre projet IA, et sera utilisé pour authentifier les appels d’API.

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import CodeInterpreterTool
from azure.ai.projects.models import FilePurpose
from azure.identity import DefaultAzureCredential
from pathlib import Path

# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(), conn_str=os.environ["PROJECT_CONNECTION_STRING"]
)

Pour utiliser l’interpréteur de code, créez d’abord un client de projet, qui contiendra une chaîne de connexion à votre projet IA, et sera utilisé pour authentifier les appels d’API.

var connectionString = Environment.GetEnvironmentVariable("PROJECT_CONNECTION_STRING");
AgentsClient client = new AgentsClient(connectionString, new DefaultAzureCredential());

Pour utiliser l’interpréteur de code, créez d’abord un client de projet, qui contiendra une chaîne de connexion à votre projet IA, et sera utilisé pour authentifier les appels d’API.

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set.");
}
const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
);

Charger un fichier

Chargez le fichier à l’aide de la fonction upload_and_poll(), en spécifiant le chemin d’accès du fichier et l’objectif FilePurpose.AGENTS.

# Upload a file and add it to the client 
file = project_client.agents.upload_file_and_poll(
    file_path="nifty_500_quarterly_results.csv", purpose=FilePurpose.AGENTS
)
print(f"Uploaded file, file ID: {file.id}")

Les fichiers peuvent être chargés, puis référencés par des agents ou des messages. Utilisez d’abord l’API de chargement généralisé avec un purposeAgents pour rendre un ID de fichier disponible. Une fois le chargement effectué, l’ID de fichier peut être fourni afin de créer un magasin de vecteurs pour celui-ci. L’ID de magasin de vecteurs peut ensuite être fourni à un agent au moment de la création.

Remarque

Vous n’avez pas besoin de fournir toolResources si vous ne créez pas de magasin de vecteurs.

// Upload a file and wait for it to be processed
Response<AgentFile> uploadAgentFileResponse = await client.UploadFileAsync(
    filePath: "sample_file_for_upload.txt",
    purpose: AgentFilePurpose.Agents);

AgentFile uploadedAgentFile = uploadAgentFileResponse.Value;

// Create a vector store with the file and wait for it to be processed.
// If you do not specify a vector store, create_message will create a vector store with a default expiration policy of seven days after they were last active
VectorStore vectorStore = await client.CreateVectorStoreAsync(
    fileIds:  new List<string> { uploadedAgentFile.Id },
    name: "my_vector_store");

CodeInterpreterToolResource codeInterpreterToolResource = new CodeInterpreterToolResource();
CodeInterpreterToolResource.VectorStoreIds.Add(vectorStore.Id);

Les fichiers peuvent être chargés, puis référencés par des agents ou des messages. Une fois chargé, l’interpréteur de code peut être ajouté à l’utilitaire d’outil pour référencement.

const fileStream = fs.createReadStream("nifty_500_quarterly_results.csv");
const fFile = await client.agents.uploadFile(fileStream, "assistants", {
  fileName: "nifty_500_quarterly_results.csv",
});
console.log(`Uploaded local file, file ID : ${file.id}`);

const codeInterpreterTool = ToolUtility.createCodeInterpreterTool([file.id]);

curl $AZURE_AI_AGENTS_ENDPOINT/files?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -F purpose="assistants" \
  -F file="@c:\\path_to_file\\file.csv"

Créer un agent avec l’outil Interpréteur de code

Définissez l’outil code_interpreter avec CodeInterpreterTool(), puis incluez l’ID du fichier que vous avez chargé. Créez ensuite l’agent avec tools ayant la valeur code_interpreter.definitions, et tool_resources ayant la valeur code_interpreter.resources.


code_interpreter = CodeInterpreterTool(file_ids=[file.id])

# create agent with code interpreter tool and tools_resources
agent = project_client.agents.create_agent(
    model="gpt-4o-mini",
    name="my-agent",
    instructions="You are helpful agent",
    tools=code_interpreter.definitions,
    tool_resources=code_interpreter.resources,
)

Response<Agent> agentResponse = await client.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "My agent",
    instructions: "You are a helpful agent.",
    tools: new List<ToolDefinition> { new CodeInterpreterToolDefinition() },
    toolResources: new ToolResources() { CodeInterpreter = codeInterpreterToolResource });
Agent agent = agentResponse.Value;

// Notice that CodeInterpreter must be enabled in the agent creation, otherwise the agent will not be able to see the file attachment
const agent = await client.agents.createAgent("gpt-4o-mini", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: [codeInterpreterTool.definition],
  toolResources: codeInterpreterTool.resources,
});
console.log(`Created agent, agent ID: ${agent.id}`);

curl $AZURE_AI_AGENTS_ENDPOINT/assistants?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4o-mini",
    "tool_resources"{
      "code interpreter": {
          "file_ids": ["assistant-1234"]
      }
    }
  }'

Créer un thread, un message, et obtenir la réponse de l’agent

Créez ensuite un thread avec create_thread(), puis attachez un message à celui-ci à l’aide de create_message(), ce qui déclenche l’outil Interpréteur de code. Créez et lancez ensuite une exécution avec create_and_process_run(). Une fois l’exécution terminée, vous pouvez supprimer le fichier de l’agent avec delete_file() pour libérer de l’espace dans l’agent. Pour finir, imprimez les messages de l’agent.

# create a thread
thread = project_client.agents.create_thread()
print(f"Created thread, thread ID: {thread.id}")

# create a message
message = project_client.agents.create_message(
    thread_id=thread.id,
    role="user",
    content="Could you please create bar chart in the TRANSPORTATION sector for the operating profit from the uploaded csv file and provide file to me?",
)
print(f"Created message, message ID: {message.id}")

# create and execute a run
run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
print(f"Run finished with status: {run.status}")

if run.status == "failed":
    # Check if you got "Rate limit is exceeded.", then you want to get more quota
    print(f"Run failed: {run.last_error}")

# delete the original file from the agent to free up space (note: this does not delete your version of the file)
project_client.agents.delete_file(file.id)
print("Deleted file")

# print the messages from the agent
messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")

# get the most recent message from the assistant
last_msg = messages.get_last_text_message_by_sender("assistant")
if last_msg:
    print(f"Last Message: {last_msg.text.value}")

Créez ensuite un thread avec CreateThreadAsync(), et un thread avec CreateMessageAsync(). Une fois le thread créé, vous pouvez lui ajouter des messages avec CreateMessageAsync(), ce qui entraîne le déclenchement de l’outil Interpréteur de code. Créez une exécution, puis continuez à l’interroger jusqu’à ce qu’elle atteigne un état terminal. En partant du principe que l’exécution a réussi, analysez la réponse de l’agent en listant les messages.

//Create a thread
Response<AgentThread> threadResponse = await client.CreateThreadAsync();
AgentThread thread = threadResponse.Value;

//With a thread created, messages can be created on it:
Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "I need to solve the equation `3x + 11 = 14`. Can you help me?");
ThreadMessage message = messageResponse.Value;

//A run can then be started that evaluates the thread against an agent:
Response<ThreadRun> runResponse = await client.CreateRunAsync(
    thread.Id,
    agent.Id,
    additionalInstructions: "Please address the user as Jane Doe. The user has a premium account.");
ThreadRun run = runResponse.Value;

//Once the run has started, it should then be polled until it reaches a terminal status:
do
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));
    runResponse = await client.GetRunAsync(thread.Id, runResponse.Value.Id);
}
while (runResponse.Value.Status == RunStatus.Queued
    || runResponse.Value.Status == RunStatus.InProgress);

//Assuming the run successfully completed, listing messages from the thread that was run will now reflect new information added by the agent:

Response<PageableList<ThreadMessage>> afterRunMessagesResponse
    = await client.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;

// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages)
{
    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
    foreach (MessageContent contentItem in threadMessage.ContentItems)
    {
        if (contentItem is MessageTextContent textItem)
        {
            Console.Write(textItem.Text);
        }
        else if (contentItem is MessageImageFileContent imageFileItem)
        {
            Console.Write($"<image from ID: {imageFileItem.FileId}");
        }
        Console.WriteLine();
    }
}

  // create a thread
  const thread = await client.agents.createThread();

  // add a message to thread
  await client.agents.createMessage(
      thread.id, {
      role: "user",
      content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
  });
  // create a run
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
      const textContent = m.content[0];
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

Créer un thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

Ajouter une question utilisateur au thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

Exécuter le thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Récupérer l’état de l’exécution

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

Récupérer la réponse de l’agent

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

Télécharger les fichiers générés par l’interpréteur de code

Les fichiers générés par l’interpréteur de code se trouvent dans les réponses sous forme de messages de l’agent. Vous pouvez télécharger le fichier image généré par l’interpréteur de code, en itérant au sein du image_contents de la réponse, et en appelant save_file() avec un nom et l’ID de fichier.

# save the newly created file
for image_content in messages.image_contents:
  print(f"Image File ID: {image_content.image_file.file_id}")
  file_name = f"{image_content.image_file.file_id}_image_file.png"
  project_client.agents.save_file(file_id=image_content.image_file.file_id, file_name=file_name)
  print(f"Saved image file to: {Path.cwd() / file_name}")

Les fichiers générés par l’interpréteur de code se trouvent dans les réponses sous forme de messages de l’agent. Vous pouvez télécharger le fichier image généré par l’interpréteur de code en itérant au sein des messages de la réponse, et en recherchant un ImageFileId. Si ce champ existe, utilisez le code suivant :

foreach (MessageContent contentItem in message.Content)
{
    if (!string.IsNullOrEmpty(contentItem.ImageFileId))
    {
        OpenAIFileInfo imageInfo = await fileClient.GetFileAsync(contentItem.ImageFileId);
        BinaryData imageBytes = await fileClient.DownloadFileAsync(contentItem.ImageFileId);
        using FileStream stream = File.OpenWrite($"{imageInfo.Filename}.png");
        imageBytes.ToStream().CopyTo(stream);

        Console.WriteLine($"<image: {imageInfo.Filename}.png>");
    }
}

Les fichiers chargés par les agents ne peuvent pas être récupérés. Si votre cas d’utilisation doit accéder au contenu d’un fichier chargé par les agents, il est conseillé de conserver une copie supplémentaire du fichier, accessible par votre application. Les fichiers générés par les agents sont toutefois récupérables par getFileContent.

const messages = await client.agents.listMessages(thread.id);
const imageFile = (messages.data[0].content[0] as MessageImageFileContentOutput).imageFile;
const imageFileName = (await client.agents.getFile(imageFile.fileId)).filename;

const fileContent = await (await client.agents.getFileContent(imageFile.fileId).asNodeStream()).body;
if (fileContent) {
  const chunks: Buffer[] = [];
  for await (const chunk of fileContent) {
    chunks.push(Buffer.from(chunk));
  }
  const buffer = Buffer.concat(chunks);
  fs.writeFileSync(imageFileName, buffer);
} else {
  console.error("Failed to retrieve file content: fileContent is undefined");
}
console.log(`Saved image file to: ${imageFileName}`);

Lorsque l’interpréteur de code génère une image, vous pouvez rechercher le fichier généré dans le champ file_id du message de réponse de l'Assistant :

{
	"id": "msg_abc123",
	"object": "thread.message",
	"created_at": 1698964262,
	"thread_id": "thread_abc123",
	"role": "assistant",
	"content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "assistant-abc123"
      }
    }
  ],
  # ...
}

Vous pouvez ensuite le télécharger à l’aide de :

curl $AZURE_AI_AGENTS_ENDPOINT/files/assistant-abc123/content?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  --output image.png

Types de fichiers pris en charge

Format de fichier	Type MIME
`.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`

Voir aussi

Découvrez plus en détail les agents.

Partager via