Codedolmetschertool für Microsoft Foundry Agents

Code Interpreter ermöglicht es einem Microsoft Foundry-Agent, Python Code in einer Sandkastenausführungsumgebung auszuführen. Das Foundry-Modell des Agents schreibt Und führt Code für Datenanalyse, Diagrammgenerierung und iterative Problemlösungsaufgaben aus.

Tipp

Erwägen Sie das Hinzufügen dieses Tools mithilfe einer Toolbox. Mithilfe einer Toolbox können Sie das Tool über Agents und Laufzeiten hinweg wiederverwenden sowie die Verwaltung von Anmeldeinformationen, versionsverwaltung und Richtlinienerzwingung über einen verwalteten MCP-Endpunkt zentralisieren. Sehen Sie sich die Schnellstartanleitung der Toolbox an.

In diesem Artikel erstellen Sie einen Agent, der Code-Interpreter verwendet, eine CSV-Datei zur Analyse hochlädt und ein generiertes Diagramm herunterlädt.

Wenn Sie Code Interpreter aktivieren, kann Ihr Agent Python Code iterativ schreiben und ausführen, um Datenanalyse- und mathematische Aufgaben zu lösen und Diagramme zu generieren.

Wichtig

CodeDolmetscher hat zusätzliche Gebühren zusätzlich zu den tokenbasierten Gebühren für die Azure OpenAI-Nutzung. Wenn Ihr Agent Code Interpreter in zwei verschiedenen Unterhaltungen gleichzeitig aufruft, werden zwei Codedolmetschersitzungen erstellt. Jede Sitzung ist standardmäßig für eine Stunde mit einem Leerlauftimeout von 30 Minuten aktiv.

Voraussetzungen

  • Grundlegende oder Standard-Agent-Umgebung. Details finden Sie unter Agent-Umgebungseinrichtung.
  • Das neueste SDK-Paket ist für Ihre Sprache installiert. Das .NET SDK ist derzeit als Vorschauversion verfügbar. Die Installationsschritte finden Sie in der Schnellstartanleitung .
  • Azure-KI-Modellbereitstellung, die in Ihrem Projekt konfiguriert ist.

Hinweis

Codedolmetscher ist in allen Regionen nicht verfügbar. Siehe "Überprüfen der regionalen Verfügbarkeit und Modellverfügbarkeit".

Verwendungsunterstützung

Die folgende Tabelle zeigt die SDK- und Setupunterstützung.

Microsoft Foundry-Unterstützung Python SDK C# SDK JavaScript SDK Java SDK REST-API Grundlegendes Agent-Setup Standard-Agenten-Einrichtung
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Erstellen Sie einen Agenten mit Code-Interpreter

In den folgenden Beispielen wird veranschaulicht, wie Sie einen Agent mit aktiviertem Codedolmetscher erstellen, eine Datei zur Analyse hochladen und die generierte Ausgabe herunterladen. Jedes Dateiuploadbeispiel generiert eine kleine CSV im aktuellen Arbeitsverzeichnis, lädt es hoch und löscht dann die lokale temporäre Datei.

Tipp

Sie können das Verhalten des Codedolmetschers zur Laufzeit anpassen, z. B. angeben, welche Dateien pro Anforderung eingeschlossen oder angepasst werden sollen, indem Sie strukturierte Eingaben verwenden.

Beispiel für die Verwendung von Agent mit Code-Interpreter-Tool im Python SDK

Im folgenden Python Beispiel wird gezeigt, wie Sie das Codedolmetschertool einer Toolbox hinzufügen, die Toolbox an einen Agent anfügen, eine CSV-Datei zur Analyse hochladen und ein Balkendiagramm basierend auf den Daten anfordern. Wählen Sie Prompt Agents aus, um das AZURE AI Projects SDK zum Erstellen eines serverseitigen Eingabeaufforderungs-Agents oder Hosted Agents zu verwenden, um das Agent Framework FoundryChatClient zum Erstellen eines ephemeralen, in-Process-Agents zu verwenden.

Prompt-Agenten

In diesem Beispiel wird ein vollständiger Workflow veranschaulicht: Hochladen einer Datei, Erstellen eines Agents mit aktiviertem Codedolmetscher, Anfordern der Datenvisualisierung und Herunterladen des generierten Diagramms.

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

CSV_DATA = """name,sector,operating_profit
SkyBridge Logistics,TRANSPORTATION,185.2
Velocity Rail Freight,TRANSPORTATION,310.2
AeroJet Airlines,TRANSPORTATION,510.6
"""
csv_path = os.path.abspath("synthetic-company-financial-results.csv")
with open(csv_path, "w", encoding="utf-8", newline="") as csv_file:
    csv_file.write(CSV_DATA)

# 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 generated CSV file for the code interpreter to use
with open(csv_path, "rb") as csv_file:
    file = openai.files.create(purpose="assistants", file=csv_file)
os.remove(csv_path)

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

Erwartete Ausgabe

Der Beispielcode erzeugt eine Ausgabe ähnlich dem folgenden Beispiel:

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

Der Agent lädt Ihre CSV-Datei in Azure Speicher hoch, erstellt eine Sandkasten-Python Umgebung, filtert Transportsektorunternehmen, generiert ein PNG-Balkendiagramm, das den Betriebsgewinn nach Unternehmen anzeigt, und lädt das Diagramm in Ihr lokales Verzeichnis herunter. Die Dateianmerkungen in der Antwort stellen die Datei-ID und containerinformationen bereit, die zum Abrufen des generierten Diagramms erforderlich sind.

Gehostete Agents

In diesem Beispiel wird die Code-Interpreter-Toolbox erstellt, dann FoundryChatClient aus dem Microsoft Agent Framework verwendet und unter Verwendung von MCPStreamableHTTPTool eine Verbindung mit dem MCP-Endpunkt der Toolbox hergestellt. Legen Sie die FOUNDRY_PROJECT_ENDPOINT Variablen und FOUNDRY_MODEL umgebungsvariablen fest, und melden Sie sich mit az loginan.

import asyncio
import os
import httpx

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential, get_bearer_token_provider
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import CodeInterpreterToolboxTool, AutoCodeInterpreterToolParam

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"
CSV_DATA = """name,sector,operating_profit
SkyBridge Logistics,TRANSPORTATION,185.2
Velocity Rail Freight,TRANSPORTATION,310.2
AeroJet Airlines,TRANSPORTATION,510.6
"""


class _ToolboxAuth(httpx.Auth):
    def __init__(self, token_provider):
        self._token_provider = token_provider

    def auth_flow(self, request):
        request.headers["Authorization"] = "Bearer " + self._token_provider()
        yield request


async def main() -> None:
    credential = AzureCliCredential()

    csv_path = os.path.abspath("synthetic-company-financial-results.csv")
    with open(csv_path, "w", encoding="utf-8", newline="") as csv_file:
        csv_file.write(CSV_DATA)

    # 1. Add the code interpreter tool to a toolbox. Using a toolbox is the recommended way
    #    to give agents tools: you curate tools once and reuse the toolbox across agents.
    #    See /azure/foundry/agents/concepts/toolbox-overview
    project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=credential)
    openai = project.get_openai_client()
    with open(csv_path, "rb") as csv_file:
        file = openai.files.create(purpose="assistants", file=csv_file)
    os.remove(csv_path)
    toolbox = project.toolboxes.create_version(
        name="code-interpreter-toolbox",
        description="Toolbox with the code interpreter tool",
        tools=[CodeInterpreterToolboxTool(container=AutoCodeInterpreterToolParam(file_ids=[file.id]))],
    )

    # 2. The toolbox exposes an MCP-compatible endpoint.
    TOOLBOX_MCP_URL = (
        f"{PROJECT_ENDPOINT}/toolboxes/{toolbox.name}"
        f"/versions/{toolbox.version}/mcp?api-version=v1"
    )

    # 3. Attach the toolbox to the hosted agent as an MCP tool.
    token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
    http_client = httpx.AsyncClient(auth=_ToolboxAuth(token_provider), timeout=120.0)
    mcp_tool = MCPStreamableHTTPTool(
        name="toolbox",
        url=TOOLBOX_MCP_URL,
        http_client=http_client,
        load_prompts=False,
    )

    agent = Agent(
        client=FoundryChatClient(credential=credential),
        instructions="You are a helpful assistant that can write and execute Python code to solve problems.",
        tools=[mcp_tool],
    )

    result = await agent.run("Use code to calculate the factorial of 100.")
    print(f"Agent: {result.text}")


if __name__ == "__main__":
    asyncio.run(main())

Erwartete Ausgabe

Der Agent generiert Python Code, führt ihn im Sandkastencontainer aus und gibt die Antwort zurück:

Agent: 100! = 93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000

Das vollständige Beispiel (einschließlich Dateieingaben und Extrahieren des generierten Codes) finden Sie unter foundry_chat_client_with_code_interpreter.py und foundry_chat_client_code_interpreter_files.py.

Erstellen eines Diagramms mit Codedolmetscher in C#

Im folgenden C#-Beispiel wird gezeigt, wie Sie das Codedolmetschertool einer Toolbox hinzufügen, die Toolbox an einen Agent anfügen, eine CSV-Datei zur Analyse hochladen und das generierte Diagramm herunterladen. Wählen Sie Prompt Agents aus, um das AZURE AI Projects SDK zum Erstellen eines serverseitigen Eingabeaufforderungs-Agents oder Hosted Agents zu verwenden, um das Microsoft Agent Framework zum Erstellen eines ephemeren, in-Process-Agents zu verwenden.

Prompt-Agenten

Für eine asynchrone Verwendung finden Sie das Codebeispiel im Azure SDK für .NET Repository auf GitHub.

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

const string CsvData = """
name,sector,operating_profit
SkyBridge Logistics,TRANSPORTATION,185.2
Velocity Rail Freight,TRANSPORTATION,310.2
AeroJet Airlines,TRANSPORTATION,510.6
""";
string csvPath = Path.GetFullPath("synthetic-company-financial-results.csv");
File.WriteAllText(csvPath, CsvData);

// 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: csvPath,
    purpose: FileUploadPurpose.Assistants);
File.Delete(csvPath);
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);

Erwartete Ausgabe

Der Beispielcode erzeugt eine Ausgabe ähnlich dem folgenden Beispiel:

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

Der Agent lädt Ihre CSV-Datei in Azure Speicher hoch, erstellt eine Sandkasten-Python Umgebung, analysiert die Daten zum Filtern von Transportsektordatensätzen und generiert ein PNG-Balkendiagramm. Die Anmerkungsanalyse extrahiert die Container-ID und Datei-ID aus der Antwort, die zum Herunterladen des Diagramms in Ihr lokales Verzeichnis verwendet wird.

Gehostete Agents

Dieses Beispiel erstellt die Code-Interpreter-Toolbox und verwendet dann ResponsesServer aus dem Microsoft Agent Framework mit einem benutzerdefinierten ToolboxMcpClient, um den Code Interpreter über den Toolbox-MCP-Endpunkt zu erkennen und aufzurufen. Legen Sie die Umgebungsvariablen AZURE_AI_PROJECT_ENDPOINT, AZURE_OPENAI_ENDPOINT und AZURE_AI_MODEL_DEPLOYMENT_NAME fest, und melden Sie sich mit az login an.

using System;
using System.IO;
using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;
using OpenAI.Files;

const string CsvData = """
name,sector,operating_profit
SkyBridge Logistics,TRANSPORTATION,185.2
Velocity Rail Freight,TRANSPORTATION,310.2
AeroJet Airlines,TRANSPORTATION,510.6
""";
const string AgentInstructions = "You are a personal math tutor. When asked a math question, write and run code using the python tool to answer the question.";
const string AgentName = "CoderAgent";

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? "https://<account>.services.ai.azure.com/api/projects/<project>";
string openAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";

DefaultAzureCredential credential = new();

// 1. Add the code interpreter tool to a toolbox. Using a toolbox is the recommended
//    way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
OpenAIFileClient fileClient = projectClient.ProjectOpenAIClient.GetOpenAIFileClient();
string csvPath = Path.GetFullPath("synthetic-company-financial-results.csv");
File.WriteAllText(csvPath, CsvData);
OpenAIFile uploadedFile = fileClient.UploadFile(
  filePath: csvPath,
    purpose: FileUploadPurpose.Assistants);
File.Delete(csvPath);

ProjectsAgentTool codeInterpreterTool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateCodeInterpreterTool(
        new CodeInterpreterToolContainer(
            CodeInterpreterToolContainerConfiguration.CreateAutomaticContainerConfiguration(
                fileIds: [uploadedFile.Id]
            )
        )
    ));

ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "code-interpreter-toolbox",
        tools: [codeInterpreterTool],
        description: "Toolbox with the code interpreter tool");

// 2. The toolbox exposes an MCP-compatible endpoint.
string toolboxMcpEndpoint =
    $"{projectEndpoint}/toolboxes/{toolboxVersion.Name}/versions/{toolboxVersion.Version}/mcp?api-version=v1";

// 3. Attach the toolbox to the hosted agent.
AzureOpenAIClient openAIClient = new(new Uri(openAiEndpoint), credential);
ChatClient chatClient = openAIClient.GetChatClient(deploymentName);

// ToolboxMcpClient discovers toolbox tools via MCP tools/list and calls them via tools/call.
ToolboxMcpClient toolboxClient = new(toolboxMcpEndpoint, credential);

ResponsesServer.Run<ToolboxHandler>(configure: builder =>
{
    builder.Services.AddSingleton(new AgentConfig(
        name: AgentName,
        instructions: AgentInstructions,
        chatClient: chatClient,
        toolboxClient: toolboxClient));
});

Erwartete Ausgabe

Der gehostete Agent verwendet den MCP-Endpunkt der Toolbox, um Python im Sandkasten auszuführen und die endgültige Antwort zurückzugeben:

Response: One solution is x ≈ 6.36, since sin(x) + x^2 is approximately 42 at that value.

Eine verwaltete .NET Agent Framework-Integration finden Sie unter Verwenden einer Toolbox mit einem gehosteten Agent.

Beispiel für die Verwendung von Agent mit Codedolmetschertool im TypeScript SDK

Im folgenden TypeScript-Beispiel wird gezeigt, wie Sie das Codedolmetschertool einer Toolbox hinzufügen, die Toolbox an einen Agent anfügen, eine CSV-Datei zur Analyse hochladen und ein Balkendiagramm basierend auf den Daten anfordern. Eine JavaScript-Version finden Sie im beispiel JavaScript im Azure SDK für JavaScript-Repository auf GitHub.

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

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const CSV_DATA = `name,sector,operating_profit
SkyBridge Logistics,TRANSPORTATION,185.2
Velocity Rail Freight,TRANSPORTATION,310.2
AeroJet Airlines,TRANSPORTATION,510.6
`;

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

  // Generate and upload the CSV file
  const csvPath = "synthetic-company-financial-results.csv";
  fs.writeFileSync(csvPath, CSV_DATA);
  const fileStream = fs.createReadStream(csvPath);

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

  console.log("Creating a toolbox with the code interpreter tool...");

  // 1. Add the code interpreter tool to a toolbox. Using a toolbox is the recommended
  //    way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
  const toolbox = await project.toolboxes.createVersion(
    "code-interpreter-toolbox",
    [
      {
        type: "code_interpreter",
        container: {
          type: "auto",
          file_ids: [uploadedFile.id],
        },
      },
    ],
    { description: "Toolbox with the code interpreter tool" },
  );

  // 2. The toolbox exposes an MCP-compatible endpoint.
  const toolboxMcpUrl =
    `${PROJECT_ENDPOINT}/toolboxes/${toolbox.name}` +
    `/versions/${toolbox.version}/mcp?api-version=v1`;

  // 3. Create a remote-tool project connection that points at the toolbox endpoint.
  //    Use a user Entra token so the caller's identity is passed through
  //    (audience https://ai.azure.com). Create the connection once, for example
  //    with the Azure Developer CLI:
  //
  //    azd ai connection create code-interpreter-toolbox-conn \
  //      --kind remote-tool \
  //      --target "<toolboxMcpUrl>" \
  //      --auth-type user-entra-token \
  //      --audience https://ai.azure.com
  const toolboxConnectionName = "code-interpreter-toolbox-conn";

  // 4. Attach the toolbox to a prompt agent as an MCP tool.
  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "You are a helpful assistant.",
    tools: [
      {
        type: "mcp",
        server_label: "toolbox",
        server_url: toolboxMcpUrl,
        require_approval: "never",
        project_connection_id: toolboxConnectionName,
      },
    ],
  });

  // 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_reference: { 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(
      fileId,
      { container_id: containerId },
    );
    const buffer = Buffer.from(await fileContent.arrayBuffer());

    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);
});

Erwartete Ausgabe

Der Beispielcode erzeugt eine Ausgabe ähnlich dem folgenden Beispiel:

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

Der Agent lädt Ihre CSV-Datei in Azure Speicher hoch, erstellt eine Sandkasten-Python Umgebung, filtert Transportsektorunternehmen, generiert ein PNG-Balkendiagramm, das den Betriebsgewinn nach Unternehmen anzeigt, und lädt das Diagramm in Ihr lokales Verzeichnis herunter. Die Dateianmerkungen in der Antwort stellen die Datei-ID und containerinformationen bereit, die zum Abrufen des generierten Diagramms erforderlich sind.

Erstellen eines Diagramms mit Codedolmetscher in Java

Fügen Sie für die meisten Agents das Codedolmetschertool über eine Toolbox hinzu, und fügen Sie die Toolbox als MCP-Tool an Ihren Agent an. Das Java SDK macht noch keine Toolboxerstellungs-API verfügbar. Erstellen Sie daher die Toolbox mithilfe einer der derzeit unterstützten Methoden (Python, REST-API, C#, TypeScript oder das Foundry-Portal). Nachdem die Toolbox erstellt wurde, verweisen Sie in Ihrem Java-Agenten auf ihren MCP-Endpunkt als McpTool. Im folgenden Beispiel wird der MCP-Endpunkt der Code-Interpreter-Toolbox an den Agent angefügt.

Fügen Sie die Abhängigkeit zu Ihrem pom.xml hinzu:

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

Erstellen eines Agents und Generieren eines Diagramms

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.McpTool;
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";
        String toolboxMcpUrl = projectEndpoint
            + "/toolboxes/code-interpreter-toolbox/versions/1/mcp?api-version=v1";
        String toolboxConnectionName = "code-interpreter-toolbox-conn";

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

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

        // The Java SDK doesn't yet expose a toolbox creation API. Create the
        // code-interpreter toolbox with Python, REST, C#, TypeScript, or the
        // Foundry portal, then attach its MCP endpoint as an MCP tool.
        McpTool toolboxTool = new McpTool("toolbox")
            .setServerUrl(toolboxMcpUrl)
            .setProjectConnectionId(toolboxConnectionName)
            .setRequireApproval("never");

        // Create agent with the code-interpreter toolbox MCP tool
        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(toolboxTool));

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

Erwartete Ausgabe

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.

Der Agent verwendet Code Interpreter über den MCP-Endpunkt der Toolbox, schreibt Python Code mithilfe von matplotlib, um das Diagramm zu generieren, und führt den Code in einer Sandkastenumgebung aus. Wählen Sie beispielsweise Python oder TypeScript aus der Sprachauswahl oben in diesem Artikel aus, um eine CSV-Datei hochzuladen und das generierte Diagramm herunterzuladen. Weitere Beispiele finden Sie unter Azure AI Agents Java SDK-Beispiele.

Erstellen eines Diagramms mit Code-Interpreter mithilfe der REST-API

Das folgende Beispiel zeigt, wie Sie eine CSV-Datei hochladen, einen Agent mit Code Interpreter erstellen, ein Diagramm anfordern und die generierte Datei herunterladen.

Voraussetzungen

Legen Sie diese Umgebungsvariablen fest:

  • FOUNDRY_PROJECT_ENDPOINT: Ihre Projektendpunkt-URL.
  • AGENT_TOKEN: Ein Bearer-Token für Foundry.

Zugriffstoken abrufen:

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

Verwenden des Codedolmetschers in einer Toolbox

Um eine Datei hochzuladen, damit Code Interpreter sie über eine Toolbox verwenden kann, laden Sie die Datei über den Files-Endpunkt auf Ressourcenebene (POST {account_endpoint}/openai/v1/files) mit dem Header x-aml-project-id hoch. Im Gegensatz zum Prompt-Agent-Flow erhalten Dateien, die über den projektbezogenen Files-Endpunkt (/api/projects/{name}/openai/v1/files) hochgeladen werden, ein owner_id, das der Toolbox-Container nicht verifizieren kann, sodass tools/call mit einem Besitzüberprüfungsfehler fehlschlägt.

  1. Rufen Sie die Projekt-GUID aus Azure Resource Manager ab. Verwenden properties.amlWorkspace.internalId (gestricheltes UUID-Format), nichtproperties.internalId (keine Gedankenstriche - der Toolboxcontainer lehnt es ab):

    ARM_TOKEN=$(az account get-access-token --query accessToken -o tsv)
PROJECT_GUID=$(curl -s -H "Authorization: Bearer $ARM_TOKEN" \
  "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}?api-version=2025-06-01" \
  | jq -r '.properties.amlWorkspace.internalId')

  2. Laden Sie die Datei auf Kontoebene (Ressourcenebene) mit dem x-aml-project-id Header hoch:

    cat > synthetic-company-financial-results.csv <<'CSV'
name,sector,operating_profit
SkyBridge Logistics,TRANSPORTATION,185.2
Velocity Rail Freight,TRANSPORTATION,310.2
AeroJet Airlines,TRANSPORTATION,510.6
CSV

TOKEN=$(az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv)
curl -X POST "https://{account}.services.ai.azure.com/openai/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-aml-project-id: $PROJECT_GUID" \
  -F "purpose=assistants" \
  -F "file=@synthetic-company-financial-results.csv"
rm synthetic-company-financial-results.csv

Die zurückgegebene Datei id ist der Wert, den Sie wie <FILE_ID> in der Toolkonfiguration angeben. Dateien werden in der Sandbox unter /mnt/data/{file-id}-{original-filename} eingehängt.

Wichtig

Wenn Codedolmetscher über eine Toolbox in einem gehosteten Agent verwendet wird, wird die Benutzerisolation nicht unterstützt. Alle Benutzer im selben Projekt verwenden denselben Containerkontext.

Hinzufügen von Codedolmetschern zu einer Toolbox

Fügen Sie Codedolmetscher hinzu, indem Sie eine Toolbox erstellen und dann die Toolbox als MCP-Tool an Ihren Agent anfügen. Weitere Informationen finden Sie unter Was ist eine Toolbox?

  • Erstellen Sie eine Toolbox, die das Codedolmetschertool enthält:

    curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/code-interpreter-toolbox/versions?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "Toolbox with the code interpreter tool",
    "tools": [
      {
        "type": "code_interpreter",
        "container": {
          "type": "auto",
          "file_ids": ["<FILE_ID>"]
        }
      }
    ]
  }'

    Die Toolbox stellt unter $FOUNDRY_PROJECT_ENDPOINT/toolboxes/code-interpreter-toolbox/versions/<version>/mcp?api-version=v1 einen MCP-kompatiblen Endpunkt bereit, wobei <version> die vom vorherigen Aufruf zurückgegebene Version ist.

  • Erstellen Sie eine Projektverbindung für das Remotetool, die auf den Toolbox-Endpunkt verweist, und verwenden Sie dazu ein Entra-Benutzertoken, sodass die Identität des Aufrufers durchgereicht wird (Zielgruppe https://ai.azure.com).

    azd ai connection create code-interpreter-toolbox-conn \
  --kind remote-tool \
  --target "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/code-interpreter-toolbox/versions/<version>/mcp?api-version=v1" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com

Erstellen eines Agents mit der Codedolmetscher-Toolbox

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": "mcp",
          "server_label": "toolbox",
          "server_url": "'$FOUNDRY_PROJECT_ENDPOINT'/toolboxes/code-interpreter-toolbox/versions/<version>/mcp?api-version=v1",
          "require_approval": "never",
          "project_connection_id": "code-interpreter-toolbox-conn"
        }
      ]
    }
  }'

Generieren eines Diagramms

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 company for the TRANSPORTATION sector from the uploaded CSV file. Use a blue color scheme and add data labels."
  }'

Die Antwort enthält container_file_citation Anmerkungen mit den generierten Dateidetails. Speichern Sie die Werte von container_id und file_id aus der Anmerkung.

Herunterladen des generierten Diagramms

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

Aufräumen

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

Überprüfen der regionalen Verfügbarkeit und Modellverfügbarkeit

Die Verfügbarkeit von Tools variiert je nach Region und Modell.

Die aktuelle Liste der unterstützten Regionen und Modelle für Codedolmetscher finden Sie unter Best practices for using tools in Microsoft Foundry Agent Service.

Unterstützte Dateitypen

Dateiformat MIME-Typ
.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 Oder text/xml
.zip application/zip

Problembehandlung

Angelegenheit Wahrscheinliche Ursache Auflösung
Der Code-Interpreter wird nicht ausgeführt. Das Tool ist nicht aktiviert, oder das Modell unterstützt es in Ihrer Region nicht. Bestätigen Sie, dass der Codedolmetscher für den Agent aktiviert ist. Überprüfen Sie, dass die Modellbereitstellung in Ihrer Region das Tool unterstützt. Siehe "Überprüfen der regionalen Verfügbarkeit und Modellverfügbarkeit".
Es wird keine Datei generiert. Der Agent hat eine reine Textantwort ohne Dateianhang zurückgegeben. Überprüfen Sie die Anmerkungen zu Antworten für container_file_citation. Wenn keine vorhanden ist, hat der Agent keine Datei generiert. Formulieren Sie die Eingabeaufforderung neu, um die Dateiausgabe explizit anzufordern.
Fehler beim Hochladen der Datei. Nicht unterstützter Dateityp oder falscher Zweck. Vergewissern Sie sich, dass sich der Dateityp in der Liste der unterstützten Dateitypen befindet . Hochladen mit purpose="assistants".
Die generierte Datei ist beschädigt oder leer. Codeausführungsfehler oder unvollständige Verarbeitung. Überprüfen Sie die Antwort des Agents auf Fehlermeldungen. Überprüfen Sie, ob die Eingabedaten gültig sind. Versuchen Sie es zuerst mit einer einfacheren Anforderung.
Sitzungstimeout oder hohe Latenz. Codedolmetschersitzungen haben Zeitlimits. Sitzungen verfügen über ein aktives 1-Stunden-Timeout und ein Leerlauf-Timeout von 30 Minuten. Verringern Sie die Komplexität von Vorgängen, oder teilen Sie sie in kleinere Vorgänge auf.
Unerwartete Abrechnungsgebühren. Mehrere gleichzeitige Sitzungen wurden erstellt. Jede Unterhaltung erstellt eine separate Sitzung. Überwachen Sie die Sitzungsnutzung, und konsolidieren Sie Vorgänge, sofern möglich.
Python Paket nicht verfügbar. Der Codedolmetscher verfügt über einen festen Satz von Paketen. Code Interpreter enthält allgemeine Data-Science-Pakete. Verwenden Sie für benutzerdefinierte Pakete einen benutzerdefinierten Codedolmetscher.
Fehler beim Herunterladen der Datei. Container-ID oder Datei-ID falsch. Überprüfen Sie, ob Sie die richtigen container_id Und file_id aus den Antwortanmerkungen verwenden.

Bereinigen von Ressourcen

Löschen Sie ressourcen, die Sie in diesem Beispiel erstellt haben, wenn Sie sie nicht mehr benötigen, um laufende Kosten zu vermeiden:

  • Löschen Sie die Agentversion.
  • Löschen Sie die Unterhaltung.
  • Hochgeladene Dateien löschen.

Beispiele für Unterhaltungs- und Dateibereinigungsmuster finden Sie unter Websuchtool und Dateisuchtool für Agents.

Sandkastenausführungsumgebung

Codedolmetscher führt Python Code in einer Microsoft verwalteten Sandbox aus. Der Sandkasten wurde für die Ausführung nicht vertrauenswürdiger Code entwickelt und verwendet dynamic Sessions (Code interpreter sessions) in Azure Container Apps. Jede Sitzung wird durch eine Hyper-V Grenze isoliert.

Wichtige Verhaltensweisen, die geplant werden sollten:

  • Region: Der Codedolmetscher-Sandkasten wird in derselben Azure Region wie Ihr Foundry-Projekt ausgeführt.
  • Sitzungsdauer: Eine Codedolmetschersitzung ist bis zu einer Stunde aktiv, mit einem Leerlauftimeout (siehe Wichtig am Anfang dieses Artikels).
  • Isolation: Jede Sitzung wird in einer isolierten Umgebung ausgeführt. Wenn Ihr Agent Code-Interpreter gleichzeitig in verschiedenen Unterhaltungen aufruft, werden separate Sitzungen erstellt.
  • Netzwerkisolation und Internetzugriff: Die Sandbox erbt ihre Agent-Subnetzkonfiguration nicht, und dynamische Sitzungen können keine ausgehenden Netzwerkanforderungen stellen.
  • Dateien in der Sandbox: Die sandboxesierte Python-Laufzeitumgebung hat Zugriff auf die Dateien, die Sie zur Analyse anhängen. Codedolmetscher können auch Dateien generieren, z. B. Diagramme, und sie als herunterladbare Ausgaben zurückgeben.

Wenn Sie mehr Kontrolle über die Sandkastenlaufzeit benötigen oder ein anderes Isolationsmodell benötigen, lesen Sie das Tool für den benutzerdefinierten Codedolmetscher für Agents.

Verwandte Inhalte

  • Last updated on