Verwenden Sie das Shell-Tool mit der Azure OpenAI Responses-API

Das Shelltool führt Befehle in einer vollständigen Terminalumgebung als Teil eines Antwort-API-Aufrufs aus. Verwenden Sie sie, um Skripts auszuführen, mit Dateien zu arbeiten und Programme auszuführen. Das Shelltool unterstützt zwei Ausführungsmodi:

• Hosted shell: Azure OpenAI stellt für die Anfrage einen isolierten Container bereit und verwaltet ihn.
• Lokale Shell: Sie führen die Aktionen des shell_call Modells in Ihrer eigenen Laufzeit aus und geben die Ergebnisse zurück.

Sie können nur über die Antwort-API auf das Shelltool zugreifen. Sie ist nicht über die Chatabschluss-API verfügbar.

Wichtig

Das Ausführen beliebiger Shellbefehle kann gefährlich sein. Führen Sie die Ausführung stets in einer Sandbox aus, verwenden Sie nach Möglichkeit Positivlisten oder Blocklisten, und protokollieren Sie die Aktivitäten der Tools für Überwachungszwecke.

Note

Das Shelltool erfordert eine Azure OpenAI-API-Version, die sie unterstützt, und eine Modellbereitstellung, die die Antwort-API unterstützt. Bestätigen Sie die Unterstützung für Ihre Ziel-API-Version, bevor Sie sie in der Produktion bereitstellen.

Voraussetzungen

• Ein Azure OpenAI-Modell bereitgestellt, das die Antwort-API und das Shelltool unterstützt.
• Eine Authentifizierungsmethode:
  • API-Schlüssel oder
  • Microsoft Entra-ID.
• Installieren Sie die Clientbibliothek für Ihre Sprache:
  • Python: pip install openai azure-identity
  • JavaScript/TypeScript: npm install openai @azure/identity
  • Java: Fügen Sie ihrem Projekt com.openai:openai-java und com.azure:azure-identity hinzu.
• Legen Sie für REST-Beispiele AZURE_OPENAI_API_KEY (API-Schlüsselfluss) oder AZURE_OPENAI_AUTH_TOKEN (Microsoft Entra ID Flow) fest.

Ausführen des ersten Befehls mit gehosteter Shell

Gehostete Shell ist die schnellste Möglichkeit, loszulegen. Legen Sie die Umgebung auf container_auto fest, damit Azure OpenAI einen Container für die Anforderung bereitstellen und verwalten kann. Das Modell entscheidet, ob das Tool basierend auf Ihrer Eingabeaufforderung aufgerufen werden soll.

Ersetzen Sie gpt-5.5 in den folgenden Beispielen durch den Namen Ihrer eigenen model Modellimplementierung.

Python

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

# Create the client against the Azure OpenAI v1 endpoint.
openai = OpenAI(base_url=endpoint, api_key=token_provider)

# Run a command in an auto-provisioned hosted container.
response = openai.responses.create(
    model="gpt-5.5",
    tools=[{"type": "shell", "environment": {"type": "container_auto"}}],
    input="Run: python --version && echo 'hello from the shell'",
)

print(response.output_text)

JavaScript

import { OpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

const endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
const tokenProvider = getBearerTokenProvider(
  new DefaultAzureCredential(),
  "https://ai.azure.com/.default"
);

// Create the client against the Azure OpenAI v1 endpoint.
const openai = new OpenAI({ baseURL: endpoint, apiKey: await tokenProvider() });

// Run a command in an auto-provisioned hosted container.
const response = await openai.responses.create({
  model: "gpt-5.5",
  tools: [{ type: "shell", environment: { type: "container_auto" } }],
  input: "Run: python --version && echo 'hello from the shell'",
});

console.log(response.output_text);

Java

import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import com.openai.models.responses.ContainerAuto;
import com.openai.models.responses.FunctionShellTool;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

public class ShellExample {
    public static void main(String[] args) {
        String endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1";

        // Create the client against the Azure OpenAI v1 endpoint.
        OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
            .baseUrl(endpoint)
            .credential(BearerTokenCredential.create(
                AuthenticationUtil.getBearerTokenSupplier(
                    new DefaultAzureCredentialBuilder().build(),
                    "https://ai.azure.com/.default")))
            .build();

        // Run a command in an auto-provisioned hosted container.
        FunctionShellTool shellTool = FunctionShellTool.builder()
            .environment(ContainerAuto.builder().build())
            .build();

        ResponseCreateParams params = ResponseCreateParams.builder()
            .model("gpt-5.5")
            .input("Run: python --version && echo 'hello from the shell'")
            .addTool(shellTool)
            .build();

        Response response = openAIClient.responses().create(params);
        response.output().forEach(item -> item.message().ifPresent(msg ->
            msg.content().forEach(content -> content.outputText().ifPresent(
                t -> System.out.println(t.text())))));
    }
}

REST

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
    "model": "gpt-5.5",
    "tools": [
      { "type": "shell", "environment": { "type": "container_auto" } }
    ],
    "input": "Execute: ls -lah /mnt/data && python --version"
    }'

Tipp

In diesen Beispielen wird Microsoft Entra ID verwendet. Um stattdessen einen API-Schlüssel zu verwenden, legen Sie api_key auf Ihren Schlüsselwert (Python und JavaScript) fest, übergeben Sie AzureApiKeyCredential, wenn Sie den Client erstellen (Java), oder senden Sie den api-key Header anstelle von Authorization: Bearer (REST).

Referenz: Verwenden der Azure OpenAI Responses API | OpenAI Python SDK | OpenAI Node SDK | OpenAI Java SDK

Details zur gehosteten Laufzeit

Der gehostete Container stellt eine verwaltete Linux-Umgebung für jede Anforderungs- oder Containersitzung bereit:

• Die Laufzeit basiert auf Debian 12 und kann sich im Laufe der Zeit ändern.
• Das Standard-Arbeitsverzeichnis ist /mnt/data. Dieses Verzeichnis ist immer vorhanden und der unterstützte Pfad für vom Benutzer herunterladbare Artefakte.
• Python 3.11 ist vorinstalliert.
• Die gehostete Shell unterstützt keine interaktiven TTY-Sitzungen, und Befehle werden nicht mit sudoausgeführt.
• Gehostete Container haben keinen ausgehenden Netzwerkzugriff.

Sie können Dienste innerhalb des Containers ausführen, wenn Ihr Workflow sie benötigt.

Wiederverwenden eines Containers über Anforderungen hinweg

Erstellen Sie für iterative Workflows einmal einen Container, und verweisen Sie ihn in späteren Antwort-API-Aufrufen darauf. Der Container speichert Dateien und den Zustand zwischen Anfragen, solange er aktiv ist.

Erstellen Sie zuerst den Container.

Python

# Create a reusable container.
container = openai.containers.create(
    name="analysis-container",
    expires_after={"anchor": "last_active_at", "minutes": 20},
)

print(container.id)

JavaScript

// Create a reusable container.
const container = await openai.containers.create({
  name: "analysis-container",
  expires_after: { anchor: "last_active_at", minutes: 20 },
});

console.log(container.id);

Java

Note

Erstellen und referenzieren Sie Container über die REST-API, die auf der Registerkarte REST angezeigt wird. Erstellen Sie den Client wie im vorherigen Java-Beispiel gezeigt und setzen Sie den Workflow dann mit der Container-ID fort, die der REST-Aufruf zurückgibt.

REST

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/containers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
    "name": "analysis-container",
    "expires_after": { "anchor": "last_active_at", "minutes": 20 }
    }'

Verweisen Sie dann in einer Shellanforderung auf den Container anhand der ID.

Python

# Reference the existing container in a shell request.
response = openai.responses.create(
    model="gpt-5.5",
    tools=[{
        "type": "shell",
        "environment": {
            "type": "container_reference",
            "container_id": container.id,
        },
    }],
    input="List files in the container and show disk usage.",
)

print(response.output_text)

JavaScript

// Reference the existing container in a shell request.
const response = await openai.responses.create({
  model: "gpt-5.5",
  tools: [{
    type: "shell",
    environment: {
      type: "container_reference",
      container_id: container.id,
    },
  }],
  input: "List files in the container and show disk usage.",
});

console.log(response.output_text);

Java

Note

Verweisen Sie auf einen vorhandenen Container über die REST-API, die auf der Registerkarte REST angezeigt wird. Übergeben Sie die Container-ID in der Umgebung des container_reference Shelltools.

REST

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
    "model": "gpt-5.5",
    "tools": [
      {
        "type": "shell",
        "environment": {
          "type": "container_reference",
          "container_id": "<container_id>"
        }
      }
    ],
    "input": "List files in the container and show disk usage."
    }'

Um die Arbeit im selben Container über mehrere Interaktionen hinweg fortzusetzen, übergeben Sie dasselbe container_id und das previous_response_id aus der vorherigen Antwort.

Ausführen von Befehlen im lokalen Shellmodus

Im lokalen Shellmodus führen Sie die Befehle des Modells in Ihrer eigenen Laufzeit anstelle eines gehosteten Containers aus. Verwenden Sie diesen Modus, wenn Sie die vollständige Kontrolle über die Ausführungsumgebung, den Dateisystemzugriff oder vorhandene interne Tools benötigen.

Stellen Sie die Umgebung auf local ein. Das Modell gibt Elemente zurück shell_call , die die auszuführenden Befehle beschreiben.

response = openai.responses.create(
    model="gpt-5.5",
    instructions="The local shell environment is on Linux.",
    input="Find the largest PDF file in the current directory.",
    tools=[{"type": "shell", "environment": {"type": "local"}}],
)

print(response.model_dump_json(indent=2))

Wenn Sie shell_call Elemente erhalten, führen Sie die angeforderten Befehle aus, erfassen Sie die Ausgabe und geben Sie die Ergebnisse in Ihrer nächsten Anfrage als shell_call_output zurück. Der folgende Executor erfasst stdout, stderrund das Ausgangsergebnis und behandelt Timeouts.

import subprocess
from dataclasses import dataclass

@dataclass
class CmdResult:
    stdout: str
    stderr: str
    exit_code: int | None
    timed_out: bool

def run_command(cmd: str, timeout: float = 60) -> CmdResult:
    process = subprocess.Popen(
        cmd, shell=True, stdout=subprocess.PIPE,
        stderr=subprocess.PIPE, text=True,
    )
    try:
        out, err = process.communicate(timeout=timeout)
        return CmdResult(out, err, process.returncode, False)
    except subprocess.TimeoutExpired:
        process.kill()
        out, err = process.communicate()
        return CmdResult(out, err, process.returncode, True)

Referenz: Use the Azure OpenAI Responses API

Shell-Ausgabe in Antworten

Gehostete Shell und lokale Shell verwenden dieselben Ausgabeelementtypen. Jede Shellausführung wird durch ein Elementpaar dargestellt:

• shell_call: die Befehle, die das Modell anfordert.
• shell_call_output: Das Ausgabe- und Ausgangsergebnis des Befehls.

Das Modell fordert Befehle mit einem shell_call Element an:

{
  "type": "shell_call",
  "call_id": "call_<id>",
  "action": {
    "commands": ["ls -l"],
    "timeout_ms": 120000,
    "max_output_length": 4096
  },
  "status": "in_progress"
}

Sie geben Ergebnisse mit einem shell_call_output Element zurück:

{
  "type": "shell_call_output",
  "call_id": "call_<id>",
  "max_output_length": 4096,
  "output": [
    {
      "stdout": "...",
      "stderr": "",
      "outcome": { "type": "exit", "exit_code": 0 }
    }
  ]
}

Wenn ein shell_callmax_output_length enthält, geben Sie bei shell_call_output denselben Wert an. Wenn ein Befehl das Ausführungszeitlimit überschreitet, geben Sie ein timeout-Ergebnis zurück und fügen Sie jede Teilausgabe bei, die Sie erfassen konnten.

Herunterladen von Artefakten

Gehostete Shell kann herunterladbare Dateien erzeugen. Wenn Sie Artefakte abrufen möchten, schreiben Sie sie unter /mnt/data, und laden Sie sie dann mithilfe der gleichen Container- und Datei-APIs herunter, die von Code Interpreter verwendet werden.

Datenaufbewahrung und Containerlebenszyklus

• Eine gehostete Containersitzung endet nach 20 Minuten Leerlaufzeit.
• Ein gehosteter Container wird eine Stunde nach dem Erstellen gelöscht. Alle im Container gespeicherten Daten werden entfernt, wenn der Container gelöscht wird.

Gehostete Container schreiben möglicherweise den temporären Anwendungsstatus in das Containerdateisystem (unterstützt durch ephemeralen Blockspeicher), während der Container aktiv ist. Containerdaten werden gelöscht, wenn der Container abläuft oder Sie ihn löschen.

Häufige Fehler beheben

• Timeouts: Wenn ein Befehl das Ausführungszeitlimit überschreitet, geben Sie ein timeout-Ergebnis zurück und fügen Sie jede erfasste Teilausgabe bei.
• Abgeschnittene Ausgabe: Wenn max_output_length auf einem shell_call vorhanden ist, setzen Sie denselben Wert auf dem shell_call_output.
• Interaktive Befehle: Die Ausführung des Shelltools ist nicht interaktiv. Verlassen Sie sich nicht auf Befehle, die Eingaben erfordern.
• Beendigungen mit einem Exitcode ungleich null: Behalten Sie die Ausgabe von Beendigungen mit einem Exitcode ungleich null bei, damit das Modell Wiederherstellungsschritte ableiten kann.

Verwandte Inhalte

• Verwenden von Fähigkeiten mit der Antwort-API
• Verwenden der Azure OpenAI-Antwort-API
• Websuche mit der Antwort-API