Interpretador de código de serviço do Agente de IA do Azure

O Interpretador de Código permite que os agentes escrevam e executem código Python em um ambiente de execução em área restrita. Com o Interpretador de Código habilitado, seu agente pode executar o código iterativamente para resolver problemas de análise de dados, matemática e código mais desafiadores. Quando o Agente grava o código que não é executado, ele pode iterar nesse código modificando e executando código diferente até que a execução do código seja bem-sucedida.

Importante

O Interpretador de Código tem encargos adicionais além das taxas baseadas em token para uso do OpenAI do Azure. Se o Agente chamar o Interpretador de Código simultaneamente em dois threads diferentes, duas sessões de interpretador de código serão criadas. Cada sessão fica ativa por padrão por uma hora.

Modelos com suporte

A página de modelos contém as informações mais atualizadas sobre regiões/modelos em que há suporte para agentes e interpretador de código.

É recomendável usar agentes com os modelos mais recentes para aproveitar os novos recursos, janelas de contexto maiores e dados de treinamento mais atualizados.

Definir importações e criar um cliente de projeto

Python

Para usar o interpretador de código, primeiro adicione as instruções import mostradas no exemplo e crie um cliente de projeto, que conterá uma cadeia de conexão ao projeto de IA e será usado para autenticar chamadas à 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#

Para usar o interpretador de código, primeiro você precisa criar um cliente de projeto, que conterá uma cadeia de conexão para seu projeto de IA e será usado para autenticar chamadas à API.

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

Carregar um arquivo

Python

Carregue o arquivo usando a função upload_and_poll(), especificando o caminho do arquivo e a finalidade 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#

Os arquivos podem ser carregados e referenciados por agentes ou mensagens. Primeiro, use a API de upload generalizada com um purpose de Agents para disponibilizar uma ID de arquivo. Depois de carregado, a ID do arquivo pode ser fornecida para criar um repositório de vetores para ele. A ID do repositório de vetores pode ser fornecida a um agente após a criação.

Observação

Você não precisará fornecer toolResources se não criar um repositório de vetores.

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

Criar um agente com a ferramenta de interpretador de código

python

Defina a ferramenta code_interpreter com CodeInterpreterTool() e inclua a ID do arquivo que você carregou. Posteriormente, crie o agente com tools definido como code_interpreter.definitions e tool_resources definido como 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;

Criar um thread, uma mensagem e obter a resposta do agente

Python

Em seguida, crie um thread com create_thread() e anexe uma mensagem a ela usando create_message() que disparará a ferramenta de interpretador de código. Posteriormente, crie e execute uma execução com create_and_process_run(). Depois que a execução for concluída, você poderá excluir o arquivo do agente com delete_file() para liberar espaço no agente. Por fim, imprima as mensagens do agente.

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

Em seguida, crie um thread com CreateThreadAsync() e um thread com CreateMessageAsync(). Depois que o thread for criado, você poderá adicionar mensagens a ele com CreateMessageAsync() que fará com que a ferramenta de interpretador de código seja disparada. Crie uma execução e continue sondando-a até atingir um status de terminal. Supondo que a execução foi bem-sucedida, analise a resposta do agente listando as mensagens.

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

Baixar arquivos gerados pelo interpretador de código

Python

Os arquivos gerados pelo Interpretador de Código podem ser encontrados nas respostas de mensagem do Agente. Você pode baixar o arquivo de imagem gerado pelo interpretador de código, iterando por meio do image_contents da resposta e chamando save_file() com um nome e a ID do arquivo.

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

Os arquivos gerados pelo interpretador de código podem ser encontrados nas respostas de mensagem do Agente. Você pode baixar o arquivo de imagem gerado pelo interpretador de código iterando por meio das mensagens da resposta e verificando se há um ImageFileId. Se esse campo existir, use o seguinte código:

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

Tipos de arquivo compatíveis

Formato de arquivo	Tipo MIME
.c	text/x-c
.cpp	text/x-c++
.csv	application/csv
.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html	text/html
.java	text/x-java
.json	application/json
.md	text/markdown
.pdf	application/pdf
.php	text/x-php
.pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation
.py	text/x-python
.py	text/x-script.python
.rb	text/x-ruby
.tex	text/x-tex
.txt	text/plain
.css	text/css
.jpeg	image/jpeg
.jpg	image/jpeg
.js	text/javascript
.gif	image/gif
.png	image/png
.tar	application/x-tar
.ts	application/typescript
.xlsx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml	application/xml ou text/xml
.zip	application/zip

Confira também

• Saiba mais sobre agentes.