ADK ile ajan tabanlı iş akışı

1. Giriş

Bu codelab'de, Agent Development Kit'teki (ADK) iş akışlarını ve grafikleri kullanarak yeni nesil ajan tabanlı sistemler oluşturma işlemi adım adım açıklanır. Yaygın mimari modelleri uygulayacak, kullanıcıların dahil edilmesi (HITL) etkileşimlerini düzenleyecek ve uzun süren eşzamansız yürütmeyi işleyeceksiniz. Ayrıca, aracı davranışını özelleştirmek ve geliştirmek için kurumsal bilgi tabanlarını ve kalıcı belleği entegre edeceksiniz. Son olarak, otomatik video oluşturma ardışık düzenini çalıştırmak için bu özellikleri bağlayacaksınız.

Senaryo

VibeTube'da etkin bir kitleye sahip ve yaratıcı fikirler biriktiren bir dijital kanalınız var. Her videonun üretilmesi için birden fazla aşamada sürekli olarak çalışmak gerekir: trend olan biçimleri araştırma, izleyici geri bildirimlerini sentezleme, senaryo geliştirme, politika uygunluğunu kontrol etme ve video klipler oluşturma. Üretken modeller tek tek öğeler oluşturabilir ancak tutarlı yayınlar sunmak için düzenlenmiş bir aracı mimarisi gerekir.

Bu yaşam döngüsünü otomatikleştirmek için VibeStudio'yu oluşturacaksınız. Bu ajan tabanlı ardışık düzen, rutin araştırmaları paralel olarak yürütür, insan müdahalesiyle onay için seçilmiş seçenekler sunar, video oluşturmadan önce otomatik politika kapılarını uygular ve üretim çalıştırmaları boyunca bağlamı korur.

Öğrenecekleriniz

• Grafik mühendisliği temelleri: Çok adımlı aracı mimarileri, açık kontrol akışı ve yapılandırılmış yürütme yolları gerektirir. Kenar demetleri, Workflow giriş noktası, START paralel fan-out toplama için JoinNode ve duruma göre yürütmeyi yönlendirmek için deterministik yönlendirici düğümleri kullanarak bir ADK oluşturursunuz.
• Aracı modları ve yaşam döngüsü geri çağırmaları: Özel görevler, farklı operasyonel davranışlar ve deterministik koruma sınırları gerektirir. ADK Agent örneklerini chat, single_turn ve araç etkin task modlarını iş akışı düğümleri olarak kullanarak yapılandırır, before_model_callback ve after_agent_callback ile kesiciler uygularsınız.
• İnsan müdahalesi gerektiren düzenleme: Üretim işlem hatları, kritik yaratıcı kontrol noktalarında insan değerlendirmesi için duraklatılır. İş akışı yürütmesini askıya almak, yapılandırılmış yanıt şemalarını zorunlu kılmak ve boşta kalan çalışma zamanı süreçlerini canlı tutmadan yürütmeye devam etmek için RequestInput'ı uygularsınız.
• Hiyerarşik aracı belleği: Üretim sistemleri, geçici yürütme durumunu kalıcı bağlamdan ayırır. Event(state=...) ve parametre bağlama ile kısa süreli oturum durumunu yönetirsiniz. Ayrıca, GEAP Memory Bank'ı bağlayarak içerik üreticilerin tercihlerini çalıştırmalar arasında ayıklayıp birleştirir ve kalıcı hale getirirsiniz.
• Kurumsal bilgi tabanlarıyla temellendirme: Bağımsız temsilciler için dinamik alan bağlamı ve kitle duyarlılığı gerekir. GEAP RAG Engine gövdesini, paralel fan-out içinde özel bir alma düğümü olarak bağlayarak aracı çıkışlarını semantik olarak temellendirirsiniz.
• Uzun süreli iş akışları ve dağıtım: Çok formatlı video oluşturma, uzun süreler boyunca eşzamansız olarak çalışır. İş akışını arama kimliğine göre askıya almak ve devam ettirmek için bekleyen arama makbuzlarıyla LongRunningFunctionTool işlevini uygularsınız ve tamamlanan ardışık düzeni Cloud Run'da ADK Runner'yı kullanarak dağıtırsınız.

Bu codelab'in düzeni

Bu codelab, kavramsal ve mimari referansınız olarak kullanılabilir. Her bölümde, ilgili iş istasyonu adımında uygulanan ADK yapıları açıklanır, referans kodu sağlanır ve temel tasarım ilkeleri belirlenir. Çalışma tezgahındaki ilgili alıştırmayı tamamlamadan önce her bölümü inceleyin.

Pratik çalışmalar, etkileşimli bir kod düzenleyici, çalışma zamanı doğrulayıcıları ve yerleştirilmiş bir ADK inceleyicisi içeren yardımcı bir web arayüzü olan VibeStudio Workbench'te yapılır. Çalışma tezgahındaki adım numaralandırması, ilerleme durumunuzun senkronize kalması için bu codelab ile doğrudan uyumludur. Temel grafik düzenlemeleri adımlar boyunca devam eder. Çalışma alanı, ilerledikçe ön koşulları otomatik olarak doğrular.

Workbench alıştırmalarını tamamladığınızda uçtan uca bir aracı işlem hattı oluşturacak ve video içeriği oluşturmak için çalışan bir VibeStudio uygulamasını Cloud Run'a dağıtacaksınız.

Ortam üç temel bileşenden oluşur: VibeStudio Workbench (kod düzenleme ve çalışma zamanı doğrulama için yerel web arayüzü), arka ucunuz (ADK Workflow ve agent/ içindeki aşama sanal alanları) ve Google Cloud (Gemini modelleri, GEAP Memory Bank, RAG Engine ve Veo video oluşturma).

2. Kurulum

Atölye kredilerinizi kullanma

Eğitmen tarafından yönetilen bir laboratuvara katılıyorsanız eğitmen, Google Cloud projeniz için kredileri dağıtır. Kredilerinizi kullanmak için eğitmenin talimatlarını uygulayın ve devam etmeden önce hesabınızda faturalandırmanın etkin olduğundan emin olun.

Cloud Shell'i açın

Cloud Shell, gcloud, Python ve git'in önceden yüklendiği tarayıcı tabanlı bir geliştirme ortamıdır.

Cloud Shell'i başlatmak için:

1. Google Cloud Console'a gidin.
2. Üst gezinme başlığında Cloud Shell'i etkinleştir'i (terminal penceresi simgesi) tıklayın.

Tarayıcı penceresinin en altında bir terminal oturumu açılır.

Depoyu klonlama ve başlatma

Projeyi klonlamak için Cloud Shell terminalinde aşağıdaki komutları çalıştırın:

git clone https://github.com/gca-americas/vibetube-studio
cd ~/vibetube-studio

Yapılandırma istemleri

Kurulum sırasında aşağıdaki ayrıntıları girmeniz istenir:

• Google Cloud proje kimliği: setup_project.sh tarafından istendiğinde yeni bir proje oluşturmak için Enter tuşuna basın. Mevcut bir projeyi (ör. önceden atanmış bir proje) kullanmayı tercih ederseniz proje kimliğinizi girin ve faturalandırmanın etkin olduğunu doğrulayarak yazım hatası yapmadığınızdan emin olun.
• Etkinlik kodu: Eğitmeninizin verdiği oda kodunu girin. Bu kartı almadıysanız bir öğretim asistanına veya komşunuza danışın. Bu laboratuvarı evde tamamlıyorsanız varsayılan sandbox odasını kabul etmek için Enter tuşuna basın.
• Kanalın görünen adı: setup_codelab.sh tarafından istendiğinde adınızı veya tercih ettiğiniz kanal herkese açık kullanıcı adını girin ya da Google Hesabınızdan oluşturulan varsayılan adı kabul etmek için Enter tuşuna basın.

İki kurulum komut dosyasını sırayla çalıştırın:

./setup_project.sh
./setup_codelab.sh

• setup_project.sh: Etkin faturalandırması olan bir Google Cloud projesi oluşturur veya yeniden kullanır, proje kimliğini ~/project_id.txt konumuna kaydeder ve etkin gcloud bağlamını yapılandırır.
• setup_codelab.sh: uv ve Python bağımlılıklarını .venv içine yükler, gerekli Google Cloud API'lerini etkinleştirir, .env'deki kanal ayarlarınızı yapılandırır, Gemini ile model erişimini doğrular, Memory Bank ve RAG kaynaklarını sağlar, Workbench arayüzünü oluşturur ve VibeStudio Workbench'i başlatır.

Komut dosyası, uçuş öncesi kontrolü çalıştırır ve VibeStudio Workbench'i arka planda başlatır. Son satırlarında açılacak bağlantı gösterilir.

7 · Preflight
  ✓ python 3.12
  ✓ auth path A: Vertex via ADC (STUDIO_VERTEX=1)
  ✓ Google Cloud ADC (project <your-project>)
  ✓ stage0_prompt loads
  ...
  ✓ stage6_video loads (13 edges)
  ✓ aiplatform.googleapis.com enabled (Gemini, Veo, Memory Bank, RAG Engine)
  ✓ vectorsearch.googleapis.com enabled (the vector store a RAG corpus is built on)
  ✓ Memory Bank connected
  ✓ RAG corpus connected
  ✓ VibeStudio Workbench running on port 4600

PREFLIGHT GREEN

Setup finished. The VibeStudio Workbench is already running.

  Open this and start at step 1
      https://4600-<your cloud shell host>/step/story

  It runs in the background. You do not need to start anything else.
      log      runs/lab.log
      stop     kill $(cat runs/lab.pid)
      start    scripts/start.sh

Bağlantıyı tıklayın. Aynı adres Web Önizlemesi → Bağlantı noktasını değiştir → 4600 altında da mevcuttur.

Ortamı istediğiniz zaman yeniden kontrol etmek için python scripts/preflight.py komutunu çalıştırın. Çalışma tezgahını yeniden başlatmak için scripts/restart.sh komutunu çalıştırın. Yeniden kurmak için ./setup_codelab.sh komutunu çalıştırın. Bu komut, yapılandırmanızı ve ilerleme durumunuzu korur.

Bu doküman açıkken senaryo için 1. adım: Hikaye, tamamlanmış grafiğin şekli için 2. adım: Ne oluşturacaksınız? bölümlerini okuyun. İkisinde de alıştırma yok. Ardından 3. adım için buraya geri dönün.

VibeStudio Workbench'in her uygulamalı bölümü, gerçek yapıları (diskteki dosya ve çalıştırmalar tarafından yazılan oturumlar) okuyan bir doğrulama paneliyle sona erer.

Depo düzeni

Depo; temel iş akışı mantığı, adım adım korumalı alanlar, çalışma tezgahı ortamı ve üretim uygulaması olarak yapılandırılmıştır:

vibe-studio-lab/
├── agent/                  # Core ADK workflow, graph definition, and platform services
│   ├── graph.py            # Workflow graph definition, node functions, and routers
│   ├── desk.py             # Video render desk using LongRunningFunctionTool
│   ├── schemas.py          # Pydantic schemas for directions, gates, and scripts
│   ├── trends.py           # Trend generation and sampling utilities
│   ├── backlog.txt         # Creator video ideas backlog
│   ├── comments.md         # Audience comments for RAG Engine corpus seeding
│   ├── policy_words.txt    # Blocked subject words for deterministic policy checks
│   └── platform/           # Google Cloud service clients (Memory Bank, RAG, Veo)
│       ├── config.py       # Environment variables, locations, and model configurations
│       ├── memory.py       # GEAP Memory Bank callbacks and context injection
│       ├── rag.py          # GEAP RAG Engine corpus creation and semantic retrieval
│       └── videogen.py     # Veo video generation and operation polling
├── stage0_prompt/          # Step sandboxes: isolated agent.py files runnable in adk web
│   └── ...                 # stage1_fanout through stage6_video for incremental steps
├── server/ & web/          # VibeStudio Workbench (FastAPI backend and React frontend)
├── vibestudio/             # Complete production application deployed to Cloud Run
│   ├── server/             # FastAPI production server and event runner
│   ├── web/                # End-user React web application

• agent/: Temel iş akışı grafiğini içerir. Paralel fan-out düğümlerini, deterministik politika yönlendirmeyi, bellek geri çağırmalarını ve video oluşturma araçlarını uygulamak için bu dizindeki dosyaları düzenleyeceksiniz.
• agent/platform/: Gemini modelleri, GEAP Memory Bank, GEAP RAG Engine ve Veo video sentezi dahil olmak üzere Google Cloud hizmetleriyle arayüz oluşturur.
• stage0_prompt/ aracılığıyla stage6_video/: Bağımsız korumalı alan ortamları. Her klasör bağımsız bir root_agent olarak dışa aktarılır. Böylece, yerleştirilmiş ADK geliştirme arayüzü aracılığıyla her adımı ayrı ayrı çalıştırıp inceleyebilirsiniz.
• server/ ve web/: 4600 numaralı bağlantı noktasında yerel olarak çalışan VibeStudio Workbench uygulaması. Adım dokümanlarını, sayfa içi kod düzenleyiciyi, çalışma zamanı kanıt doğrulayıcılarını ve grafik görselleştirmeyi barındırır.
• vibestudio/: Üretim uygulamasının tamamı, son adımda paketlenip Cloud Run'a dağıtılır. Tamamlanmış iş akışı grafiğinin kendi bağımsız kopyasını içerir.

3. Monolitik ajan

Çok düğümlü bir iş akışı grafiği oluşturmadan önce stage0_prompt/agent.py içinde tek bir aracıyla mimari bir temel oluşturursunuz. Bu aracı, iki Python işlevi aracıyla desteklenen, üretim hattını düz yazı şeklinde açıklayan tek bir sistem istemi kullanır.

Bu temel değerin değerlendirilmesi, istem odaklı koordinasyonun operasyonel sınırlarını gösterir ve üretim sistemlerinin neden grafik düzenlemesi gerektirdiğini ortaya koyar.

ADK temsilci mimarisi (3A)

VibeStudio Workbench'te 3. Adım: Monolitik ajan'a gidin ve ADK ajan mimarisi (3A)'ni açın. Bu görünüm, bir ADK aracısının temel mimari katmanlarını (LlmAgent) gösterir:

from google.adk.agents import LlmAgent
from google.adk.tools import mcp_toolset

root_agent = LlmAgent(
    model="gemini-3.5-flash",                 # model
    instruction=BRAND_INSTRUCTION,            # instruction
    skills=[load_skill("brand-audit")],       # skills
    tools=[mcp_toolset("mcp_brand_style")],   # tools
    output_schema=BrandStyleReport,           # structured output
    before_agent_callback=setup_ctx,          # interceptor
    before_model_callback=require_image,      # interceptor
    after_model_callback=schema_guard,        # interceptor
)

Etkileşimli diyagram, aracı bileşenlerini beş operasyonel alanda gruplandırır:

• Akıl yürütme katmanı (Model): Bilişsel görevleri, istem akıl yürütmesini ve araç seçimini yürüten temel dil modeli (ör. Gemini 3 Flash). Mimarideki diğer her şey bu modeli ya bilgilendirir ya da kısıtlar.
• Bağlam katmanı (Talimat ve Beceriler): Modelin muhakemesini şekillendiren direktifler. instruction kalıcı sistem istemini, karakteri ve operasyonel kuralları oluşturur. skills Tekrarlanabilir iş akışları için sürüm oluşturulmuş, prosedürlere dayalı rehberlik (SKILL.md) sunun.
• İşbirliği ve işlem katmanı (Araçlar, Alt Ajanlar, İş Akışı, Çıkış Şeması): Ajanın harici sistemlerde işlem yapmasını ve türü belirlenmiş veriler yayınlamasını sağlayan arayüzler. tools çağrılabilir Python işlevleri veya Model Bağlam Protokolü (MCP) uç noktaları sağlamalıdır. subagents alt birimlere devredilen görevleri yürütme workflow çoklu ajan grafiklerini koordine eder. output_schema, aşağı akış tüketicilerinin yapılandırılmamış metin yerine doğrulanmış JSON almasını sağlamak için Pydantic modellerini uygular.
• Arayıcı katmanı (Yaşam Döngüsü Geri Çağırmaları): Temsilci yürütülmeden önce ve sonra (before_agent/after_agent), tek tek model dönüşlerinden (before_model/after_model) ve araç çağrılarından (before_tool/after_tool) önce ve sonra özel kodu yürüten deterministik koruma rayları. Arayıcılar, model uygunluğuna güvenmeden politika kurallarını uygular.
• Harici durum (Oturum ve Bellek): Durumlu kalıcılık, aracı mantığından ayrılır. Session, geçici çalışma belleğini ve mevcut yürütme iş parçacığı için etkinlik izini korur. Memory, GEAP Memory Bank gibi yönetilen hizmetleri kullanarak oturumlar arası kalıcı olguları ve tercihleri korur.

Bu adımdaki tek bloklu aracı yalnızca bu temel öğelerden üçünü (model, instruction ve tools) uygular. Sonraki adımlarda grafik iş akışları, yapılandırılmış şemalar, araya girenler ve kalıcı bellek hizmetleri tanıtılmaktadır.

Monolitik aracı spesifikasyonu (3B)

Çalışma tezgahında Monolitik aracı spesifikasyonu (3B)'na gidin. Temel aracı tanımını incelemek için stage0_prompt/agent.py dosyasını açın:

• Tek istem talimatı: Sistem istemi, beş farklı prodüksiyon görevini sürekli bir metin halinde özetler: platform trendlerini keşfetme, birikmiş fikirleri inceleme, reklam öğesi konseptleri önerme, yasaklanmış konu politikalarını uygulama ve çekim listeleri oluşturma.
• Temel veri kaynakları: Ajan, grafiğin yanında tanımlanan iki kaynağa referans verir:
  • agent/trends.py: 250 öğeden oluşan bir havuzdaki on etkin biçim ve stil trendini dinamik popülerlik puanlarıyla örnekler.
  • agent/backlog.txt: İçerik üreticinin ham konsept notlarını satır satır okur.

Agent'taki (3C) Araçlar

Workbench'te Tools in Agent (3C)'ye (Aracıdaki Araçlar) gidin.

Aracılar için araç nedir?

Dil modeli, doğası gereği kapalı dünya muhakeme motorudur: Yalnızca önceden eğitilmiş ağırlıklar ve anlık bağlam penceresinde bulunan jetonlarla çalışır. Yerel olarak bir veritabanına sorgu gönderemez, anlık API'lere erişemez veya kod yürütemez.

Araçlar bu sınırı aşar. Bu sayede model, harici sistemlerde kesin sonuç veren işlemler gerçekleştirebilir ve doğru bilgileri alabilir.

Araç çağrısı, model ile ADK çalışma zamanı arasında açık bir beş aşamalı protokolü izler:

1. Şema bildirimi: Geliştirici, aracıya Python işlevleri sağlar. ADK, her işlevin adını, tür ek açıklamalarını ve doküman dizelerini inceleyerek parametrelerini ve amacını açıklayan OpenAPI uyumlu bir JSON şema bildirimi oluşturur.
2. Model muhakemesi: Model, çıkarım sırasında kullanıcının isteminin harici veri gerektirip gerektirmediğini değerlendirir. Gerekirse model, hedef işlev adını ve şemaya uyan bağımsız değişken sözlüğünü içeren yapılandırılmış bir function_call etkinliği yayınlar.
3. Çalışma zamanı yürütmesi: Modelin kendisi kodu yürütmez. ADK çalışma zamanı function_call öğesini yakalar, sağlanan bağımsız değişkenleri kullanarak gerçek yerel Python işlevini yürütür ve dönüş değerini yakalar.
4. Bağlamı yeniden yerleştirme: ADK çalışma zamanı, işlevin döndürdüğü değeri bir function_response etkinliğine paketler ve etkin oturum geçmişine ekler.
5. Son sentez: Model, bağlam penceresinde bulunan araç çıkışını işler ve yanıtını tamamlar.

stage0_prompt/agent.py içinde iki araştırma aracı standart Python işlevleri olarak tanımlanır:

def check_trends() -> dict:
    """Ten formats trending on the platform right now, with a heat score each."""
    from agent.trends import sample_trends
    return {"trends": sample_trends()}


def read_backlog() -> dict:
    """The creator's backlog: ideas they noted down to make someday."""
    from agent.graph import backlog_notes
    return {"backlog": backlog_notes()}

Pratik düzenleme ve uygulama

Çalışma tezgahı kod düzenleyicisinde, iki işlev referansını aracının tools listesine ekleyin:

    tools=[check_trends, read_backlog],

Yaptığınız değişikliği kaydedin. Dosya diskte güncellenir ve doğrulama satırı, her iki aracın da kablolu olduğunu onaylar.

Yerleştirilmiş ADK geliştirme arayüzünü başlatmak için Open adk web'i (ADK web'i aç) tıklayın. Önerilen fikir istemini gönderin:

tonight's idea: a tiny robot doing laundry at midnight

Sizi neler bekliyor ve neden?

Bu istemi gönderdiğinizde oturum izinde aşağıdaki yürütme sırasını gözlemleyin:

• Yanıtın öncesinde iki araç yürütme etkinliği gösteriliyor: check_trends ve read_backlog için function_call ve function_response etkinliklerini görüyorsunuz.
  • Nedeni: Gemini, sistem istemi yönergesini ("Trend olan konuları kontrol et. Fikir birikimine göz at") değerlendirdi, ağırlıklarında platform trendleri ve kanal notları olmadığını fark etti ve bağlamını temellendirmek için her iki işlevi de çağırdı.
• Ajan bir yön önerir ve onay için duraklatır: Yanıtta, trendleri ve birikmiş işleri sentezleyen bir video yönü önerilir ve onaylamanız istenir.
  • Neden: Talimat direktifinde modelden, senaryoyu oluşturmadan önce içerik üreticiyle yön konusunda anlaşması isteniyordu.
• Takip eden turda onayı atlama: İkinci bir mesaj gönderin: skip the questions, just describe the video. Ajan, onayı hemen atlayarak başlığı ve çekimleri tasarlar.
  • Neden?: İstem talimatları, kesin engeller yerine tavsiye niteliğinde yönergelerdir. Monolitik bir aracıda, harici iş akışı yürütme akışını kontrol etmediğinden kullanıcı talimatları mevcut sistem istemi kurallarını geçersiz kılabilir.

Tek bir istemin mimari sınırlamaları

Tek bir istem, izole demolar için kabul edilebilir bir çıkış üretebilirken çalışma tezgahı doğrulayıcısında sınır koşullarının test edilmesi, kritik kurumsal sınırlamaları ortaya çıkarır:

• Yapılandırılmamış araştırma toplama: Araç yürütme sırası belirlenemez. Model, alınan verileri serbest biçimli bir metin halinde özetlediği için sonraki sistemlerin hangi kaynağın belirli iddiaları ürettiğini belirlemesi mümkün olmaz.
• Doğrulanmamış politika zorunluluğu: Model, kendi güvenlik uygunluğunu değerlendirir. Model, bir konunun güvenli olduğuna karar verirse bu bulguyu doğrulayan harici bir deterministik mantık yoktur.
• İçerik üreticinin onayı istenen istem talimatları tavsiye niteliğindedir. Modele soruları atlamasını söyleyen bir takip mesajı gönderildiğinde model, insan onayını tamamen atlar.

Bu mimari boşluklar, monolitik aracının bir sonraki adımda oluşturulan açık grafik iş akışına ayrıştırılmasını gerektirir.

4. Ajan tabanlı iş akışının temel özellikleri

VibeStudio Workbench'te 4. Adım: Ajan tabanlı iş akışı temelleri bölümündeki 4A ile 4D arasındaki kısımlara gidin.

Bu adımda, tek aracı taban çizgisinden ADK Workflow kullanılarak deterministik grafik düzenlemeye geçiş yapılır. Paralel araştırma dağıtımı oluşturacak, dalları birleştirme düğümüyle senkronize edecek, şeması doğrulanmış reklam öğesi adayları oluşturacak ve deterministik bir insan müdahalesiyle onay kapısı sunacaksınız.

Grafik mimarisi ve yürütme zincirleri (4A)

Workbench'te Graph architecture and execution chains (4A)'yı (Grafik mimarisi ve yürütme zincirleri) açın.

Bir ADK Workflow, temsilci yürütmesini bir kenar listesiyle tanımlanan yönlendirilmiş grafik olarak yapılandırır:

• Zincirler: Sıralı demetler, doğrusal düğüm yürütmeyi tanımlar ((node_a, node_b, node_c)).
• Paralel dallar: Bir başlangıç düğümünü paylaşan bağımsız zincirler eşzamanlı olarak yürütülür.
• Senkronizasyon: JoinNode üzerinde birleşen zincirler, yayınlanmadan önce tüm gelen dalların rapor vermesini bekler.
• Belirleyici kontrol: Yürütme akışı, istem metninden çıkarılmak yerine beyan edilen kod yapıları tarafından yönetilir.

ADK'daki düğüm arketipleri

ADK iş akışları, birkaç özel düğüm türünden oluşur. Her arketip, grafikte belirli bir operasyonel rol oynar ve deterministik kod yürütmeyi üretken model muhakemesinden ayırır:

Düğüm Arketipi	Uygulama	Ardışık düzendeki rol
İşlev düğümü	Event döndüren Python işlevi	Belirleyici mantığı, veri almayı ve durum mutasyonlarını yürütür.
Birleştirme düğümü	Yerleşik JoinNode örneği	Eşzamanlı dalları toplu bir sözlükte senkronize eder.
Agent node (Aracı düğümü)	Agent, single_turn modunda çalışıyor	Talimatları yukarı akış girişine göre değerlendirir ve doğrulanmış veriler yayınlar.
Router node (Yönlendirici düğümü)	route etiketiyle Event döndüren işlev	Aşağı akış yürütme dallarını seçmek için koşullu mantığı değerlendirir.
İnsan girişi düğümü	İşlev verimi RequestInput	Harici bir kullanıcı yanıtı gelene kadar yürütme durumunu askıya alır.

root_agent = Workflow(
    name="stage1_fanout",
    description="2 real readers -> join -> one research dict",
    edges=[...])

Bu yapılandırmada root_agent, bağımsız bir Agent yerine Workflow örneğidir. ADK, iş akışlarını birinci sınıf aracı olarak ele alır. Bu sayede, tüm grafiğin birleşik bir uygulama olarak yüklenmesine, sunulmasına ve incelenmesine olanak tanır. name, uygulamayı ADK Web'e kaydederken edges listesi, uygulamanın yürütme topolojisini tanımlar.

Paralel araştırma fan-out'u (4B)

Workbench'te Paralel araştırma dağıtımı (4B)'na ilerleyin. stage1_fanout/agent.py uygulamasını açın.

İşlev düğümleri ve senkronizasyon engelleri

Araştırma aşamasında agent/graph.py'dan içe aktarılan iki işlev düğümü kullanılır:

• scan_trends: Puanlanmış on platform trendini içeren Event(output={"trends": [...]}) değerini döndürür.
• read_backlog: İlk çalıştırma istemiyle birlikte on beş kanal birikimi fikri içeren Event(output={"backlog": [...], "idea": "..."}) döndürür.

Her işlev node_input (önceki düğümün çıkışı) değerini kabul eder ve Event değerini döndürür.

JoinNode, senkronizasyon engeli olarak işlev görür: Her gelen zincir bir etkinlik sunana kadar duraklatır, ardından tüm dal sonuçlarını düğüm adına ({"scan_trends": {...}, "read_backlog": {...}}) göre anahtarlanmış bir sözlükte toplar.

Pratik düzenleme: birleştirme ve paralel kenarları tanımlama

stage1_fanout/agent.py içinde JoinNode öğesini oluşturun ve START ile başlayarak iki paralel zinciri bağlayın:

join_research = JoinNode(name="join_research")

    edges=[(START, scan_trends, join_research),
           (START, read_backlog, join_research)])

Değişikliklerinizi kaydedin. Çalışma tezgahı doğrulayıcısı, birleştirme ve kenarların kablolu olduğunu onaylar. Run Stage 1'i kullanarak veya yerleştirilmiş ADK Web arayüzü üzerinden aşamayı çalıştırın.

Sizi neler bekliyor ve neden?

• Eşzamanlı okuyucu yürütme: Yürütme grafiğinde scan_trends ve read_backlog aynı anda yürütülür.
  • Neden: Her iki zincir de START konumunda başlıyor. ADK motoru, bağımsız dalları eşzamanlı olarak planlar.
• Toplu sözlük çıkışı: İş akışı join_research konumunda tamamlanır ve her iki okuyucu için girişler içeren bir sözlük oluşturur.
  • Nedeni: JoinNode, sonraki düğümlerin yürütülmesine izin vermeden önce verilerin eksiksiz şekilde yakalanmasını sağlar.

Aracı düğümleri (4C)

Workbench'te Agent nodes (4C)'a (Aracı düğümleri (4C)) gidin. stage2_direction/agent.py uygulamasını açın.

Çalışma modları ve yapılandırılmış şemalar

Workflow içine yerleştirildiğinde Agent, varsayılan olarak single_turn modunda çalışır:

• Önceki düğümün çıkışını bağlam girişi olarak alır.
• Sohbet etmeden tek bir çıkarım çağrısı yürütür.
• Yapılandırılmış verileri bir sonraki düğüme aktarır.

output_schema=Directions atanarak aracı, model çıkışında Pydantic doğrulamasını zorunlu kılar. Aşağı akış grafiği, yapılandırılmamış metin yerine türü belirlenmiş nesneler alır:

class Direction(BaseModel):
    title: str           # <=60 chars, filmable, characterful
    angle: str           # the twist, one line
    hook: str = ""       # 2-4 words, the video's sticker line
    evidence: list[Evidence]


class Directions(BaseModel):
    candidates: list[Direction]   # exactly 4

PROPOSE_INSTRUCTION, modele hem trendlerden hem de birikimden kanıtlar göstererek dört aday önermesini söyler. 1-3 numaralı adaylar, uygulanabilir kanal konseptleri sunuyor. 4. Aday, bir sonraki adımda güvenlik kapısını test etmek için politikayı ihlal eden bir kavramı kasıtlı olarak tanıtıyor.

Pratik düzenleme: Ajan düğümünü tanımlama ve birleştirme işlemini zincirleme

stage2_direction/agent.py bölümünde propose_directions öğesini yapılandırın ve iş akışı kenarlarını genişletin:

propose_directions = Agent(
    name="propose_directions",
    model=config.MODEL,
    instruction=PROPOSE_INSTRUCTION,
    output_schema=Directions)

    edges=[(START, scan_trends, join_research),
           (START, read_backlog, join_research),
           (join_research, propose_directions, direction_gate)])

Sizi neler bekliyor ve neden?

• Doğrudan sözlük tüketimi: propose_directions, join_research tarafından yayınlanan JSON yükünü manuel biçimlendirme olmadan tüketir.
• Türlendirilmiş aday çıkışı: Ajan, dört ayrı aday içeren doğrulanmış bir Directions nesnesi oluşturur. Aşağı akış düğümleri, alanları dize ayrıştırması olmadan özellik adına (candidate.title) göre okur.

Sürecin parçası olan insan (4D)

Workbench'te Human-in-the-loop (4D)'ye (İnsan müdahalesi gerektiren) ilerleyin. agent/graph.py uygulamasını açın.

İstem talimatları ve deterministik askıya alma

Maliyetli olan veya içerik yayınlayan üretim iş akışları, kritik karar noktalarında insan gözetimi gerektirir. Tek bir istemde, onay istekleri, kullanıcının modeli kolayca atlamaya yönlendirebileceği tavsiye niteliğindeki talimatlardır. ADK iş akışında, yürütme motoru tarafından insan onayı zorunlu kılınır: Grafik, belirlenmiş bir düğümde durur ve harici, şema doğrulanmış giriş alana kadar ilerleyemez:

• Verim RequestInput, iş akışı yürütmesini hemen askıya alır.
• ADK, oturum deposunda açık bir kesme çağrısı kaydeder ve benzersiz bir interrupt_id yayınlar.
• Yürütme işlemi, jeton veya sunucu iş parçacığı tüketmeden durur.
• Grafik yürütme işlemi yalnızca şemaya ve kesme kimliğine uygun geçerli bir function_response gönderildiğinde devam eder.

Uygulamalı düzenleme: RequestInput ile yürütmeyi askıya alma

agent/graph.py içinde, askıya alma çağrısını direction_gate içine uygulayın:

    yield RequestInput(
        message="Pick tonight's direction: 1, 2, 3 or 4.",
        response_schema={
            "type": "object",
            "properties": {
                "pick": {"type": "string", "enum": ["1", "2", "3", "4"]}}},
        payload={"candidates": cands})

RequestInput üç özelliği yapılandırır:

• message: Kullanıcıya gösterilen yorum istemi.
• response_schema: Ön uç tarafından giriş formu olarak oluşturulan ve gönderildiğinde ADK tarafından doğrulanan bir JSON şeması.
• payload: İstemle birlikte paketlenmiş meta veriler (dört aday), istemci arayüzlerinin oturum durumu sorgulanmadan yorum kartlarını oluşturmasını sağlar.

Sizi neler bekliyor ve neden?

• İş akışı, direction_gate'te durur: ADK Web'de veya workbench arayüzünde çalıştırma işlemi duraklatılır ve etkileşimli bir aday seçimi formu gösterilir.
  • Nedeni: Motor, RequestInput ile karşılaştı ve yürütme durumunu runs/sessions.db olarak kalıcı hale getirdi.
• Devam ettirme için yapılandırılmış giriş gerekir: Rastgele sohbet metni göndermek grafiği ilerletmez. Bir seçeneği (1, 2, 3 veya 4) belirlediğinizde response_schema koşulunu karşılayan ve yürütmeye devam eden bir function_response yazılır.

5. Durum ve Yönlendirici

VibeStudio Workbench'te Adım 5 · Durum ve Yönlendirici bölümündeki (5A) ile (5C) arasındaki kısımlara gidin.

Kullanıcı seçimlerini oturum durumunda kalıcı hale getirecek, kanal güvenlik politikalarını deterministik yönlendirici düğümleri kullanarak zorunlu kılacak ve video senaryoları oluşturmadan önce politika ihlallerini otomatik olarak düzeltecek yinelemeli bir görev aracısı oluşturacaksınız.

İş Akışı Durumu (5A)

Workbench'te Workflow State (5A)'ya (İş Akışı Durumu) gidin.

Oturum durumu ve düğüm çıkışı

ADK iş akışında veriler, grafikte iki farklı mekanizma aracılığıyla hareket eder:

• Düğüm çıkışı (Event(output=...)): Veriler, uç listesinde tanımlanan doğrudan aşağı akış tüketicilerine yönlendirilir.
• Oturum durumu (Event(state=...)): Yürütme yaşam döngüsündeki sonraki düğümlerin erişebileceği paylaşılan bir anahtar/değer sözlüğü.

Kullanıcı direction_gate konumunda bir aday seçtiğinde seçim, sayısal dizin ({"pick": "2"}) olarak gelir. Aşağı akış düğümlerinin, başlık, anlatı açısı ve ilgi çekici cümle gibi yönlendirme nesnesinin tamamına ihtiyacı vardır. Ayrıntılı meta verileri her ara düğüm yükünden geçirmek yerine, persist_direction, çözümlenen adayı paylaşılan oturum durumuna yazar.

Düğümlerin tüm oturum durumu sözlüğünü iletmesi gerekmez. Bir düğüm Event(state=...) verdiğinde yalnızca yeni veya güncellenmiş anahtar/değer çiftlerini sağlar. ADK, bu güncellemeleri oturum deposunda otomatik olarak birleştirir:

    yield Event(state={"direction": chosen["title"], "angle": chosen.get("angle", ""),
                       "hook": hook, "user:prefs": {"last_direction": chosen["title"]}})

Bu işlem, Event kontrolünü Workflow çalışma zamanına bırakır. Bu çalışma zamanı, yeni değerleri runs/sessions.db içindeki oturum günlüğüne kalıcı olarak yazar.

Parametre bağlama

ADK işlev düğümleri, oturum durumunu parametre incelemesi aracılığıyla otomatik olarak okur. Bir işlev imzası, mevcut bir durum anahtarıyla eşleşen bir parametre adı bildiriyorsa ADK bu anahtarı durumdan çıkarır ve doğrudan geçirir:

def persist_direction(node_input, candidates: list = []):
    ni = node_input if isinstance(node_input, dict) else {}
    raw = ni.get("pick")
    pick = str(raw).strip() if raw is not None else ""
    if candidates:
        i = int(pick) - 1 if pick.isdigit() else 0
        chosen = candidates[max(0, min(len(candidates) - 1, i))]
    else:
        chosen = {"title": "untitled", "angle": "", "evidence": []}
    hook = chosen.get("hook") or " ".join(chosen["title"].split()[:4])

Burada, candidates değeri direction_gate tarafından oturum durumuna yazılmıştır. ADK, açık sözlük aramaları gerektirmeden doğrudan persist_direction(node_input, candidates: list = []) içine bağlar.

user: ile başlayan anahtarlar, kullanıcı düzeyindeki depolamada oturumlar arasında kalıcı olur. Böylece, sonraki iş akışı çalıştırmaları içerik üreticinin tercihlerine erişebilir.

Pratik düzenleme: durumu kalıcı hale getirme ve düğümü bağlama

1. agent/graph.py içinde, persist_direction içinde, TODO: PERSIST_STATE satırını durum etkinliği getirisiyle değiştirin:

    yield Event(state={"direction": chosen["title"], "angle": chosen.get("angle", ""),
                       "hook": hook, "user:prefs": {"last_direction": chosen["title"]}})

2. stage3_router/agent.py içinde, edges listesindeki üçüncü zincire persist_direction öğesini ekleyin:

           (join_research, propose_directions, direction_gate,
            persist_direction)

Dosyalarınızı kaydedin. Çalışma alanında, hem state write in place hem de persist_direction in the chain simgelerinin yeşil onay işareti gösterdiğini doğrulayın.

Yönlendirici düğümü (5B)

Workbench'te Yönlendirici düğümü (5B)'ne gidin.

Belirleyici politika yönlendirmesi

Yönlendirici, yukarı akış çıkışını değerlendiren ve yürütmeyi koşullu grafik dalları boyunca yönlendiren özel bir işlev düğümüdür. Yönlendirici, üretken ajanlardan farklı olarak LLM çağrıları yapmadan deterministik mantık yürütür.

Bir yönlendirici, route etiketi belirten bir Event döndürür:

def length_check(node_input):
    too_long = len(node_input.get("title", "")) > 60
    return Event(output=node_input, route="TRIM" if too_long else "PASS")

İş akışı tanımında, sözlük olarak tanımlanan bir kenar hedefi, rota adlarını hedef düğümlere eşler:

    (length_check, {"TRIM": shorten, "PASS": scripter}),

İş akışı yönlendiricisi, policy_check agent/policy_words.txt içindeki yasaklanmış ifadeleri okur ve seçilen yönün başlığı ile açısı için tam kelime eşleştirme işlemi gerçekleştirir:

    return Event(output=node_input, route="BLOCK" if bad else "OK")

Politikayı sabit kodlanmış talimatlar yerine veri olarak depolamak, iş akışı grafiğini değiştirmeden güncellemeler yapmanızı sağlar. Metin dosyasını güncellemek, sonraki çalıştırmalara hemen uygulanır. Değerlendirme, belirleyici bir normal ifade eşleştirme işlemi olduğundan üretken komut dosyası oluşturma başlamadan önce sıfır jeton maliyetiyle milisaniyeler içinde yürütülür.

Hedefler: Scripter ve Karantina

Yönlendirici, trafiği iki aşağı akış düğümünden birine yönlendirir:

• scripter: Onaylanan yönlendirmeyi, Script Pydantic şemasına uygun yapılandırılmış bir üretim senaryosuna dönüştüren single_turn temsilci düğümü:

scripter = Agent(
    name="scripter",
    model=config.MODEL,
    instruction=SCRIPT_INSTRUCTION,
    output_schema=Script)

• quarantine: Başlangıçta işaretlenen yönlendirmeleri durduran bir yer tutucu işlevdir. Bir sonraki bölümde bağımsız bir düzeltme aracısı tarafından değiştirilir.

Uygulamalı düzenleme: politika kontrolünü yönlendirme

1. agent/graph.py bölümündeki policy_check içinde dönüş ifadesini tamamlayın:

    return Event(output=node_input, route="BLOCK" if bad else "OK")

2. stage3_router/agent.py içinde, edges öğesini policy_check rotasına yönlendirecek şekilde güncelleyin ve karantina dalını scripter ile yeniden birleştirin:

           (join_research, propose_directions, direction_gate,
            persist_direction, policy_check),
           (policy_check, {"OK": scripter, "BLOCK": quarantine}),
           (quarantine, scripter)])

Dosyalarınızı kaydedin. Çalışma tezgahında, yönlendirici uç eşlemelerinin doğrulandığını onaylayın.

Ajan modları ve görev düğümü (5C)

Workbench'te Agent modes and the task node (5C) [Aracı modları ve görev düğümü (5C)] bölümüne gidin.

Ajan yürütme modları

ADK Agent örnekleri, belirli ardışık düzen gereksinimlerine göre uyarlanmış üç yürütme modunu destekler:

Mod	Yürütme yaşam döngüsü	Ardışık düzendeki rol
chat	Çok adımlı etkileşimli döngü. Model, araçların ne zaman çağrılacağını, girişin ne zaman isteneceği ve dönüşün ne zaman sonlandırılacağını belirler.	Etkileşimli bir insan kullanıcıyla karşılaşan kök aracılar.
single_turn	Tek model çıkarımı çağrısı. Önceki düğüm girişini kabul eder ve yapılandırılmış bir şema nesnesi yayınlar.	Sıralı grafik dönüşümleri (propose_directions, scripter).
task	Araç yürütme içeren bağımsız döngü. Ajan, yerleşik finish_task aracını çağırana kadar tekrarlama yapar.	Çok adımlı düzeltme ve inceleme (quarantine).

Bağımsız politika düzeltme

İşaretlenmiş bir talimatın yeniden yazılması için task modu gerekir. Bunun nedeni, düzeltme yinelemelerinin sayısının değişken olmasıdır. Ajan, işaretlenen talimatı alır, ihlalleri tespit etmek için find_policy_hits işlevini çağırır, suggest_replacement aracılığıyla onaylanmış alternatifler ister, talimatı yeniden yazar ve devam etmeden önce temizliği doğrular.

Her iki araç da agent/cleanup_tools.py içinde türü belirtilmiş imzalar ve doküman dizeleriyle tanımlanır:

def find_policy_hits(text: str) -> dict:
    """Which refused words appear in `text`. Matches whole words and phrases
    from agent/policy_words.txt, case-insensitive.

    Returns {"hits": [...], "clean": bool}. clean is true when hits is empty.
    """


def suggest_replacement(word: str) -> dict:
    """The channel's approved stand-in for a refused word, read from
    agent/policy_replacements.txt.

    Returns {"word", "replacement", "listed"}. When the word has no entry,
    listed is false and replacement is a hint to pick a gentle synonym.
    """

Uygulamalı düzenleme: Karantina görev aracısını birleştirme

stage3_router/agent.py içinde, yer tutucu quarantine işlevini görev aracısı tanımıyla değiştirin:

quarantine = Agent(
    name="quarantine",
    model=config.MODEL,
    instruction=QUARANTINE_INSTRUCTION,
    mode="task",
    tools=[find_policy_hits, suggest_replacement],
    output_schema=CleanedDirection,
)

Görev modu, ajana araçlar sağlar ve finish_task çağrısı yaparak yürütmeyi sonlandırır. mode="task" yapılandırıldığında ADK, finish_task sağlar ve parametrelerini output_schema öğesinden türetir. Böylece, düğümün, komut dosyası oluşturucu düğümün giriş şemasıyla eşleşen türü belirlenmiş bir CleanedDirection nesnesi oluşturması sağlanır.

Sizi neler bekliyor ve neden?

ADK Web veya VibeStudio Workbench'te her iki yürütme yolunu da test edin:

• Onaylanan rota (1., 2. veya 3. aday):
  • Onaylanmış bir aday rotayı seçtiğinizde policy_check doğrudan scripter'ye (route="OK") yönlendirilirsiniz.
  • Senaryo yazarı, Script şemasına uygun 3 sahneli bir yapım senaryosu oluşturur.
• Karantina düzeltme yolu (4. Aday):
  • 4. aday, işaretlenmiş kelimeler ("tıklama tuzağı", "viral hack") içeriyor.
  • quarantine konumuna kadar policy_check rota (route="BLOCK").
  • Oturum izinde, her ihlal için quarantine işlevinin find_policy_hits işlevini, suggest_replacement işlevini ve finish_task işlevini çağırdığını, başlığı yeniden yazdığını gözlemleyin.
  • Yürütme, scripter ile yeniden birleşerek temizlenmiş yönergeden bir komut dosyası oluşturur.

Yönlendiriciler ve yedekler. Geliştirme kullanıcı arayüzü, yedek kenarı olmayan bir yönlendiriciyi işaretler. policy_check, OK veya BLOCK dışında bir rota döndürseydi koşunun hedefi olmazdı. DEFAULT_ROUTE: quarantine öğesini kenar sözlüğüne eklemek bu durumu kapsar. DEFAULT_ROUTE öğesini google.adk.workflow konumundan içe aktarın.

6. Memory Bank

VibeStudio Workbench'te 6. Adım: Hafıza Bankası'na gidin. (6A) ve (6B) bölümlerini inceleyin.

İş akışı şu anda oturumlar arasında bellek olmadan çalışmaktadır. Her yürütme, içerik üreticinin daha önce ne seçtiğini veya hangi türleri tercih ettiğini bilmeden sıfırdan başlar. Bu adımda, Vertex AI Agent Engine Memory Bank'i bağlayarak içerik üreticilerin tercihlerini çalıştırmalar arasında depolayıp alabilirsiniz.

En önemlisi, bellek, işlem hattı düğümleri yerine aracı yaşam döngüsü geri çağırmaları aracılığıyla entegre edilir. Bellek çıkarma ve alma işlemleri, ara veri aşamaları yerine tek tek aracılara hizmet ettiğinden geri çağırma eklemek temiz ve ayrılmış bir grafik topolojisini korur.

Bellek Bankası (6A)

Çalışma alanında Bellek Bankası (6A)'ya gidin.

Yönetilen kullanıcı düzeyindeki hafıza

Memory Bank, uzun vadeli kullanıcı belleği için yönetilen bir hizmettir. Bir kişiyle ilgili bilgileri, tanımlanmış bir kapsam altında düzenler. Bu kapsam, uygulama adı ve kullanıcı kimliğiyle tanımlanır:

SCOPE = {"app_name": config.APP, "user_id": config.USER}
TOPICS = {
    "CREATOR_TASTE": "Which video directions this creator picks and passes on, "
                     "and how that preference changes over time.",
    "CHANNEL_RULES": "Standing instructions the creator states for every video "
                     "(style, subjects to avoid, format rules).",
}

Özel bellek konuları, bankanın kaydettiği bilgilerin sınırlarını tanımlar:

• Konu çıkarma: memories.generate üzerinden yeni görüşme metni gönderildiğinde hizmet, her konu açıklamasına karşı bir çıkarma modeli uygular. Bir konuyla eşleşmeyen metinler anı oluşturmaz.
• Birleştirme ve tekilleştirme: Hizmet, yeni çıkarılan bilgileri yerleştirmelere dönüştürür ve bunları kapsamdaki mevcut anılarla karşılaştırır. Bir gözlem mevcut bir anıyla eşleştiğinde hizmet, bu anıyı günceller. Hizmet, yeni bilgileri temsil ettiğinde yeni bir giriş oluşturur. Bu birleştirme süreci, bir konuyla ilgili birden fazla oturumun gereksiz girişler oluşturmak yerine tutarlı bir özet halinde birleştirilmesini sağlar.
• Alma: Kullanıcı kapsamıyla memories.retrieve çağrıldığında, en eskiden başlayarak sıralanmış şekilde depolanan bilgiler döndürülür.

Her iki işlem de agent/platform/memory.py içinde uygulanır. Sağlanan banka kaynağının adı, runs/memorybank.json içinde yerel olarak önbelleğe alınır.

Anı Bankası'nı ayarlama

Çalışma tezgahı kontrollerini kullanın veya terminalinizde CLI komutlarını çalıştırın:

1. Bankayı bağlayın ve temel hazırlığını yapın:

   python -m agent.platform.bank
   

   Agent Engine örneğini oluşturur ve CREATOR_TASTE ile CHANNEL_RULES konularını yapılandırır.
2. Geçmiş oturumları başlangıç noktası olarak kullanma:

   python -m agent.platform.bank load
   

   Dört tarihi içerik üretici oturumu yüklenir (stil kısıtlamaları olan iki hayvan teması, bir cihaz teması ve bir yakın tarihli fantezi teması).
3. Birleştirilmiş bilgileri inceleme:

   python -m agent.platform.bank list
   

   Çıkışı inceleyin. Anlatı transkriptlerinin nasıl yapılandırılmış ve birleştirilmiş gerçeklik ifadelerine dönüştürüldüğüne dikkat edin.

Geri aramalar (6 milyar)

Workbench'te Callbacks (6B)'e (Geri Arama İşlevleri) gidin. stage4_memory/agent.py uygulamasını açın.

ADK temsilcisinin yaşam döngüsü geri çağırma yöntemleri

Geri çağırma, Agent işlevine bağımsız değişken olarak iletilen bir işlevdir. ADK, önceden tanımlanmış yaşam döngüsü anlarında geri çağırma işlemlerini başlatarak etkin bağlamı iletir. Döndürme None normal yürütmeye devam eder; yedek nesne döndürme işlemi geçersiz kılar veya engeller.

ADK üç geri çağırma çifti sağlar:

Geri Arama Çifti	Çağrı Noktası	Alınan Parametreler	Döndürülen Değer Davranışı
before_agent_callback after_agent_callback	Tüm temsilci yanıtını kapsar.	CallbackContext (durum, oturum, çağırma)	Dönüş Content, temsilci yanıtının yerini alır; None normal şekilde devam eder.
before_model_callback after_model_callback	Her LLM çıkarım çağrısının etrafında	LlmRequest veya LlmResponse	Döndürülen LlmResponse, model çağrısını keser veya atlar; None devam eder.
before_tool_callback after_tool_callback	Her araç yürütme işleminin çevresinde	Araç tanımı, bağımsız değişkenler, sonuç	Bir sözlük döndürmek, araç çıkışını geçersiz kılar ve None devam eder.

Geri aramalar, iş akışı grafiğine gereksiz düğümler eklemeden bağlam yerleştirme, koruma sınırları, telemetri ve önbellek aramaları için temiz bir konum sağlar.

Pratik düzenleme: Kablo tesisatı geri çağırma ve geri aramaları hatırlama

1. stage4_memory/agent.py içinde before_model_callback=recall_taste eklemek için propose_directions uygulamasını güncelleyin:

    output_schema=Directions,
    before_model_callback=recall_taste)

recall_taste, Gemini olası talimatlar oluşturmadan hemen önce yürütülür. İçerik üreticinin geçmişini Memory Bank'ten alır, anıları en eskiden başlayarak biçimlendirir ve giden LlmRequest'ye ekler. İstem, modelin 1-3 arasındaki adayları kanal kurallarını katı sınırlamalar olarak ele alırken içerik üreticinin mevcut zevkine göre şekillendirmesini sağlar.

2. stage4_memory/agent.py içinde after_agent_callback=remember_pick eklemek için scripter uygulamasını güncelleyin:

    output_schema=Script,
    after_agent_callback=remember_pick)

remember_pick, scripter sırasını tamamladıktan sonra çalışır. Oturum durumundan seçilen yönü okur, içerik üreticinin kararını özetleyen kısa bir ifade sentezler ve memories.generate işlevini çağırarak Memory Bank'ı günceller.

Sizi neler bekliyor ve neden?

Geri arama ile zenginleştirilmiş iş akışını Workbench'te veya ADK Web'de test edin:

1. Boş istemle çalıştırma işlemi gerçekleştirme:
   • Oturum izinde, LlmRequest için propose_directions değerini inceleyin. İçerik üreticinin fantezi temaları ve kısa tempolarla ilgili tercihini ayrıntılı olarak açıklayan eklenmiş anı bağlamına dikkat edin.
   • Önerilen yönlendirmelere uyun: Trendler diğer konuları vurgulasa bile 1-3 numaralı adaylar, içerik üreticinin geçmiş tercihlerine uygundur.
2. direction_gate adresinde bir aday seçin.
3. scripter tamamlandıktan sonra Anı Bankası kayıtlarını inceleyin:

   python -m agent.platform.bank list
   

   Banka, önceki zevk kayıtlarıyla birleştirerek en son tercihi yansıtır.

7. RAG Engine

VibeStudio Workbench'te 7. Adım: RAG Motoru'nun (7A) ve (7B) bölümlerine gidin.

Yayınlanan videolar, izleyicilerden sürekli geri bildirim alır. agent/comments.md bölümünde, izleyicilerin övgülerini, sponsorlu ilerleme hızına yönelik eleştirilerini ve ses tercihlerini içeren 30 temsili yorum toplanır. Bu adımda, Vertex AI RAG Engine'i kullanarak bu yorumları dizine ekler ve semantik almayı araştırma fan-out'una bağlarsınız.

Dokümanlar üzerinden alma (7A)

Workbench'te RAG Engine (7A)'ya gidin.

Bellek Bankası ve RAG Motoru

Her iki araç da iş akışlarını harici verilere dayandırır ancak farklı mimari amaçlara hizmet eder:

Boyut	Memory Bank	RAG Engine
Birincil Kullanım Alanı	Uzun vadeli kullanıcı tercihleri ve operasyonel kurallar	Büyük doküman koleksiyonlarında anlamsal alma
Kapsam	Kapsamı, bağımsız kullanıcı kimlikleri ve uygulama adlarıyla sınırlıdır.	Tüm kullanıcılar arasında paylaşılan gövde kaynaklarıyla sınırlıdır.
Veri İşleme	Gerçek zamanlı ayıklama, yerleştirme ve anlamsal birleştirme	Belge parçalama, vektör yerleştirme ve en yakın komşu araması
Grafik Entegrasyonu	Aracı yaşam döngüsü geri çağırmaları (before_model_callback, after_agent_callback)	Araştırma fan-out'unda özel işlev düğümü (read_feedback)

Belge parçalama ve yerleştirmeler

RAG Engine, metni semantik pasajlara bölerek ve vektörlerini yönetilen bir veritabanında saklayarak dokümanları indeksler:

corpus = rag.create_corpus(
    display_name="vibestudio-feedback",
    description="Vibe Studio: what the audience wrote under the channel's past videos.",
    backend_config=rag.RagVectorDbConfig(
        rag_embedding_model_config=rag.RagEmbeddingModelConfig(
            vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
                publisher_model="publishers/google/models/text-embedding-005"))))

rag.upload_file(
    corpus_name=corpus.name, path="agent/comments.md", display_name="comments.md",
    transformation_config=rag.TransformationConfig(
        chunking_config=rag.ChunkingConfig(chunk_size=120, chunk_overlap=20)))

• Parça boyutu: 20 jetonluk çakışma ile 120 jeton olarak yapılandırılır. Bu sayede, her pasaj için iki ila üç yorum alınır. Böylece, her vektör, alakasız geri bildirimlerde anlamı sulandırmadan tutarlı bir duyguya karşılık gelir.
• Yerleştirme modeli: text-embedding-005, metni yüksek boyutlu vektörlere dönüştürür. Bir sorgu gönderildiğinde model, sorguyu vektöre dönüştürür ve semantik uzaklığa göre en yakın eşleşmeleri bulur. Çorapları koruyan küçük bir ejderha hakkındaki yorum, tam anahtar kelime çakışması gerektirmeden sihirli yaratıklarla ilgili bir istemle eşleşiyor.

RAG korpusunu ayarlama

Çalışma tezgahı düğmelerini veya terminal komutlarını kullanarak gövdeyi başlatın:

1. Derlemi oluşturun:

   python -m agent.platform.rag
   

   Yönetilen vektör veritabanını sağlar ve kaynak kimliğini runs/ragcorpus.json içine kaydeder.
2. Yorumları yükleme ve dizine ekleme: Parçalama yapılandırmasıyla agent/comments.md yükler ve dizine eklemenin tamamlanmasını bekler.
3. Corpus'a sorgu gönderme: Yorumlarla aynı kelimeleri içermeyen sorgularla benzerlik alma işlemini test edin (örneğin, ejderhalarla ilgili yorumları almak için "küçük sihirli yaratıklar" sorgusunu gönderin).

Alma düğümü (7B)

Çalışma alanında Üçüncü okuyucu (7B)'ye gidin. stage5_rag/agent.py uygulamasını açın.

Grafik düğümü olarak alma

Kitle geri bildirimi, iş akışında paylaşılan araştırma verilerini temsil eder. Kişisel içerik üretici belleğinin aksine, izleyici duyarlılığı, trendler ve birikmiş verilerle birlikte doğrudan join_research'ya aktarılır. Bu nedenle, bir işlev düğümü olarak uygulanır:

def read_feedback(node_input):
    """The third reader (step 7): what the audience wrote under past videos,
    the passages nearest to tonight's idea. Retrieval, not a model call."""
    from .platform import rag
    idea = idea_text(node_input)
    query = idea or "what viewers liked and what they complained about"
    try:
        hits = rag.retrieve(query)
    except Exception as e:
        print(f"  [rag] feedback unavailable ({str(e)[:80]})")
        return Event(output={"query": query, "feedback": [],
                             "note": "no corpus connected - run: python -m agent.platform.rag"})
    return Event(output={"query": query, "feedback": [h["text"] for h in hits]})

read_feedback, kullanıcının ilk fikrini ayıklar ve RAG Engine gövdesine karşı bir vektör sorgusu yürütür. Alınan yorumları Event(output=...) yükünde yayınlar.

Uygulamalı düzenleme: Üçüncü okuyucuyu dağıtıcıya bağlama

stage5_rag/agent.py içinde, edges öğesini güncelleyerek read_feedback öğesini join_research'e giren üçüncü bir paralel dal olarak ekleyin:

           (START, read_backlog, join_research),
           (START, read_feedback, join_research),

join_research, JoinNode olduğundan tüm gelen dalları senkronize eder ve birleştirilmiş paketi aşağı akışa geçirmeden önce scan_trends, read_backlog ve read_feedback'in tüm etkinlikleri yayınlamasını bekler.

Sizi neler bekliyor ve neden?

İş akışını Workbench'te çalıştırma:

1. Fikir istemi gönderin (ör. "mutfak tezgahını koruyan minyatür bir ejderha").
2. Yürütme izinde, üç okuyucu düğümünün de eşzamanlı olarak yürütüldüğünü doğrulayın.
3. join_research öğesini inceleyin: Çıkış sözlüğü artık trends, backlog ve feedback öğelerini içeriyor.
4. propose_directions simgesinden oluşturulan adayları inceleyin: Model, izleyici yorumlarını önerilerine dahil eder ve kanıt alanlarında kitle duyarlılığına referans verir.
5. RAG alımının deterministik (aynı sorgular aynı yorum pasajlarını döndürür) olduğunu, üretken öneri düğümünün ise yaratıcı varyasyonlar ürettiğini unutmayın.

8. Veo ile asenkron video üretimi

VibeStudio Workbench'te 8. Adım: Video bölümünün (8A) ve (8B) kısımlarına gidin.

Google Veo ile yüksek çözünürlüklü video oluşturmak için her oluşturma işlemi birkaç dakika sürer. Bu dönemde grafik yürütmenin engellenmesi, işlem kaynaklarının boşa harcanmasına, iş parçacığı havuzlarının kilitlenmesine ve çalıştırmanın HTTP bağlantı kesintilerine maruz kalmasına neden olur. Bu adımda, ADK'nın LongRunningFunctionTool özelliğini kullanarak video oluşturmayı eşzamansız hale getiriyorsunuz.

Uzun süreli araçlar (8A)

Workbench'te Uzun süren bir araç (8A)'ya gidin. stage6_video/agent.py ve agent/deliver.py uygulamalarını açın.

Eşzamanlı araçlar ve uzun süren araçlar

Standart ADK işlevi araçları, bir ajan dönüşü içinde eşzamanlı olarak yürütülür: Model, aracı çağırır, dönüş yükünü bekler ve sonucu devam eden dönüşe dahil eder.

Video oluşturma işlemi tek bir dönüşte tamamlanamaz. Bunun yerine, render_submit, oluşturma işini başlatır ve durumu "pending" olan bir işlem makbuzunu hemen döndürür:

def render_submit(prompt: str) -> dict:
    """Submit one Veo render of `prompt`. Returns at once with a pending
    receipt; the clip is delivered later, to this call, by id."""
    receipt = videogen.start(f"{prompt} {videogen.NO_TEXT}")
    return {"status": "pending", "operation": receipt["operation"], "prompt": receipt["prompt"]}

LongRunningFunctionTool ile sarmalandığında ADK, "pending" durumunu yakalar. Temsilcinin sırası sona erer, iş akışı düğümde askıya alınır ve bekleyen çağrı meta verileri (çağrı kimliği ve makbuz dahil) runs/sessions.db içinde kaydedilir. Yürütme işlemi, etkin ağ bağlantılarını veya çalışan iş parçacıklarını korumadan temiz bir şekilde çıkar.

Pratik düzenleme: Oluşturma aracını sarmalama

stage6_video/agent.py içinde render_desk'i render_submit'yi LongRunningFunctionTool içine sarmalayacak şekilde güncelleyin:

    tools=[LongRunningFunctionTool(render_submit)])

Arama kimliğine göre devam ettirme

Evrensel devam ettirme kalıbı

ADK, hem insanlar hem de harici araçlar için iş akışlarını askıya alma ve devam ettirme konusunda aynı mekanizmayı kullanır:

Askıya Alma Tetikleyicisi	Construct'ı başlatma	Kayıtlı Askıya Alma Durumu	Devam Ettirme Etkinliği
İnsan Kararı	yield RequestInput(...)	Giriş istemini oturum deposunda açma	FunctionResponse askıya alma görüşmesi kimliğini içeriyorsa
Uzun Süreli Araç	LongRunningFunctionTool(...) geri dönüyor pending	Oturum deposunda araç çağrısını açma	FunctionResponse askıya alma görüşmesi kimliğini içeriyorsa

Her iki senaryoda da iş akışı tamamen durur ve yalnızca eşleşen bir FunctionResponse içeren bir etkinlik harici bir kaynaktan (kullanıcı arayüzü, webhook veya arka plan çalışanı) geldiğinde devam eder.

Pratik düzenleme: Teslimat yanıtını tamamlama

agent/deliver.py içinde, devam ettirme FunctionResponse bölümünü oluşturun:

    part = Part(function_response=FunctionResponse(
        id=row["call_id"], name=row["name"], response=response))

Teslimat arka plan programı, video dosyası oluşturulana kadar Veo'yu yoklar, ardından bu FunctionResponse öğesini oturuma gönderir. ADK, çağrı kimliğiyle eşleşir ve iş akışına doğrudan bir sonraki düğümden devam eder. Tamamlanan düğümler yeniden yürütülmez ve aracı başka bir üretken adım atmaz.

.env içinde STUDIO_REAL_VIDEO=0 ayarını belirlemek sahte oluşturmayı etkinleştirir: start anında bir test makbuzu döndürür ve check, faturalandırılabilir Veo API çağrıları yapmadan beş saniye içinde tamamlanmayı simüle eder.

Ardışık düzen entegrasyonu (8B)

Çalışma alanında render_desk in the graph (8B) öğesine gidin. stage6_video/agent.py uygulamasını açın.

İşlem hattındaki terminal düğümü store_video'dır. Tamamlanan oluşturma bilgilerini runs/state.json konumundan (teslimat sürecinin kaydedildiği yer) okur ve video URL'sini ve oluşturma durumunu paylaşılan oturum durumuna işler.

Pratik düzenleme: Video işlem hattının tamamını bağlama

stage6_video/agent.py içinde, render_desk ve store_video eklemek için edges öğesini güncelleyin:

           (quarantine, scripter),
           (scripter, render_desk, store_video)])

Sizi neler bekliyor ve neden?

Eşzamansız oluşturma akışını Workbench'te test edin:

1. Aday seçimi ve senaryo oluşturma yoluyla iş akışını yürütün.
2. render_desk konumunda, aracının render_submit'yi çağırdığını gözlemleyin.
3. İş akışı hemen askıya alınır. Çalışma tezgahında veya ADK Web'de bekleyen durumu gözlemleyin: Oturum, açık görüşme kimliğini tutar ve arka plan işlemleri kaynak tüketmez.
4. Workbench konsolunu veya terminalinizi kullanarak teslimat arka plan programını çalıştırın:

   python -m agent.deliver
   

   Teslimat süreci, video hazır olana kadar Veo'yu izler ve ardından devam ettirme etkinliğini gönderir.
5. ADK Web'de oturumu yenileyin: Yürütme store_video konumunda devam eder, video URL'si oturum durumuna işlenir ve iş akışı tamamlanır.

9. Cloud Run'a dağıt

VibeStudio Workbench'te 9. Adım: Dağıt'a gidin.

Ardışık düzenin her bileşenini özel korumalı alanlarda geliştirip doğruladınız. Bu adımda, eksiksiz üretim ardışık düzenini bir araya getirip Google Cloud Run'a dağıtırsınız.

ADK Runner

Geliştirme aşamasında, adk web grafiği düzenledi. Üretimde uygulama, ADK'nın Runner sınıfını kullanarak iş akışını barındırır:

self._svc = DatabaseSessionService(db_url=config.DB_URL)
self._runner = Runner(app_name=config.APP, agent=wf, session_service=self._svc)

async for ev in self._runner.run_async(user_id=config.USER, session_id=run_id, new_message=message):
    self._absorb(ev)    # fold the ADK event into the run state, publish one app event

# the gate's answer and the render's delivery are the same call, with a function_response part
part = Part(function_response=FunctionResponse(id=call_id, name=name, response=response))

• run_async: İş akışı yürütmeyi yönlendirir, düğümler yürütüldükçe etkinlikleri sırayla oluşturur ve oturum hizmetinde güncellemeleri kalıcı hale getirir.
• Birleştirilmiş devam ettirme: Hem direction_gate konumundaki kullanıcı kararları hem de Veo'dan tamamlanan video yayınları, run_async'ye gönderilen aynı FunctionResponse nesneleri aracılığıyla yürütülmeye devam eder.

Üretim uygulaması mimarisi

vibestudio/ içindeki üretim uygulaması, tüm işlem hattını entegre eder:

vibestudio/
  server/
    main.py                 FastAPI: application server, REST routes, static assets
    api.py                  REST API endpoints: run, pick, publish, backlog, profile, history
    runner.py               Runner orchestration over the workflow, background render poller
    platform/               Event bus (SSE stream), file storage, publishing, telemetry
    agent/                  Production agent package, verified by checks/verify_app.py
      graph.py              The complete workflow graph and node definitions
      desk.py               render_desk and render_submit wrapped with LongRunningFunctionTool
      schemas.py            Pydantic schemas: Directions, CleanedDirection, Script
      cleanup_tools.py      Deterministic policy tools: find_policy_hits, suggest_replacement
      platform/             Memory Bank, RAG Engine, and Veo integrations
  web/                      Production React user interface
  Dockerfile · deploy.py · run.sh

• Tek etkinlik akışı: FastAPI arka ucu, etkinlikleri tek bir sunucu tarafından gönderilen etkinlikler (SSE) akışında yayınlar. React ön ucu, grafik ilerlemesini anlık olarak görselleştirir ve durumu kaybetmeden geç bağlantıları işler.
• Ayrılmış yürütme: Uygulama, etkinlik döngüsünü yönetir. İş akışı grafiği, ön uç arayüzünden bağımsız olarak tamamen yürütme mantığına odaklanır.

agent/graph.py bölümündeki eksiksiz iş akışı kenar listesi, bu codelab boyunca oluşturulan her mimari kalıbı birleştirir:

        (START, scan_trends, join_research),
        (START, read_backlog, join_research),
        (START, read_feedback, join_research),
        (join_research, propose_directions, direction_gate,
         persist_direction, policy_check),
        (policy_check, {"OK": scripter, "BLOCK": quarantine}),
        (quarantine, scripter),
        (scripter, render_desk, store_video),

Cloud Run'a dağıtma

Google Cloud Run, otomatik ölçeklendirme, istek yönlendirme ve entegre container derlemeleriyle sunucusuz barındırma sağlar:

gcloud run deploy vibestudio --source vibestudio \
  --project $GOOGLE_CLOUD_PROJECT --region us-central1 \
  --labels dev-tutorial-codelab=vibetube --allow-unauthenticated \
  --memory 2Gi --cpu 2 --timeout 3600 --concurrency 40 \
  --max-instances 1 --min-instances 1 --session-affinity \
  --set-env-vars GOOGLE_CLOUD_PROJECT=...,STUDIO_VERTEX=1,STUDIO_MEMORY_BANK=...,STUDIO_RAG_CORPUS=...,VIBETUBE_URL=...,VIBETUBE_EVENT=...,VIBETUBE_NAME=...,VIBETUBE_PROJECT=...

• Container derleme: gcloud run deploy --source vibestudio/ dizinini paketler, Cloud Build'i kullanarak container görüntüsünü oluşturur ve hizmeti tek bir işlemde dağıtır.
• Oturum benzeşimi: Aynı kullanıcının isteklerini aynı kapsayıcı örneğine yönlendirerek yerel oturum durumunu yinelemeli adımlar boyunca korur.
• Gözlemlenebilirlik: Cloud Trace entegrasyonu, her düğüm, LLM çağrısı ve araç yürütme için dağıtılmış aralıkları kaydeder. Bu aralıklara Google Cloud Console'daki Trace Explorer bölümünden erişilebilir.

Dağıtım komut dosyasını yürütmek için tezgahtaki Dağıt düğmesini tıklayın. Derleme tamamlandığında terminalde canlı hizmet URL'si gösterilir.

10. Özet

Tamamlanan mimariyi incelemek için VibeStudio Workbench'te 10. Adım: Özet'e gidin.

Adım	Mimari ve Kavramlar	Uygulama modeli
Tek bir istem	Tek istem, işlev araçları, sıralı sohbet döngüsü	Agent(tools=[...]), function_call / function_response
Ajan tabanlı iş akışının temel özellikleri	Grafik iş akışı, paralel araştırma, şema çıktıları, insan kontrolü	Workflow, START, JoinNode, output_schema, RequestInput
Durum ve Yönlendirici	Paylaşılan oturum durumu, parametre bağlama, deterministik yönlendirme, görev aracısı	Event(state=...), Event(route=...), mode="task", finish_task
Memory Bank	Kullanıcı düzeyinde uzun süreli hafıza, anlamsal birleştirme, yaşam döngüsü kancaları	memories.generate / retrieve, before_model_callback, after_agent_callback
RAG Engine	Kitle yorumları ve semantik yerleştirmeler üzerinden doküman alma	rag.create_corpus, RagEmbeddingModelConfig, read_feedback düğümü
Veo ile asenkron video üretimi	Uzun süren araçlar, bekleyen makbuzlar, harici teslimat arka plan programı	LongRunningFunctionTool, FunctionResponse(id=...) devam ettirme
Cloud Run'a dağıt	Programatik düzenleme, Server-Sent Events, sunucusuz kapsayıcı	Runner(agent=wf), run_async, Cloud Run dağıtımı

Temel mimari ilkeler

1. Beklemek yerine askıya alma: İş akışları, kullanıcı girişi (RequestInput) veya uzun süren işlemler (LongRunningFunctionTool) için sorunsuz bir şekilde duraklatılır. İşlemler, iş parçacıklarında veya ağ soketlerinde boşta beklemez.
2. Evrensel devam ettirme: Her askıya alma işlemi, askıya alınan düğümün çağrı kimliğini taşıyan tek bir function_response ile aynı mekanizma üzerinden devam ettirilir.
3. Ayrılmış durum yönetimi: Düğümler, ayrıntılı ve sıkıca bağlı ara yükler yerine adlandırılmış oturum durumu anahtarları ve parametre bağlama yoluyla veri paylaşır.
4. Üretken maliyetten önce deterministik yönlendirme: Kural tabanlı yönlendiriciler ve normal ifade filtreleri, üretken modeller çalıştırılmadan önce politikayı sıfır jeton maliyetiyle değerlendirir.
5. İlgi alanlarının ayrılması: Belirli bir aracıya özgü bağlam, yaşam döngüsü geri çağırmalarına aittir. Paylaşılan veri bağımlılıkları ise