Средство интерпретатора пользовательского кода для агентов (предварительная версия)

Это важно

Элементы, обозначенные в этой статье как (предварительная версия), сейчас предлагаются в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и мы не рекомендуем ее для рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Дополнительные сведения см. в разделе Supplemental Terms of Use for Microsoft Azure Previews.

Настраиваемый интерпретатор кода обеспечивает полный контроль над средой выполнения для сгенерированного агентом кода Python. Вы можете настроить настраиваемые пакеты Python, вычислительные ресурсы и среду Контейнеры приложений Azure. Контейнер интерпретатора кода предоставляет сервер протокола контекста модели (MCP).

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

Дополнительные сведения о MCP и способах подключения агентов к средствам MCP см. в разделе "Подключение к серверам протокола контекста модели" (предварительная версия).

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

В этой статье используются Azure CLI и запускаемый пример проекта.

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

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

Сведения о последней поддержке пакета SDK и API для средств агентов см. в статье Best practices for using tools in Майкрософт Foundry Agent Service.

Поддержка пакета SDK

Пользовательский интерпретатор кода использует тип инструмента MCP. Любой пакет SDK, поддерживающий средства MCP, может создать пользовательский агент интерпретатора кода. Пакет SDK .NET в настоящее время находится в предварительной версии. Инструкции по подготовке инфраструктуры (Azure CLI, Bicep) см. в разделе Create агент с пользовательским интерпретатором кода.

Предпосылки

• Azure CLI версии 2.60.0 или более поздней.
• (Необязательно) uv для ускорения управления пакетами Python.
• Подписка Azure и группа ресурсов со следующими назначениями ролей:
  • владелец Azure ИИ
  • Участник ManagedEnvironment для контейнерных приложений
• Пакет разработки программного обеспечения Пакет SDK для Azure AI Foundry . См. краткое руководство по установке.

Перед тем как начать

Эта процедура подготавливает инфраструктуру Azure, включая ресурсы Контейнеры приложений Azure. Перед развертыванием ознакомьтесь с Azure затратами и требованиями к управлению вашей организации.

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

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

Регистрация функции предварительной версии

Зарегистрируйте функцию сервера MCP для динамических сеансов в Контейнеры приложений Azure:

az feature register --namespace Microsoft.App --name SessionPoolsSupportMCP
az provider register -n Microsoft.App

Получите пример кода

Клонируйте образец кода в репозитории GitHub и перейдите в samples/python/prompt-agents/code-interpreter-custom каталог в терминале.

Подготовка инфраструктуры

Чтобы подготовить инфраструктуру, выполните следующую команду с помощью Azure CLI (az):

az deployment group create \
    --name custom-code-interpreter \
    --subscription <your_subscription> \
    --resource-group <your_resource_group> \
    --template-file ./infra.bicep

Замечание

Развертывание может занять до одного часа в зависимости от количества запрашиваемых резервных экземпляров. Распределение динамического пула сеансов является самым длинным шагом.

Настройка и запуск агента

Скопируйте файл .env.sample из репозитория в .env и заполните значения из ваших выходных данных развертывания. Эти значения можно найти на портале Azure в группе ресурсов.

Установите зависимости Python с помощью uv sync или pip install. Наконец, запустите ./main.py.

Пример кода

В следующем примере на Python показано, как создать агент, используя пользовательский интерпретатор кода MCP:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, MCPTool

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
MCP_SERVER_URL = "https://your-mcp-server-url"
# Optional: set to your project connection ID if your MCP server requires authentication
MCP_CONNECTION_ID = "your-mcp-connection-id"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Configure the custom code interpreter MCP tool
custom_code_interpreter = MCPTool(
    server_label="custom-code-interpreter",
    server_url=MCP_SERVER_URL,
    project_connection_id=MCP_CONNECTION_ID,
)

# Create an agent with the custom code interpreter
agent = project.agents.create_version(
    agent_name="CustomCodeInterpreterAgent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can run Python code to analyze data and solve problems.",
        tools=[custom_code_interpreter],
    ),
    description="Agent with custom code interpreter for data analysis.",
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

# Test the agent with a simple calculation
response = openai.responses.create(
    input="Calculate the factorial of 10 using Python.",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(f"Response: {response.output_text}")

# Clean up
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")

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

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

Agent created (id: agent-xxxxxxxxxxxx, name: CustomCodeInterpreterAgent, version: 1)
Response: The factorial of 10 is 3,628,800. I calculated this using Python's math.factorial() function.
Agent deleted

Пример кода

В следующем примере C# показано, как создать агент с помощью пользовательского интерпретатора кода MCP. Дополнительные сведения о работе с инструментами MCP в .NET см. в примере средства MCP в Azure SDK репозитория .NET на GitHub.

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";
var mcpServerUrl = "https://your-mcp-server-url";
// Optional: set to your project connection ID if your MCP server requires authentication
var mcpConnectionId = "your-mcp-connection-id";

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create agent with custom code interpreter MCP tool
// Code runs in a sandboxed Azure Container Apps session
McpTool tool = ResponseTool.CreateMcpTool(
    serverLabel: "custom-code-interpreter",
    serverUri: new Uri(mcpServerUrl));
tool.ProjectConnectionId = mcpConnectionId;

DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant that can run Python code to analyze data and solve problems.",
    Tools = { tool }
};

AgentVersion agent = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "CustomCodeInterpreterAgent",
    options: new(agentDefinition));

Console.WriteLine($"Agent created: {agent.Name} (version {agent.Version})");

// Create a response using the agent
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agent.Name);

ResponseResult response = responseClient.CreateResponse(
    new([ResponseItem.CreateUserMessageItem("Calculate the factorial of 10 using Python.")]));

Console.WriteLine(response.GetOutputText());

// Clean up
projectClient.AgentAdministrationClient.DeleteAgentVersion(
    agentName: agent.Name,
    agentVersion: agent.Version);
Console.WriteLine("Agent deleted");

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

Agent created: CustomCodeInterpreterAgent (version 1)
The factorial of 10 is 3,628,800.
Agent deleted

Пример кода

В следующем примере TypeScript показано, как создать агента с пользовательским инструментом MCP интерпретатора кода. Сведения о версии JavaScript см. в примере средства MCP в репозитории Azure SDK для JavaScript на GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const MCP_SERVER_URL = "https://your-mcp-server-url";

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

  // Create agent with custom code interpreter MCP tool
  // The custom code interpreter uses require_approval: "never" because code
  // runs in a sandboxed Azure Container Apps session
  const agent = await project.agents.createVersion("CustomCodeInterpreterAgent", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions:
      "You are a helpful assistant that can run Python code to analyze data and solve problems.",
    tools: [
      {
        type: "mcp",
        server_label: "custom-code-interpreter",
        server_url: MCP_SERVER_URL,
        require_approval: "never",
      },
    ],
  });
  console.log(`Agent created (name: ${agent.name}, version: ${agent.version})`);

  // Send a request to the agent
  const response = await openai.responses.create(
    {
      input: "Calculate the factorial of 10 using Python.",
    },
    {
      body: { agent: { name: agent.name, type: "agent_reference" } },
    },
  );
  console.log(`Response: ${response.output_text}`);

  // Clean up
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

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

Agent created (name: CustomCodeInterpreterAgent, version: 1)
Response: The factorial of 10 is 3,628,800. I calculated this using Python's math.factorial() function.
Agent deleted

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

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

Пример кода

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.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 CustomCodeInterpreterExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";
        String mcpServerUrl = "https://your-mcp-server-url";
        // Optional: set to your project connection ID if your MCP server requires authentication
        String mcpConnectionId = "your-mcp-connection-id";

        // Create clients to call Foundry API
        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

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

        // Create custom code interpreter MCP tool
        // Uses require_approval: "never" because code runs in a sandboxed Container Apps session
        McpTool customCodeInterpreter = new McpTool("custom-code-interpreter")
            .setServerUrl(mcpServerUrl)
            .setProjectConnectionId(mcpConnectionId)
            .setRequireApproval("never");

        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini")
            .setInstructions("You are a helpful assistant that can run Python code to analyze data and solve problems.")
            .setTools(Collections.singletonList(customCodeInterpreter));

        AgentVersionDetails agent = agentsClient.createAgentVersion(
            "CustomCodeInterpreterAgent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("Calculate the factorial of 10 using Python."));

        System.out.println("Response: " + response.output());

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
        System.out.println("Agent deleted");
    }
}

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

Agent created: CustomCodeInterpreterAgent (version 1)
Response: The factorial of 10 is 3,628,800.
Agent deleted

Предпосылки

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

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

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

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

Пример кода

1. Создание агента с помощью пользовательского интерпретатора кода

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "CustomCodeInterpreterAgent",
    "definition": {
      "kind": "prompt",
      "model": "<MODEL_DEPLOYMENT>",
      "instructions": "You are a helpful assistant that can run Python code to analyze data and solve problems.",
      "tools": [
        {
          "type": "mcp",
          "server_label": "custom-code-interpreter",
          "server_url": "<MCP_SERVER_URL>",
          "project_connection_id": "<MCP_PROJECT_CONNECTION_ID>",
          "require_approval": "never"
        }
      ]
    }
  }'

2. Создание ответа

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": "CustomCodeInterpreterAgent"},
    "input": "Calculate the factorial of 10 using Python."
  }'

3. Очистка

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

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

{
  "id": "resp_xxxxxxxxxxxx",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The factorial of 10 is 3,628,800."
        }
      ]
    }
  ]
}

Проверка настройки

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

1. Убедитесь, что развертывание Azure выполнено успешно.
2. Убедитесь, что образец подключается, используя значения из файла .env.
3. Убедитесь, что в Майкрософт Foundry ваш агент вызывает инструмент с помощью трассировки. Дополнительные сведения см. в статье Best practices for using tools in Майкрософт Foundry Agent Service.

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

Проблема	Вероятно, причина	Резолюция
Регистрация функций по-прежнему ожидается	Команда az feature register возвращает Registering состояние.	Дождитесь завершения регистрации (может занять 15–30 минут). Проверьте состояние с помощью az feature show --namespace Майкрософт.App --name SessionPoolsSupportMCP. Затем снова запустите az provider register -n Майкрософт.App.
Сбой развертывания с ошибкой прав доступа	Отсутствуют необходимые назначения ролей.	Убедитесь, что у вас есть роли Владелец Azure AI и Участник ManagedEnvironment для Container Apps в подписке или группе ресурсов.
Сбой развертывания из-за региональной ошибки	Выбранный регион не поддерживает Контейнеры приложений Azure динамических сеансов.	Попробуйте другой регион. См. регионы Контейнеры приложений Azure для получения сведений о поддерживаемых регионах.
Агент не вызывает инструмент	Подключение MCP настроено неправильно, или инструкции агента не запрашивают использование средства.	Используйте трассировку в Майкрософт Foundry для подтверждения вызова средства. Проверьте, соответствует ли MCP_SERVER_URL вашей развернутой конечной точке приложений контейнеров. См. Лучшие практики.
Время ожидания подключения сервера MCP	Пул сеансов "Container Apps" не запущен или не имеет наготове доступных экземпляров.	Проверьте состояние пула сеансов на портале Azure. При необходимости увеличьте standbyInstanceCount в шаблоне Bicep.
Выполнение кода завершается сбоем в контейнере	Отсутствуют пакеты Python в пользовательском контейнере.	Обновите образ контейнера, чтобы включить необходимые пакеты. Перестройте и повторно разверните контейнер.
Ошибка проверки подлинности при подключении к серверу MCP	Учетные данные подключения к проекту недопустимы или истекли.	Повторно создайте учетные данные подключения и обновите .env файл. MCP_PROJECT_CONNECTION_ID Проверьте формат.

Ограничения

API не поддерживают напрямую входные или выходные данные файла или использование хранилищ файлов. Для получения и передачи данных необходимо использовать URL-адреса, такие как URL-адреса данных для небольших файлов и URL-адреса с подписанными строками доступа Blob-сервиса для больших файлов.

Безопасность

Если вы используете URL-адреса SAS для передачи данных в среду выполнения или из нее:

• Используйте кратковременные маркеры SAS.
• Не записывайте URL-адреса SAS или не сохраняйте их в системе управления версиями.
• Ограничьте разрешения до минимума (например, только для чтения или только для записи).

Очистка

Чтобы остановить выставление счетов за подготовленные ресурсы, удалите созданные пробной разверткой ресурсы. Если вы использовали выделенную группу ресурсов для этой статьи, удалите группу ресурсов.

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

• Подключение к серверам протокола контекста модели (предварительная версия)
• Наилучшие практики использования инструментов в службе Майкрософт Foundry Agent
• Контейнеры приложений Azure Dynamic Sessions
• Пулы сеансов с пользовательскими контейнерами
• среда Контейнеры приложений Azure
• Install Azure CLI
• Средство интерпретатора кода для агентов