Phase 14: Agent Engineering

Repo hafızası ve kalıcı durum

Type: Build

Languages: Python (stdlib + jsonschema optional)

Prerequisites: Phase 14 · 32 (Minimal Workbench)

Time: ~60 minutes

Öğrenme Hedefleri

• repo hafızasına ne ait olduğunu ve sohbet geçmişine neyin ait olduğunu tanımlayın.
• Yazar JSON Schemas for agent_state.jsonve task_board.json- Evet .
• Atomik olarak devleti yükleyen, onaylayan, mutasyon yapan ve devam eden bir devlet yöneticisi oluşturun.
• İş masasını bozan kötü yazıları reddetmek için şema kullan.

Sorun

Bu nedenle, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre sonra, bir süre, bir süre sonra, bir süre sonra, bir süre sonra, bir süre, bir süre, bir süre, bir süre sonra, bir süre, bir süre, bir süre, bir süre, bir süre sonra, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir süre, bir bir bir bir, bir, bir bir bir, bir, bir, bir, bir, bir, bir, bir, bir, bir, bir, bir, bir, bir, bir,

İşleme tabanı düzeltmesi repo bellekidir: repo'daki JSON dosyalarında durum yaşamaktadır, bir şema altında yazılır, atomik olarak devam eder, kod incelemesinde farklılık dostu. Çat geçici bir beslenme; repo kayıt sistemidir.

Anlaşım

flowchart LR
  Agent[Agent Loop] --> Manager[StateManager]
  Manager --> Schema[agent_state.schema.json]
  Schema --> Validate{valid?}
  Validate -- yes --> Write[agent_state.json]
  Validate -- no --> Reject[refuse + raise]
  Write --> Manager

repo hafızasına ait olan şey

Test dayanıklılık: 3 ay sonra bir CI tekrarlaması için yararlı olur mu?

Şema birinci durum

JSON Schema sözleşmesidir. Bu olmadan her ajan yeni alanlar icat eder, her inceleyiciler yeni bir şekil öğrenir ve her CI senaryosu geçmiş sürümlere özel durumlar oluşturmalıdır.

Şema şuları kapsar:

• Gerekli anahtarlar.
• İzin veriliyor .statusdeğerleri.
• Yasak değerler (örneğin nullArraylar için).
• Şablon kısıtlamaları (iş kimlikleri eşleşir T-\d{3,})
• Göçmenlik için sürüm alanı.

Atomik yazıyor

Devlet yazıları kısmi başarısızlıklardan kurtulmak için gerekli: bir tempfile'ye yazın, fsync, hedefi yeniden adlandırın. Devlet dosyası gerçeğin kaynağıdır; yarı yazılı bir dosya hiç dosya olmaktan daha kötüdür.

Göçmenlik

Şema değişirken, şema yumruğunun yanında bir göç metni gönderin.schema_versionalan; yöneticisi bir dosyayı taşımayacağı bir sürümden yüklemeyi reddeder.

Yapın

code/main.pyUygulamaları:

• agent_state.schema.jsonve task_board.schema.json- Evet .
• Sadece stdlib onaylayıcı (JSON Şema alt kümesi: gerekli, tür, enum, desen, öğeler).
• StateManager.load- Evet .StateManager.update- Evet .StateManager.commitAtom temp-and-rename yazısı ile.
• Bir demo, durumunu mutasyonla değiştirir, devam eder, yeniden yüklenir ve dönüş yolculuğunu kanıtlar.

Çek şunu:

Copypython3 code/main.py

Senaryo yazıyor .workdir/agent_state.jsonve workdir/task_board.json, onları iki dönüşte mutasyonlandırır ve her adımda onaylanmış durumun yazdırılmasını sağlar.

Doğada üretim biçimleri

Dört örnektir ders minimumunu bir çok ajanlı monorepo hayatta kalabilecek bir şeye dönüştürür.

Atomic temp-and-rename is not optional.Mart 2026 Hive proje hata raporunda başarısızlık modunun temiz bir şekilde belgelenmesi: state.jsontarafından yazıldı write_text()Partial Left yazıyor, yolsuzluğa karşı sessiz bir şekilde devam ediyor.tempfile.mkstempHedef ile aynı dizinde yazın, fsync- Evet .os.replaceBu ders, bu ders için bir ders.atomic_writeTam olarak öyle.

Idempotency keys on every non-idempotent tool call.Bir aracı aradıktan sonra bir ajan çökerse ama sonuç kontrol noktası olmadan önce, kurtarma araç çağrısını tekrar dener. Okuyucular için güvenli; e-postalar, DB eklemeleri, dosya yüklemeleri için tehlikeli.pending_calls.jsonl. Yeniden denediğinizde kimliği kontrol edin; mevcutsa, çağrıdan atlayın ve önbelleğe alınmış sonucu kullanın. Anthropic ve LangChain her ikisi de 2026 yönlendirmeinde bunu çağırır; LangGraph'in kontrol noktası aynı nedenle yazıları bekleyen olarak kalır.

Separate large artifacts from state.CSV'leri, uzun transkriptleri veya oluşturulan dosyaları saklama agent_state.json. Eserleri ayrı bir dosya olarak kaydet (veya nesne depolama alanına yükle) ve sadece yolun durumunda tut. Kontrol noktaları küçük ve hızlı kalır; eserler bağımsız olarak büyür.

Event sourcing for audit, snapshots for resume.Bir olay günlüğüne ekle (state.events.jsonl) her mutasyonda; düzenli olarak state.jsonResume anlık görüntüyü okuyor, ardından anlık görüntünün zaman damgasından sonra olan her olayı yeniden oynar. Bu daha fazla disk maliyetini alır, ancak uzun ufuk çalışmalar düzeltirken ajan kararlarını sözcük anlamda tekrar oynamalarını sağlar. Postgres'in WAL için içsel olarak kullandığı aynı şekil.

Schema migrations or refuse to load.- Evet .schema_versiontam sayı sözleşmedir. yöneticisi bir dosyayı bilinmeyen bir sürümde yüklerken, okumaktan kaçınır. Şema yumruğunun yanında bir göç metni gönderin; tools/migrate_state.pyHer başlangıçta idempotently çalışır.

Kullan

Üretim:

• LangGraph checkpointers.Aynı fikir, farklı depolama. Kontrol noktası SQLite, Postgres veya özel bir arka planda grafik durumunu sürdürür. Bu dersin öğrettiği şema, kontrol noktası ölünce neye ulaştığınızı ve durumu elden okumak zorunda olduğunuz şeydir.
• Letta memory blocks.Yapılandırılmış şemalarla sürekli bloklar (Fase 14 · 08).
• OpenAI Agents SDK session store.Bu dersdeki devlet dosyası yerel dosya arka uçları.

Gönder

outputs/skill-state-schema.mdprojeye özel bir JSON Schema çiftini (stat + board), Python StateManageratom yazısı ile kablolanmış ve bir göç asması var. Böylece bir sonraki şema çarpması çalışma masasını kırmaz.

Egzersizler

1. Bir eklelast_human_touchİnsan düzenlemesinden beş saniye sonra herhangi bir ajanın yazmasını reddet.
2. Validatörü desteklemek için uzat oneOfBu nedenle bir görev, farklı gerekli alanlarla bir yapı görevinden veya bir inceleme görevinden olabilir.
3. Bir ekleschema_versionalanı ve v1 ' den v2 ' e göçü yaz (dönüştürme blockers- ...risks)
4. Kayıt arka uçlarını yerel dosyadan SQLite'e taşı.StateManagerAPI aynı.
5. 50 ms yazma yarışıyla iki ajanı aynı devlet dosyasına karşı çalıştır.

Anahtar Terimler

Daha Fazla Okumak

• JSON Schema specification
• LangGraph checkpointers
• Letta memory blocks
• Fast.io, AI Agent State Checkpointing: A Practical Guide İdempotency ile ilk şema kontrol noktası
• Fast.io, AI Agent Workflow State Persistence: Best Practices 2026 Eşzamanlılık kontrolü, TTL, olay kaynakları
• Hive Issue #6263 — non-atomic state.json writes silently ignored Gerçek bir projede başarısızlık modu
• eunomia, Checkpoint/Restore Systems: Evolution, Techniques, Applications Ajanlara uygulanan işletim sisteminin geçmişindeki CR primitifleri
• Indium, 7 State Persistence Strategies for Long-Running AI Agents in 2026
• Microsoft Agent Framework, Compaction Satıcı kontrol noktası yöneticisi
• Fase 14 · 08 hafıza blokları ve uyku zamanı hesaplama
• Fase 14 · 32 bu ders üç dosya minimumı çizer
• Fase 14 · 40 aynı şema ile birlikte gönderilen paketler

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.