Alat penerjemah kode kustom untuk agen (pratinjau)

Penting

Item yang ditandai sebagai pratinjau dalam artikel ini saat ini masih dalam pratinjau. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan Microsoft tidak merekomendasikannya untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan yang dibatasi. Untuk informasi selengkapnya, lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure.

Penerjemah kode kustom memberi Anda kontrol penuh atas lingkungan runtime untuk kode Python yang dihasilkan agen. Anda dapat mengonfigurasi paket Python kustom, sumber daya komputasi, dan lingkungan Azure Container Apps. Kontainer penerjemah kode mengekspos server Model Context Protocol (MCP).

Gunakan penerjemah kode kustom saat alat Code Interpreter bawaan untuk agen tidak memenuhi persyaratan Anda—misalnya, saat Anda memerlukan paket Python tertentu, gambar kontainer kustom, atau sumber daya komputasi khusus.

Untuk informasi selengkapnya tentang MCP dan cara agen tersambung ke alat MCP, lihat Menyambungkan ke server Protokol Konteks Model (pratinjau).

Tip

Pertimbangkan untuk menambahkan alat ini menggunakan kotak alat. Dengan menggunakan kotak alat, Anda dapat menggunakan kembali alat di seluruh agen dan runtime, serta memusatkan manajemen kredensial, penerapan versi, dan penegakan kebijakan melalui titik akhir MCP terkelola. Lihat panduan memulai cepat kotak alat.

Prasyarat

Azure CLI versi 2.60.0 atau yang lebih baru.
Python 3.12 atau yang lebih baru untuk proyek sampel yang dipertahankan.
(Opsional) uv untuk manajemen paket Python yang lebih cepat.
Langganan Azure dan grup sumber daya dengan penetapan peran berikut:
- Pengguna Foundry di proyek Foundry untuk mengonfigurasi dan menjalankan agen setelah penyediaan.
  
  Penting
  
  Peran Foundry RBAC baru-baru ini diubah namanya. Pengguna Foundry, Pemilik Foundry, Pemilik Akun Foundry, dan Manajer Proyek Foundry sebelumnya bernama Pengguna Azure AI, Pemilik Azure AI, Pemilik Akun Azure AI, dan Manajer Proyek Azure AI. Anda mungkin masih melihat nama sebelumnya di beberapa tempat saat penggantian nama diluncurkan. ID peran dan izin inti tidak berubah oleh penggantian nama.
- Pemilik Foundry pada grup sumber daya target hanya saat penyebaran sampel membuat sumber daya Foundry dan koneksi proyek.
- Kontributor Container Apps ManagedEnvironment pada grup sumber daya target hanya saat penyebaran sampel membuat lingkungan Container Apps.
Aktifkan peran penyediaan saat diperlukan melalui Microsoft Entra Privileged Identity Management (PIM), dan nonaktifkan peran tersebut setelah deployment. Pengembang agen dan pengguna runtime yang bekerja sehari-hari tidak memerlukan peran penyediaan ini.
Sebuah SDK Microsoft Foundry. Lihat panduan singkat untuk pemasangan.
Wilayah yang didukung oleh kedua layanan Foundry Agent Service dan Azure Container Apps Dynamic Sessions. Lihat wilayah Sesi Dinamis Azure Container Apps.

Dukungan penggunaan

Artikel ini menggunakan Azure CLI dan proyek sampel yang dapat dijalankan.

Tabel berikut ini memperlihatkan SDK dan dukungan penyiapan.

dukungan Microsoft Foundry	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Penyiapan agen dasar	Penyiapan agen standar
✔️	✔️	✔️	✔️	✔️	✔️	-	✔️

Untuk dukungan SDK dan API terbaru untuk alat agen, lihat praktik terbaik untuk menggunakan alat di Microsoft Foundry Agent Service.

Dukungan SDK

Penerjemah kode kustom menggunakan jenis alat MCP. SDK apa pun yang mendukung alat MCP dapat membuat agen penerjemah kode kustom. SDK .NET saat ini dalam pratinjau. Untuk langkah-langkah provisi infrastruktur (Azure CLI, Bicep), lihat Buat agen dengan penerjemah kode kustom.

Sebelum Anda mulai

Prosedur ini menyediakan infrastruktur Azure, termasuk sumber daya Azure Container Apps. Tinjau persyaratan biaya dan tata kelola organisasi Anda Azure sebelum menyebarkan.

Membuat agen dengan penerjemah kode kustom

Langkah-langkah berikut menunjukkan cara menyediakan infrastruktur dan membuat agen yang menggunakan server MCP penerjemah kode kustom. Penyiapan infrastruktur berlaku untuk semua bahasa. Sampel kode yang spesifik untuk bahasa tertentu disajikan.

Mendaftarkan fitur pratinjau

Daftarkan fitur server MCP untuk Sesi Dinamis Azure Container Apps:

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

Dapatkan kode sampel

Kloning kode sample di repositori GitHub dan navigasikan ke folder samples/python/prompt-agents/code-interpreter-custom di terminal Anda.

Memprovisikan infrastruktur

Sampel agen langsung yang dikelola menyimpan titik akhir MCP kumpulan sesi dalam koneksi proyek. Definisi kotak alat juga memerlukan titik akhir sebagai server_url. Tambahkan output ini ke file kloning infra.bicep :

output MCP_SERVER_URL string = sessionPool.properties.mcpServerSettings.mcpServerEndpoint

Jangan gunakan poolManagementEndpoint. Nilai tersebut adalah titik akhir manajemen Sesi Dinamis, bukan titik akhir server MCP.

Untuk menyediakan infrastruktur, jalankan perintah berikut dengan menggunakan Azure CLI (az):

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

Catatan

Penyebaran dapat memakan waktu hingga satu jam, bergantung pada jumlah instance siaga yang Anda minta. Alokasi kumpulan sesi dinamis adalah langkah terpanjang.

Mengonfigurasi dan menjalankan agen

.env.sample Salin file dari repositori ke .env. Petakan output penyebaran Bicep ke variabel lingkungan yang cocok:

Output Bicep	Variabel Lingkungan	Digunakan untuk
`AZURE_AI_PROJECT_ENDPOINT`	`AZURE_AI_PROJECT_ENDPOINT`	Titik akhir proyek Foundry.
`AZURE_AI_CONNECTION_ID`	`AZURE_AI_CONNECTION_ID`	Koneksi proyek yang targetnya adalah server MCP interpreter kode kustom.
`MCP_SERVER_URL`	`MCP_SERVER_URL`	Titik akhir MCP kumpulan sesi yang diperlukan oleh definisi kotak alat.
`AZURE_AI_MODEL_DEPLOYMENT_NAME`	`AZURE_AI_MODEL_DEPLOYMENT_NAME`	Penyebaran model agen.

Contoh sebaris menggunakan PROJECT_ENDPOINT untuk AZURE_AI_PROJECT_ENDPOINT dan MCP_CONNECTION_ID untuk AZURE_AI_CONNECTION_ID. Contoh direct-agent yang dipelihara menentukan target MCP melalui koneksi proyek dan menggunakan https://localhost sebagai URL placeholder yang diperlukan. Untuk kotak peralatan, atur MCP_SERVER_URL ke output mcpServerEndpoint karena MCPToolboxTool memerlukan server_url atau connector_id bahkan saat Anda juga menyediakan koneksi proyek.

Instal dependensi Python dan jalankan sampel yang dipertahankan dengan salah satu pasangan perintah ini:

uv sync
uv run ./main.py

Atau buat lingkungan virtual dan instal persyaratan check-in:

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

Contoh kode

Sampel Python berikut menunjukkan cara membuat agen dengan alat MCP penerjemah kode kustom:

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"
AGENT_NAME = "CustomCodeInterpreterAgent"
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 a client to call Foundry API
with AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
) as project:
    # 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=AGENT_NAME,
        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})")

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

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

Output yang diharapkan

Saat menjalankan sampel, Anda akan melihat output yang mirip dengan:

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

Menggunakan agen yang dihosting

Contoh ini menggunakan FoundryChatClient dari Microsoft Agent Framework dan menghubungkan ke endpoint MCP toolbox menggunakan FoundryToolbox.

import asyncio

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from azure.identity import AzureCliCredential
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"


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.
    toolbox_tool = FoundryToolbox(credential, url=TOOLBOX_MCP_URL)

    agent = Agent(
        client=FoundryChatClient(credential=credential),
        instructions="You are a helpful assistant that can run Python code to analyze data and solve problems.",
        tools=[toolbox_tool],
    )

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


    project.toolboxes.delete_version(
      name=toolbox.name,
      version=toolbox.version,
    )


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

Contoh kode

Sampel C# berikut menunjukkan cara membuat agen dengan alat MCP penerjemah kode kustom. Untuk informasi selengkapnya tentang bekerja dengan alat MCP di .NET, lihat sampel alat MCP di Azure SDK untuk repositori .NET di 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");

Hapus versi toolbox setelah agen tidak lagi merujuk ke versi tersebut. Lihat Menghapus versi toolbox untuk melihat panggilan .NET yang terverifikasi.

Output yang diharapkan

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

Menggunakan agen yang dihosting

Sampel ini menggunakan integrasi Microsoft Agent Framework AddFoundryToolboxes untuk menghubungkan agen yang dihosting ke kotak alat.

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.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
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");

// Create the hosted agent and register the toolbox integration.
AIAgent agent = projectClient.AsAIAgent(
    model: deploymentName,
    instructions: "You are a helpful assistant with access to the toolbox tools.",
    name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxVersion.Name);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Contoh kode

Sampel TypeScript berikut menunjukkan cara membuat agen dengan alat MCP penerjemah kode kustom. Untuk versi JavaScript, lihat sampel alat MCP di Azure SDK untuk repositori JavaScript di 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 yang diharapkan

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

Direkomendasikan: Untuk sebagian besar agen, tambahkan alat melalui kotak alat dan lampirkan kotak alat ke agen Anda sebagai alat MCP. SDK Java belum mengekspos API pembuatan kotak alat, jadi buat kotak alat dengan menggunakan contoh Python, REST API, C#, atau TypeScript, atau portal Foundry, lalu referensikan titik akhir MCP-nya dari agen Java Anda sebagai McpTool. Contoh berikut menautkan endpoint MCP toolbox yang berisi interpreter kode kustom ke agen.

Tambahkan dependensi ke pom.xml:

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

Contoh kode

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 yang diharapkan

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

Prasyarat

Atur variabel lingkungan ini:

FOUNDRY_PROJECT_ENDPOINT: URL titik akhir proyek Anda.
AGENT_TOKEN: Token pembawa untuk Foundry.

Dapatkan token akses:

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

Contoh kode

Membuat kotak alat dengan penerjemah kode kustom

Tambahkan penerjemah kode kustom dengan membuat kotak alat. Kemudian, lampirkan kotak alat ke agen Anda sebagai alat MCP. Untuk informasi selengkapnya, lihat Apa itu kotak alat?

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

Toolbox menyediakan endpoint yang kompatibel dengan MCP di $FOUNDRY_PROJECT_ENDPOINT/toolboxes/custom-code-interpreter-toolbox/versions/<version>/mcp?api-version=v1, dengan <version> merupakan versi yang dikembalikan oleh panggilan sebelumnya.

Membuat koneksi alat jarak jauh ke kotak alat

Buat koneksi proyek alat jarak jauh yang menunjuk ke titik akhir kotak alat. Gunakan token Entra pengguna sehingga identitas pemanggil diteruskan (audiens 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

Membuat agen yang menggunakan kotak alat

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

Membuat respons

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

Bersihkan

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 yang diharapkan

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

Verifikasi pengaturan Anda

Setelah Anda menyediakan infrastruktur dan menjalankan sampel:

Konfirmasikan penyebaran Azure berhasil diselesaikan.
Konfirmasikan sampel tersambung menggunakan nilai dalam file Anda .env .
Di Microsoft Foundry, pastikan agen Anda melakukan pemanggilan alat dengan pelacakan. Untuk informasi selengkapnya, lihat praktik terbaik untuk menggunakan alat di Microsoft Foundry Agent Service.

Pemecahan masalah

Masalah	Kemungkinan penyebabnya	Resolusi
Pendaftaran fitur masih tertunda	Perintah `az feature register` mengembalikan `Registering` status.	Tunggu pendaftaran selesai (bisa memakan waktu 15-30 menit). Periksa status dengan `az feature show --namespace Microsoft.App --name SessionPoolsSupportMCP`. Kemudian jalankan `az provider register -n Microsoft.App` lagi.
Penyebaran gagal karena kesalahan izin	Tidak ada penetapan peran yang diperlukan.	Untuk penyebaran infrastruktur, aktifkan Pemilik Foundry dan Kontributor ManagedEnvironment Container Apps pada grup sumber daya target melalui Microsoft Entra PIM. Nonaktifkan setelah penerapannya. Untuk operasi agen, konfirmasikan bahwa Anda memiliki Pengguna Foundry pada proyek Foundry.
Penyebaran gagal dengan kesalahan wilayah	Wilayah yang dipilih tidak mendukung Sesi Dinamis Azure Container Apps.	Coba wilayah lain. Lihat wilayah Azure Container Apps untuk wilayah yang didukung.
Agen tidak memanggil alat	Koneksi MCP tidak dikonfigurasi dengan benar, atau instruksi agen tidak meminta penggunaan alat.	Gunakan pelacakan di Microsoft Foundry untuk mengonfirmasi pemanggilan alat. Verifikasi apakah `MCP_SERVER_URL` sesuai dengan titik akhir Aplikasi Kontainer yang telah Anda sebarkan. Lihat Praktik terbaik.
Batas waktu koneksi server MCP	Kumpulan sesi Container Apps sedang tidak berjalan atau tidak memiliki instans cadangan.	Periksa status kumpulan sesi di portal Azure. Tingkatkan `standbyInstanceCount` di templat Bicep Anda jika diperlukan.
Eksekusi kode gagal dalam kontainer	Paket Python yang hilang dalam kontainer kustom.	Perbarui gambar kontainer Anda untuk menyertakan paket yang diperlukan. Membangun ulang dan melakukan penerapan ulang kontainer.
Kesalahan autentikasi saat menyambungkan ke server MCP	Kredensial koneksi proyek tidak valid atau kedaluwarsa.	Regenerasikan kredensial koneksi dan perbarui file `.env`. Verifikasi formatnya `MCP_PROJECT_CONNECTION_ID` .

Keterbatasan

API tidak secara langsung mendukung input atau output file, atau penggunaan penyimpanan file. Untuk memasukkan dan mengeluarkan data, Anda harus menggunakan URL, seperti URL data untuk file kecil, dan URL tanda tangan akses bersama Azure Blob Service (SAS) untuk file besar.

Keamanan

Perlakukan kode yang dihasilkan dan dependensinya sebagai tidak tepercaya. Gunakan gambar dasar dan daftar izin paket yang disetujui, jalankan dengan komputasi dan izin minimum yang diperlukan, dan batasi akses jaringan keluar ke tujuan yang diperlukan. Jangan memasang data sensitif atau kredensial produksi ke dalam sesi.

Jika Anda menggunakan URL SAS untuk meneruskan data masuk ke atau keluar dari lingkungan runtime:

Gunakan token SAS berumur pendek.
Jangan mencatat URL SAS atau menyimpannya di kontrol sumber.
Batasi izin ke minimum yang diperlukan (misalnya, hanya-baca atau hanya-tulis).

Bersihkan

Untuk menghentikan penagihan untuk sumber daya yang disediakan, hapus sumber daya yang dibuat oleh penyebaran sampel. Jika Anda menggunakan grup sumber daya khusus untuk artikel ini, hapus grup sumber daya.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-08-24

Alat penerjemah kode kustom untuk agen (pratinjau)

Prasyarat

Dukungan penggunaan

Dukungan SDK

Sebelum Anda mulai

Membuat agen dengan penerjemah kode kustom

Mendaftarkan fitur pratinjau

Dapatkan kode sampel

Memprovisikan infrastruktur

Mengonfigurasi dan menjalankan agen

Contoh kode

Output yang diharapkan

Menggunakan agen yang dihosting

Contoh kode

Output yang diharapkan

Menggunakan agen yang dihosting

Contoh kode

Output yang diharapkan

Contoh kode

Output yang diharapkan

Prasyarat

Contoh kode

Membuat kotak alat dengan penerjemah kode kustom

Membuat koneksi alat jarak jauh ke kotak alat

Membuat agen yang menggunakan kotak alat

Membuat respons

Bersihkan

Output yang diharapkan

Verifikasi pengaturan Anda

Pemecahan masalah

Keterbatasan

Keamanan

Bersihkan

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: