1. Giriş

Bu codelab'de, Agent Development Kit'teki (ADK) iş akışlarını ve grafikleri kullanarak yeni nesil temsilci sistemleri oluşturma adımları açıklanmaktadır. Yaygın mimari modelleri uygulayacak, insan müdahalesi gerektiren (HITL) etkileşimleri 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 bankalarını ve kalıcı belleği entegre edeceksiniz. Son olarak, otomatik video üretimi ardışık düzenini çalıştırmak için bu özellikleri bağlayacaksınız.
Senaryo
VibeTube'da etkin bir kitleye ve sürekli artan yaratıcı fikirler listesine sahip bir dijital kanalınız var. Her videonun üretilmesi için birden fazla aşamada sürekli olarak çalışmak gerekir: trend olan formatları araştırma, izleyici geri bildirimlerini sentezleme, senaryo geliştirme, politika uygunluğunu kontrol etme ve video klipler oluşturma. Üretken modeller, bağımsız öğelerin taslağını oluşturabilir ancak tutarlı sürümler sunmak için düzenli bir temsilci mimarisi gerekir.
Bu yaşam döngüsünü otomatikleştirmek için VibeStudio'yu oluşturacaksınız. Bu ajan tabanlı işlem hattı, rutin araştırmaları paralel olarak yürütür, insan müdahalesi gerektiren 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ı temsilci mimarileri, açık kontrol akışı ve yapılandırılmış yürütme yolları gerektirir. Kenar demetleri,
STARTgiriş noktası, paralel fan-out toplama içinJoinNodeve yürütmeyi duruma göre yönlendirmek için deterministik yönlendirici düğümleri kullanarak bir ADKWorkflowoluşturursunuz. - Temsilci modları ve yaşam döngüsü geri çağırma yöntemleri: Özel görevler, farklı operasyonel davranışlar ve deterministik güvenlik önlemleri gerektirir. ADK
Agentörneklerini iş akışı düğümleri olarakchat,single_turnve araç özelliklitaskmodlarını kullanarak yapılandırır,before_model_callbackveafter_agent_callbackile kesiciler uygularsınız. - İnsan müdahalesi gerektiren düzenleme: Üretim süreçleri, kritik reklam öğesi kontrol noktalarında insan müdahalesi 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 kullanarak kısa süreli oturum durumunu yönetirsiniz. Ayrıca, içerik üreticilerin tercihlerini çalıştırmalar arasında ayıklamak, birleştirmek ve kalıcı hale getirmek için GEAP Memory Bank'ı bağlarsınız. - Kurumsal bilgi tabanlarıyla temellendirme: Bağımsız temsilciler için dinamik alan bağlamı ve kitle duyarlılığı gerekir. Temsilci çıkışlarını semantik olarak temellendirmek için paralel fan-out içinde özel bir alma düğümü olarak GEAP RAG Engine derlemesi bağlarsınız.
- 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ı çağrı kimliğine göre askıya almak ve devam ettirmek için bekleyen çağrı makbuzlarıyla
LongRunningFunctionTooluygulayacak ve tamamlanan ardışık düzeni Cloud Run'da ADKRunnerkullanarak dağıtacaksınız.
Bu codelab'in düzeni
Bu codelab, kavramsal ve mimari referansınız olarak kullanılabilir. Her bölümde, ilgili çalışma alanı adımında uygulanan ADK yapıları açıklanır, referans kod sağlanır ve temel tasarım ilkeleri belirlenir. Çalışma alanındaki ilgili alıştırmayı tamamlamadan önce her bölümü inceleyin.
Uygulamalı çalışmalar, etkileşimli kod düzenleyici, çalışma zamanı doğrulayıcıları ve yerleştirilmiş ADK inceleyicisi içeren yardımcı bir web arayüzü olan VibeStudio Workbench'te yapılır. Çalışma alanındaki adım numaralandırması, ilerleme durumunuzu senkronize etmek için doğrudan bu codelab ile uyumludur. Temel grafik düzenlemeleri adımlar boyunca devam eder. Çalışma alanı, ilerledikçe ön koşulları otomatik olarak doğrular.
Çalışma alanı alıştırmalarını tamamladıktan sonra uçtan uca bir ajan tabanlı ardışık düzen oluşturacak ve video içeriği üretmek için çalışan bir VibeStudio uygulamasını Cloud Run'da 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 uç (ADK Workflow ve agent/ içindeki aşama sanal alanları) ve Google Cloud (Gemini modelleri, GEAP Memory Bank, RAG Engine ve Veo video üretimi).
2. Kurulum
Atölye kredilerinizi alma
Eğitmen eşliğinde bir laboratuvara katılıyorsanız eğitmen, Google Cloud projeniz için kredi dağıtır. Devam etmeden önce kredilerinizi kullanmak için eğitmenin talimatlarını uygulayın ve 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üklü olduğu tarayıcı tabanlı bir geliştirme ortamıdır.
Cloud Shell'i başlatmak için:
- Google Cloud Shell'e gidin.
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 bilgileri girmeniz istenir:
- Google Cloud proje kimliği:
setup_project.shtarafından istendiğinde otomatik olarak yeni bir proje oluşturmak için Enter tuşuna basın. Mevcut bir projeyi (ör. önceden atanmış bir proje) kullanmayı tercih ediyorsanız proje kimliğinizi girin ve yazımının doğru olduğundan emin olun. Faturalandırma etkin olmalıdır. - Etkinlik kodu: Eğitmeniniz tarafından sağlanan oda kodunu girin. Almadıysanız bir öğretim asistanına veya komşunuza sorun. Bu laboratuvarı evde tamamlıyorsanız varsayılan
sandboxodasını kabul etmek için Enter tuşuna basın. - Kanalın görünen adı:
setup_codelab.shtarafı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ırmaya sahip bir Google Cloud projesi oluşturur veya yeniden kullanır, proje kimliğini~/project_id.txtkonumuna kaydeder ve etkingcloudbağlamını yapılandırır.setup_codelab.sh:uvve Python bağımlılıklarını.venvdizinine yükler, gerekli Google Cloud API'lerini etkinleştirir, kanal ayarlarınızı.enviçinde yapılandırır, Gemini ile model erişimini doğrular, Memory Bank ve RAG kaynaklarını hazırlar, çalışma ekranı arayüzünü oluşturur ve VibeStudio Workbench'i başlatır.
Komut dosyası, ön 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
Bu bağlantıyı tıklayın. Aynı adres Web Preview → Change port → 4600 (Web Önizlemesi → Bağlantı noktasını değiştir → 4600) bölümünde de mevcuttur.
Ortamı istediğiniz zaman yeniden kontrol etmek için python scripts/preflight.py komutunu çalıştırın. Çalışma alanını yeniden başlatmak için scripts/restart.sh komutunu çalıştırın. Yeniden ayarlamak için ./setup_codelab.sh komutunu çalıştırın. Bu komut, yapılandırmanızı ve ilerlemenizi korur.
Bu doküman açıkken senaryo için 1. adım: Hikaye, tamamlanmış grafiğin şekli için ise 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 ortamı ve üretim uygulaması şeklinde 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üğümleri, deterministik politika yönlendirme, bellek geri çağırmaları ve video üretimi 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/-stage6_video/: Bağımsız korumalı alan ortamları. Her klasör bağımsız birroot_agentdışa aktarır. Böylece her adımı yerleşik ADK geliştirme arayüzü üzerinden ayrı ayrı çalıştırıp inceleyebilirsiniz.server/veweb/: 4600 numaralı bağlantı noktasında yerel olarak çalışan VibeStudio Workbench uygulaması. Adım belgelerini, 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/: Son adımda paketlenip Cloud Run'a dağıtılan eksiksiz üretim uygulaması. Tamamlanan 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 temsilciyle mimari bir temel oluşturursunuz. Bu temsilci, üretim hattını düz yazı olarak açıklayan monolitik bir sistem istemi kullanır ve iki Python işlev aracı tarafından desteklenir.
Bu referansın değerlendirilmesi, isteme dayalı koordinasyonun operasyonel sınırlarını gösterir ve üretim sistemlerinin neden grafik düzenlemesi gerektirdiğini açıklar.
ADK temsilci mimarisi (3A)
VibeStudio Workbench'te 3. adım: Monolitik temsilci'ye gidin ve ADK temsilci mimarisi (3A)'ni açın. Bu görünüm, bir ADK temsilcisinin (LlmAgent) temel mimari katmanlarını 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, temsilci bileşenlerini beş operasyonel alanda gruplandırır:
- Akıl yürütme katmanı (Model): Bilişsel görevleri, istem akıl yürütmeyi ve araç seçimini yürüten temel dil modeli (ör. Gemini 3 Flash). Mimarideki diğer her şey bu modeli bilgilendirir veya kısıtlar.
- Bağlam katmanı (Talimat ve Beceriler): Modelin muhakemesini şekillendiren yönergeler.
instructionkalıcı sistem istemini, karakteri ve operasyonel kuralları oluşturur.skills, tekrarlanabilir iş akışları için sürümlere ayrılmış, prosedürlere dayalı rehberlik (SKILL.md) sağlar. - İşbirliği ve işlem katmanı (Araçlar, Alt Temsilciler, İş Akışı, Çıkış Şeması): Temsilcinin harici sistemlerde işlem yapmasını ve yazılı veriler yayınlamasını sağlayan arayüzler.
toolsçağrılabilir Python işlevleri veya Model Context Protocol (MCP) uç noktaları sağlamalıdır.subagents, astlara devredilen görevleri yürütür.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ğırma Yöntemleri): Arayıcılar, aracı yürütülmeden önce ve sonra (
before_agent/after_agent), tek tek model dönüşleri (before_model/after_model) ve araç çağrıları (before_tool/after_tool) için özel kod yürüten deterministik koruma raylarıdır. 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ı bilgileri ve tercihleri saklar.
Bu adımdaki monolitik temsilci, bu temel öğelerden yalnızca üçünü uygular: model, instruction ve tools. 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 temsilci tanımını incelemek için stage0_prompt/agent.py uygulamasını açın:
- Tek istem talimatı: Sistem istemi, beş farklı prodüksiyon görevini tek bir metinde birleştirir: platform trendlerini keşfetme, birikmiş fikirleri inceleme, reklam öğesi konseptleri önerme, yasaklanmış konu politikalarını uygulama ve çekim listeleri hazırlama.
- Temel veri kaynakları: Temsilci, grafiğin yanında tanımlanan iki kaynağa başvurur:
agent/trends.py: Dinamik ilgi puanlarına sahip 250 trendden oluşan bir havuzdan, etkin olan on format ve stil trendini örnekler.agent/backlog.txt: İçerik üreticinin ham konsept notlarını satır satır okur.
Agent'taki Araçlar (3C)
Çalışma alanında Tools in Agent (3C) (Temsilcideki Araçlar (3C)) bölümüne gidin.
Ajan için araç nedir?
Dil modeli, doğası gereği kapalı dünya akıl yürütme motorudur. Yalnızca önceden eğitilmiş ağırlıklar ve bağlam penceresindeki jetonlarla çalışır. Doğrudan bir veritabanına sorgu gönderemez, anlık API'lere erişemez veya kod yürütemez.
Araç bu sınırı aşar. Bu sayede model, harici sistemlerde gerçek doğru bilgilerini alabilir ve deterministik işlemler gerçekleştirebilir.

Araç çağırma, model ile ADK çalışma zamanı arasında açık bir beş aşamalı protokolü izler:
- Şema beyanı: Geliştirici, temsilciye Python işlevleri sağlar. ADK, her işlevin adını, tür ek açıklamalarını ve docstring'lerini inceleyerek parametrelerini ve amacını açıklayan OpenAPI uyumlu bir JSON şeması bildirimi oluşturur.
- Model muhakemesi: Model, çıkarım sırasında kullanıcının isteminin harici veri gerektirip gerektirmediğini değerlendirir. Model, gerekirse hedef işlev adını ve şemayla eşleşen bağımsız değişken sözlüğünü içeren yapılandırılmış bir
function_calletkinliği yayınlar. - Ç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. - Bağlamı yeniden ekleme: ADK çalışma zamanı, işlevin döndürdüğü değeri bir
function_responseetkinliğine paketler ve etkin oturum geçmişine ekler. - 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()}
Uygulamalı düzenleme ve yürütme
Çalışma alanı kod düzenleyicisinde, temsilcinin tools listesine iki işlev referansını 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 bağlı 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örürsünüz:
- Yanıttan önce iki araç yürütme etkinliği görünür:
check_trendsveread_backlogiçinfunction_callvefunction_responseetkinliklerini görürsünüz.- Neden: Gemini, sistem istemi yönergesini ("Trendleri 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 duraklar: Yanıtta, trendleri ve birikmiş işleri sentezleyen bir video yönü önerilir ve sizden onay istenir.
- Neden: Talimat yönergesinde modelden, senaryoyu oluşturmadan önce içerik üreticiyle yön konusunda anlaşması isteniyor.
- Takip eden turda onayı atlama: İkinci bir mesaj gönderin:
skip the questions, just describe the video. Temsilci, onay adımını hemen atlayarak başlığı ve çekimleri taslak olarak hazırlar.- Neden: İstem talimatları, kesin engeller yerine tavsiye niteliğindeki 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 çıktılar üretebilir ancak çalışma alanı doğrulayıcıda sınır koşullarını test etmek, kritik kurumsal sınırlamaları ortaya çıkarır:
- Yapılandırılmamış araştırma toplama: Araç yürütme sırası belirsizdir. Model, alınan verileri serbest biçimli metin olarak özetler. Bu nedenle, alt sistemlerin belirli iddiaları hangi kaynağın ürettiğini ayırt etmesi imkansız hale gelir.
- Doğrulanmamış politika yaptırımı: 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.
- Zorunlu olmayan insan müdahalesi gerektiren duraklatmalar: İçerik üreticinin onayını isteyen 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 temsilciyi bir sonraki adımda oluşturulan açık grafik iş akışına ayırmayı gerektirir.
4. Temsilci tabanlı iş akışıyla ilgili temel bilgiler
VibeStudio Workbench'te 4. Adım: Ajan tabanlı iş akışının temelleri bölümündeki 4A ile 4D arasındaki kısımlara gidin.
Bu adımda, ADK Workflow kullanılarak tek temsilcili temel modelden deterministik grafik düzenlemeye geçilir. Paralel araştırma fan-out'u oluşturacak, dalları birleştirme düğümüyle senkronize edecek, şeması doğrulanmış reklam öğesi adayları oluşturacak ve insan müdahalesi gerektiren deterministik bir onay kapısı ekleyeceksiniz.
Grafik mimarisi ve yürütme zincirleri (4A)
Workbench'te Graph architecture and execution chains (4A) (Grafik mimarisi ve yürütme zincirleri) seçeneğini açın.
ADK Workflow, temsilci yürütme işlemini kenar listesiyle tanımlanan yönlendirilmiş bir grafik olarak yapılandırır:
- Zincirler: Sıralı demetler, doğrusal düğüm yürütmeyi (
(node_a, node_b, node_c)) tanımlar. - Paralel dallar: Bir kaynak düğümü paylaşan bağımsız zincirler aynı anda yürütülür.
- Senkronizasyon: Bir
JoinNodeüzerinde birleşen zincirler, serbest bırakılmadan önce tüm gelen dalların rapor vermesini bekler. - Deterministik kontrol: Yürütme akışı, istem metninden çıkarım yapmak yerine tanımlanan 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ü |
| Belirleyici mantığı, veri almayı ve durum mutasyonlarını yürütür. |
Join node (Birleştirme düğümü) | Yerleşik | Eşzamanlı dalları toplu bir sözlükte senkronize eder. |
Aracı düğümü |
| Talimatları yukarı akış girişine göre değerlendirir ve doğrulanmış veriler yayınlar. |
Yönlendirici düğümü |
| Alt yürütme dallarını seçmek için koşullu mantığı değerlendirir. |
İnsan girişi düğümü | İşlev verimi | 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ılar olarak ele alır. Bu sayede, tüm grafik birleşik bir uygulama olarak yüklenebilir, sunulabilir ve incelenebilir. name, uygulamayı ADK Web'e kaydederken edges listesi, yürütme topolojisini tanımlar.
Paralel araştırma fan-out (4B)
Workbench'te Paralel araştırma dağıtımı (4B)'na ilerleyin. stage1_fanout/agent.py sayfasını açın.

İşlev düğümleri ve senkronizasyon engelleri
Araştırma aşamasında, agent/graph.py adresinden içe aktarılan iki işlev düğümü kullanılır:
scan_trends: On adet puanlanmış platform trendini içerenEvent(output={"trends": [...]})döndürür.read_backlog: İlk çalıştırma isteminin yanı sıra on beş kanal birikimi fikri içerenEvent(output={"backlog": [...], "idea": "..."})döndürür.
Her işlev node_input (önceki düğümün çıkışı) kabul eder ve bir Event döndürür.
JoinNode, senkronizasyon bariyeri görevi görür: Her gelen zincir bir etkinlik yayınlayana kadar duraklatılı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.
Uygulamalı düzenleme: Birleştirme ve paralel kenarları tanımlama
stage1_fanout/agent.py içinde JoinNode öğesini örneklendirin 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. Tezgah doğrulayıcı, birleştirme ve kenarların kablolu olduğunu onaylar. Aşamayı Run Stage 1'i kullanarak veya yerleştirilmiş ADK Web arayüzü üzerinden çalıştırın.
Sizi neler bekliyor ve neden?
- Eşzamanlı okuyucu yürütme: Yürütme grafiğinde
scan_trendsveread_backlogaynı anda yürütülür.- Neden: Her iki zincir de
STARTadresinde başlar. ADK motoru, bağımsız dalları eşzamanlı olarak planlar.
- Neden: Her iki zincir de
- Toplu sözlük çıkışı: İş akışı
join_researchkonumunda 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.
- Nedeni:
Temsilci düğümleri (4C)
Workbench'te Agent nodes (4C)'a (Aracı düğümleri (4C)) gidin. stage2_direction/agent.py sayfasını açın.

Çalışma modları ve yapılandırılmış şemalar
Bir 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.
- Sonraki düğüme yapılandırılmış veriler gönderir.
output_schema=Directions atandığında temsilci, model çıkışında Pydantic doğrulamasını zorunlu kılar. Alt 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.
Uygulamalı düzenleme: Temsilci düğümünü tanımlama ve birleştirme işlemini zincirleme
stage2_direction/agent.py içinde 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_researchtarafından yayınlanan JSON yükünü manuel biçimlendirme olmadan tüketir. - Yazılı aday çıkışı: Temsilci, dört farklı aday içeren doğrulanmış bir
Directionsnesnesi yayınlar. Aşağı akış düğümleri, alanları dize ayrıştırması olmadan özellik adına (candidate.title) göre okur.
İnsan müdahalesi gerektiren (4D)
Vertex AI Workbench'te İnsan müdahalesi gerektiren (4D) bölümüne gidin. agent/graph.py uygulamasını açın.

İstem talimatları ve deterministik askıya alma
Mali maliyet gerektiren 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 atlamasını isteyebileceği tavsiye niteliğindeki talimatlardır. ADK iş akışında, insan onayı yürütme motoru tarafından zorunlu kılınır: Grafik, belirlenmiş bir düğümde durur ve harici, şemayla doğrulanmış bir giriş alana kadar ilerleyemez:
- Yielding
RequestInputiş akışı yürütmesini hemen askıya alır. - ADK, oturum deposunda açık bir kesme çağrısı kaydeder ve benzersiz bir
interrupt_idyayınlar. - Yürütme işlemi, jeton veya sunucu iş parçacığı tüketmeden durur.
- Grafik yürütme, yalnızca şemayla ve kesinti kimliğiyle eşleşen geçerli bir
function_responsegö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çinde 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 üç özellik 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: İstekle birlikte paketlenen meta veriler (dört aday), istemci arayüzlerinin oturum durumunu sorgulamadan inceleme kartlarını oluşturmasına olanak tanır.
Sizi neler bekliyor ve neden?
- İş akışı, direction_gate'te duraklıyor: ADK Web'de veya workbench arayüzünde çalıştırma işlemi duraklatılıyor ve etkileşimli bir aday seçimi formu gösteriliyor.
- Neden: Motor, bir
RequestInputile karşılaştı ve yürütme durumunuruns/sessions.dbolarak sürdürdü.
- Neden: Motor, bir
- Devam ettirmek 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_schemakoşulunu karşılayan birfunction_responseyazılır ve yürütme devam eder.
5. State and Router
VibeStudio Workbench'te 5. Adım · 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, deterministik yönlendirici düğümlerini kullanarak kanal güvenliği politikalarını 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)
Çalışma alanında Workflow State (5A) (İş Akışı Durumu (5A)) bölümüne gidin.

Oturum durumu ve düğüm çıkışı
Bir 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 bir dizin ({"pick": "2"}) olarak gelir. Sonraki düğümler için tam yön nesnesi gerekir: başlık, anlatım açısı ve ilgi çekici cümle. persist_direction, her ara düğüm yükü aracılığıyla ayrıntılı meta veriler iletmek yerine, çö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 devreder. 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, parametre denetimi aracılığıyla oturum durumunu otomatik olarak okur. Bir işlev imzası, mevcut bir durum anahtarıyla eşleşen bir parametre adı bildirirse 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, direction_gate tarafından oturum durumuna yazıldı. ADK, açık sözlük aramaları gerektirmeden bunu doğrudan persist_direction(node_input, candidates: list = []) ile bağlar.
user: ile başlayan anahtarlar, kullanıcı düzeyindeki depolamada oturumlar arasında kalıcı olur. Bu sayede, sonraki iş akışı çalıştırmaları içerik üreticinin tercihlerine erişebilir.
Uygulamalı düzenleme: durumu kalıcı hale getirme ve düğümü bağlama
agent/graph.pyiçinde,persist_directioniçinde,TODO: PERSIST_STATEsatı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"]}})
stage3_router/agent.pyiçinde,edgeslistesindeki üçüncü zincirepersist_directionekleyin:
(join_research, propose_directions, direction_gate,
persist_direction)
Dosyalarınızı kaydedin. Çalışma alanında, state write in place ve persist_direction in the chain için yeşil onay işaretlerinin gösterildiğini doğrulayın.
Yönlendirici düğümü (5B)
Çalışma alanında Yönlendirici düğümü (5B) bölümüne gidin.

Deterministik politika yönlendirme
Yönlendirici, üst akış çıkışını değerlendiren ve yürütmeyi koşullu grafik dalları boyunca yönlendiren özel bir işlev düğümüdür. Üretken temsilcilerin aksine, yönlendirici LLM çağrıları yapmadan deterministik mantığı yürütür.
Yönlendirici, route etiketini 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üğümlerle eşler:
(length_check, {"TRIM": shorten, "PASS": scripter}),
İş akışı yönlendiricisi policy_check, agent/policy_words.txt adresindeki yasaklı ifadeleri okur ve seçilen yönün başlığı ve açısıyla tam kelime eşleşmesi yapar:
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 normal ifade eşleşmesi 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 alt düğümden birine yönlendirir:
scripter: Onaylanan talimatı,ScriptPydantic şemasına uygun yapılandırılmış bir prodüksiyon senaryosuna dönüştürensingle_turntemsilci 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ıyla değiştirilir.
Uygulamalı düzenleme: Politika kontrolünü yönlendirme
agent/graph.pydosyasında,policy_checkiçinde dönüş ifadesini tamamlayın:
return Event(output=node_input, route="BLOCK" if bad else "OK")
stage3_router/agent.pyiçinde,edgesöğesinipolicy_check'ye yönlendirecek şekilde güncelleyin ve karantina dalınıscripter'e 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 alanında, yönlendirici kenar eşlemelerinin doğrulandığından emin olun.
Temsilci 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.

Temsilci 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 |
| Çok adımlı etkileşimli döngü. Model; araçların ne zaman çağrılacağını, girişlerin ne zaman isteneceğini veya sıranın ne zaman sona ereceğini belirler. | Etkileşimli bir insan kullanıcıyla karşılaşan kök temsilciler. |
| 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 ( |
| Araç yürütme içeren bağımsız döngü. Temsilci, yerleşik | Çok adımlı düzeltme ve denetleme ( |
Otonom politika düzeltme
İşaretlenen bir talimatı yeniden yazmak için task modu gerekir. Bunun nedeni, düzeltme iterasyonlarının sayısının değişken olmasıdır. Temsilci, işaretlenen talimatı alır, ihlalleri tespit etmek için find_policy_hits aracını çağırır, suggest_replacement aracılığıyla onaylanmış alternatifler ister, talimatı yeniden yazar ve devam etmeden önce temizliğini 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örevi temsilcisini oluşturma
stage3_router/agent.py dosyasında, yer tutucu quarantine işlevini görev temsilcisi 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, temsilciyi araçlarla donatır ve finish_task yöntemini çağırarak yürütmeyi sonlandırır. mode="task" yapılandırıldığında ADK, finish_task öğesini otomatik olarak sağlar ve parametrelerini output_schema öğesinden türetir. Böylece düğüm, senaryo yazma düğümünün giriş şemasıyla eşleşen, yazılı bir CleanedDirection nesnesi oluşturur.

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ı
policy_checkkonumundan doğrudanscripterkonumuna (route="OK") yönlendirme. - Senarist,
Scriptşemasına uygun 3 çekimlik bir prodüksiyon senaryosu oluşturur.
- Onaylanmış bir aday rotayı
- Karantina düzeltme rotası (Aday 4):
- 4. aday, işaretlenmiş kelimeler ("tıklama tuzağı", "viral hile") içeriyor.
quarantinekonumuna kadarpolicy_checkrota (route="BLOCK").- Oturum izinde, her ihlal için
quarantineçağrısıfind_policy_hits,suggest_replacementçağrısı, başlığın yeniden yazılması vefinish_taskçağrısı yapıldığını gözlemleyin. - Yürütme,
scripterile yeniden birleşerek temizlenmiş yönergeden bir senaryo oluşturur.
6. Bellek Bankası
VibeStudio Workbench'te Step 6 · Memory Bank (6. Adım: Bellek Bankası) bölümüne gidin ve (6A) ile (6B) kısımlarını inceleyin.
İş akışı şu anda oturumlar arasında hafıza olmadan çalışmaktadır. Her yürütme sıfırdan başlar ve içerik üreticinin daha önce ne seçtiğini veya hangi türleri tercih ettiğini bilmez. Bu adımda, içerik üretici tercihlerini çalıştırmalar arasında depolamak ve almak için Vertex AI Agent Engine Memory Bank'i bağlayacaksınız.
Önemli bir nokta da, hafızanın ardışık düzen düğümleri yerine temsilci yaşam döngüsü geri çağırma yöntemleri aracılığıyla entegre edilmesidir. Bellek çıkarma ve alma işlemleri, ara veri aşamaları yerine ayrı ayrı temsilcilere hizmet ettiğinden geri çağırma işlevleri eklemek, temiz ve ayrılmış bir grafik topolojisi sağlar.
Memory Bank (6A)
Çalışma alanında Memory Bank (6A)'ya gidin.

Yönetilen kullanıcı düzeyindeki hafıza
Memory Bank, uzun süreli kullanıcı hafızası için yönetilen bir hizmettir. Bir kişiyle ilgili bilgileri, burada uygulama adı ve kullanıcı kimliğiyle tanımlanan belirli bir kapsam altında düzenler:
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 hafıza konuları, bankanın kaydettiği bilgilerin sınırlarını belirler:
- 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 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 işlemi, 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, saklanan bilgiler en eskiden en yeniye doğru sıralanarak 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'da yerel olarak önbelleğe alınır.
Anı Bankası'nı ayarlama
Çalışma alanı kontrollerini kullanın veya terminalinizde CLI komutlarını çalıştırın:
- Bankayı bağlayın ve sağlayın:
Agent Engine örneğini oluşturur vepython -m agent.platform.bankCREATOR_TASTEileCHANNEL_RULESkonularını yapılandırır. - Geçmiş oturumları başlatma:
Dört tarihi içerik üretici oturumu yükler (stil kısıtlamaları olan iki hayvan teması, bir cihaz teması ve bir yakın tarihli fantezi teması).python -m agent.platform.bank load - Birleştirilmiş bilgileri inceleme:
Çıkışı inceleyin. Anlatı transkriptlerinin nasıl yapılandırılmış, birleştirilmiş gerçek beyanlara dönüştürüldüğüne dikkat edin.python -m agent.platform.bank list
Geri aramalar (6 milyar)
Workbench'te Callbacks (6B)'e (Geri Arama (6B)) gidin. stage4_memory/agent.py uygulamasını açın.

ADK temsilcisinin yaşam döngüsü geri çağırmaları
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ğırmaları çağırarak etkin bağlamı iletir. Döndürme None normal yürütmeye devam eder; yedek bir nesne döndürme işlemi geçersiz kılar veya engeller.

ADK, üç çift geri çağırma sağlar:
Geri Arama Çifti | Çağrı Noktası | Alınan Parametreler | Döndürülen Değer Davranışı |
| Tüm temsilci yanıtını kapsar. |
| Geri dönme |
| Her LLM çıkarım çağrısını çevreleyen |
| Döndürme |
| Her araç yürütme işleminin etrafında | Araç tanımı, bağımsız değişkenler, sonuç | Sözlük döndürmek, araç çıkışını geçersiz kılar; |
Geri çağırmalar, iş akışı grafiğine fazladan düğüm eklemeden bağlam ekleme, güvenlik önlemleri, telemetri ve önbellek aramaları için temiz bir konum sağlar.
Uygulamalı düzenleme: geri çağırma ve geri çağırma işlevlerini hatırlama
stage4_memory/agent.pyiçinde,before_model_callback=recall_tasteeklemek içinpropose_directionsöğesini güncelleyin:
output_schema=Directions,
before_model_callback=recall_taste)
recall_taste, Gemini aday talimatlar oluşturmadan hemen önce yürütülür. İçerik üreticinin geçmişini Anı Bankası'ndan alır, anıları en eskiden başlayarak biçimlendirir ve giden LlmRequest'ya ekler. İstem, modeli 1 ila 3 numaralı adayları içerik üreticinin mevcut zevkine göre yönlendirmeye ve kanal kurallarını katı kısıtlamalar olarak ele almaya yönlendirir.
stage4_memory/agent.pyiçinde,after_agent_callback=remember_pickeklemek içinscripteröğesini 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 Hafıza Bankası'nı günceller.
Sizi neler bekliyor ve neden?
Geri çağırma ile geliştirilmiş iş akışını, çalışma alanında veya ADK Web'de test edin:
- Boş bir istemle çalıştırma işlemi yürütün:
- Oturum izinde,
propose_directionsiçinLlmRequestöğesini inceleyin. İçerik üreticinin fantastik temalar ve kısa tempo tercihini ayrıntılı olarak açıklayan eklenmiş hafıza bağlamına dikkat edin. - Önerilen yönlendirmelere dikkat edin: Trendler diğer konuları vurgulasa bile 1-3 numaralı adaylar, içerik üreticinin geçmiş tercihlerine uygundur.
- Oturum izinde,
direction_gatekonumunda bir aday seçin.scriptertamamlandıktan sonra Memory Bank kayıtlarını inceleyin: Banka, önceki zevk kayıtlarıyla birleştirerek son tercihi yansıtır.python -m agent.platform.bank list
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'ı kullanarak bu yorumları dizine ekleyecek ve semantik erişimi araştırma fan-out'una bağlayacaksı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 | Bellek Bankası | RAG Engine |
Birincil Kullanım Alanı | Uzun vadeli kullanıcı tercihleri ve operasyonel kurallar | Büyük doküman koleksiyonlarında semantik bilgi getirme |
Kapsam | Kapsamı, bireysel kullanıcı kimlikleri ve uygulama adlarıdır. | Tüm kullanıcılar arasında paylaşılan korpus kaynaklarıyla sınırlıdır. |
Veri İşleme | Anlık ayıklama, yerleştirme ve anlamsal birleştirme | Doküman parçalama, vektör yerleştirme ve en yakın komşu araması |
Grafik Entegrasyonu | Temsilci yaşam döngüsü geri çağırma yöntemleri ( | Araştırma fan-out'unda özel işlev düğümü ( |

Doküman 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ışmayla 120 jeton olarak yapılandırılmıştır. Bu sayede, her pasaj için iki ila üç yorum alınır ve her vektör, alakasız geri bildirimlerde anlamı sulandırmadan tutarlı bir duyguyla temsil edilir.
- 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 eşleşmesi gerektirmeden sihirli yaratıklarla ilgili bir istemle eşleşir.
RAG korpusunu ayarlama
Çalışma tezgahı düğmelerini veya terminal komutlarını kullanarak gövdeyi başlatın:
- Derlem oluşturma:
Yönetilen vektör veritabanını sağlar ve kaynak kimliğinipython -m agent.platform.ragruns/ragcorpus.jsoniçine kaydeder. - Yorumları yükleme ve dizine ekleme: Parçalama yapılandırmasıyla
agent/comments.mdyükler ve dizine ekleme işleminin tamamlanmasını bekler. - Derlemeyi sorgulama: Yorumlarla tam olarak aynı kelimeleri içermeyen sorgularla benzerlik alma özelliğini test edin (örneğin, ejderhalarla ilgili yorumları almak için "küçük sihirli yaratıklar" sorgusunu kullanın).
Alma düğümü (7B)
Çalışma alanında The third reader (7B) (Üçüncü okuyucu (7B)) bölümüne gidin. stage5_rag/agent.py uygulamasını açın.

Grafik düğümü olarak alma
Kitle geri bildirimi, iş akışı boyunca paylaşılan araştırma verilerini temsil eder. İçerik üreticinin kişisel hafızasından farklı olarak izleyici yaklaşımı, trendler ve birikmiş verilerle birlikte doğrudan join_research'a 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 çıkarır ve RAG Engine derlemesinde bir vektör sorgusu yürütür. Alınan yorumları Event(output=...) yükünde yayınlar.
Pratik 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 bir JoinNode olduğundan, gelen tüm dalları senkronize eder ve birleştirilmiş paketi aşağı akışa iletmeden önce scan_trends, read_backlog ve read_feedback'nin tümünün etkinlikleri yayınlamasını bekler.
Sizi neler bekliyor ve neden?
İş akışını çalışma alanında çalıştırın:
- Bir fikir istemi (ör. "mutfak tezgahını koruyan minyatür bir ejderha") gönderin.
- Yürütme izinde, üç okuyucu düğümünün de aynı anda yürütüldüğünü doğrulayın.
join_researchöğesini inceleyin: Çıkış sözlüğü artıktrends,backlogvefeedbacköğelerini içeriyor.propose_directionstarafından oluşturulan adayları inceleyin: Model, izleyici yorumlarını önerilerine dahil eder ve kanıt alanlarında kitle yaklaşımına atıfta bulunur.- RAG alma işleminin deterministik olduğunu (aynı sorgular aynı yorum pasajlarını döndürür), üretken öneri düğümünün ise yaratıcı varyasyonlar ürettiğini unutmayın.
8. Veo ile eşzamansız video üretimi
VibeStudio Workbench'te Step 8 · The video (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 bir oluşturma işlemi birkaç dakika sürer. Bu süre zarfında 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ısı kesintilerine maruz kalmasına neden olur. Bu adımda, ADK'nin LongRunningFunctionTool özelliğini kullanarak video oluşturmayı eşzamansız hale getireceksiniz.
Uzun süreli araçlar (8A)
Çalışma alanında Uzun süren bir araca (8A) gidin. stage6_video/agent.py ve agent/deliver.py uygulamasını açın.

Eşzamanlı araçlar ve uzun süreli araçlar
Standart ADK işlev araçları, bir temsilci sırası içinde eşzamanlı olarak yürütülür: Model, aracı çağırır, döndürülen yükü bekler ve sonucu devam eden sıraya dahil eder.
Video oluşturma işlemi tek bir adımda tamamlanamaz. Bunun yerine, render_submit oluşturma işini başlatır ve hemen "pending" durumuyla bir operasyon makbuzu 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 keser. 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çine kaydedilir. Yürütme işlemi, etkin ağ bağlantılarını veya çalışan iş parçacıklarını sürdürmeden sorunsuz bir şekilde sonlanır.
Pratik düzenleme: Oluşturma aracını sarmalama
stage6_video/agent.py içinde, render_submit öğesini LongRunningFunctionTool ile sarmalamak için render_desk öğesini 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 Alınma Durumu | Devam Etme Etkinliği |
İnsan Kararı |
| Oturum deposunda giriş istemini aç |
|
Uzun Süre Çalışan Araç |
| Oturum deposunda araç çağrısını aç |
|
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.
Uygulamalı 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))
Yayınlama arka plan programı, video dosyası oluşturulana kadar Veo'yu sorgular ve ardından bu FunctionResponse oturuma gönderir. ADK, çağrı kimliğini eşleştirir ve iş akışını doğrudan sonraki düğümde devam ettirir. Tamamlanan düğümler yeniden yürütülmez ve temsilci başka bir üretken sıra almaz.
.env içinde STUDIO_REAL_VIDEO=0 ayarı, 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)'a (Grafikteki render_desk) gidin. stage6_video/agent.py uygulamasını açın.
Ardışık düzendeki terminal düğümü store_video. Tamamlanan oluşturma bilgilerini runs/state.json adresinden (yayınlama işleminin kaydettiği yer) okur ve video URL'sini ve oluşturma durumunu paylaşılan oturum durumuna kaydeder.

Uygulamalı düzenleme: Tüm video ardışık düzenini bağlama
stage6_video/agent.py dosyasında, render_desk ve store_video değerlerini eklemek için edges değerini güncelleyin:
(quarantine, scripter),
(scripter, render_desk, store_video)])
Sizi neler bekliyor ve neden?
Çalışma alanında asenkron oluşturma akışını test edin:
- Aday seçimi ve senaryo oluşturma yoluyla iş akışını yürütün.
render_deskadresinde, temsilcininrender_submitaracını çağırdığını gözlemleyin.- İş akışı hemen askıya alınır. Çalışma alanında veya ADK Web'de bekleme durumunu gözlemleyin: Oturum, açık çağrı kimliğini tutar ve arka plan işlemleri kaynak tüketmez.
- Workbench konsolunu veya terminalinizi kullanarak teslimat arka plan programını çalıştırın:
Teslimat süreci, video hazır olana kadar Veo'yu izler ve ardından devam ettirme etkinliğini gönderir.python -m agent.deliver - ADK Web'de oturumu yenileyin: Yürütme
store_videoadresinde devam eder, video URL'sini oturum durumuna kaydeder ve iş akışını tamamlar.
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, üretim ardışık düzeninin tamamını bir araya getirip Google Cloud Run'a dağıtacaksı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ışının yürütülmesini sağlar. Düğümler yürütüldükçe etkinlikleri sırayla oluşturur ve oturum hizmetindeki güncellemeleri kalıcı hale getirir.- Birleştirilmiş devam ettirme: Hem
direction_gatekonumundaki kullanıcı kararları hem de Veo'dan tamamlanan video yayınları,run_async'e gönderilen aynıFunctionResponsenesneleri 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ışı üzerinden yayınlar. React ön ucu, grafik ilerlemesini gerçek zamanlı olarak görselleştirir ve geç bağlantıları durum kaybetmeden yönetir.
- 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 içindeki tam iş akışı kenar listesi, bu codelab'de 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 hizmeti sunar:
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ü derler ve hizmeti tek bir işlemde dağıtır. - Oturum benzeşimi: Aynı kullanıcıdan gelen istekleri aynı container ö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 workbench'teki Dağıt düğmesini tıklayın. Derleme tamamlandığında terminalde canlı hizmet URL'si gösterilir.

10. Özet
VibeStudio Workbench'te, tamamlanan mimariyi incelemek için Step 10 · Summary'ye (10. Adım: Özet) gidin.

Adım | Mimari ve Kavramlar | Uygulama Modeli |
Tek bir istem | Tek istem, işlev araçları, sıralı sohbet döngüsü |
|
Ajan tabanlı iş akışıyla ilgili temel bilgiler | Grafik iş akışı, paralel araştırma, şema çıkışları, insan kontrolü |
|
Durum ve Yönlendirici | Paylaşılan oturum durumu, parametre bağlama, deterministik yönlendirme, görev temsilcisi |
|
Memory Bank | Kullanıcı düzeyinde uzun süreli bellek, semantik birleştirme, yaşam döngüsü kancaları |
|
RAG Engine | Kitle yorumları üzerinden doküman alma, semantik yerleştirmeler |
|
Veo ile eşzamansız video üretimi | Uzun süren araçlar, bekleyen makbuzlar, harici teslimat arka plan programı |
|
Cloud Run'a dağıt | Programatik düzenleme, sunucu tarafından gönderilen etkinlikler, sunucusuz kapsayıcı |
|
Temel mimari ilkeler
- Beklemek yerine askıya alma: İş akışları, kullanıcı girişi (
RequestInput) veya uzun süreli işlemler (LongRunningFunctionTool) için sorunsuz bir şekilde duraklatılır. İşlemler, iş parçacıklarında veya ağ soketlerinde boşta beklemez. - Evrensel devam ettirme: Her askıya alma işlemi, aynı mekanizma üzerinden devam ettirilir: Askıya alınan düğümün çağrı kimliğini taşıyan tek bir
function_response. - Ayrılmış durum yönetimi: Düğümler, ayrıntılı ve sıkı bağlantılı ara yükler yerine adlandırılmış oturum durumu anahtarları ve parametre bağlama yoluyla paylaşılan veri paylaşır.
- Ü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.
- İlgili konuların ayrılması: Belirli bir temsilciye özgü bağlam, yaşam döngüsü geri çağırma yöntemlerine aitken paylaşılan veri bağımlılıkları,
