Nástroj interpretu vlastního kódu pro agenty (Preview)

Důležité

Položky označené (Preview) v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v tématu Supplementální podmínky použití pro Microsoft Azure Verze Preview.

Interpret vlastního kódu poskytuje úplnou kontrolu nad prostředím runtime pro Python kód generovaný agentem. Můžete nakonfigurovat vlastní balíčky Python, výpočetní prostředky a Azure Container Apps prostředí nastavení. Kontejner interpretu kódu zveřejňuje server MCP (Model Context Protocol).

Vlastní interpret kódu použijte, když integrovaný nástroj Code Interpret pro agenty nesplňuje vaše požadavky – například pokud potřebujete konkrétní balíčky Python, vlastní image kontejnerů nebo vyhrazené výpočetní prostředky.

Další informace o MCP a o tom, jak se agenti připojují k nástrojům MCP, najdete v tématu Připojení k serverům s kontextem modelu (Preview).

Podpora využití

Tento článek používá Azure CLI a spustitelný ukázkový projekt.

Následující tabulka ukazuje podporu sady SDK a nastavení.

podpora Microsoft Foundry	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Základní nastavení agenta	Nastavení standardního agenta
✔️	✔️	✔️	✔️	✔️	✔️	-	✔️

Nejnovější podpora sady SDK a rozhraní API pro nástroje agentů je k dispozici v části Nejlepší postupy pro používání nástrojů ve službě Microsoft Foundry Agent.

Podpora sady SDK

Interpret vlastního kódu používá typ nástroje MCP. Každá sada SDK, která podporuje nástroje MCP, může vytvořit vlastního agenta interpreta kódu. Sada .NET SDK je aktuálně ve verzi Preview. Postup zřizování infrastruktury (Azure CLI, Bicep) najdete v tématu Vytvoření agenta pomocí interpreta vlastního kódu.

Požadavky

Azure CLI verze 2.60.0 nebo novější.
(Volitelné) uv pro rychlejší správu balíčků Python.
Předplatné Azure a skupina prostředků s následujícími přiřazeními rolí:
- Vlastník foundry
  
  Důležité
  
  Nedávno byly přejmenovány role Foundry RBAC. Foundry User, Foundry Owner, Foundry Account Owner a Foundry Project Manager se dříve nazývaly Uživatel Azure AI, Vlastník Azure AI, Vlastník účtu Azure AI a Správce projektů Azure AI. Během zavádění přejmenování se stále můžou zobrazovat předchozí názvy na některých místech. ID rolí a základní oprávnění se při přejmenování nezmění.
- Přispěvatel ManagedEnvironment služby Container Apps
Sada SDK Azure AI Foundry. Informace o instalaci najdete v rychlém startu .

Než začnete

Tento postup zřizuje infrastrukturu Azure, včetně prostředků Azure Container Apps. Před nasazením zkontrolujte požadavky vaší organizace na náklady na Azure a správu a řízení.

Vytvoření agenta s interpretem vlastního kódu

Následující kroky ukazují, jak zřídit infrastrukturu a vytvořit agenta, který používá vlastní server MCP interpret kódu. Nastavení infrastruktury platí pro všechny jazyky. Následují ukázky kódu specifické pro konkrétní jazyk.

Registrace funkce Preview

Zaregistrujte funkci serveru MCP pro dynamické relace Azure Container Apps:

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

Získání ukázkového kódu

Naklonujte kód sample v úložišti GitHub a přejděte do složky samples/python/prompt-agents/code-interpreter-custom v terminálu.

Zřízení infrastruktury

Pokud chcete zřídit infrastrukturu, spusťte následující příkaz pomocí Azure CLI (az):

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

Poznámka

Nasazení může trvat až jednu hodinu v závislosti na počtu instancí pohotovostního režimu, které požadujete. Přidělení dynamických relací ve fondu je nejdelší krok.

Konfigurace a spuštění agenta

Zkopírujte soubor z .env.sample úložiště do .env a naplňte hodnoty z výstupu vašeho nasazení. Tyto hodnoty najdete na portálu Azure pod skupinou prostředků.

Nainstalujte závislosti Python pomocí uv sync nebo pip install. Nakonec spusťte ./main.pypříkaz .

Příklad kódu

Následující Python ukázka ukazuje, jak vytvořit agenta pomocí vlastního nástroje MCP interpretu kódu:

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

Očekávaný výstup

Při spuštění ukázky se zobrazí výstup podobný následujícímu:

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

Příklad kódu

Následující ukázka jazyka C# ukazuje, jak vytvořit agenta pomocí vlastního nástroje MCP interpreta kódu. Další informace o práci s nástroji MCP v .NET najdete v ukázce nástroje MCP v Azure SDK pro .NET úložiště na 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");

Očekávaný výstup

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

Příklad kódu

Následující ukázka TypeScriptu ukazuje, jak vytvořit agenta pomocí vlastního nástroje MCP interpretu kódu. Verzi JavaScriptu najdete v ukázce nástroje MCP v úložišti Azure SDK pro JavaScript na 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);
});

Očekávaný výstup

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

Přidejte závislost do svého pom.xml:

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

Příklad kódu

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

Očekávaný výstup

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

Požadavky

Nastavte tyto proměnné prostředí:

FOUNDRY_PROJECT_ENDPOINT: Adresa URL koncového bodu projektu.
AGENT_TOKEN: Nosný token pro Foundry.

Získání přístupového tokenu:

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

Příklad kódu

1. Vytvoření agenta s interpretem vlastního kódu

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. Vytvoření odpovědi

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. Vyčistěte

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

Očekávaný výstup

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

Ověření nastavení

Po zřízení infrastruktury a spuštění ukázkového příkladu:

Ověřte, že se nasazení Azure úspěšně dokončilo.
Ověřte, že se vzorek připojí pomocí hodnot ve vašem .env souboru.
V Microsoft Foundry ověřte, že agent spouští nástroj pomocí trasování. Další informace najdete v tématu Osvědčené postupy pro používání nástrojů ve službě Microsoft Foundry Agent Service.

Řešení potíží

Problém	Pravděpodobná příčina	Rozlišení
Registrace funkce stále čeká na zpracování	Příkaz `az feature register` vrátí `Registering` stav.	Počkejte na dokončení registrace (může to trvat 15 až 30 minut). Zkontrolujte stav pomocí `az feature show --namespace Microsoft.App --name SessionPoolsSupportMCP`. Potom znovu spusťte `az provider register -n Microsoft.App`.
Nasazení selže s chybou oprávnění	Chybí požadovaná přiřazení rolí.	Ověřte, že máte role Foundry Owner a Container Apps ManagedEnvironment Contributor v rámci předplatného nebo skupiny prostředků.
Nasazení selže s chybou regiónu	Vybraná oblast nepodporuje dynamické relace Azure Container Apps.	Zkuste jinou oblast. Podívejte se na regiony Azure Container Apps pro podporované oblasti.
Agent nevolá nástroj	Připojení MCP není správně nakonfigurované, nebo pokyny agenta nepodněcují použití nástroje.	Pomocí trasování v Microsoft Foundry potvrďte vyvolání nástroje. Ověřte, že `MCP_SERVER_URL` odpovídá nasazenému koncovému bodu Container Apps. Podívejte se na osvědčené postupy.
Vypršení časového limitu připojení k serveru MCP	Bazén relací Container Apps není spuštěný nebo nemá žádné připravené instance.	Zkontrolujte stav fondu relací na portálu Azure. V případě potřeby v šabloně Bicep zvyšte `standbyInstanceCount`.
Selhání spuštění kódu v kontejneru	V kontejneru na míru chybí balíčky Python.	Aktualizujte image kontejneru tak, aby zahrnovala požadované balíčky. Znovu sestavte a nasaďte kontejner.
Chyba ověřování při připojování k serveru MCP	Přihlašovací údaje pro připojení k projektu jsou neplatné nebo vypršela jeho platnost.	Znovu vygenerujte přihlašovací údaje připojení a aktualizujte `.env` soubor. `MCP_PROJECT_CONNECTION_ID` Ověřte formát.

Omezení

Rozhraní API přímo nepodporují vstup nebo výstup souboru nebo použití úložišť souborů. Pro zajištění přenosu dat dovnitř i ven musíte používat adresy URL, jako jsou datové URL pro malé soubory a URL s podpisem sdíleného přístupu (SAS) Azure Blob Service pro velké soubory.

Zabezpečení

Pokud používáte adresy URL SAS k předávání dat do runtime nebo z runtime:

Používejte krátkodobé tokeny SAS.
Neukládejte adresy URL SAS ani je neukládejte do správy zdrojového kódu.
Rozsah oprávnění na minimum (například jen pro čtení nebo jen pro zápis).

Vyčištění

Pokud chcete zastavit fakturaci zřízených prostředků, odstraňte prostředky vytvořené ukázkovým nasazením. Pokud jste pro tento článek použili vyhrazenou skupinu prostředků, odstraňte ji.

Připojte se k serverům protokolu Model Context (náhled)
Nejlepší postupy pro používání nástrojů ve službě Microsoft Foundry Agent
Azure Container Apps dynamické relace
Fondy relací s vlastními kontejnery
prostředí Azure Container Apps
Instalujte Azure CLI
Nástroj Interpret kódu pro agenty

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-05-01

Nástroj interpretu vlastního kódu pro agenty (Preview)

Podpora využití

Podpora sady SDK

Požadavky

Než začnete

Vytvoření agenta s interpretem vlastního kódu

Registrace funkce Preview

Získání ukázkového kódu

Zřízení infrastruktury

Konfigurace a spuštění agenta

Příklad kódu

Očekávaný výstup

Příklad kódu

Očekávaný výstup

Příklad kódu

Očekávaný výstup

Příklad kódu

Očekávaný výstup

Požadavky

Příklad kódu

1. Vytvoření agenta s interpretem vlastního kódu

2. Vytvoření odpovědi

3. Vyčistěte

Očekávaný výstup

Ověření nastavení

Řešení potíží

Omezení

Zabezpečení

Vyčištění

Související obsah

Váš názor

Další materiály