KISA KES
Yapay zeka ajanlarına bebek bakıcılığı yapmayı üç şey inşa ederek durdurursunuz: güvenlik bariyerleri (felaketle sonuçlanan hataları önleyen kısıtlamalar), gözlemlenebilirlik (ne olduğunu anlatan günlükler ve metrikler) ve kontrol noktaları (insanların kararları doğruladığı otomatik duraklamalar). Bunları bir kez kurduğunuzda, ajanlarınız dakikalar yerine saatlerce otonom olarak çalışabilir. Apidog gibi araçlar, ajanların ihlal edemeyeceği API sözleşmelerini tanımlamanıza olanak tanıyarak API katmanınızı bir güvenlik ağına dönüştürmenize yardımcı olur.
Giriş
Geçen hafta bir geliştiricinin, zaman kazandırması beklenen bir yapay zeka ajanını denetlemek için 4 saat harcadığını izledim. Her birkaç dakikada bir, ajanı durduruyor, bir hatayı düzeltiyor ve yeniden başlatıyordu. Sonunda, kodu kendisi yazmış olsaydı yapacağından daha fazla manuel iş yapmış oldu.
Bu, bebek bakıcılığı sorunudur ve yapay zeka ajanlarının vaatlerini yerine getirememelerinin 1 numaralı nedenidir. Araçlar çalışıyor. Modeller yetenekli. Ancak çoğu ekip, sürekli denetim aşamasını asla geçemiyor.
İşte olan şu: çoğu yapay zeka ajanı kurulumu, büyük dil modelini (LLM) her görevde elinden tutulması gereken bir stajyer geliştirici gibi ele alıyor. Ancak LLM'ler stajyer değil. Onlar daha çok, sınırlar belirlemezseniz yanlış şeyi kendinden emin bir şekilde yapacak olan, son derece hızlı, ara sıra halüsinasyon gören stajyerlere benziyorlar.
Yapay zeka ajanlarınızın takip edebileceği API sözleşmeleri tanımlayın
Bu rehberin sonunda şunlara sahip olacaksınız:
- Ajan otonomisi hakkında düşünmek için zihinsel bir model
- Güvenlik bariyerleri, gözlemlenebilirlik ve kontrol noktaları için somut desenler
- Bugün projelerinize kopyalayabileceğiniz kod örnekleri
- Bir ajanın denetimsiz çalışmaya hazır olup olmadığını değerlendirmek için bir kontrol listesi
Ajanlar neden sürekli denetime ihtiyaç duyar?
Yapay zeka ajanları öngörülebilir şekillerde başarısız olur. Bu hata modlarını anlamak, onları düzeltmenin ilk adımıdır.
Hata modu 1: Kapsam kayması
Bir ajandan “API uç noktasına kimlik doğrulama eklemesini” istersiniz. O kimlik doğrulama ekler. Sonra hız sınırlaması ekler. Sonra veritabanı şemasını yeniden düzenler. Sonra “kullanılmayan” olduğunu düşündüğü dosyaları siler ve bunların önemli olduğu ortaya çıkar.
Ajan devam etti çünkü kimse ona durmasını söylemedi. LLM'lerin doğuştan gelen bir “tamamlandı” hissi yoktur. Bir token limitine ulaşana kadar veya siz onları kesene kadar değişiklik yapmaya devam ederler.
Hata modu 2: Yanlış soyutlamalar
“Hata işlemeyi iyileştir” görevi verilen bir ajan her yere try-catch blokları ekleyebilir. Teknik olarak doğru. Pratik olarak korkunç. Kod okunaksız hale gelir, günlükleme tutarsız olur ve gerçek hata durumları ele alınmaz.
Ajan isteği kelimenin tam anlamıyla anladı ancak niyeti kaçırdı. İyi hata işleme örnekleri olmadan, en bariz (ve en kötü) yoruma yöneldi.
Hata modu 3: Art arda gelen hatalar
Bir ajan adım 1'de küçük bir hata yapar. Adım 10'a gelindiğinde, bu hata sonraki her karara yayılmıştır. Bir fonksiyon adındaki bir yazım hatası olarak başlayan şey, bozuk bir API'ye, bozuk testlere ve neyin yanlış gittiğini anlamaya çalışan kafası karışmış bir geliştiriciye dönüşür.
Bu en tehlikeli hata modudur çünkü ajan başarısız olduğunu bilmez. Her adım tek başına makul görünür. Sorunu ancak nihai sonuç ortaya koyar.
Hata modu 4: Kaynak tükenmesi
Denetimsiz bırakılan bazı ajanlar sonsuza kadar döngüye girecektir. Başarısız API çağrılarını süresiz olarak tekrar deneyecek, sınırsız yeni alt ajanlar üretecek veya fatura tavanınıza ulaşana kadar kod üretmeye devam edeceklerdir.
Kaynak kısıtlamaları olmadan, ajanlar ne zaman bırakacaklarını bilmezler.
Otonomi çerçevesi: güvenlik bariyerleri, gözlemlenebilirlik, kontrol noktaları
Bu sorunları üç katmanla çözersiniz. Onları bir piramit olarak düşünün: altta güvenlik bariyerleri (hataları önleme), ortada gözlemlenebilirlik (hataları tespit etme) ve üstte kontrol noktaları (hatalardan kurtulma).
Katman 1: Güvenlik Bariyerleri (önleme)
Güvenlik bariyerleri, felaketle sonuçlanan hataları önleyen kısıtlamalardır. Bunlar, ajanınızın bozamayacağı, istemler (prompt'lar) ile değil, kodla uygulanan kurallardır.
Kod aracılığıyla katı kısıtlamalar:
# Don't: Trust the agent to follow instructions
agent.run("Only modify files in the src/ directory")
# Do: Enforce constraints in code
import os
from pathlib import Path
ALLOWED_DIRECTORIES = {"src", "tests", "docs"}
def validate_file_path(path: str) -> bool:
"""Agent cannot write outside allowed directories."""
abs_path = Path(path).resolve()
return any(
str(abs_path).startswith(str(Path(d).resolve()))
for d in ALLOWED_DIRECTORIES
)
# Use in your agent's file operations
def agent_write_file(path: str, content: str):
if not validate_file_path(path):
raise ValueError(f"Cannot write to {path}: outside allowed directories")
with open(path, 'w') as f:
f.write(content)
API şema kısıtlamaları:
Ajanınız API'ları çağırdığında, hatalı biçimlendirilmiş istekleri önlemek için şemaları kullanın. Apidog burada öne çıkar. API sözleşmenizi bir kez tanımlayın, ajanınız yanlış veri biçimini gönderemez.
// apidog-schema.ts
export const CreateUserSchema = {
type: 'object',
required: ['email', 'name'],
properties: {
email: { type: 'string', format: 'email' },
name: { type: 'string', minLength: 1, maxLength: 100 },
role: { type: 'string', enum: ['user', 'admin', 'guest'] }
},
additionalProperties: false
}
// Agent must validate before calling API
function validateRequest(schema: object, data: unknown): void {
const valid = ajv.validate(schema, data)
if (!valid) {
throw new Error(`Invalid request: ${JSON.stringify(ajv.errors)}`)
}
}
Bütçe kısıtlamaları:
import time
from dataclasses import dataclass
@dataclass
class AgentBudget:
max_steps: int = 50
max_tokens: int = 100000
max_time_seconds: int = 600 # 10 minutes
max_api_calls: int = 100
class BudgetEnforcer:
def __init__(self, budget: AgentBudget):
self.budget = budget
self.start_time = time.time()
self.steps = 0
self.tokens_used = 0
self.api_calls = 0
def check(self) -> bool:
"""Returns False if budget exceeded."""
elapsed = time.time() - self.start_time
if self.steps >= self.budget.max_steps:
raise RuntimeError(f"Step limit reached: {self.steps}")
if self.tokens_used >= self.budget.max_tokens:
raise RuntimeError(f"Token limit reached: {self.tokens_used}")
if elapsed >= self.budget.max_time_seconds:
raise RuntimeError(f"Time limit reached: {elapsed:.0f}s")
if self.api_calls >= self.budget.max_api_calls:
raise RuntimeError(f"API call limit reached: {self.api_calls}")
return True
def record_step(self, tokens: int, api_calls: int = 0):
self.steps += 1
self.tokens_used += tokens
self.api_calls += api_calls
self.check()
Katman 2: Gözlemlenebilirlik (tespit)
Ajanlar saatlerce çalıştığında, her adımı izlemeden ne yaptıklarını bilmeniz gerekir. Gözlemlenebilirlik size bir karar zaman çizelgesi sunar.
Yapılandırılmış günlükleme:
import json
from datetime import datetime
from typing import Any
class AgentLogger:
def __init__(self, log_file: str = "agent_trace.jsonl"):
self.log_file = log_file
self.entries = []
def log(self, event: str, data: dict[str, Any] | None = None):
entry = {
"timestamp": datetime.utcnow().isoformat(),
"event": event,
"data": data or {}
}
self.entries.append(entry)
# Append to file immediately (don't lose logs on crash)
with open(self.log_file, 'a') as f:
f.write(json.dumps(entry) + '\n')
def log_decision(self, decision: str, reasoning: str, confidence: float):
"""Log when agent makes a significant decision."""
self.log("decision", {
"decision": decision,
"reasoning": reasoning,
"confidence": confidence
})
def log_action(self, action: str, params: dict, result: str):
"""Log agent actions and their outcomes."""
self.log("action", {
"action": action,
"params": params,
"result": result[:200] # Truncate long results
})
def log_error(self, error: str, context: dict):
"""Log errors with full context."""
self.log("error", {
"error": error,
"context": context
})
# Usage in agent
logger = AgentLogger()
logger.log_decision(
decision="Add rate limiting to API",
reasoning="Current endpoint has no protection against abuse",
confidence=0.85
)
logger.log_action(
action="write_file",
params={"path": "src/middleware/rate-limit.ts"},
result="Successfully wrote 45 lines"
)
Metrikler panosu:
Daha uzun süreli ajanlar için, yalnızca bireysel günlükler değil, toplu metrikler istersiniz.
from collections import Counter
from dataclasses import dataclass, field
@dataclass
class AgentMetrics:
actions_taken: Counter = field(default_factory=Counter)
files_modified: list[str] = field(default_factory=list)
api_calls: dict[str, int] = field(default_factory=dict)
errors: list[str] = field(default_factory=list)
decisions_by_confidence: dict[str, int] = field(default_factory=lambda: {
"high (>0.9)": 0,
"medium (0.7-0.9)": 0,
"low (<0.7)": 0
})
def record_action(self, action: str):
self.actions_taken[action] += 1
def record_file_modification(self, path: str):
if path not in self.files_modified:
self.files_modified.append(path)
def record_api_call(self, endpoint: str):
self.api_calls[endpoint] = self.api_calls.get(endpoint, 0) + 1
def record_error(self, error: str):
self.errors.append(error)
def record_decision(self, confidence: float):
if confidence > 0.9:
self.decisions_by_confidence["high (>0.9)"] += 1
elif confidence >= 0.7:
self.decisions_by_confidence["medium (0.7-0.9)"] += 1
else:
self.decisions_by_confidence["low (<0.7)"] += 1
def summary(self) -> str:
return f"""
Agent Metrics Summary
=====================
Actions: {dict(self.actions_taken)}
Files modified: {len(self.files_modified)}
API calls: {self.api_calls}
Errors: {len(self.errors)}
Decisions by confidence: {self.decisions_by_confidence}
"""
Katman 3: Kontrol Noktaları (kurtarma)
Kontrol noktaları, ajanın insan doğrulaması beklediği otomatik duraklamalardır. Sürekli denetim olmadan sorunları erken yakalamanızı sağlarlar.
Otomatik kontrol noktaları:
from enum import Enum
from typing import Callable
class CheckpointTrigger(Enum):
BEFORE_FILE_WRITE = "before_file_write"
BEFORE_API_CALL = "before_api_call"
BEFORE_GIT_COMMIT = "before_git_commit"
BEFORE_DELETE = "before_delete"
AFTER_N_STEPS = "after_n_steps"
@dataclass
class Checkpoint:
trigger: CheckpointTrigger
description: str
data: dict
requires_approval: bool = True
class CheckpointManager:
def __init__(self, auto_approve: set[CheckpointTrigger] | None = None):
self.auto_approve = auto_approve or set()
self.pending: list[Checkpoint] = []
def create_checkpoint(
self,
trigger: CheckpointTrigger,
description: str,
data: dict
) -> bool:
"""Returns True if approved, False if rejected."""
# Auto-approve certain triggers
if trigger in self.auto_approve:
return True
checkpoint = Checkpoint(
trigger=trigger,
description=description,
data=data
)
self.pending.append(checkpoint)
# In a real system, this would notify the human and wait
# For now, we return False to pause execution
return False
def approve(self, checkpoint_id: int) -> None:
"""Human approves a pending checkpoint."""
if 0 <= checkpoint_id < len(self.pending):
self.pending.pop(checkpoint_id)
def reject(self, checkpoint_id: int) -> None:
"""Human rejects a pending checkpoint."""
raise RuntimeError(f"Checkpoint rejected: {self.pending[checkpoint_id]}")
# Usage in agent
checkpoints = CheckpointManager(
auto_approve={CheckpointTrigger.BEFORE_FILE_WRITE} # Trust file writes
)
# Before destructive action
if not checkpoints.create_checkpoint(
trigger=CheckpointTrigger.BEFORE_DELETE,
description="About to delete src/legacy/ directory",
data={"path": "src/legacy/", "files": ["old_handler.ts", "deprecated.ts"]}
):
# Wait for human approval
agent.pause("Waiting for approval to delete files")
Apidog ile otonom ajanlar oluşturma
Yapay zeka ajanınız API'larla etkileşime girdiğinde, en büyük risk, aşağı akış hatalarına neden olan hatalı biçimlendirilmiş isteklerdir. Apidog, ajanınızın uyması gereken kesin API şemalarını tanımlamanıza olanak tanıyarak yardımcı olur.
API sözleşmelerini ayarlama:
- OpenAPI spesifikasyonunuzu Apidog'a aktarın veya tanımlayın
- Yerleşik doğrulama ile istemci kodu oluşturun
- Ajanınıza ham HTTP yerine doğrulanmış istemciyi verin
// Instead of letting agent call APIs directly
const response = await fetch('/api/users', {
method: 'POST',
body: JSON.stringify(data) // No validation
})
// Give agent a validated client
import { UsersApi } from './generated/apidog-client'
const usersApi = new UsersApi()
// Agent can only send valid requests - schema enforced
const response = await usersApi.createUser({
email: 'user@example.com',
name: 'Test User',
role: 'user' // Must be valid enum value
})
Bu, API katmanınızı bir güvenlik bariyerine dönüştürür. İstemci, istek gönderilmeden önce reddettiği için ajan kelimenin tam anlamıyla geçersiz veri gönderemez.
Yapay zeka ajanlarınız için doğrulanmış API istemcileri oluşturun
Kanıtlanmış desenler ve yaygın hatalar
Desen 1: Onay sandviçi
Riskli işlemler için, hem önce hem de sonra onay isteyin.
def risky_operation(agent, operation):
# Pre-approval
if not agent.checkpoint(f"About to: {operation.description}"):
return "Cancelled by user"
# Do the operation
result = operation.execute()
# Post-approval (verify the result)
if not agent.checkpoint(f"Verify result of: {operation.description}"):
operation.rollback()
return "Rolled back by user"
return result
Desen 2: Güven eşikleri
Ajanların düşük güvenli kararlar üzerinde hareket etmesine izin vermeyin.
MIN_CONFIDENCE = 0.75
def agent_decide(options: list[dict]) -> dict:
best = max(options, key=lambda x: x.get('confidence', 0))
if best['confidence'] < MIN_CONFIDENCE:
# Escalate to human
return {
'action': 'escalate',
'reason': f"Best option has confidence {best['confidence']:.2f} < {MIN_CONFIDENCE}",
'options': options
}
return best
Desen 3: İdempotent işlemler
Ajanınızın eylemlerini yan etkiler olmadan tekrarlanabilir olacak şekilde tasarlayın.
import hashlib
def idempotent_write(path: str, content: str) -> bool:
"""Only write if content changed."""
content_hash = hashlib.sha256(content.encode()).hexdigest()
existing_hash = None
if os.path.exists(path):
with open(path, 'r') as f:
existing_hash = hashlib.sha256(f.read().encode()).hexdigest()
if content_hash == existing_hash:
logger.log_action("write_file", {"path": path}, "Skipped - no changes")
return False
with open(path, 'w') as f:
f.write(content)
logger.log_action("write_file", {"path": path}, f"Wrote {len(content)} bytes")
return True
Kaçınılması gereken yaygın hatalar
İstemlere kısıtlama olarak güvenmek. Bir istemdeki “Dosyaları silme” bir kısıtlama değildir. Dosya izinleri kısıtlamalardır.
Geri alma planı olmaması. Bir ajan hata yaptığında, onu geri almanız gerekir. Git veya yedekleme kullanmıyorsanız, ajana kurtarılamaz eylemler konusunda güveniyorsunuz demektir.
Güven puanlarını göz ardı etmek. Çoğu LLM güven puanı çıkarır veya bu konuda yönlendirilebilir. Düşük güven = durakla ve insana sor.
Aşırı izleme. Her adımı izliyorsanız, otonom bir sistem inşa etmemişsinizdir. Yavaş, manuel bir sistem inşa etmişsinizdir.
Başarıyı yetersiz belirtme. Ajan ne zaman bittiğini bilmeli. “Hatayı düzelt”in bir bitiş koşulu yoktur. “Hatayı düzelt VE tüm testler geçsin”in vardır.
Alternatifler ve karşılaştırmalar
| Yaklaşım | Otonomi | Risk | En uygun olduğu yer |
|---|---|---|---|
| Manuel kodlama | Yok | Düşük | Karmaşık, kritik işler |
| Yapay zeka ile eşli programlama | Düşük | Düşük | Öğrenme, keşif |
| Denetimli ajanlar | Orta | Orta | Rutin görevler |
| Güvenlik bariyerleri olan otonom ajanlar | Yüksek | Kontrollü | Toplu işlemler, migrasyonlar |
| Tamamen otonom ajanlar | Çok yüksek | Yüksek | Güvenilir, iyi test edilmiş iş akışları |
Çoğu ekip “güvenlik bariyerleri olan otonom” ajanları hedeflemelidir. Bu, riskin %10'u ile zaman tasarrufunun %80'ini elde ettiğiniz ideal noktadır.
Gerçek dünya kullanım senaryoları
Kod tabanı geçişi. Bir ekip, 200 API uç noktasını REST'ten GraphQL'e taşımak için otonom bir ajan kullandı. Güvenlik bariyerleri şema değişikliklerini engelledi. Kontrol noktaları eski uç noktaları silmeden önce onay gerektirdi. Geçiş, 3 hafta yerine 3 gün sürdü ve sıfır üretim olayına neden oldu.
Dokümantasyon oluşturma. Bir ajan, koddan otomatik olarak API belgeleri oluşturur. Güvenlik bariyerleri, yalnızca belirli dizinlerden okumasını sağlar. Kontrol noktaları yayınlamadan önce duraklar. Ekip, belgeleri manuel olarak yazmak yerine haftada bir kez gözden geçirir.
Test kapsamı. Bir ajan kodu analiz eder ve eksik testleri yazar. Bütçe kısıtlamaları kontrolsüz test üretimini önler. Güven eşikleri, belirsiz testleri insan incelemesi için işaretler. Kapsam bir ayda %60'tan %85'e çıktı.
Özetle
İşte öğrendikleriniz:
- Yapay zeka ajanları öngörülebilir şekillerde başarısız olur: kapsam kayması, yanlış soyutlamalar, art arda gelen hatalar, kaynak tükenmesi
- Üç katman çoğu sorunu çözer: güvenlik bariyerleri (önleme), gözlemlenebilirlik (tespit), kontrol noktaları (kurtarma)
- Güvenlik bariyerleri koddur, istemler değil. Kısıtlamaları programatik olarak uygulayın.
- Gözlemlenebilirlik, her adımı izlemek değil, yapılandırılmış günlükler ve metrikler anlamına gelir
- Kontrol noktaları, insanların sürekli denetim olmadan kararları doğrulamasını sağlar
- Apidog'dan gelen API şemaları, API katmanınızı bir güvenlik bariyerine dönüştürür
Sonraki adımlarınız:
- En tekrarlayan yapay zeka destekli görevinizi belirleyin
- Güvenlik bariyerlerini tanımlayın: ajan asla ne yapmamalıdır?
- Ne olduğunu görmek için yapılandırılmış günlükleme ekleyin
- Yüksek riskli işlemler için kontrol noktaları oluşturun
- 30 dakika çalışmasına izin verin ve günlükleri kontrol edin
Amaç, insanları döngüden çıkarmak değildir. Amaç, insanları döngüde doğru yere yerleştirmektir: düşük seviyeli hataları düzeltmek yerine üst düzey kararlar almak.
Yapay zeka ajanlarınız için API güvenlik bariyerleri oluşturun - ücretsiz
Sıkça Sorulan Sorular
Yapay zeka ajanı ile yapay zeka asistanı arasındaki fark nedir? Bir asistan isteklerinize yanıt verir ve bir sonraki talimatınızı bekler. Bir ajan ise bir hedefi alır ve buna ulaşmak için adımları otonom olarak planlar ve yürütür. Asistanlar sizi her döngüde ister. Ajanlar ise bir kontrol noktasına ulaşana veya bitene kadar çalışır.
Ajanımın otonom olarak çalışmaya hazır olup olmadığını nasıl anlarım? Onu denetimli modda 10 oturum boyunca çalıştırın. Her müdahale etmeniz gerektiğinde bunu takip edin. Müdahaleler oturum başına 2'nin altına düşerse ve hepsi küçükse (düzeltmeler değil, açıklamalarsa), hazır demektir. Müdahaleler sık ise veya yapılan işi geri almayı gerektiriyorsa, daha fazla güvenlik bariyeri ekleyin.
Otonom ajanlarla en büyük risk nedir? Ajanın tanımadığı art arda gelen hatalar. Erken yapılan küçük bir hata daha sonra büyük bir sorun haline gelir ve ajan, her adım tek başına makul göründüğü için çalışmaya devam eder. Kontrol noktaları, doğrulamayı zorunlu kılarak bu şelaleleri kırar.
Bu desenleri herhangi bir LLM ile kullanabilir miyim? Evet. Desenler (güvenlik bariyerleri, gözlemlenebilirlik, kontrol noktaları) modelden bağımsızdır. Claude, GPT-4, Gemini veya başka herhangi bir modelle çalışırlar. Belirli uygulama detayları değişebilir, ancak kavramlar aktarılabilir.
Gözlemlenebilirlik ajanı ne kadar yavaşlatır? İhmal edilebilir düzeyde. Bir günlük dosyasına yazmak mikro saniyeler sürer. Yavaşlama, insan girdisi bekleyen kontrol noktalarından kaynaklanır. Gerçekten otonom çalışmalar için, her adımda değil, yalnızca yüksek riskli anlarda kontrol noktası kullanırsınız.
Ajanın katılmadığım bir karar vermesi durumunda ne olur? İşte kontrol noktaları bunun içindir. Katılmadığınız bir karar gördüğünüzde, kontrol noktasını reddedin. Ajan geri döner veya farklı bir yaklaşım dener. Daha iyisi: tercihlerinizi ajanın talimatlarına dahil edin, böylece zamanla sizin tarzınızı öğrenir.
Denetimli mi yoksa otonom ajanlarla mı başlamalıyım? Her zaman denetimli başlayın. Ajana güvenene kadar her önemli eylemde kontrol noktalarıyla çalıştırın. Düşük riskli eylemler için kontrol noktalarını kademeli olarak kaldırın. Bu, ilk otonom çalışmanızda felaketle sonuçlanacak bir hatayı riske atmak yerine güveni kademeli olarak artırır.
Apidog yapay zeka ajanlarına özel olarak nasıl yardımcı olur? Apidog, şemalarınızdan doğrulanmış API istemcileri oluşturur. Bir ajan bu istemcileri kullandığında, hatalı biçimlendirilmiş istekler arka ucunuza ulaşmadan önce reddedilir. Bu, ajanın yanlış veri biçimi veya geçersiz değerler gönderdiği tüm bir hata sınıfını önler.