Yazılım Eğitimi Asistanlarında Agent Durumu ve Güvenli Tekrarlar

Yazılım Eğitimi Asistanlarında Agent Durumunu Olay Olarak Saklamak

Çok turlu bir agent'ta sadece son mesajları Redis'te tutmak, süreç yeniden başlatıldığında hangi tool çağrısının tamamlandığını belirsiz bırakır. Bunun yerine PostgreSQL'de append-only bir agent_events tablosu kullanın. Her olayda thread_id, artan sequence_no, event_type, JSONB yükü ve UTC zaman damgası bulunmalıdır. Bu yapı, hatalı bir yanıtı aynı başlangıç olaylarından tekrar üretmeyi ve kullanıcıya ait belirli bir oturumun denetim izini çıkarmayı mümkün kılar.

CREATE TABLE agent_events (
  thread_id UUID NOT NULL,
  sequence_no BIGINT NOT NULL,
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (thread_id, sequence_no)
);

CREATE INDEX agent_events_thread_created_idx
ON agent_events (thread_id, created_at);

Sıra numarasını uygulama belleğinde artırmayın. İki HTTP isteği aynı oturuma eşzamanlı gelirse ikisi de aynı sonraki sıra numarasını seçebilir. PostgreSQL transaction'ı içinde ilgili thread için advisory lock alın veya ayrı bir agent_threads satırını SELECT ... FOR UPDATE ile kilitleyin. Bu kilit sadece event ekleme süresince tutulmalı, LLM isteği veya harici tool çağrısı kilit altında yapılmamalıdır; aksi halde yavaş bir API çağrısı tüm konuşmayı bloklar.

BEGIN;
SELECT pg_advisory_xact_lock(hashtextextended('thread:' || :thread_id::text, 0));

INSERT INTO agent_events (thread_id, sequence_no, event_type, payload)
SELECT :thread_id,
       COALESCE(MAX(sequence_no), 0) + 1,
       'user_message',
       jsonb_build_object('text', :text)
FROM agent_events
WHERE thread_id = :thread_id;
COMMIT;

Tool Çağrılarında Idempotency ve Outbox ile Güvenli Tekrar

Agent bir Git deposunda dosya oluşturuyor, bir sandbox derlemesi başlatıyor veya eğitim ortamında değerlendirme kuyruğuna iş gönderiyorsa HTTP timeout sonrası aynı tool çağrısını körlemesine tekrarlamak çift yan etki üretir. Modelin ürettiği argümanları doğrudan anahtar yapmak da güvenli değildir, çünkü alan sırası veya anlamsız açıklama metni değişebilir. Bunun yerine thread_id, agent adımı ve normalize edilmiş tool argümanlarından SHA-256 ile türetilmiş bir idempotency_key kullanın.

import hashlib
import json

def tool_key(thread_id: str, step: int, tool: str, args: dict) -> str:
    canonical = json.dumps(args, sort_keys=True, separators=(',', ':'))
    raw = f'{thread_id}:{step}:{tool}:{canonical}'.encode()
    return hashlib.sha256(raw).hexdigest()

# tools.idempotency_key alanı UNIQUE olmalıdır.
# Aynı anahtar varsa önceki sonucu döndürün, tool'u yeniden çalıştırmayın.

Veritabanına tool_requested olayı yazıp ardından doğrudan iş kuyruğuna mesaj göndermek, transaction commit olmadan süreç ölürse kayıp iş üretir. Ters sırada gönderim yapmak ise commit başarısız olduğunda hayalet iş üretir. Transactional outbox tablosuna hem olay hem yayın kaydını aynı transaction'da ekleyin; ayrı bir worker FOR UPDATE SKIP LOCKED ile kayıtları alıp RabbitMQ, SQS veya benzeri kuyruğa yayınlasın. Yayıncı en az bir kez teslim yaptığı için tüketici de aynı idempotency_key ile deduplikasyon yapmalıdır.

WITH next_jobs AS (
  SELECT id
  FROM outbox
  WHERE published_at IS NULL
  ORDER BY id
  FOR UPDATE SKIP LOCKED
  LIMIT 50
)
UPDATE outbox o
SET attempts = attempts + 1
FROM next_jobs j
WHERE o.id = j.id
RETURNING o.id, o.topic, o.payload;

Checkpoint Sıkıştırma ve Bağlamı Deterministik Yeniden Kurma

Ham event geçmişinin tamamını her model çağrısına koymak token maliyetini doğrusal büyütür ve uzun oturumlarda modelin dikkat penceresini gereksiz tool çıktılarıyla doldurur. Her 20 olayda bir checkpoint üretin, ancak checkpoint'i gerçek kaynak olarak görmeyin. Kaynak gerçeklik append-only olay günlüğüdür; checkpoint yalnızca hızlandırıcı bir türevdir. Checkpoint yükünde son işlenen sıra numarası, yapılandırılmış öğrenen profili, açık görevler ve kullanılan araçların sonuç referansları yer almalıdır.

CREATE TABLE agent_checkpoints (
  thread_id UUID NOT NULL,
  through_sequence_no BIGINT NOT NULL,
  state JSONB NOT NULL,
  event_digest TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (thread_id, through_sequence_no)
);

Yeniden kurulumda önce en yüksek through_sequence_no değerine sahip checkpoint'i yükleyin, sonra yalnızca sonraki event'leri fold edin. Checkpoint içine serbest metin özet koymak yerine open_tasks, known_concepts ve last_tool_result_id gibi şemalı alanlar koyun. Serbest metin özet, modelin önceki bir varsayımını gerçek veri gibi kalıcılaştırabilir. Özetin kapsadığı event'lerin SHA-256 digest'ini saklayın; digest uyuşmazsa checkpoint'i atıp tam event replay çalıştırın.

SELECT state, through_sequence_no
FROM agent_checkpoints
WHERE thread_id = :thread_id
ORDER BY through_sequence_no DESC
LIMIT 1;

SELECT sequence_no, event_type, payload
FROM agent_events
WHERE thread_id = :thread_id
  AND sequence_no > :through_sequence_no
ORDER BY sequence_no ASC;

Agent Durumu Gecikmesini OpenTelemetry ile Ölçmek ve Karşılaştırmak

Durum yönetimi değişikliğini sadece toplam yanıt süresiyle değerlendirmeyin. OpenTelemetry span'larında thread_id'nin kendisini değil, hash'lenmiş halini; checkpoint_hit, replayed_event_count, tool_deduplicated ve prompt_token_count özniteliklerini kaydedin. Ham kullanıcı kimliği veya mesaj gövdesini telemetry etiketi olarak eklemek, yüksek cardinality nedeniyle Prometheus benzeri arka uçlarda maliyeti ve sorgu süresini artırır.

from opentelemetry import trace

tracer = trace.get_tracer('learning-agent')
with tracer.start_as_current_span('agent.restore_state') as span:
    span.set_attribute('checkpoint_hit', checkpoint is not None)
    span.set_attribute('replayed_event_count', len(events_to_replay))
    span.set_attribute('prompt_token_count', prompt_tokens)
    state = replay(checkpoint, events_to_replay)

Önce mevcut akışta en az 1.000 üretim benzeri oturum kaydıyla agent.restore_state span'larının p50, p95 ve p99 değerlerini çıkarın. Ardından checkpoint ve kısmi replay değişikliğini feature flag ile oturumların bir bölümüne uygulayın. Karşılaştırmada sadece gecikmeyi değil, aynı input için üretilen tool çağrısı sayısını, deduplikasyon oranını ve replay sonrası durum hash eşleşmesini ölçün. p95 düşerken durum hash uyuşmazlığı artıyorsa optimizasyon doğru değildir; hızlı fakat semantik olarak bozuk bir yeniden kurulum yapıyorsunuz demektir.

# Tempo veya Jaeger verisi OTel Collector'a aktarıldıktan sonra
# span adını ve dağılımı sorgulamak için örnek TraceQL filtresi:
{ resource.service.name = 'learning-agent' && name = 'agent.restore_state' }

# PostgreSQL sorgularını karşılaştırmak için:
SELECT query, calls, mean_exec_time, rows
FROM pg_stat_statements
WHERE query LIKE '%agent_events%'
ORDER BY total_exec_time DESC
LIMIT 10;

Sık Sorulan Sorular

Yazılım eğitimi asistanında conversation memory yerine event sourcing ne zaman kullanılmalı?

Kullanıcı oturumu içinde tool çağrısı, insan onayı, değerlendirme sonucu veya dosya değişikliği gibi yeniden oynatılması gereken yan etkiler varsa event sourcing kullanın. Sadece kısa ömürlü sohbetlerde Redis listesi yeterli olabilir. Kararı doğrulamak için her thread'de event sayısını, yeniden başlatma sonrası hata oranını ve agent.restore_state p95 süresini OpenTelemetry ile ölçün.

Yazılım eğitimi agent tool çağrıları iki kez çalışmayı nasıl engeller?

Her tool isteği için UNIQUE(idempotency_key) tanımlayın ve anahtarı thread kimliği, adım numarası, tool adı ve canonical JSON argümanlarından üretin. Tool sonucu kaydedilmişse aynı anahtarda sonucu döndürün. Kuyruk tüketicisi tekrar teslim aldığında da bu anahtarı kontrol etmelidir; yalnızca API katmanında kontrol etmek yeterli değildir.

Yazılım eğitimi LLM asistanında checkpoint ne sıklıkta oluşturulmalı?

Sabit bir sayı ile başlamayın. Önce oturum başına event sayısı ve replay span gecikmesi için dağılım çıkarın. Örneğin p95 replay 300 ms hedefini aşıyorsa 10, 20 ve 40 event aralıklarını feature flag ile deneyin. Checkpoint üretiminin ek yazma maliyetini pg_stat_statements ile, doğruluğunu da checkpoint digest ile tam replay digest'ini karşılaştırarak izleyin.