Phase 14: Agent Engineering

Ajanlar için İnsanize Skriptleri

Soğuk bir sesyonda bir vergi ödeniyor ajan aynı dosyaları okuyor, aynı araştırmaları tekrar denediyor ve aynı yolları yeniden keşfediyor.

Type: Build

Languages: Python (stdlib)

Prerequisites: Phase 14 · 32 (Minimal Workbench), Phase 14 · 34 (Repo Memory)

Time: ~45 minutes

Öğrenme Hedefleri

  • Bir ajanın bir seansta asla tekrar etmesi gerekmeyen bir işi belirleyin.
  • Çalışma zamanını, bağımlılıkları ve repo sağlığını araştırmak için belirleyici bir init metni oluşturun.
  • Araçın sonucuyu devam ettirin, böylece ajan tekrar kontrol etmek yerine onu okuyabilir.
  • Başlangıç başarısız olduğunda yüksek sesle, hızlı ve tek bir yere bak.

Sorun

Bir oturum açın. Ajan Python sürümünü tahmin eder. Test komutunu tahmin eder. Giriş noktasını bulmak için repo köküünü beş kez listeler. Kurulmamış bir paket içeriye aktarmaya çalışır. Kullanıcıya yapılandırma dosyasının nerede yaşadığını sorar. Gerçek bir düzenleme yapıldığı zaman, on bin token tek bir senaryo olması gereken kurulum işlerine gitti.

Düzeltme , ajanın başka bir şey yapmadan önce çalıştırılan ve bir yazı yazılan bir başlangıç metni .init_report.jsonAjanın başlatma noktası.

Anlaşım

flowchart TD
  Start[Session Start] --> Init[init_agent.py]
  Init --> Probes[probe runtime / deps / paths / env / tests]
  Probes --> Report[init_report.json]
  Report --> Decision{healthy?}
  Decision -- yes --> Agent[Agent Loop]
  Decision -- no --> Halt[fail loud, halt, surface to human]

İnt script neyi araştırıyor

ProbeWhy it matters
Runtime versionsWrong Python or Node version means silent wrong-version bugs
Dependency availabilityA missing package later costs ten times the cost of catching it now
Test commandThe agent must know how to verify; if the command is missing the workbench is broken
Repo pathsHard-coded paths drift; resolve them once and pin
Environment variablesMissing OPENAI_API_KEY is a failure surface, not a runtime mystery
State + board freshnessStale state from a crashed session is a footgun
Last-known-good commitAnchor for the handoff diff at the end of the session

Sesli başarısız olun, hızlı başarısız olun, tek bir yerde başarısız olun.

Bir sonda başarısızlık, durmak ve insan yüzeyi anlamına gelir. "Ajent bunu çözecek".

Gücün yetersiz

İkinci atış yeni bir zaman damgası hariç bir no-op olmalıdır. İdempotency senaryoyu CI, haklar veya görev öncesi kesme komutlarına bağlamanızı sağlayan şeydir.

Başlangıç kuralları karşı karşıya

Kurallar (Fase 14 · 33) hareket etmek için neyin doğru olması gerektiğini açıklar. Init bu kurallara kontrol edilebileceğini belirleyen metin.

Yapın

code/main.pyuygulamalar init_agent.py- ...

  • Beş sonda: Python versiyonu, listelenmiş bağımlılıklar importlib.util.find_spec, test komut çözülebilirliği, gerekli çevre gücü, dosyaların tazeliği.
  • Her sonda geri dönüyor .(name, status, detail)- Evet .
  • Senaryo yazıyor .init_report.jsonTüm sonda ayarlanmış ve blok ağırlığı sonda başarısız olursa sıfır dışı çıkıyor.

Çek şunu:

python3 code/main.py

Senaryo, sondanın tablolarını basıyor, yazıyor.init_report.json, ve mutlu yolda sıfırdan çıkıyor veya başarısız sondların bir listesine sahip olmayan sıfırdan çıkıyor.

Doğada üretim biçimleri

Üç örnektir, faydalı bir init metnini bir törenden ayırır.

Last-known-good commit anchoring.Bir LKGBu, Cloudflare'ın AI Code Review'i değerlendirme ajanlarını etkilemek için kullanan bir dosyadır: her inceleme seansı aynı bilinen iyiliğe karşı demirlenir ve asla bileşikler seanslar arasında sürüklenmez.

Lock files with TTL.Bir yazın .prereqs.lockSonraki çalışmalar N saat (24 saat varsayılan) için kilit güven ve pahalı araştırma atlamak. init senaryo ilk olarak kilit okur; eğer taze ve bağımlılık manifesto hasha eşleşir, kısa devre. Bu Docker katman önbelleği için kullanılan aynı kalıp: idempotent probe + içeriği hasha = atlamak.

No network, no LLM, no surprises in the hot path.Init sondaları belirleyici tesisat. Bir hatayı sınıflandırmak için bir LLM'yi çağıran veya bir lisans kontrol etmek için bir dış hizmete çarpan bir sonda bir sonda değildir; bir iş akışıdır. Bir sonda kuru bir çalışmada üç saniyeden uzun sürerse, bunu bir çalışma tahtası kokusu olarak değerlendirin ve ya init'ten çıkarın veya sonuçlarını önbelleğe koyun.

Kullan

Üretim:

  • Claude Code hooks. pre-taskHook, init senaryoyu arıyor ve başarısız olursa ajanı başlatmayı reddediyor.
  • GitHub Actions.A.setup-agentİş init senaryoyu çalıştırır; ajan işi buna bağlıdır.
  • Docker entrypoint.Ajan konteyneri, Ajan çalıştırma zamanını gerçekleştirmeden önce init senaryosunu çalıştırır; başarısızlık durumunda kayıtlar açılır.

init senaryosu taşınabilir çünkü belirli bir çerçeveye çağrı yapmaz. Bash, Make veya bir görev dosyası hepsini sarılabilir.

Gönder

outputs/skill-init-script.mdProjeyi röportaj eder, kurulum çalışmalarını araştırmalara sınıflandırır ve projeye özel bir bilgi gönderir init_agent.pyBir ajanın adımlarından önce çalıştırılan bir bilgi akışı da var.

Egzersizler

  1. Son bilinen iyi commit ile mevcut commit'i farklılaştıran ve 50'den fazla dosya değiştirildiğinde başlatmayı reddeden bir sonda ekleyin.
  2. Bir yazı yazmak için senaryoyu bağlayın prereqs.lockEğer kilit yedi günden daha eskiyse başlatmayı reddeder.
  3. Bir ekle--fixKayıp dev bağımlılıklarını otomatik olarak yükleyen ama hiçbir zaman onay olmadan çalıştırma süresi bağımlılıklarını değiştirmeyen bir bayrak.
  4. Sondeyi sert kodlanmış fonksiyonlardan YAML kayıtlarına taşı.
  5. Bir sondada üç saniye daha uzun süren bir sonda iş masası kokusu.

Anahtar Terimler

TermWhat people sayWhat it actually means
Probe"A check"A deterministic function returning (name, status, detail)
Init report"Setup output"JSON written next to state with the probe results
Idempotent"Safe to re-run"Two runs in a row produce identical reports modulo timestamp
Fail loud"Don't swallow"Halt and surface to the human; no silent fallback
Setup tax"Bootstrap cost"The tokens the agent spends per session rediscovering the obvious

Daha Fazla Okumak

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.