OpenAI Barındırmalı Korumalı Alanlar: Güvenli Bir Yapay Zekâ Finans Analisti Oluşturun

Yapay zekâ ajanları artık basit metin üretiminin çok ötesine geçti. Artık kod yazabiliyor, komut çalıştırabiliyor, dosyalarla çalışabiliyor, hataları düzeltebiliyor ve çok adımlı görevleri kendi başlarına tamamlayabiliyorlar.

Ancak BBA'lar her zaman öngörülebilir değildir. 

Net talimatlara rağmen bir ajan beklenmedik bir komut üretebilir veya değiştirmemesi gereken bir şeyi değiştirebilir. Bu kodu doğrudan yerel makinenizde veya uygulama sunucunuzda çalıştırmak gereksiz risk yaratabilir.

Bu eğitimde, güvenli bir yapay zekâ finans analisti oluşturmak için OpenAI barındırmalı bir korumalı alan kullanacağım. Finansal bir veri kümesi yükleyeceğiz, bir ajanı izole ortama bağlayacağız, analizini ve çıktı üretimini burada yapmasına izin vereceğiz ve ardından oluşan raporları, grafikleri ve veri dosyalarını indireceğiz.

Finans analisti yalnızca bir örnek. Asıl amaç, bir yapay zekâ ajanına güvenle kod çalıştırabileceği ve dosyalarla çalışabileceği kontrollü bir ortam sağlamayı anlamaktır.

OpenAI Barındırmalı Korumalı Alan Nedir?

Korumalı alan, uygulamanızı barındıran sisteme sınırsız erişim olmadan kodun çalışabildiği izole bir ortamdır.

Bu, davranışları tamamen öngörülebilir olmayan yapay zekâ ajanları için özellikle yararlıdır. 

Bir ajana tek bir dosyayı değiştirmesi söylenebilir ama başka bir dizini etkileyen bir komut üretebilir, beklenmedik bir bağımlılık kurabilir veya öngörmediğiniz bir şeyi çalıştırabilir.

Bu komutların doğrudan dizüstü bilgisayarınızda veya sunucunuzda çalışmasına izin vermek yerine, ajanı bir korumalı alanın içine yerleştirebilirsiniz.

OpenAI bu amaçla kendi barındırılan korumalı alan ortamını sağlar. 

Bu sayede ajana, dosya sistemi ve kabuğu olan gerçek bir Linux çalışma alanı verilir ve çalıştırma yerel sisteminizden ayrı tutulur.

Korumalı alan içinde ajan şunları yapabilir:

• Dosyaları okuma ve yazma.
• Betikler oluşturma ve çalıştırma.
• Kabuk komutları çalıştırma.
• Komut çıktısını inceleme.
• Hataları düzeltme ve kodu yeniden çalıştırma.
• Raporlar, veri kümeleri, grafikler ve diğer çıktıları üretme.

Ayrıca korumalı alanın nelere erişebileceğini de kontrol edebilirsiniz. 

Örneğin, yalnızca bir görev için gereken dosyaları yükleyebilir ve ajanın dış bilgiye ihtiyaç duymadığı durumlarda ağ erişimini devre dışı bırakabilirsiniz.

OpenAI Korumalı Alanlarını Kullanmanın Farklı Yolları

OpenAI, ajanları veya modelleri izole ortamlarda çalıştırmak için birkaç farklı yöntem sunar. Temel fark, yürütme ve ajan iş akışının ne kadarını OpenAI'ın yönetmesini istediğinizdir.

1. Shell Aracı

Shell aracı en basit seçenektir. Modellerin, Yanıtlar API'si aracılığıyla OpenAI tarafından barındırılan bir konteyner içinde kabuk komutları çalıştırmasına olanak tanır.

response = client.responses.create(
    model=MODEL,
    tools=[{
        "type": "shell",
        "environment": {"type": "container_auto"}
    }],
    input="Analyze the files in /mnt/data."
)

Kod yürütme, dosya işleme veya komut satırı görevlerine ağırlık verdiğiniz durumlar için iyi bir seçimdir.

2. Agents API

Agents API daha yönetimli bir seçenektir. OpenAI hem ajan oturumunu hem de barındırılan ortamı yönetir.

stream = client.beta.agents.sessions.create(
    agent={
        "model": MODEL,
        "instructions": "Analyze the data and create a report."
    },
    environment={"type": "openai_hosted"},
    input="Analyze the files in the workspace.",
    stream=True,
)

Ajanın çalışma zamanı ve korumalı alan yaşam döngüsünün daha fazlasını OpenAI'ın yönetmesini istediğinizde kullanışlıdır.

3. SandboxAgent

SandboxAgent, Agents SDK'nın bir parçasıdır ve korumalı alan çalışma alanının uygulamanın çekirdek bir parçası olduğu ajanlar için tasarlanmıştır.

from agents.sandbox import SandboxAgent
from agents.sandbox.capabilities import Shell

agent = SandboxAgent(
    name="Financial Analyst",
    model=MODEL,
    capabilities=[Shell()],
)

Kalıcı çalışma alanlarına, dosyalara, çıktılara veya hangi korumalı alan sağlayıcısını kullanacağınıza dair esnekliğe ihtiyaç duyduğunuzda iyi çalışır.

4. Agents SDK + ShellTool

Bu rehberde bu yaklaşımı kullanıyoruz.

OpenAI barındırmalı konteyneri kendimiz oluşturuyor ve ardından ajana ShellTool kullanarak bu belirli ortama bağlantı kurduruyoruz.

sandbox_shell = ShellTool(
    environment={
        "type": "container_reference",
        "container_id": container.id,
    }
)

Bu yaklaşımı, sadelik ile kontrol arasında iyi bir denge sağladığı için seçtik. 

OpenAI korumalı alan altyapısını yönetirken, biz hâlâ konteyner, dosyalar, ağ erişimi, ajan talimatları, araçlar ve yürütme akışı üzerinde kontrol sahibiyiz.

OpenAI Barındırmalı Korumalı Alan Nasıl Kullanılır

Güvenli bir finans analisti ajanı oluşturmak için OpenAI barındırmalı korumalı alanın nasıl kullanılacağını inceleyelim. 

1. Ortamı ve projeyi kurun

İş akışını kurmak ve test etmek için bir Jupyter Defteri kullanacağız. 

Defter; gerekli SDK'ların kurulumu, veri kümesinin yüklenmesi, korumalı alanın oluşturulması, ajanın başlatılması ve nihai çıktıların indirilmesi gibi görevleri yönetecek.

Ancak önemli fark, finans analizinin bizzat Jupyter içinde çalışmayacak olmasıdır. 

Ajan OpenAI korumalı alanına bağlandığı anda, kod yürütme, kabuk komutları, doğrulama, hesaplamalar ve çıktı üretimi barındırılan korumalı alanın içinde gerçekleşecek.

Jupyter'ı kontrol katmanı, korumalı alanı ise yürütme ortamı olarak düşünebilirsiniz.

Önce OpenAI Python SDK'sını ve OpenAI Agents SDK'sını kurun:

%pip install -q -U openai openai-agents

OPENAI_API_KEY ortam değişkeni üzerinden erişilebilir bir OpenAI API anahtarına da ihtiyacınız var.

Bu eğitim için, şu konumda saklanan kurgusal bir şirket veri kümesini kullanacağız:

financial_data/northstar_cloud_financial_statements.csv

Ardından gerekli kütüphaneleri içe aktarın ve modeli, giriş CSV'sini, yerel çıktı dizinini ve ajanın üretmesini beklediğimiz dosyaları tanımlayın.

import json
import os
from pathlib import Path

from IPython.display import Markdown, SVG, display


MODEL = os.getenv("OPENAI_MODEL", "gpt-6-luna")

STATEMENT_CSV = Path(
    "financial_data/northstar_cloud_financial_statements.csv"
)

OUTPUT_DIR = Path("financial_analysis_output")
OUTPUT_DIR.mkdir(exist_ok=True)

EXPECTED_ARTIFACTS = [
    "analyze_financials.py",
    "calculated_metrics.csv",
    "unusual_movements.csv",
    "financial_trends.svg",
    "investment_analysis.md",
    "analysis_run.json",
]

assert os.getenv("OPENAI_API_KEY"), \
    "Set OPENAI_API_KEY before continuing."

assert STATEMENT_CSV.exists(), \
    f"Missing input: {STATEMENT_CSV.resolve()}"

print(f"Model: {MODEL}")
print(
    f"Input: {STATEMENT_CSV} "
    f"({STATEMENT_CSV.stat().st_size:,} bytes)"
)

Çıktı:

Model: gpt-6-luna
Input: financial_data\northstar_cloud_financial_statements.csv (1,480 bytes)

Doğrulamalar, herhangi bir OpenAI kaynağı oluşturmadan önce hızlı bir sağlamlık kontrolü sağlar. API anahtarı yoksa veya veri kümesi bulunamazsa, iş akışının ilerleyen aşamalarında hatayla karşılaşmak yerine defter hemen durur.

OUTPUT_DIR, yerel Jupyter dizinidir ve korumalı alandan indirilecek dosyaları en sonunda burada saklayacağız. 

EXPECTED_ARTIFACTS ise ajanın korumalı alan içinde oluşturmasını beklediğimiz dosyaları tanımlar.

2. Finansal verileri yükleyin

Korumalı alanın finansal verilerimizle çalışabilmesi için önce CSV'yi OpenAI'a yüklememiz gerekir.

Bu adımı Jupyter Defteri yönetir. Yerel dosyayı okur ve OpenAI Files API'si üzerinden gönderir.

from openai import OpenAI

client = OpenAI()

with STATEMENT_CSV.open("rb") as handle:
    uploaded_input = client.files.create(
        file=handle,
        purpose="user_data",
    )

print(f"Uploaded raw statements: {uploaded_input.id}")

Çıktı:

Uploaded raw statements: file-C6Pb6RhZrVPR4Fiq9tZ6Hn

Sizin dosya kimliğiniz farklı olacaktır.

Dönen dosya kimliği önemlidir; çünkü korumalı alanı oluştururken bunu kullanacağız. CSV içeriğini bir isteme kopyalamak yerine, özgün dosyayı doğrudan ajanın çalışma ortamına iliştirebiliriz.

Bu noktada Northstar finansal tabloları OpenAI'da saklanmıştır, ancak ajanın hâlâ bir yürütme ortamı yoktur.

Bunu şimdi oluşturacağız.

3. OpenAI barındırmalı korumalı alanı oluşturun

Artık ajanın finans analizini gerçekte yürüteceği barındırılan ortamı oluşturabiliriz.

Konteynerler API'sini kullanarak yeni bir korumalı alan oluşturun ve yüklenen CSV'yi dosya kimliğini kullanarak iliştirin:

container = client.containers.create(
    name="northstar-financial-analysis",
    file_ids=[uploaded_input.id],
    memory_limit="4g",
    network_policy={"type": "disabled"},
)

print(f"OpenAI sandbox: {container.id}")

Çıktı:

OpenAI sandbox: cntr_6ab7a1080b4081938d8d08ab67ac963c084798905ec997e9

Korumalı alan 4 GB bellekle oluşturulur ve yüklenen finansal tablolar baştan itibaren içinde kullanılabilir durumdadır.

Ağ erişimini de devre dışı bırakıyoruz:

network_policy={"type": "disabled"}

Finans analizimiz internetten bilgi gerektirmediği için ajana dış ağ erişimi vermemize gerek yok. İhtiyaç duyduğu her şey CSV'de mevcut.

4. Finans analistinin görevini tanımlayın

Korumalı alan ajana çalışması için güvenli bir yer sağlar, ancak ondan tam olarak ne istediğimizi hâlâ tanımlamamız gerekir.

Modeli "bu şirketi analiz et" gibi muğlak bir talimatla yönlendirmek yerine; hesaplamaları, doğrulama kontrollerini, üretilecek dosyaları ve ajanın kendi çalışmasını nasıl teyit edeceğini açıklayan ayrıntılı bir görev veriyoruz.

ANALYST_INSTRUCTIONS = """
You are a skeptical senior buy-side financial analyst preparing an investment-committee memo.

Every analytical operation must occur in the hosted shell container under /mnt/data. Do not
estimate results mentally or ask the caller to calculate anything.

Find the uploaded Northstar statement CSV. Write analyze_financials.py using only the Python
standard library and execute it. Validate required columns, numeric values, unique ordered years,
and total_assets = total_liabilities + equity for every row. Calculate revenue growth, gross/
operating/net margins, current and quick ratios, total-liabilities-to-equity, average-balance ROA
and ROE, interest coverage, free cash flow, FCF margin, cash conversion, receivables growth, and
inventory growth. Leave a ratio blank when its denominator makes it undefined.

Flag absolute year-over-year movements of at least 15%, operating-margin moves of at least two
percentage points, and receivables growth exceeding revenue growth by at least ten points. Create
calculated_metrics.csv, unusual_movements.csv, financial_trends.svg, investment_analysis.md, and
analysis_run.json in /mnt/data. The SVG must contain four readable chart panels without external
packages.

The report must cover Executive view, KPI table, Profitability, Liquidity and leverage, Cash flow
and earnings quality, Unusual movements, Bull case, Bear case, Diligence questions, Data
limitations, and Conclusion. Tie receivables, deferred revenue, stock compensation, capex, and
interest expense to evidence; separate facts from hypotheses and cite filenames and years.

analysis_run.json must contain input_filename, row_count, year_range, validation_results,
generated_filenames, and execution_directory='/mnt/data'. validation_results must include
accounting_equation_passed_every_row=true. Run the script, inspect every artifact, independently
recompute at least three 2025 metrics in a second command, and fix discrepancies. Do not finish
until all six required files exist and are non-empty.
"""

Burada önemli bir tasarım tercihi var.

Modelden finans analizini yalnızca yanıtında muhakeme etmesini istemiyoruz. 

Talimatlar açıkça kod yazmasını, o kodu çalıştırmasını, sonuçları incelemesini, seçili hesaplamaları doğrulamasını ve uyuşmazlıkları düzeltmesini söylüyor.

Ayrıca ajana, her analitik işlemin barındırılan korumalı alan içinde /mnt/data altında gerçekleşmesi gerektiğini belirtiyoruz.

Bu, ajana net bir iş akışı verir:

Verileri bul → doğrula → analiz betiğini yaz → çalıştır → çıktıları üret → sonuçları incele → hesaplamaları teyit et → gerekiyorsa hataları düzelt.

Bu da korumalı alanı, sadece geçici dosya depolama alanı değil, gerçek bir çalışma ortamına dönüştürür.

5. Ajana Korumalı Alana Bağlanın

Sırada, daha önce oluşturduğumuz konteynere bir OpenAI ajanını bağlıyoruz.

Bunu ShellTool kullanarak yapıyoruz.

from agents import Agent, ModelSettings, Runner, ShellTool

sandbox_shell = ShellTool(
    environment={
        "type": "container_reference",
        "container_id": container.id,
    }
)

analyst = Agent(
    name="Sandbox Financial Analyst",
    model=MODEL,
    instructions=ANALYST_INSTRUCTIONS,
    tools=[sandbox_shell],
    model_settings=ModelSettings(tool_choice="required"),
)

Önemli kısım şudur:

"type": "container_reference",
"container_id": container.id,

Bu, ShellTool aracına, farklı bir yürütme ortamı oluşturmak veya kullanmak yerine ajanın, zaten oluşturduğumuz korumalı alana bağlanmasını söyler.

Ayrıca şunu ayarladık:

tool_choice="required"

Bu, ajanın yalnızca normal bir metin yanıtıyla görevi tamamlamak yerine, çalıştırma sırasında bir araç kullanmasını zorunlu kılar.

Bu eğitim için tam olarak istediğimiz de budur. 

Ajan finansal metrikleri nasıl hesaplayacağını sadece açıklamamalıdır. Kabuğu kullanmalı, kodu korumalı alanda çalıştırmalı ve istenen dosyaları üretmelidir.

6. Ajanın analizi yürütmesine izin verin

Veri kümesi yüklendiğinde, korumalı alan çalışır durumdayken ve ajan ShellTool üzerinden bağlandığında artık analizi başlatabiliriz.

result = await Runner.run(
    analyst,
    "Analyze Northstar entirely inside the sandbox and produce every required artifact.",
    max_turns=30,
)

display(Markdown(result.final_output))

Bu, finans analisti ajanını başlatır ve ona daha önce oluşturduğumuz korumalı alana erişim verir.

Ajanın nihai çıktısı, veri doğrulama, metrik kontrolleri ve gerekli altı çıktının oluşturulması dahil olmak üzere analizin /mnt/data içinde başarıyla tamamlandığını teyit eder.

7. Üretilen çıktıları indirin

Analiz tamamlandı, ancak üretilen dosyalar hâlâ OpenAI korumalı alanının içinde.

Sırada, konteynerdeki dosyaları listeleyip beklenen tüm çıktıların oluşturulduğunu kontrol edecek ve bunları yerel dizinimize indireceğiz.

remote_files = {
    Path(item.path).name: item
    for item in client.containers.files.list(container.id)
}

missing = [
    name for name in EXPECTED_ARTIFACTS
    if name not in remote_files
]

assert not missing, f"Sandbox did not create: {missing}"

for name in EXPECTED_ARTIFACTS:
    remote = remote_files[name]
    destination = OUTPUT_DIR / name

    client.containers.files.content.retrieve(
        remote.id,
        container_id=container.id,
    ).write_to_file(destination)

    assert destination.stat().st_size > 0, \
        f"Empty artifact: {destination}"

    print(
        f"Downloaded {name}: "
        f"{destination.stat().st_size:,} bytes"
    )

Çıktı:

Downloaded analyze_financials.py: 22,778 bytes
Downloaded calculated_metrics.csv: 3,740 bytes
Downloaded unusual_movements.csv: 25,405 bytes
Downloaded financial_trends.svg: 13,846 bytes
Downloaded investment_analysis.md: 12,159 bytes
Downloaded analysis_run.json: 1,522 bytes

Bu noktada yerel financial_analysis_output dizinini açarak ajanın oluşturduğu her şeyi inceleyebilirsiniz.

Klasör; analiz betiğini, hesaplanan metrikleri, olağandışı hareket bayraklarını, tam yatırım notunu, doğrulama özetini ve finansal eğilimlerin SVG görselleştirmesini içerir.

investment_analysis.md dosyası; yönetici özeti, kârlılık, likidite, kaldıraç, nakit akışı, olağandışı hareketler ve iyimser & kötümser senaryolar dahil olmak üzere ana yazılı analizi içerir.

financial_trends.svg dosyasını açarak görsel sonuçları da inceleyebilirsiniz. 

Bu sayede, tam raporu okumadan önce gelir, kârlılık, marjlar ve diğer temel metrikler gibi başlıca finansal eğilimleri hızlıca görebilirsiniz.

Önemli bir nokta, ajanın rastgele oluşturduğu dosyaları indirmememizdir. 

Defter önce korumalı alan içeriğini EXPECTED_ARTIFACTS ile karşılaştırır.

Gerekli dosyalardan biri eksikse, doğrulama başarısız olur. Ayrıca indirilen her dosyanın boş olmadığını da kontrol ederiz.

Bu sayede ajanın çıktısını kabul etmeden önce basit bir teyit adımı elde ederiz.

8. Korumalı alanı temizleyin

Dosyalar indirildikten ve doğrulandıktan sonra artık geçici korumalı alana veya yüklenen kaynak dosyaya ihtiyacımız kalmaz.

Her iki kaynağı da silin:

client.containers.delete(container.id)
client.files.delete(uploaded_input.id)

Bu, iş akışı tamamlandıktan sonra barındırılan konteyneri ve yüklenen finansal veri kümesini kaldırır.

Geçici kaynakları temizlemek, özellikle bir ajan iş akışının parçası olarak düzenli olarak korumalı alanlar oluşturduğunuzda iyi bir maliyet tasarrufu uygulamasıdır.

Son Düşünceler

OpenAI barındırmalı korumalı alanın en büyük avantajı, tüm iş akışının tek bir ekosistem içinde kalmasıdır.

Ayrı bir korumalı alan sağlayıcısına bağlanmanız, kendi bulut ortamınızı tahsis etmeniz veya kendi konteyner altyapınızı kurup bakımını yapmanız gerekmez. 

OpenAI platformu üzerinden bir korumalı alan oluşturabilir, dosyaları iliştirebilir, ağ erişimini kontrol edebilir, ajanın içinde çalışmasına izin verebilir, sonuçları alabilir ve işiniz bittiğinde ortamı silebilirsiniz.

Bu da iş akışının yönetimini çok daha basit hale getirir.

Bu eğitimde, bir ajanın mevcut bir konteynere doğrudan bağlanmasını sağlarken talimatlar, dosyalar, araçlar ve yürütme akışı üzerinde kontrolü korumanın basit bir yolunu sunduğu için ShellTool ile OpenAI Agents SDK'yı kullandım.

OpenAI ekosistemi içinde aynı tür iş akışını oluşturmanın başka yolları da vardır; daha doğrudan ajan API'leri ve daha üst düzey korumalı alan soyutlamaları dahil. 

Ancak bu örnek için Agents SDK, sadelik ile kontrol arasında doğru denge gibi hissettirdi.

Esas çıkarım şu: Artık OpenAI ekosisteminden çıkmadan bir yapay zekâ ajanına gerçek bir yürütme ortamı verebilirsiniz:

Korumalı alanı oluştur → verileri iliştir → ajanı bağla → görevi çalıştır → çıktıları al → korumalı alanı sil.

Kod çalıştırması, dosya işleme, rapor üretimi veya çok adımlı analiz gerektiren ajan uygulamaları için bu çok faydalı bir kalıptır.