Bir ajan, hangi araçları çağıracağı ve sonuçlarını nasıl kullanacağı konusunda karar verebilir.
Bu esneklik kesinlikle faydalıdır, ancak aynı zamanda yürütme sırasında sınırlar gerektirir.
Yapacağınız ilk şey muhtemelen istediğiniz davranışı betimleyen talimatlar eklemek olur. Ancak talimatlar yalnızca yumuşak bir yaptırım biçimidir; ajanın bunlara her zaman uyacağına dair bir garanti yoktur.
Koruyucu önlemler (guardrails) buna karşılık daha güçlü bir kontrol sağlar. Somut olarak, ajanın girdisini veya çıktısını doğrulayabileceğimiz, çalıştırma devam etmeden önce bunu kabul/red/değiştirebileceğimiz bir çalıştırma anında denetim noktası sunarlar.
Bu yazıda, OpenAI Agents SDK kullanarak bir çalıştırma anında koruyucu önlem nasıl ekleneceğini göstereceğiz.
Bunların yalnızca OpenAI modelleriyle sınırlı kalmayıp, yerel olarak barındırılan modellerle çalışan ajanlar için de geçerli olduğunu göstermek amacıyla Gemma 4 E4B’yi Ollama üzerinden yerel olarak çalıştıracağız.
1. Koruyucu Önlemler Nerede Yer Alır
Klasik bir ajan çalıştırması birkaç aşamadan geçer. Bir talep almaktan başlayarak ajan ne yapması gerektiğine karar verir, ardından bazı araçları çağırır, sonuçlarını işler ve nihayetinde bir yanıt üretir.
OpenAI Agents SDK, koruyucu önlemleri ajansal problem çözme sürecinin farklı noktalarına yerleştirmemizi olanak tanır:
-
Girdi koruyucu önlemleri: talebi ajan başlamadan önce kontrol eder.
-
Aracı-girdi koruyucu önlemleri: araç argümanlarını almadan önce bir araç çağırısını kontrol eder.
-
Aracı-çıktı koruyucu önlemleri: araç sonucunun ajana geri dönmeden önce kontrol eder.
-
Çıktı koruyucu önlemleri: ajanın son yanıtını kullanıcıya gösterilmeden önce kontrol eder.
Bu categorileştirme, sınırın kritik olduğu noktada bir sınır uygulayabilmemizi sağlar. Konuma ve uygulamaya bağlı olarak bir koruyucu önlem, ajanın devam etmesine izin verebilir, bir değeri reddedebilir veya değiştirilmiş bir sürümle değiştirebilir.
Sonraki aşamada, somut bir vaka çalışmasında bir aracı-çıktı koruyucu önlem uygulayacağız.
2. Korumalı Bir Destek Ajansı İnşa Etmek
2.1 Vaka Çalışmasının Kurulumu
Vaka çalışması için küçük bir müşteri destek ajansı inşa edeceğiz.
Burada aşağıdaki senaryoyu göz önünde bulunduruyoruz: müşteri, bir iade ödemesi henüz ulaşmadığı için online bir mağazayla iletişime geçmek zorundadır. Bu soruyu yanıtlamak için destek ajanımız, o sipariş için dosyayı arar.
Kayıtlar destek sisteminin farklı bölümlerinden gelir:
python
SUPPORT_RECORDS
=
[
{
“record_id”
“order:MUN-2048”
“record_type”
“order”
“content”
“Order MUN-2048 has a refund approved for EUR 120.”
},
{
“record_id”
“payment:MUN-2048”
“record_type”
“payment”
“internal_refund_token”
“RF-8472-PRIVATE”
“content”
: (
“The refund settlement is now pending “
“with the payment provider.”
),
},
{
“record_id”
“policy:refund-timing”
“record_type”
“policy”
“content”
: (
“Approved refunds usually appear within “
“5 to 10 business days.”
),
},
{
“record_id”
“review:MUN-2048”
“record_type”
“review”
“fraud_risk_score”
0.91
“internal_case_assessment”
: (
“The refund was held for manual fraud review because “
“the account was flagged for possible repeat-refund “
“abuse. The review is now complete.”
),
“content”
: (
“Manual review completed; the refund was released “
“to the payment provider.”
),
},
]
Gördüğünüz gibi, dosya iade tutarı, geçerli durum ve beklenen işleme süresi gibi müşteriyle paylaşılabilir bilgiler içeriyor; ancak iç iade jetonu, dolandırıcılık risk skoru ve hesabın olası tekrarlayan iade kötüye kullanımı nedeniyle işaretlendiğine dair değerlendirme gibi gizli kalması gereken iç detaylar da içeriyor.
Bu kayıtlar aynı vakaya ait ve aynı arama ile döndürülebilir. İnsan bir destek temsilcisi hangi detayların kullanılacağını bilir, ancak ajanımız bu ayrımı güvenilir bir şekilde yapmayabilir.
Bu da bir koruyucu (guardrail) kullanımını gerekli kılıyor.
Ancak önce, böyle bir koruyucu olmadan sade bir ajan tanımlayalım ve vaka üzerinde arama yaptığında ne olacağını görelim.
2.2 (Sade) Yerel Ajanı Tanımlayın
Ajanı tanımlamadan önce Ollama ve yerel bir Gemma 4 modele ihtiyacımız var. Ollama’yı ollama.com adresinden kurabilir, ardından modeli çekebilirsiniz:
bash
ollama
pull
gemma4:e4b
Ollama, OpenAI ile uyumlu yerel bir uç nokta sunar, böylece ona AsyncOpenAI ile bağlanabiliriz:
python
# pip install openai-agents
from
openai
import
AsyncOpenAI
from
agents
import
(
Agent,
OpenAIChatCompletionsModel,
)
client
=
AsyncOpenAI(
api_key
=
“ollama”
base_url
=
“http://127.0.0.1:11434/v1”
)
model
=
OpenAIChatCompletionsModel(
model
=
“gemma4:e4b”
openai_client
=
client,
)
Bu yapılandırma ile OpenAI Agents SDK, Gemma 4’ü kullanabilir. Bu sayede, yerel olarak barındırılan bir model ile SDK’nın ajan ve koruyucu (guardrail) özelliklerinden yararlanabiliriz.
Ardından, ajanın destek kayıtlarına erişebilmesi için bir arama aracı oluşturuyoruz:
python
import
json
def
search_support_records
(query:
str
)->
str
“””İsteğe ilgili destek kayıtlarını arayın.”””
query_terms
=
query.lower().split()
matches
=
[]
for
record
in
SUPPORT_RECORDS
searchable_text
=
” “
.join(
[
record[
“record_id”
],
record[
“record_type”
],
record[
“content”
],
]
).lower()
if
any
(term
in
searchable_text
for
term
in
query_terms):
matches.append(record)
return
json.dumps(matches,
ensure_ascii
=
False
)
search_tool
=
function_tool(search_support_records)
Şimdi ajanı tanımlayabiliriz:
python
support_agent
=
Agent(
name
=
“Customer support agent”
instructions
=
(
“Mevcut kayıtları kullanarak destek isteğini araştırun “
“ve müşteriye yönelik bir yanıt hazırlayın.”
),
model
=
model,
tools
=
[search_tool],
)
Bu sade tabanımız: ajan vaka dosyasını arayabilir ve bir yanıt hazırlayabilir, ancak henüz bir çalışma zamanı sınırı eklenmedi.
2.3 Sade Ajanı Çalıştırın
Şimdi sade ajanı müşterinin isteği ile çalıştıralım:
python
from
agents
import
RunConfig, Runner
user_request
=
(
“MUN-2048 siparişim için iade talebim ulaşmadı. “
“Yaşananlar hakkında bildiklerinin tamamını söyleyin.”
)
baseline_result
=
await
Runner.run(
support_agent,
user_request,
max_turns
=,
run_config
=
RunConfig(
tracing_disabled
=
True
),
)
(baseline_result.final_output)
Kendi çalıştırmamda ajan aşağıdaki yanıtı üretiyor:
MUN-2048 siparişi için kayıtlara dayanarak, iadenizle ilgili olarak şunları biliyoruz: – İade Tutarı ve Durumu: Bu sipariş için 120 EUR iade onaylandı. – Başlangıçta Yaşayan Gecikme/İnceleme: İade, hesabın olası tekrarlayan iade kötüye kullanımı açısından işaretlenmesi ve manuel dolandırıcılık incelemesi gerektirmesi nedeniyle başlangıçta askıya alındı. Bu inceleme şimdi tamamlandı ve iade ödeme sağlayıcısına gönderildi. – Güncel Durum: İade ödemesi şu anda ödeme sağlayıcısında bekliyor. – Süreç: Genel olarak, onaylanan iadeler 5 ile 10 iş günü içinde görünür.
Yanıttaki çoğu kısım yararlı ve uygundur. Ancak ajan, müşteriye hesabının olası tekrarlayan iade kötüye kullanımı açısından işaretlendiğini de söylüyor.
Bu, müşteriye yönelik bir yanıttan uygun değil.
2.4 Koruyucu Kuralı Ekleyin ve Tekrar Çalıştırın
Ulaşmak istediğimiz şey, arama aracı kayıtları döndükten sonra ve bu kayıtlar ajana geri gönderilmeden önce iç alanların kaldırılmasıdır. Bu şekilde ajan bu hassas bilgiyi hiç görmez, böylece ajanın bunu müşterilere sızdırması için de bir yol kalmaz.
Burada bir araç-çıktı koruyucu kuralı devreye giriyor.
Kavramsal olarak, bu koruyucu kural, search_support_records ham JSON’ı döndükten sonra ancak bu sonucun ajana geri gönderilmeden önce çalışır. Sonucu araya girerek araç çıktısını izin verebilir, reddedebilir veya değiştirebilir.
Mevcut durumumuz için bunu şöyle uygulayabiliriz:
python
from
agents
import
(
ToolGuardrailFunctionOutput,
tool_output_guardrail,
)
SENSITIVE_FIELDS
=
{
“internal_refund_token”
“fraud_risk_score”
“internal_case_assessment”
}
@tool_output_guardrail
def
redact_sensitive_fields
(data):
records
=
json.loads(data.output)
for
record
in
records:
for
field_name
in
SENSITIVE_FIELDS
record.pop(field_name,
None
)
sanitized_output
=
json.dumps(
records,
ensure_ascii
=
False
)
return
ToolGuardrailFunctionOutput.reject_content(
sanitized_output
)
Yukarıdaki kod parçacığında, koruyucu k araç sonucunu ayrıştırır ve her nerede görünüyorlarsa o hassas alanları kaldırır.
Ayrıca, reject_content() fonksiyonunu kullandığımıza dikkat edin. Bu fonksiyorijinal araç çıktısını reddeder ve yerine temizlenmiş sürümü koyar.
Koruyucu kuralı artık arama aracına bağlayabiliriz:
python
from
agents
import
function_tool
guarded_search_tool
=
function_tool(
search_support_records,
tool_output_guardrails
=
[redact_sensitive_fields],
)
support_agent.tools
=
Ardından, ajayı tam olarak aynı müşteri isteğiyle tekrar çalıştırırız:
python
guarded_result
=
await
Runner.run(
support_agent,
user_request,
max_turns
=
run_config
=
RunConfig(
tracing_disabled
=
True
),
)
(guarded_result.final_output)
Bu sefer ajan şöyle yanıtlar:
Mevcut kayıtlara dayanarak MUN-2048 siparişi için, iadenizle ilgili olarak şunları biliyoruz: – İade Durumu: Bu sipariş için 120 EUR iade onaylandı. İşlem: Manuel inceleme süreci tamamlandı ve iade ödeme sağlayıcısına gönderildi. – Güncel Aşama: İade ödemesi şu ödeme sağlayıcısında bekliyor.
– Süreç: Onaylanan iadeler genellikle 5 ile 10 iş günü içinde görünür.
Bu istediğimiz şey: yanıttan müşteriye gerekli bilgiler hâlâ dahil, ancak artık hesabının olası iade kötüye kullanımı işaretlendiğini ortaya çıkarmıyor.
···
3. Sonuç
Bu yazıda, OpenAI Agents SDK ile koruyucu kuralları nasıl uygulayacağımıza baktık.
Bu tür runtime sınırlamalarını uygulamak için birkaç nokta bulunur. Hangisini kullanmanız gerektiğine karar vermek için şu soruyu sorun:
-
Bu istek ajan başlatılmadan önce reddedilmeli mi? Bir girdi güvence kullanın.
-
Araç argümanları bir eylem yürütülmeden önce kontrol edilmeli mi? Bir araç-girdi güvence kullanın.
-
Bir araçtan dönen veri ajan tarafından kullanılmadan önce filtrelenmeli mi? Bir araç-çıkış güvence kullanın.
-
Son yanıt kullanıcı tarafından görülmeden önce kontrol edilmeli mi? Bir çıkış güvence kullanın.
Bu Gelişmeyi Toplulukta Değerlendirin
Haber hakkındaki düşüncelerinizi, donanım deneyimlerinizi ve teknik sorularınızı topluluk üyeleriyle anlık olarak tartışın.
Bu gelişme hakkında düşüncelerinizi, donanım deneyimlerinizi veya sorularınızı Topluluk Forumumuzda paylaşın.
Foruma Katıl & Yanıtla ➔
Söz sizde.
Deneyiminizi, sorularınızı ve katkılarınızı paylaşın. E-posta adresiniz yayımlanmaz.