Поделиться через

Средство интерпретатора кода для агентов Microsoft Foundry

Интерпретатор кода позволяет агенту Microsoft Foundry запускать Python код в изолированной среде выполнения. Используйте это средство для анализа данных, создания диаграмм и итеративного решения проблем, которые получают преимущества от выполнения кода.

В этой статье вы создадите агент, использующий интерпретатор кода, отправьте CSV-файл для анализа и скачайте созданную диаграмму.

При включении интерпретатора кода агент может записывать и выполнять код Python итеративно для решения задач анализа данных и математических задач, а также создавать диаграммы.

Это важно

Интерпретатор кода имеет дополнительные сборы, помимо сборов на основе токенов за использование Azure OpenAI. Если агент вызывает интерпретатор кода одновременно в двух разных беседах, он создает два сеанса интерпретатора кода. Каждый сеанс по умолчанию активен на один час с таймаутом бездействия 30 минут.

Поддержка использования

В следующей таблице показана поддержка пакета SDK и настройки.

Поддержка Microsoft Foundry пакет SDK Python Пакет SDK для C# Пакет SDK для JavaScript пакет SDK Java REST API Базовая настройка агента Настройка стандартного агента
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Предпосылки

  • Базовая или стандартная среда агента. Дополнительные сведения см. в разделе "Настройка среды агента ".
  • Последний пакет SDK, установленный для вашего языка. Пакет SDK для .NET в настоящее время находится в предварительной версии. См. краткое руководство по установке.
  • Развертывание модели ИИ Azure, настроенной в вашем проекте.
  • Для операций с файлами: CSV или другие поддерживаемые файлы для загрузки и анализа.

Замечание

Интерпретатор кода недоступен во всех регионах. См. Проверку доступности регионов и моделей.

Создание агента с интерпретатором кода

В следующих примерах показано, как создать агент с включенным интерпретатором кода, отправить файл для анализа и скачать созданные выходные данные.

Подсказка

Поведение интерпретатора кода можно настроить во время выполнения, например указание файлов для включения или настройки параметров средства для каждого запроса с помощью структурированных входных данных.

Пример использования агента с инструментом интерпретатора кода в пакете SDK Python

В следующем примере Python показано, как создать агент с помощью средства интерпретатора кода, отправить CSV-файл для анализа и запросить линейчатую диаграмму на основе данных. Он демонстрирует полный рабочий процесс: отправка файла, создание агента с включенным интерпретатором кода, визуализация данных запроса и скачивание созданной диаграммы.

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

Ожидаемые выходные данные

Пример кода создает выходные данные, аналогичные следующему примеру:

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

Агент отправляет CSV-файл в хранилище Azure, создает изолированную среду Python, анализирует данные для фильтрации записей сектора транспорта, создает линейчатую диаграмму PNG с операционной прибылью по кварталу и загружает диаграмму в локальный каталог. Заметки к файлу в ответе предоставляют идентификатор файла и сведения о контейнере, необходимые для получения созданной диаграммы.

Создание диаграммы с интерпретатором кода в C#

В следующем примере C# показано, как создать агент с помощью средства интерпретатора кода, отправить CSV-файл для анализа и скачать созданную диаграмму. Сведения об асинхронном использовании см. в примере кода в репозитории azure SDK для .NET на сайте GitHub.

using System;
using System.IO;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using OpenAI.Files;

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

// Upload a CSV file for Code Interpreter to analyze
OpenAIFileClient fileClient = projectClient.ProjectOpenAIClient.GetOpenAIFileClient();
OpenAIFile uploadedFile = fileClient.UploadFile(
    filePath: "synthetic_500_quarterly_results.csv",
    purpose: FileUploadPurpose.Assistants);
Console.WriteLine($"Uploaded file: {uploadedFile.Id}");

// Create an agent with Code Interpreter enabled
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant.",
    Tools = {
        ResponseTool.CreateCodeInterpreterTool(
            new CodeInterpreterToolContainer(
                CodeInterpreterToolContainerConfiguration.CreateAutomaticContainerConfiguration(
                    fileIds: [uploadedFile.Id]
                )
            )
        ),
    }
};
ProjectsAgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myChartAgent",
    options: new(agentDefinition));

// Request chart generation from the uploaded CSV data
AgentReference agentReference = new(name: agentVersion.Name, version: agentVersion.Version);
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentReference);

ResponseResult response = responseClient.CreateResponse(
    "Could you please create bar chart in TRANSPORTATION sector for the operating profit " +
    "from the uploaded csv file and provide file to me?");

Console.WriteLine(response.GetOutputText());

// Extract file information from response annotations
ContainerFileCitationMessageAnnotation containerAnnotation = null;
foreach (ResponseItem item in response.OutputItems)
{
    if (item is MessageResponseItem messageItem)
    {
        foreach (ResponseContentPart content in messageItem.Content)
        {
            foreach (ResponseMessageAnnotation annotation in content.OutputTextAnnotations)
            {
                if (annotation is ContainerFileCitationMessageAnnotation cntrAnnotation)
                {
                    containerAnnotation = cntrAnnotation;
                }
            }
        }
    }
}

// Download the generated chart if available
if (containerAnnotation is not null)
{
    ContainerClient containerClient = projectClient.ProjectOpenAIClient.GetContainerClient();
    BinaryData fileData = containerClient.DownloadContainerFile(
        containerId: containerAnnotation.ContainerId,
        fileId: containerAnnotation.FileId);
    File.WriteAllBytes("chart.png", fileData.ToArray());
    Console.WriteLine($"Chart downloaded: {Path.GetFullPath("chart.png")}");
}
else
{
    Console.WriteLine("No file generated in response");
}

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

Ожидаемые выходные данные

Пример кода создает выходные данные, аналогичные следующему примеру:

Uploaded file: file-xxxxxxxxxxxxxxxxxxxx
Here is the bar chart showing operating profit by quarter in the TRANSPORTATION sector...
Chart downloaded: C:\Users\you\chart.png

Агент отправляет CSV-файл в хранилище Azure, создает изолированную среду Python, анализирует данные для фильтрации записей транспортных секторов и создает линейчатую диаграмму PNG. Синтаксический анализ заметок извлекает идентификатор контейнера и идентификатор файла из ответа, которые используются для скачивания диаграммы в локальный каталог.

Пример использования агента с инструментом интерпретатора кода в пакете SDK TypeScript

В следующем примере TypeScript показано, как создать агент с помощью средства интерпретатора кода, отправить CSV-файл для анализа и запросить линейчатую диаграмму на основе данных. Информацию о версии JavaScript можно найти в примере JavaScript из репозитория Azure SDK для JavaScript на 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);
});

Ожидаемые выходные данные

Пример кода создает выходные данные, аналогичные следующему примеру:

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

Агент отправляет CSV-файл в хранилище Azure, создает изолированную среду Python, анализирует данные для фильтрации записей сектора транспорта, создает линейчатую диаграмму PNG с операционной прибылью по кварталу и загружает диаграмму в локальный каталог. Заметки к файлу в ответе предоставляют идентификатор файла и сведения о контейнере, необходимые для получения созданной диаграммы.

Создание диаграммы с интерпретатором кода в Java

Добавьте зависимость в вашу pom.xml:

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

Создание агента и создание диаграммы

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.AzureCreateResponseOptions;
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.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(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());
    }
}

Ожидаемые выходные данные

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.

Агент создает сеанс интерпретатора кода, записывает код Python с помощью matplotlib для создания диаграммы и выполняет код в изолированной среде. Пример отправки CSV-файла и скачивания созданной диаграммы выберите Python или TypeScript из селектора языка в верхней части этой статьи. Дополнительные примеры см. в примерах Azure агентов ИИ Java SDK.

Создание диаграммы с интерпретатором кода с помощью REST API

В следующем примере показано, как отправить CSV-файл, создать агент с интерпретатором кода, запросить диаграмму и скачать созданный файл.

Предпосылки

Задайте следующие переменные среды:

  • FOUNDRY_PROJECT_ENDPOINT: URL-адрес конечной точки проекта.
  • AGENT_TOKEN: маркер носителя для Foundry.

Получение токена доступа:

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

1. Отправка CSV-файла

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

Сохраните id из ответа (например, file-abc123).

2. Создание агента с интерпретатором кода

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. Создание диаграммы

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."
  }'

Ответ содержит container_file_citation аннотации с деталями созданного файла. Сохраните container_id и file_id значения из заметки.

4. Скачивание созданной диаграммы

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

5. Очистка

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

Проверка доступности регионов и моделей

Доступность инструментов зависит от региона и модели.

Текущий список поддерживаемых регионов и моделей для интерпретатора кода см. в рекомендациях по использованию средств в службе Microsoft Foundry Agent.

Поддерживаемые типы файлов

Формат файла 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 или text/xml
.zip application/zip

Устранение неполадок

Проблема Вероятно, причина Резолюция
Интерпретатор кода не выполняется. Средство не включено или модель не поддерживает ее в вашем регионе. Убедитесь, что интерпретатор кода включен в агенте. Убедитесь, что развертывание модели поддерживает инструмент в вашем регионе. См. Проверку доступности регионов и моделей.
Файл не создается. Агент вернул ответ только в виде текста без аннотации к файлу. Проверьте аннотации ответа для container_file_citation. Если нет, агент не создавал файл. Перефразируйте запрос, чтобы явно указать вывод данных в файл.
Сбой отправки файлов. Неподдерживаемый тип файла или неправильное назначение. Убедитесь, что тип файла находится в списке поддерживаемых типов файлов . Загрузка с purpose="assistants".
Созданный файл поврежден или пуст. Ошибка выполнения кода или неполная обработка. Проверьте ответ агента на наличие сообщений об ошибках. Убедитесь, что входные данные допустимы. Сначала попробуйте простой запрос.
Тайм-аут сеанса или высокая задержка. Сеансы интерпретатора кода имеют ограничения времени. Сеансы имеют 1-часовое активное время ожидания и 30-минутное время ожидания простоя. Уменьшите сложность операций или разделите их на более мелкие задачи.
Непредвиденные расходы на выставление счетов. Создано несколько одновременных сеансов. Каждая беседа создает отдельный сеанс. Отслеживайте использование сеансов и консолидируйте операции по возможности.
Python пакет недоступен. Интерпретатор кода содержит фиксированный набор пакетов. Интерпретатор кода включает общие пакеты обработки и анализа данных. Для пользовательских пакетов используйте интерпретатор пользовательского кода.
Сбой скачивания файла. Неверный идентификатор контейнера или идентификатор файла. Убедитесь, что вы используете правильные container_id и file_id из заметок ответа.

Очистите ресурсы

Удалите ресурсы, созданные в этом примере, если их больше не нужно, чтобы избежать текущих затрат:

  • Удалите версию агента.
  • Удалите беседу.
  • Удаление отправленных файлов.

Примеры шаблонов очистки бесед и файлов см. в средстве поиска в Интернете и средстве поиска файлов для агентов.

Изолированная среда выполнения

Интерпретатор кода выполняет код Python в песочнице, управляемой корпорацией Майкрософт. Песочница предназначена для запуска ненадежного кода и использует динамические сеансы (сеансы интерпретатора кода) в приложениях контейнеров Azure. Каждый сеанс изолирован границой Hyper-V.

Ключевые действия, которые следует планировать:

  • Регион: песочница интерпретатора кода выполняется в том же регионе Azure, что и проект Foundry.
  • Время существования сеанса: сеанс интерпретатора кода активен до одного часа с временем ожидания простоя (см . важное примечание в начале этой статьи).
  • Изоляция: каждый сеанс выполняется в изолированной среде. Если агент вызывает интерпретатор кода одновременно в разных беседах, создаются отдельные сеансы.
  • Сетевая изоляция и доступ к Интернету: песочница не наследует конфигурацию подсети агента, а динамические сеансы не могут выполнять исходящие сетевые запросы.
  • Файлы в песочнице: песочница среды выполнения Python имеет доступ к файлам, присоединенным для анализа. Интерпретатор кода также может создавать файлы, такие как диаграммы, и возвращать их в виде загружаемых выходных данных.

Если вам нужен дополнительный контроль над средой выполнения песочницы или вам нужна другая модель изоляции, см. инструмент интерпретации пользовательского кода для агентов.

Связанный контент

  • Last updated on