Azure OpenAI Yanıtları API'siyle kabuk aracını kullanma

Shell aracı, bir Responses API çağrısının parçası olarak komutları tam teşekküllü bir terminal ortamında çalıştırır. Betikleri çalıştırmak, dosyalarla çalışmak ve programları yürütmek için kullanın. Kabuk aracı iki çalıştırma modunu destekler:

• Hosted shell: Azure OpenAI, istek için korumalı ve yalıtılmış bir kapsayıcı sağlar ve yönetir.
• Yerel kabuk: Modelin shell_call eylemlerini kendi çalışma zamanlarınızda yürütür ve sonuçları döndürürsiniz.

Komut satırı aracına yalnızca Responses API üzerinden erişebilirsiniz. Sohbet Tamamlamaları API'sinde kullanılamaz.

Important

Rastgele kabuk komutlarını çalıştırmak tehlikeli olabilir. Yürütmeyi her zaman korumalı alanda gerçekleştirin, mümkün olan yerlerde izin listeleri veya engelleme listeleri uygulayın ve denetim amacıyla araç etkinliklerini günlüğe kaydedin.

Note

Kabuk aracı, onu destekleyen bir Azure OpenAI API sürümü ve Yanıtlar API'sini destekleyen bir model dağıtımı gerektirir. Üretime dağıtmadan önce hedef API sürümünüz için desteği onaylayın.

Prerequisites

• Yanıtlar API'sini ve kabuk aracını destekleyen bir Azure OpenAI modeli dağıtıldı.
• Kimlik doğrulama yöntemi:
  • API anahtarı veya
  • Microsoft Entra Kimlik (ID)
• Diliniz için istemci kitaplığını yükleyin:
  • Python: pip install openai azure-identity
  • JavaScript/TypeScript: npm install openai @azure/identity
  • Java: Projenize com.openai:openai-java ve com.azure:azure-identity ekleyin.
• REST örnekleri için AZURE_OPENAI_API_KEY (API anahtar akışı) veya AZURE_OPENAI_AUTH_TOKEN (Microsoft Entra ID akışı) ayarlayın.

Barındırılan kabukla ilk komutunuzu çalıştırma

Barındırılan ortam, başlamanın en hızlı yoludur. Azure OpenAI'nin istek için bir kapsayıcı sağlamasına ve yönetmesine izin vermek üzere ortamı container_auto olarak ayarlayın. Model, isteminize bağlı olarak aracı çağırıp çağırmamaya karar verir.

Aşağıdaki örneklerde gpt-5.5 ifadesini kendi model dağıtımınızın adıyla değiştirin.

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

Tip

Bu örneklerde Microsoft Entra ID kullanılır. Bunun yerine API anahtarı kullanmak için api_key anahtar değerinize (Python ve JavaScript) ayarlayın, istemciyi oluştururken (Java) AzureApiKeyCredential geçirin veya api-key (REST) yerine Authorization: Bearer üst bilgisini gönderin.

Başvuru: Azure OpenAI Responses API’sini kullanma | OpenAI Python SDK | OpenAI Node SDK | OpenAI Java SDK

Barındırılan çalışma zamanı ayrıntıları

Barındırılan kapsayıcı, her istek veya kapsayıcı oturumu için yönetilen bir Linux ortamı sağlar:

• Çalışma zamanı Debian 12 temel alınarak oluşturulmuştur ve zaman içinde değişebilir.
• Varsayılan çalışma dizini şeklindedir /mnt/data. Bu dizin her zaman mevcuttur ve kullanıcı tarafından indirilebilen yapıtlar için desteklenen yoldur.
• Python 3.11 önceden yüklenmiştir.
• Barındırılan kabuk, etkileşimli TTY oturumlarını desteklemez ve komutlar sudo ile çalışmaz.
• Barındırılan kapsayıcıların dış ağa erişimi yoktur.

İş akışınızın ihtiyaç duyduğu hizmetleri kapsayıcı içinde çalıştırabilirsiniz.

İstekler arasında bir kapsayıcıyı yeniden kullanmak

Yinelemeli iş akışları için bir kez bir kapsayıcı oluşturun ve sonraki Yanıtlar API çağrılarında kapsayıcıya başvurun. Kapsayıcı, etkin olduğu sürece istekler arasında dosyaları ve durumu korur.

İlk olarak kapsayıcıyı oluşturun.

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

REST sekmesinde gösterilen REST API aracılığıyla kapsayıcılar oluşturun ve bunlara başvurun. İstemciyi önceki Java örnekte gösterildiği gibi derleyin, ardından IŞ akışına REST çağrısının döndürdüğü kapsayıcı kimliğiyle devam edin.

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

Ardından, bir kabuk isteğinde kapsayıcıya kimliğini kullanarak başvurun.

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

REST sekmesinde gösterilen REST API aracılığıyla mevcut bir kapsayıcıya başvurun. Kabuk aracının container_reference ortamında kapsayıcı kimliğini geçirin.

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

Sonraki turlarda aynı kapsayıcıda çalışmaya devam etmek için, önceki yanıttaki aynı container_id ile previous_response_id öğesini iletin.

Komutları yerel kabuk modunda çalıştırma

Yerel kabuk modunda, modelin komutlarını barındırılan bir kapsayıcı yerine kendi çalışma zamanınızda yürütürsünüz. Yürütme ortamı, dosya sistemi erişimi veya mevcut iç araçlar üzerinde tam denetime ihtiyacınız olduğunda bu modu kullanın.

Ortamı local olarak ayarlayın. Model, çalıştırılacak komutları açıklayan öğeleri döndürür shell_call .

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

shell_call öğeleri aldığınızda, istenen komutları çalıştırın, çıktıyı yakalayın ve sonuçları bir sonraki isteğinizde shell_call_output olarak döndürün. Aşağıdaki yürütücü, stdout, stderr ve çıkış sonucunu yakalar ve zaman aşımlarını işler.

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)

Referans: Azure OpenAI Yanıtlar API'sini kullanın

Yanıtlarda komut satırı çıktısı

Barındırılan kabuk ve yerel kabuk aynı çıkış öğesi türlerini kullanır. Her komut kabuğu çalıştırması, bir öğe çiftiyle temsil edilir:

• shell_call: modelin istediği komutlar.
• shell_call_output: komut çıktısı ve çıkış sonucu.

Model bir shell_call öğeyle komutlar istiyor:

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

Sonuçları bir shell_call_output öğeyle döndürebilirsiniz:

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

bir shell_call öğesini içeriyorsa max_output_length, öğesine shell_call_outputaynı değeri ekleyin. Bir komut yürütme zaman aşımı süresini aşarsa, timeout sonucu döndürün ve yakalayabildiğiniz tüm kısmi çıktıyı ekleyin.

Artefaktları indirme

Barındırılan komut kabuğu indirilebilir dosyalar üretebilir. Artefaktları almak için bunları /mnt/data altına yazın, ardından Code Interpreter tarafından kullanılan aynı kapsayıcı ve dosya API'lerini kullanarak indirin.

Veri saklama ve kapsayıcı yaşam döngüsü

• Barındırılan kapsayıcı oturumu 20 dakikalık boşta kalma süresinden sonra sona erer.
• Barındırılan kapsayıcı oluşturulduktan bir saat sonra silinir. Kapsayıcı silindiğinde kapsayıcıda depolanan tüm veriler kaldırılır.

Barındırılan kapsayıcılar, kapsayıcı etkin durumdayken, kısa ömürlü blok depolama tarafından desteklenen kapsayıcı dosya sistemine uygulamanın geçici durumunu yazabilir. Kapsayıcının süresi dolduğunda veya sildiğinizde kapsayıcı verileri silinir.

Yaygın hataları işleme

• Zaman aşımları: Bir komut yürütme zaman aşımınızı aşarsa, bir timeout sonuç döndürerek yakaladığınız kısmi çıkışı ekleyin.
• Kırpılmış çıktı: max_output_length, bir shell_call üzerinde bulunduğunda, shell_call_output üzerinde aynı değeri ayarlayın.
• Etkileşimli komutlar: Kabuk aracının yürütülmesi etkileşimli değildir. Giriş isteyen komutlara güvenmeyin.
• Sıfır olmayan çıkış kodları: Modelin kurtarma adımları hakkında muhakeme yürütebilmesi için sıfır olmayan çıkış kodlarından elde edilen çıktıyı koruyun.

İlgili içerik

• Yanıtlar API'siyle becerileri kullanma
• Azure OpenAI Yanıtları API'sini kullanın
• Yanıtlar API'siyle web araması