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

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 C# SDK 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.

Prerequisiti

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

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 a .env e inserire i valori dall'output della distribuzione. Questi valori sono disponibili nel portale di Azure nel gruppo di risorse.

Installare le dipendenze Python usando uv sync o pip install. Infine, eseguire ./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 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")

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

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

Output previsto

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

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

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

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

Aggiungi la dipendenza a pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.0.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 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");
    }
}

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: un token portatore 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

1. Creare un agente con interprete di codice personalizzato

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

3. Pulire

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/CustomCodeInterpreterAgent?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 aver effettuato il provisioning dell'infrastruttura ed aver eseguito l'esempio:

  1. Verificare che la distribuzione Azure sia stata completata correttamente.
  2. Verificare che l'esempio si connetta utilizzando i valori nel file .env.
  3. In Microsoft Foundry, verificare che l'agente chiami lo strumento utilizzando il tracciamento. 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. Verificare di avere il ruolo di Azure AI Owner e Container Apps ManagedEnvironment Contributor nella sottoscrizione o nel gruppo di risorse.
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.
Agent 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 dal deployment di esempio. Se per questo articolo è stato usato un gruppo di risorse dedicato, eliminare il gruppo di risorse.

Contenuto correlato

  • Last updated on