Kodtolkarverktyg för Microsoft Foundry-agenter

Code Interpreter gör det möjligt för en Microsoft Foundry-agent att köra Python-kod i en isolerad exekveringsmiljö. Använd det här verktyget för dataanalys, diagramgenerering och iterativa problemlösningsuppgifter som drar nytta av kodkörning.

I den här artikeln skapar du en agent som använder kodtolkare, laddar upp en CSV-fil för analys och laddar ned ett genererat diagram.

När du aktiverar kodtolkare kan agenten skriva och köra Python-kod iterativt för att lösa dataanalyser och matematiska uppgifter och generera diagram.

Viktigt!

Kodtolken har yrena avgifter utöver de tokenbaserade avgifterna för Azure OpenAI-användning. Om agenten anropar kodtolkaren samtidigt i två olika konversationer skapar den två kodtolkarsessioner. Varje session är aktiv som standard i en timme med en tidsgräns på 30 minuter.

Användningsstöd

✔️ (GA) anger allmän tillgänglighet, ✔️ (förhandsversion) anger offentlig förhandsversion och ett bindestreck (-) anger att funktionen inte är tillgänglig.

Microsoft Foundry-stöd	Python SDK	C# SDK	SDK för JavaScript	Java SDK	REST API	Grundläggande agentkonfiguration	Standardagentkonfiguration
✔️	✔️ (GA)	✔️ (Förhandsversion)	✔️ (GA)	✔️ (Förhandsversion)	✔️ (GA)	✔️	✔️

Förutsättningar

• Grundläggande agentmiljö eller standardagentmiljö. Mer information finns i konfigurationen av agentmiljön .
• Senaste SDK-paketet installerat för ditt språk. SDK:erna för .NET och Java finns för närvarande i förhandsversion. Se snabbstarten för installationssteg.
• Azure AI-utplacering av modell som är konfigurerad i ditt projekt.
• För filåtgärder: CSV eller andra filer som stöds att ladda upp för analys.

Anmärkning

Kodtolk är inte tillgänglig i alla regioner. Se Kontrollera regional tillgänglighet och modelltillgänglighet.

Skapa en agent med kodtolkare

Följande exempel visar hur du skapar en agent med kodtolkaren aktiverad, laddar upp en fil för analys och laddar ned de genererade utdata.

Exempel på att använda agent med kodtolkverktyg i Python SDK

Följande Python exempel visar hur du skapar en agent med kodtolkarverktyget, laddar upp en CSV-fil för analys och begär ett stapeldiagram baserat på data. Det visar ett fullständigt arbetsflöde: ladda upp en fil, skapa en agent med kodtolkaren aktiverad, begära datavisualisering och ladda ned det genererade diagrammet.

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

Förväntad utdata

Exempelkoden genererar utdata som liknar följande exempel:

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

Agenten laddar upp CSV-filen till Azure lagring, skapar en sandbox-Python miljö, analyserar data för att filtrera transportsektorposter, genererar ett PNG-stapeldiagram som visar rörelseresultat per kvartal och laddar ned diagrammet till din lokala katalog. Filanteckningarna i svaret anger det fil-ID och den containerinformation som behövs för att hämta det genererade diagrammet.

Skapa ett diagram med kodtolkare i C#

Följande C#-exempel visar hur du skapar en agent med kodtolkverktyget och använder det för att generera ett stapeldiagram. Agenten skriver och kör Python kod (med hjälp av matplotlib) i en container i begränsat läge. Asynkron användning finns i kodexemplet i Azure SDK för .NET-lagringsplatsen på 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);

Förväntad utdata

Exempelkoden genererar utdata som liknar följande exempel:

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

Agenten skapar en kodtolksession, skriver Python-kod med hjälp av matplotlib för att generera stapeldiagrammet, kör koden i en sandbox-miljö och returnerar diagrammet som en genererad fil. Om du vill ha ett exempel som laddar upp en CSV-fil och laddar ned det genererade diagrammet väljer du Python eller TypeScript från språkväljaren överst i den här artikeln.

Exempel på att använda agent med kodtolkverktyget i TypeScript SDK

Följande TypeScript-exempel visar hur du skapar en agent med kodtolkarverktyget, laddar upp en CSV-fil för analys och begär ett stapeldiagram baserat på data. En JavaScript-version finns i exemplet JavaScript i Azure SDK för JavaScript-lagringsplatsen på 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);
});

Förväntad utdata

Exempelkoden genererar utdata som liknar följande exempel:

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

Agenten laddar upp CSV-filen till Azure lagring, skapar en sandbox-Python miljö, analyserar data för att filtrera transportsektorposter, genererar ett PNG-stapeldiagram som visar rörelseresultat per kvartal och laddar ned diagrammet till din lokala katalog. Filanteckningarna i svaret anger det fil-ID och den containerinformation som behövs för att hämta det genererade diagrammet.

Skapa ett diagram med kodtolkare i Java

Lägg till beroendet till din pom.xml.

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

Skapa en agent och generera ett diagram

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

Förväntad utdata

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.

Agenten skapar en kodtolksession, skriver Python-kod med hjälp av matplotlib för att generera diagrammet och kör koden i en miljö med begränsat läge. Om du vill ha ett exempel som laddar upp en CSV-fil och laddar ned det genererade diagrammet väljer du Python eller TypeScript från språkväljaren överst i den här artikeln. Fler exempel finns i Azure AI-agenter Java SDK-exempel.

Skapa ett diagram med kodtolkaren med hjälp av REST-API:et

I följande exempel visas hur du laddar upp en CSV-fil, skapar en agent med kodtolkare, begär ett diagram och laddar ned den genererade filen.

Förutsättningar

Ange följande miljövariabler:

• FOUNDRY_PROJECT_ENDPOINT: Projektets slutpunkts-URL.
• AGENT_TOKEN: En bearer-token för Foundry.

Hämta en åtkomsttoken:

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

1. Ladda upp en CSV-fil

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

Spara id från svaret (till exempel file-abc123).

2. Skapa en agent med kodtolkare

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. Generera ett diagram

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

Svaret innehåller container_file_citation anteckningar med den genererade filinformationen. Spara container_id och file_id-värdena från anteckningen.

4. Ladda ned det genererade diagrammet

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

5. Rensa

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

Kontrollera regional tillgänglighet och modelltillgänglighet

Verktygets tillgänglighet varierar beroende på region och modell.

Den aktuella listan över regioner och modeller som stöds för kodtolkare finns i Metodtips för att använda verktyg i Microsoft Foundry Agent Service.

Filtyper som stöds

Filformat	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 eller text/xml
.zip	application/zip

Felsökning

Problematik	Sannolik orsak	Lösning / Beslut
Kodtolkaren körs inte.	Verktyget är inte aktiverat eller så stöder inte modellen det i din region.	Bekräfta att kodtolkaren är aktiverad på agenten. Kontrollera att modelldistributionen stöder verktyget i din region. Se Kontrollera regional tillgänglighet och modelltillgänglighet.
Ingen fil genereras.	Agenten returnerade textsvar utan filanteckning.	Kontrollera svarsanteckningar för container_file_citation. Om ingen fil finns, har agenten inte genererat någon. Omformulera uppmaningen för att uttryckligen begära filutmatning.
Filuppladdningen misslyckas.	Filtyp som inte stöds eller fel syfte.	Bekräfta att filtypen finns i listan med filtyper som stöds . Ladda upp med purpose="assistants".
Den genererade filen är skadad eller tom.	Kodkörningsfel eller ofullständig bearbetning.	Kontrollera agentens svar för felmeddelanden. Kontrollera att indata är giltiga. Prova en enklare begäran först.
Tidsgräns för sessioner eller långa svarstider.	Kodtolkarsessioner har tidsgränser.	Sessioner har en aktiv timeout på 1 timme och en inaktiv timeout på 30 minuter. Minska komplexiteten i åtgärder eller dela upp i mindre uppgifter.
Oväntade faktureringsavgifter.	Flera samtidiga sessioner har skapats.	Varje konversation skapar en separat session. Övervaka sessionsanvändning och konsolidera åtgärder där det är möjligt.
Python paketet är inte tillgängligt.	Kodtolkaren har en fast uppsättning paket.	Kodtolkaren innehåller vanliga datavetenskapspaket. Använd anpassad kodtolkare för anpassade paket.
Filhämtningen misslyckas.	Container-ID eller fil-ID är felaktigt.	Kontrollera att du använder rätt container_id och file_id från svarsanteckningarna.

Rensa resurser

Ta bort resurser som du skapade i det här exemplet när du inte längre behöver dem för att undvika löpande kostnader:

• Ta bort agentversionen.
• Ta bort konversationen.
• Ta bort uppladdade filer.

Exempel på konversations- och filrensningsmönster finns i Webbsökningsverktyg och Filsökningsverktyg för agenter.

Körningsmiljö i begränsat läge

Kodtolkaren kör Python-kod i en Microsoft-hanterad sandbox-miljö. Sandbox-miljön är utformad för att köra obetrodd kod och använder dynamiska sessioner (kodtolkarsessioner) i Azure Container Apps. Varje session isoleras av en Hyper-V gräns.

Viktiga beteenden att planera för:

• Region: Sandbox-miljön för kodtolkaren körs i samma Azure-region som ditt Foundry-projekt.
• Sessionslivslängd: En kodtolksession är aktiv i upp till en timme med en tidsgräns för inaktivitet (se viktig anteckning i början av den här artikeln).
• Isolering: Varje session körs i en isolerad miljö. Om agenten anropar kodtolkaren samtidigt i olika konversationer skapas separata sessioner.
• Nätverksisolering och Internetåtkomst: Sandbox-miljön ärver inte konfigurationen av agentundernätet och dynamiska sessioner kan inte göra utgående nätverksbegäranden.
• Filer i sandbox-miljön: Python-körningen i begränsat läge har åtkomst till filer som du bifogar för analys. Kodtolkare kan också generera filer, till exempel diagram, och returnera dem som nedladdningsbara utdata.

Om du behöver mer kontroll över sandbox-körningen eller om du behöver en annan isoleringsmodell kan du läsa Verktyget för anpassad kodtolkning för agenter.

Relaterat innehåll

• Metodtips för att använda verktyg i Microsoft Foundry Agent Service
• Anpassat kodtolkarverktyg för agenter (förhandsversion)