Strumento di interprete del codice personalizzato per gli agenti (anteprima)

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per altre informazioni, vedere Condizioni supplementari per l'utilizzo delle anteprime di Microsoft Azure.

Un interprete di codice personalizzato offre il controllo completo sull'ambiente di runtime per il codice Python generato dall'agente. È possibile configurare pacchetti Python personalizzati, risorse di calcolo e l'ambiente di App contenitore di Azure. Il contenitore dell'interprete di codice espone un server MCP (Model Context Protocol).

Usare un interprete di codice personalizzato quando lo strumento integrato di interpretazione del codice per gli agenti non soddisfa i requisiti, ad esempio quando sono necessari specifici pacchetti Python, immagini di container personalizzate o risorse di calcolo dedicate.

Per altre informazioni su MCP e su come gli agenti si connettono agli strumenti MCP, vedere Connettersi ai server del protocollo di contesto del modello (anteprima).

Tip

Prendere in considerazione l'aggiunta di questo strumento usando una casella degli strumenti. Usando una casella degli strumenti, è possibile riutilizzare lo strumento tra agenti e runtime, nonché centralizzare la gestione delle credenziali, il controllo delle versioni e l'imposizione dei criteri tramite un endpoint MCP gestito. Vedere la guida introduttiva alla casella degli strumenti.

Prerequisiti

• interfaccia della riga di comando di Azure versione 2.60.0 o successiva.

• Python 3.12 o versione successiva per il progetto di esempio gestito.

• (Facoltativo) uv per una gestione più rapida dei pacchetti Python.

• Una sottoscrizione Azure e un gruppo di risorse con le assegnazioni di ruolo seguenti:

  • Foundry User nel progetto Foundry per la configurazione e l'esecuzione dell'agente dopo il provisioning.

    Importante

    I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

  • Foundry Owner nel gruppo di risorse di destinazione solo mentre la distribuzione di esempio crea le risorse foundry e la connessione al progetto.

  • Collaboratore di App contenitore GestitoEnvironment nel gruppo di risorse di destinazione solo mentre la distribuzione di esempio crea l'ambiente App contenitore.

  Attivare i ruoli di provisioning just-in-time tramite Microsoft Entra Privileged Identity Management (PIM) e disattivarli dopo la distribuzione. Gli sviluppatori dell'agente quotidiano e gli utenti di runtime non necessitano di questi ruoli di provisioning.

• Microsoft Foundry SDK. Vedere la guida introduttiva per l'installazione.

Supporto per l'utilizzo

Questo articolo usa il interfaccia della riga di comando di Azure e un progetto di esempio eseguibile.

La tabella seguente illustra il supporto dell'SDK e della configurazione.

Supporto Foundry di Microsoft	PYTHON SDK	SDK di C#	JavaScript SDK	JAVA SDK	REST API	Configurazione dell'agente di base	Configurazione dell'agente standard
✔️	✔️	✔️	✔️	✔️	✔️	-	✔️

Per informazioni sul supporto dell'SDK e delle API più recenti per gli strumenti degli agenti, vedere Best practices per l'uso degli strumenti in Microsoft Foundry Agent Service.

Supporto SDK

L'interprete di codice personalizzato usa il tipo di strumento MCP. Qualsiasi SDK che supporta gli strumenti MCP può creare un agente dell'interprete del codice personalizzato. L'SDK di .NET è attualmente in anteprima. Per i passaggi di provisioning dell'infrastruttura (interfaccia della riga di comando di Azure, Bicep), vedere Creare un agente con interprete di codice personalizzato.

Prima di iniziare

Questa procedura effettua il provisioning dell'infrastruttura Azure, incluse le risorse App contenitore di Azure. Esaminare i requisiti di governance e costi Azure dell'organizzazione prima della distribuzione.

Creare un agente con interprete di codice personalizzato

I passaggi seguenti illustrano come effettuare il provisioning dell'infrastruttura e creare un agente che usa un server MCP dell'interprete di codice personalizzato. La configurazione dell'infrastruttura si applica a tutte le lingue. Di seguito sono seguiti esempi di codice specifici del linguaggio.

Registrare la funzionalità di anteprima

Registrare l'opzione server MCP per sessioni dinamiche di App contenitore di Azure.

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

Ottenere il codice di esempio

Clonare il codice sample nel repository GitHub e passare alla cartella samples/python/prompt-agents/code-interpreter-custom nel terminale.

Configurare l'infrastruttura

L'esempio di agente diretto gestito archivia l'endpoint MCP del pool di sessioni nella connessione al progetto. Le definizioni della casella degli strumenti richiedono anche l'endpoint come server_url. Aggiungere questo output al file clonato infra.bicep :

output MCP_SERVER_URL string = sessionPool.properties.mcpServerSettings.mcpServerEndpoint

Non usare poolManagementEndpoint. Questo valore è l'endpoint di gestione delle sessioni dinamiche, non l'endpoint server MCP.

Per effettuare il provisioning dell'infrastruttura, eseguire il comando seguente usando il interfaccia della riga di comando di Azure (az):

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

Nota

La distribuzione può richiedere fino a un'ora, a seconda del numero di istanze di standby richieste. L'allocazione dinamica del pool di sessioni è il passaggio più lungo.

Configurare ed eseguire l'agente

Copiare il .env.sample file dal repository in .env. Eseguire il mapping degli output della distribuzione Bicep alle variabili di ambiente corrispondenti:

Bicep output	Variabile di ambiente	Usato per
AZURE_AI_PROJECT_ENDPOINT	AZURE_AI_PROJECT_ENDPOINT	Endpoint del progetto Foundry.
AZURE_AI_CONNECTION_ID	AZURE_AI_CONNECTION_ID	Project connessione la cui destinazione è il server MCP dell'interprete del codice personalizzato.
MCP_SERVER_URL	MCP_SERVER_URL	Endpoint MCP del pool di sessioni richiesto dalle definizioni della casella degli strumenti.
AZURE_AI_MODEL_DEPLOYMENT_NAME	AZURE_AI_MODEL_DEPLOYMENT_NAME	Distribuzione del modello di agente.

Gli esempi inline usano PROJECT_ENDPOINT per AZURE_AI_PROJECT_ENDPOINT e MCP_CONNECTION_ID per AZURE_AI_CONNECTION_ID. L'esempio di agente diretto gestito risolve la destinazione MCP tramite la connessione al progetto e usa https://localhost come URL segnaposto obbligatorio. Per una casella degli strumenti, impostare sull'output MCP_SERVER_URLmcpServerEndpoint perché MCPToolboxTool richiede server_url o connector_id anche quando si fornisce anche una connessione al progetto.

Installare le dipendenze Python ed eseguire l'esempio gestito con una delle coppie di comandi seguenti:

uv sync
uv run ./main.py

In alternativa, creare un ambiente virtuale e installare i requisiti di archiviazione:

python -m venv .venv
./.venv/bin/pip install -r requirements.txt
./.venv/bin/python ./main.py

Esempio di codice

L'esempio di Python seguente illustra come creare un agente utilizzando uno strumento MCP per interprete di codice personalizzato.

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

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

# Add the custom code interpreter MCP server 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
toolbox = project.toolboxes.create_version(
    name="custom-code-interpreter-toolbox",
    description="Toolbox with the custom code interpreter MCP server",
    tools=[
        MCPToolboxTool(
            server_label="custom-code-interpreter",
            server_url=MCP_SERVER_URL,
            project_connection_id=MCP_CONNECTION_ID,
        )
    ],
)

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

# 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 custom-code-interpreter-toolbox-conn \
#      --kind remote-tool \
#      --target "<TOOLBOX_MCP_URL>" \
#      --auth-type user-entra-token \
#      --audience https://ai.azure.com
TOOLBOX_CONNECTION_NAME = "custom-code-interpreter-toolbox-conn"

# Create an agent that uses the toolbox as an MCP tool
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=[
            MCPTool(
                server_label="toolbox",
                server_url=TOOLBOX_MCP_URL,
                require_approval="never",
                project_connection_id=TOOLBOX_CONNECTION_NAME,
            )
        ],
    ),
    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)
project.toolboxes.delete_toolbox_version(
  toolbox_name=toolbox.name,
  version=toolbox.version,
)
print("Agent deleted")

Output previsto

Quando si esegue l'esempio, viene visualizzato un output simile al seguente:

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

Usare un agente ospitato

Questo esempio usa FoundryChatClient da Microsoft Agent Framework e si connette all'endpoint MCP della casella degli strumenti usando MCPStreamableHTTPTool.

import asyncio
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 MCPToolboxTool

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"
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"


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

    # 1. Create the custom code interpreter MCP tool and add it to a toolbox. Using a toolbox is the
    #    recommended way to give agents tools: curate tools once and reuse the
    #    toolbox across agents. See /azure/foundry/agents/concepts/toolbox-overview
    project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=credential)
    toolbox = project.toolboxes.create_version(
        name="custom-code-interpreter-toolbox",
        description="Toolbox with the custom code interpreter MCP server",
        tools=[
            MCPToolboxTool(
                server_label="custom-code-interpreter",
                server_url=MCP_SERVER_URL,
                project_connection_id=MCP_CONNECTION_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 run Python code to analyze data and solve problems.",
        tools=[mcp_tool],
    )

    result = await agent.run("Calculate the factorial of 10 using Python.")
    print(result.text)

    await http_client.aclose()
    project.toolboxes.delete_toolbox_version(
      toolbox_name=toolbox.name,
      version=toolbox.version,
    )


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

Esempio di codice

L'esempio C# seguente illustra come creare un agente con uno strumento MCP dell'interprete di codice personalizzato. Per altre informazioni sull'uso degli strumenti MCP in .NET, vedere l'esempio di strumento MCP nel Azure SDK per .NET repository in 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";
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());

// Add the custom code interpreter MCP server to a toolbox. Using a toolbox is the
// recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
// Code runs in a sandboxed Azure Container Apps session.
McpTool customCodeInterpreter = ResponseTool.CreateMcpTool(
    serverLabel: "custom-code-interpreter",
    serverUri: new Uri(mcpServerUrl));
customCodeInterpreter.ProjectConnectionId = mcpConnectionId;

ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "custom-code-interpreter-toolbox",
        tools: [ProjectsAgentTool.AsProjectTool(customCodeInterpreter)],
        description: "Toolbox with the custom code interpreter MCP server");

// The toolbox exposes an MCP-compatible endpoint.
var toolboxMcpUrl = new Uri(
    $"{projectEndpoint}/toolboxes/{toolboxVersion.Name}" +
    $"/versions/{toolboxVersion.Version}/mcp?api-version=v1");

// 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 custom-code-interpreter-toolbox-conn \
//      --kind remote-tool \
//      --target "<toolboxMcpUrl>" \
//      --auth-type user-entra-token \
//      --audience https://ai.azure.com
var toolboxConnectionName = "custom-code-interpreter-toolbox-conn";

McpTool toolboxTool = ResponseTool.CreateMcpTool(
    serverLabel: "toolbox",
    serverUri: toolboxMcpUrl,
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.NeverRequireApproval));
toolboxTool.ProjectConnectionId = toolboxConnectionName;

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 = { toolboxTool }
};

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

Eliminare la versione della casella degli strumenti dopo che l'agente non vi fa più riferimento. Vedere Eliminare una versione della casella degli strumenti per la chiamata .NET verificata.

Output previsto

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

Usare un agente ospitato

Questo frammento di integrazione dipendente dall'helper usa il framework agente Microsoft per connettere un agente ospitato all'endpoint MCP della casella degli strumenti. L'articolo non definisce ToolboxMcpClient, ToolboxHandlere AgentConfig. Per l'implementazione gestita, vedere Connettere un agente ospitato a una casella degli strumenti.

using System;
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.DependencyInjection;
using OpenAI.Chat;

const string AgentInstructions = "You are a helpful assistant that can run Python code to analyze data and solve problems.";
const string AgentName = "CustomCodeInterpreterAgent";

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";
string mcpServerUrl = "https://your-mcp-server-url";
string mcpConnectionId = "your-mcp-connection-id";

DefaultAzureCredential credential = new();

// 1. Create the custom code interpreter MCP tool and add it 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);
McpTool customCodeInterpreter = ResponseTool.CreateMcpTool(
    serverLabel: "custom-code-interpreter",
    serverUri: new Uri(mcpServerUrl));
customCodeInterpreter.ProjectConnectionId = mcpConnectionId;
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "custom-code-interpreter-toolbox",
        tools: [ProjectsAgentTool.AsProjectTool(customCodeInterpreter)],
        description: "Toolbox with the custom code interpreter MCP server");

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

Esempio di codice

L'esempio seguente di TypeScript mostra come sviluppare un agente utilizzando uno strumento MCP per interprete di codice personalizzato. Per una versione JavaScript, vedere l'esempio di strumento MCP nel repository Azure SDK per JavaScript in 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();

  // Add the custom code interpreter MCP server to a toolbox. Using a toolbox is
  // the recommended way to give agents tools. Code runs in a sandboxed Azure
  // Container Apps session, so the tool uses require_approval: "never".
  // See /azure/foundry/agents/concepts/toolbox-overview
  const toolbox = await project.toolboxes.createVersion(
    "custom-code-interpreter-toolbox",
    [
      {
        type: "mcp",
        server_label: "custom-code-interpreter",
        server_url: MCP_SERVER_URL,
        require_approval: "never",
      },
    ],
    { description: "Toolbox with the custom code interpreter MCP server" },
  );

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

  // 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 custom-code-interpreter-toolbox-conn \
  //      --kind remote-tool \
  //      --target "<toolboxMcpUrl>" \
  //      --auth-type user-entra-token \
  //      --audience https://ai.azure.com
  const toolboxConnectionName = "custom-code-interpreter-toolbox-conn";

  // Create an agent that uses the toolbox as an MCP tool
  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: "toolbox",
        server_url: toolboxMcpUrl,
        require_approval: "never",
        project_connection_id: toolboxConnectionName,
      },
    ],
  });
  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_reference: { name: agent.name, type: "agent_reference" } },
    },
  );
  console.log(`Response: ${response.output_text}`);

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

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

Output previsto

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

Tip

Consigliato: Per la maggior parte degli agenti, aggiungere strumenti tramite una casella degli strumenti e collegare la casella degli strumenti all'agente come strumento MCP. L'SDK di Java non espone ancora un'API di creazione della casella degli strumenti, quindi creare la casella degli strumenti usando l'esempio Python, l'API REST, C# o TypeScript o il portale Foundry e quindi fare riferimento al relativo endpoint MCP dall'agente Java come McpTool. Nell'esempio seguente viene associato l'endpoint MCP della casella degli strumenti che contiene l'interprete di codice personalizzato all'agente.

Aggiungi la dipendenza a pom.xml:

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

Esempio di codice

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 toolboxMcpUrl = projectEndpoint + "/toolboxes/custom-code-interpreter-toolbox/versions/1/mcp?api-version=v1";
        // Set to the remote-tool project connection that points at the toolbox MCP endpoint.
        String toolboxConnectionId = "custom-code-interpreter-toolbox-conn";

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

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

        // Attach the toolbox MCP endpoint as an MCP tool.
        // Uses require_approval: "never" because code runs in a sandboxed Container Apps session.
        McpTool toolboxTool = new McpTool("toolbox")
            .setServerUrl(toolboxMcpUrl)
            .setProjectConnectionId(toolboxConnectionId)
            .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(toolboxTool));

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

Output previsto

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

Prerequisiti

Impostare queste variabili di ambiente:

• FOUNDRY_PROJECT_ENDPOINT: URL dell'endpoint del progetto.
• AGENT_TOKEN: token di connessione per Foundry.

Ottenere un token di accesso:

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

Esempio di codice

Creare una casella degli strumenti con l'interprete di codice personalizzato

Aggiungere l'interprete di codice personalizzato creando una casella degli strumenti. Collegare quindi la casella degli strumenti all'agente come strumento MCP. Per altre informazioni, vedere Che cos'è una casella degli strumenti?

curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/custom-code-interpreter-toolbox/versions?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "description": "Toolbox with the custom code interpreter MCP server",
    "tools": [
      {
        "type": "mcp",
        "server_label": "custom-code-interpreter",
        "server_url": "<MCP_SERVER_URL>",
        "project_connection_id": "<MCP_PROJECT_CONNECTION_ID>",
        "require_approval": "never"
      }
    ]
  }'

La casella degli strumenti espone un endpoint compatibile con MCP in $FOUNDRY_PROJECT_ENDPOINT/toolboxes/custom-code-interpreter-toolbox/versions/<version>/mcp?api-version=v1, dove <version> è la versione restituita dalla chiamata precedente.

Creare una connessione tramite strumento remoto alla casella degli strumenti

Creare una connessione al progetto strumento remoto che punta all'endpoint della casella degli strumenti. Usare un token Entra utente in modo che l'identità del chiamante venga passata (destinatari https://ai.azure.com):

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

Creare un agente che usa la casella degli strumenti

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

Creare una risposta

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

Eseguire la pulizia

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

curl -X DELETE \
  "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/custom-code-interpreter-toolbox/versions/<version>?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Output previsto

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

Verificare la configurazione

Dopo avere effettuato il provisioning dell'infrastruttura ed eseguito l'esempio:

1. Verificare che la distribuzione Azure sia stata completata correttamente.
2. Verificare che l'esempio si connetta usando i valori nel file .env.
3. In Microsoft Foundry verificare che l'agente chiami lo strumento usando la traccia. Per altre informazioni, vedere Best practices for using tools in Microsoft Foundry Agent Service.

Risoluzione dei problemi

Problema	Probabile causa	Risoluzione
La registrazione delle funzionalità è ancora in sospeso	Il az feature register comando restituisce Registering lo stato.	Attendere il completamento della registrazione (può richiedere 15-30 minuti). Controllare lo stato con az feature show --namespace Microsoft.App --name SessionPoolsSupportMCP. Eseguire quindi di nuovo az provider register -n Microsoft.App.
La distribuzione non riesce e viene visualizzato un errore di autorizzazione	Assegnazioni di ruolo necessarie mancanti.	Per la distribuzione dell'infrastruttura, attivare Foundry Owner e Container Apps ManagedEnvironment Contributor nel gruppo di risorse di destinazione tramite Microsoft Entra PIM. Disattivarli dopo la distribuzione. Per le operazioni dell'agente, verificare di avere Trovatory User nel progetto Foundry.
La distribuzione ha esito negativo e viene visualizzato un errore di area	L'area selezionata non supporta App contenitore di Azure sessioni dinamiche.	Provare un'area diversa. Per le aree supportate, vedere App contenitore di Azure.
L'agente non chiama lo strumento	La connessione MCP non è configurata correttamente o le istruzioni dell'agente non richiedono l'uso dello strumento.	Utilizzare il tracciamento in Microsoft Foundry per confermare l'invocazione dello strumento. Verificare che MCP_SERVER_URL corrisponda all'endpoint delle Container Apps distribuite. Vedere Procedure consigliate.
Timeout della connessione al server MCP	Il pool di sessioni di Container Apps non è in esecuzione o non dispone di istanze di standby.	Controllare lo stato del pool di sessioni nel portale di Azure. Aumenta standbyInstanceCount nel tuo modello Bicep, se necessario.
L'esecuzione del codice non riesce nel contenitore	Pacchetti Python mancanti nel contenitore personalizzato.	Aggiornare l'immagine del contenitore per includere i pacchetti necessari. Ricompilare e ridistribuire il contenitore.
Errore di autenticazione durante la connessione al server MCP	Le credenziali di connessione del progetto non sono valide o scadute.	Rigenerare le credenziali di connessione e aggiornare il .env file. Verificare il MCP_PROJECT_CONNECTION_ID formato.

Limitazioni

Gli API non supportano direttamente l'input o output dei file o l'uso degli archivi file. Per ottenere dati in uscita, è necessario usare URL, ad esempio URL di dati per file di piccole dimensioni e url di firma di accesso condiviso del servizio BLOB Azure per file di grandi dimensioni.

Sicurezza

Se si utilizzano URL SAS per passare i dati nel runtime o farli uscire dal runtime:

• Usare token di firma di accesso condiviso di breve durata.
• Non registrare gli URL SAS o memorizzarli nel controllo del codice sorgente.
• Limita le autorizzazioni all'ambito minimo richiesto (ad esempio, di sola lettura o di sola scrittura).

Eseguire la pulizia

Per interrompere la fatturazione per le risorse fornite, eliminare le risorse create dalla distribuzione di esempio. Se per questo articolo è stato usato un gruppo di risorse dedicato, eliminare il gruppo di risorse.

Contenuto correlato

• Connettersi ai server del Model Context Protocol (anteprima)
• Migliori pratiche per l'uso degli strumenti nel servizio agente Foundry di Microsoft
• App contenitore di Azure Sessioni Dinamiche
• Pool di sessioni con contenitori personalizzati
• ambiente App contenitore di Azure
• Installare il interfaccia della riga di comando di Azure
• Strumento interprete del codice per gli agenti