ADK ile ajan tabanlı iş akışı

1. Giriş

VibeStudio

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.

Fikirden yayınlanmış klibe kadar oluşturduğunuz iş akışı

Öğrenecekleriniz

10-summary

  • 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, START giriş noktası, paralel fan-out toplama için JoinNode ve yürütmeyi duruma göre yönlendirmek için deterministik yönlendirici düğümleri kullanarak bir ADK Workflow oluş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 olarak chat, single_turn ve araç özellikli task modlarını kullanarak yapılandırır, before_model_callback ve after_agent_callback ile 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 LongRunningFunctionTool uygulayacak ve tamamlanan ardışık düzeni Cloud Run'da ADK Runner kullanarak 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.

Nerede ne çalışır: VibeStudio Workbench, arka uç ve Google Cloud hizmetleri

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:

  1. 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.sh tarafı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 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ırmaya sahip 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 dizinine yükler, gerekli Google Cloud API'lerini etkinleştirir, kanal ayarlarınızı .env iç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 bir root_agent dışa aktarır. Böylece her adımı yerleşik ADK geliştirme arayüzü üzerinden 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 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:

03-3A

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. instruction kalı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.

03-3C

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

  1. Ş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.
  2. 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_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 ekleme: 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()}

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_trends ve read_backlog için function_call ve function_response etkinliklerini 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.

04-4A

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.

Join node (Birleştirme düğümü)

Yerleşik JoinNode örneği

Eşzamanlı dalları toplu bir sözlükte senkronize eder.

Aracı düğümü

Agent, single_turn modunda çalışıyor

Talimatları yukarı akış girişine göre değerlendirir ve doğrulanmış veriler yayınlar.

Yönlendirici düğümü

route etiketiyle Event döndüren işlev

Alt 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ı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.

04-4B

İş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çeren Event(output={"trends": [...]}) döndürür.
  • read_backlog: İlk çalıştırma isteminin yanı sıra 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ışı) 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_trends ve read_backlog aynı anda yürütülür.
    • Neden: Her iki zincir de START adresinde başlar. 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.

Temsilci düğümleri (4C)

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

04-4C

Ç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_research tarafı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 Directions nesnesi 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.

04-4D

İ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 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, yalnızca şemayla ve kesinti kimliğiyle eşleşen 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ç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 RequestInput ile karşılaştı ve yürütme durumunu runs/sessions.db olarak sürdürdü.
  • 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_schema koşulunu karşılayan bir function_response yazı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.

05-5A

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üğü.

05-5A

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

  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"]}})
  1. stage3_router/agent.py içinde, edges listesindeki üçüncü zincire persist_direction ekleyin:
           (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.

05-5B

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ı, Script Pydantic şemasına uygun yapılandırılmış bir prodüksiyon 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ıyla değiştirilir.

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

  1. agent/graph.py dosyasında, policy_check içinde dönüş ifadesini tamamlayın:
    return Event(output=node_input, route="BLOCK" if bad else "OK")
  1. stage3_router/agent.py içinde, edges öğesini policy_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.

05-5C

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

chat

Ç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.

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ü. Temsilci, yerleşik finish_task aracını çağırana kadar iterasyon yapar.

Çok adımlı düzeltme ve denetleme (quarantine).

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.

05-5C

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_check konumundan doğrudan scripter konumuna (route="OK") yönlendirme.
    • Senarist, Script şemasına uygun 3 çekimlik bir prodüksiyon senaryosu oluşturur.
  • Karantina düzeltme rotası (Aday 4):
    • 4. aday, işaretlenmiş kelimeler ("tıklama tuzağı", "viral hile") içeriyor.
    • quarantine konumuna kadar policy_check rota (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ı ve finish_task çağrısı yapıldığını gözlemleyin.
    • Yürütme, scripter ile 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.

06-6A

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:

  1. Bankayı bağlayın ve sağlayı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şlatma:
    python -m agent.platform.bank load
    
    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ı).
  3. Birleştirilmiş bilgileri inceleme:
    python -m agent.platform.bank list
    
    Çıkışı inceleyin. Anlatı transkriptlerinin nasıl yapılandırılmış, birleştirilmiş gerçek beyanlara dönüştürüldüğüne dikkat edin.

Geri aramalar (6 milyar)

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

06-6A

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.

06-6A

ADK, üç çift geri çağırma 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ğrı)

Geri dönme 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ı çevreleyen

LlmRequest veya LlmResponse

Döndürme 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 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; None devam eder.

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

  1. stage4_memory/agent.py içinde, before_model_callback=recall_taste eklemek için propose_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.

  1. stage4_memory/agent.py içinde, after_agent_callback=remember_pick eklemek için scripter öğ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:

  1. Boş bir istemle çalıştırma işlemi yürütün:
    • Oturum izinde, propose_directions için LlmRequest öğ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.
  2. direction_gate konumunda bir aday seçin.
  3. scripter tamamlandıktan sonra Memory Bank kayıtlarını inceleyin:
    python -m agent.platform.bank list
    
    Banka, önceki zevk kayıtlarıyla birleştirerek son tercihi yansıtır.

7. RAG Engine

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

07-7A

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 (before_model_callback, after_agent_callback)

Araştırma fan-out'unda özel işlev düğümü (read_feedback)

07-7A

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:

  1. Derlem oluşturma:
    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 ekleme işleminin tamamlanmasını bekler.
  3. 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.

07-7B

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:

07-7B

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:

  1. Bir fikir istemi (ör. "mutfak tezgahını koruyan minyatür bir ejderha") gönderin.
  2. Yürütme izinde, üç okuyucu düğümünün de aynı anda 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 tarafından oluşturulan adayları inceleyin: Model, izleyici yorumlarını önerilerine dahil eder ve kanıt alanlarında kitle yaklaşımına atıfta bulunur.
  5. 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.

08-8A

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ı

yield RequestInput(...)

Oturum deposunda giriş istemini aç

FunctionResponse, askıya alma çağrısı kimliğini taşıyor

Uzun Süre Çalışan Araç

LongRunningFunctionTool(...), pending iade ediyor

Oturum deposunda araç çağrısını aç

FunctionResponse, askıya alma çağrısı kimliğini taşıyor

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.

08-8B

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:

  1. Aday seçimi ve senaryo oluşturma yoluyla iş akışını yürütün.
  2. render_desk adresinde, temsilcinin render_submit aracını çağırdığını gözlemleyin.
  3. İş 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.
  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 adresinde 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.

09-9A

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_gate konumundaki kullanıcı kararları hem de Veo'dan tamamlanan video yayınları, run_async'e 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ışı ü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.

Uygulama

10. Özet

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

10-summary

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ışıyla ilgili temel bilgiler

Grafik iş akışı, paralel araştırma, şema çıkış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 temsilcisi

Event(state=...), Event(route=...), mode="task", finish_task

Memory Bank

Kullanıcı düzeyinde uzun süreli bellek, semantik birleştirme, yaşam döngüsü kancaları

memories.generate / retrieve, before_model_callback, after_agent_callback

RAG Engine

Kitle yorumları üzerinden doküman alma, semantik yerleştirmeler

rag.create_corpus, RagEmbeddingModelConfig, read_feedback düğümü

Veo ile eşzamansız 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, sunucu tarafından gönderilen etkinlikler, 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üreli 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, aynı mekanizma üzerinden devam ettirilir: Askıya alınan düğümün çağrı kimliğini taşıyan tek bir function_response.
  3. 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.
  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. İ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ı,

10 çıkışlı