你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure AI 代理服务代码解释器

借助代码解释器，代理可以在沙盒化执行环境中编写和运行 Python 代码。 启用代码解释器后，代理可以迭代运行代码，以解决更具挑战性的代码、数学和数据分析问题。 如果代理编写了无法运行的代码，它可以通过修改并运行不同的代码来循环访问此代码，直到代码执行成功。

重要

除了与使用 Azure OpenAI 相关的基于令牌的费用之外，代码解释器还有额外的费用。 如果代理在两个不同的线程中同时调用代码解释器，则会创建两个代码解释器会话。 默认情况下，每个会话处于活动状态一小时。

支持的模型

模型页包含有关支持代理和代码解释器的区域/模型的最新信息。

建议使用具有最新模型的代理来利用新功能、更大的上下文窗口和更新的训练数据。

使用支持

Azure AI Foundry 支持	Python SDK	C# SDK	JavaScript SDK	REST API	基本代理设置	标准代理设置
✔️	✔️	✔️	✔️	✔️	✔️	✔️

将代码解释器工具与代理配合使用

可以使用本文顶部列出的代码示例或 Azure AI Foundry 门户以编程方式将代码解释器工具添加到代理。 如果要使用门户：

1. 在代理的“创建和调试”屏幕中，向下滚动右侧的“设置”窗格以转到“操作”。 然后选择“添加”。

   

2. 选择“代码解释器”，然后按照提示添加该工具。

   

3. 可以选择上传文件，以供代理从数据集读取和解释信息、生成代码，以及使用数据创建图形和图表。

   

创建项目客户端

Python

要使用代码解释器，请先添加示例中所示的 import 语句，并创建一个项目客户端，其中包含 AI 项目的连接字符串，并将用于对 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"]
)

C#

要使用代码解释器，首先需要创建一个项目客户端，其中将会包含 AI 项目的连接字符串，并将用于对 API 调用进行身份验证。

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

JavaScript

要使用代码解释器，首先需要创建一个项目客户端，其中将会包含 AI 项目的连接字符串，并将用于对 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(),
);

REST API

按照 REST API 快速入门设置环境变量 AZURE_AI_AGENTS_TOKEN 和 AZURE_AI_AGENTS_ENDPOINT 的正确值。

上传文件

Python

使用 upload_and_poll() 函数上传文件，以指定文件路径和 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}")

C#

可以上传文件，然后由代理或消息引用。 首先，将通用上传 API 与 Agents 的 purpose 配合使用以提供文件 ID。 上传后，可以提供文件 ID 以为其创建矢量存储。 然后，可以在创建时向代理提供矢量存储 ID。

注意

如果不创建矢量存储，则无需提供 toolResources。

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

JavaScript

可以上传文件，然后由代理或消息引用。 上传后，可将其添加到工具实用工具进行引用。

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

REST API

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"

使用代码解释器工具创建代理

Python

使用 CodeInterpreterTool() 定义 code_interpreter 工具，并包括所上传文件的文件 ID。 之后，创建将 tools 设为 code_interpreter.definitions，并将 tool_resources 设为 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,
)

C#

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;

JavaScript

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

REST API

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

创建线程、消息并获取代理响应

Python

接下来，使用 create_thread() 创建线程，并使用将触发代码解释器工具的 create_message() 将消息附加到该线程。 之后，使用 create_and_process_run() 创建并执行运行。 运行完成后，可以使用 delete_file() 从代理中删除该文件，以释放代理中的空间。 最后，打印来自代理的消息。

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

C#

接下来，使用 CreateThreadAsync() 一个线程，然后使用 CreateMessageAsync() 创建一个线程。 创建线程后，可以使用将导致代码解释器工具触发的 CreateMessageAsync() 向它添加消息。 创建一个运行，然后持续轮询它，直到它达到终止状态。 假设运行成功后，通过列出消息来分析代理的响应。

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

JavaScript

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

REST API

创建线程

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 ''

将用户问题添加到线程

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

运行线程

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

检索运行状态

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

检索代理响应

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

下载代码解释器生成的文件

Python

可以在代理消息响应中查找代码解释器生成的文件。 可以通过循环访问响应的 image_contents 并使用名称和文件 ID 调用 save_file() 来下载代码解释器生成的映像文件。

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

C#

可以在代理消息响应中查找代码解释器生成的文件。 可以通过循环访问响应的消息并检查 ImageFileId 来下载代码解释器生成的映像文件。 如果该字段存在，请使用以下代码：

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

JavaScript

无法检索回代理上传的文件。 如果你的用例需要访问代理上传的文件内容，建议保留应用程序可访问的其他副本。 但是，代理生成的文件可通过 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}`);

REST API

当代码解释器生成图像时，可以在助理消息响应的 file_id 字段中查找生成的文件：

{
	"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"
      }
    }
  ],
  # ...
}

然后，可以使用以下方法下载它：

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

支持的文件类型

文件格式	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 或 text/xml
.zip	application/zip

另请参阅

• 详细了解代理。