Alur kerja agentic dengan ADK

1. Pengantar

VibeStudio

Codelab ini memandu Anda membangun sistem berbasis agen generasi berikutnya menggunakan alur kerja dan grafik di Agent Development Kit (ADK). Anda akan mengimplementasikan pola arsitektur umum, mengorkestrasi interaksi human-in-the-loop (HITL), dan menangani eksekusi asinkron yang berjalan lama. Anda juga akan mengintegrasikan pusat informasi perusahaan dan memori persisten untuk menyesuaikan dan mengembangkan perilaku agen. Terakhir, Anda akan menghubungkan kemampuan ini untuk menggerakkan pipeline pembuatan video otomatis.

Skenario

Anda menjalankan channel digital di VibeTube dengan audiens yang aktif dan backlog ide kreatif yang terus bertambah. Pembuatan setiap video memerlukan eksekusi berkelanjutan di beberapa tahap: meneliti format yang sedang tren, menyintesis masukan penonton, mengembangkan skrip, memeriksa kepatuhan kebijakan, dan membuat klip video. Model generatif dapat membuat draf aset individual, tetapi untuk merilis aset secara konsisten diperlukan arsitektur agen yang terkoordinasi.

Untuk mengotomatiskan siklus proses ini, Anda akan membangun VibeStudio. Pipeline agentic ini menjalankan riset rutin secara paralel, menyajikan opsi yang telah dikurasi untuk persetujuan human-in-the-loop, menerapkan gerbang kebijakan otomatis sebelum membuat video, dan mempertahankan konteks di seluruh proses produksi.

Alur kerja yang Anda buat, mulai dari ide hingga klip yang dipublikasikan

Yang Anda pelajari

10-summary

  • Dasar-dasar rekayasa grafik: Arsitektur agen multi-langkah memerlukan alur kontrol eksplisit dan jalur eksekusi terstruktur. Anda membuat Workflow ADK menggunakan tuple edge, titik entri START, JoinNode untuk agregasi fan-out paralel, dan node router deterministik untuk mengarahkan eksekusi berdasarkan status.
  • Mode agen dan callback siklus proses: Tugas khusus memerlukan perilaku operasional yang berbeda dan batasan yang deterministik. Anda mengonfigurasi instance Agent ADK menggunakan mode chat, single_turn, dan task yang mendukung alat sebagai node alur kerja, dengan menerapkan interseptor dengan before_model_callback dan after_agent_callback.
  • Orkestrasi human-in-the-loop: Pipeline produksi dijeda untuk penilaian manusia di checkpoint kreatif yang penting. Anda menerapkan RequestInput untuk menangguhkan eksekusi alur kerja, menerapkan skema respons terstruktur, dan melanjutkan eksekusi tanpa membuat proses runtime yang tidak ada aktivitas tetap aktif.
  • Memori agen hierarkis: Sistem produksi memisahkan status eksekusi sementara dari konteks yang tahan lama. Anda mengelola status sesi jangka pendek menggunakan Event(state=...) dan binding parameter, serta menghubungkan GEAP Memory Bank untuk mengekstrak, menggabungkan, dan menyimpan preferensi kreator di seluruh operasi.
  • Grounding dengan pusat informasi perusahaan: Agen otonom memerlukan konteks domain dinamis dan sentimen audiens. Anda menghubungkan korpus GEAP RAG Engine sebagai node pengambilan khusus dalam fan-out paralel untuk melakukan grounding semantik pada output agen.
  • Alur kerja dan deployment yang berjalan lama: Rendering video multimodal beroperasi secara asinkron dalam durasi yang lama. Anda menerapkan LongRunningFunctionTool dengan tanda terima panggilan tertunda untuk menangguhkan dan melanjutkan alur kerja berdasarkan ID panggilan, serta men-deploy pipeline yang telah selesai menggunakan Runner ADK di Cloud Run.

Cara codelab ini disusun

Codelab ini berfungsi sebagai referensi konseptual dan arsitektur Anda. Setiap bagian menjelaskan konstruksi ADK yang diimplementasikan dalam langkah workbench yang sesuai, memberikan kode referensi, dan menetapkan prinsip desain inti. Tinjau setiap bagian sebelum menyelesaikan latihan yang sesuai di workbench.

Pengerjaan langsung dilakukan di VibeStudio Workbench, antarmuka web pendamping yang menampilkan editor kode interaktif, verifier runtime, dan pemeriksa ADK yang disematkan. Penomoran langkah di workbench selaras langsung dengan codelab ini agar progres Anda tetap tersinkron. Pengeditan grafik dasar tetap ada di seluruh langkah, dan workbench akan otomatis memverifikasi prasyarat saat Anda melanjutkan.

Setelah menyelesaikan latihan workbench, Anda akan merakit pipeline agentik end-to-end dan men-deploy aplikasi VibeStudio yang sedang berjalan ke Cloud Run untuk membuat konten video.

Apa yang berjalan di mana: VibeStudio Workbench, backend Anda, dan layanan Google Cloud

Lingkungan ini terdiri dari tiga komponen utama: VibeStudio Workbench (antarmuka web lokal untuk pengeditan kode dan verifikasi runtime), backend Anda (sandbox ADK Workflow dan stage di agent/), dan Google Cloud (model Gemini, GEAP Memory Bank, RAG Engine, dan pembuatan video Veo).

2. Penyiapan

Klaim kredit workshop Anda

Jika Anda mengikuti lab yang dipandu instruktur, instruktur akan mendistribusikan kredit untuk project Google Cloud Anda. Ikuti petunjuk instruktur untuk menukarkan kredit dan memastikan penagihan aktif di akun Anda sebelum melanjutkan.

Buka Cloud Shell

Cloud Shell adalah lingkungan pengembangan berbasis browser yang dilengkapi dengan gcloud, Python, dan git.

Untuk meluncurkan Cloud Shell:

  1. Buka Google Cloud Shell.

Sesi terminal akan terbuka di bagian bawah jendela browser.

Membuat clone dan melakukan inisialisasi repositori

Jalankan perintah berikut di terminal Cloud Shell untuk meng-clone project:

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

Perintah konfigurasi

Selama penyiapan, Anda akan diminta untuk memberikan detail berikut:

  • Project ID Google Cloud: Saat diminta oleh setup_project.sh, tekan Enter untuk membuat project baru secara otomatis. Jika Anda lebih memilih untuk menggunakan project yang sudah ada (seperti project yang telah ditetapkan sebelumnya), masukkan project ID Anda dan pastikan ejaannya benar dengan penagihan yang aktif.
  • Kode acara: Masukkan kode ruang yang diberikan oleh instruktur Anda. Jika Anda tidak menerimanya, tanyakan kepada asisten pengajar atau tetangga. Jika Anda menyelesaikan lab ini di rumah, tekan Enter untuk menerima ruang sandbox default.
  • Nama tampilan channel: Masukkan nama atau nama sebutan channel pilihan Anda saat diminta oleh setup_codelab.sh, atau tekan Enter untuk menerima nama default yang dibuat dari Akun Google Anda.

Jalankan dua skrip penyiapan secara berurutan:

./setup_project.sh
./setup_codelab.sh
  • setup_project.sh: Membuat atau menggunakan kembali project Google Cloud dengan penagihan aktif, menyimpan project ID ke ~/project_id.txt, dan mengonfigurasi konteks gcloud yang aktif.
  • setup_codelab.sh: Menginstal uv dan dependensi Python ke .venv, mengaktifkan Google Cloud API yang diperlukan, mengonfigurasi setelan channel Anda di .env, memverifikasi akses model dengan Gemini, menyediakan resource Memory Bank dan RAG, membangun antarmuka workbench, dan memulai VibeStudio Workbench.

Skrip menjalankan pemeriksaan pra-penerbangan dan memulai VibeStudio Workbench di latar belakang. Baris terakhirnya menampilkan link yang akan dibuka.

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

Klik link tersebut. Alamat yang sama tersedia di Web Preview → Change port → 4600.

Untuk memeriksa ulang lingkungan kapan saja, jalankan python scripts/preflight.py. Untuk memulai ulang workbench, jalankan scripts/restart.sh. Untuk menyiapkan lagi, jalankan ./setup_codelab.sh; perintah ini akan mempertahankan konfigurasi dan progres Anda.

Setelah terbuka, baca langkah 1, Cerita, untuk skenarionya, dan langkah 2, Yang Anda bangun, untuk bentuk grafik yang sudah selesai. Keduanya tidak memiliki latihan. Kemudian, kembali ke sini untuk langkah 3.

Setiap bagian praktik langsung VibeStudio Workbench diakhiri dengan panel verifikasi yang membaca artefak sebenarnya: file di disk dan sesi yang ditulis oleh run.

Tata letak repositori

Repositori ini disusun ke dalam logika alur kerja inti, sandbox langkah demi langkah, lingkungan workbench, dan aplikasi produksi:

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/: Berisi grafik alur kerja inti. Anda akan mengedit file dalam direktori ini untuk mengimplementasikan node fan-out paralel, perutean kebijakan deterministik, callback memori, dan alat pembuatan video.
  • agent/platform/: Berinteraksi dengan layanan Google Cloud, termasuk model Gemini, GEAP Memory Bank, GEAP RAG Engine, dan sintesis video Veo.
  • stage0_prompt/ hingga stage6_video/: Lingkungan sandbox mandiri. Setiap folder mengekspor root_agent mandiri sehingga Anda dapat menjalankan dan memeriksa setiap langkah secara terpisah melalui antarmuka pengembangan ADK yang disematkan.
  • server/ dan web/: Aplikasi VibeStudio Workbench yang berjalan secara lokal di port 4600. Platform ini menghosting dokumentasi langkah, editor kode dalam halaman, pemverifikasi bukti runtime, dan visualisasi grafik.
  • vibestudio/: Aplikasi produksi lengkap yang dipaketkan dan di-deploy ke Cloud Run pada langkah terakhir. File ini berisi salinan mandiri dari grafik alur kerja yang telah selesai.

3. Agen monolitik

Sebelum membuat grafik alur kerja multi-node, Anda membuat dasar pengukuran arsitektur dengan satu agen di stage0_prompt/agent.py. Agen ini mengandalkan perintah sistem monolitik yang menjelaskan pipeline produksi dalam bentuk prosa, yang didukung oleh dua alat fungsi Python.

Mengevaluasi dasar pengukuran ini menunjukkan batasan operasional koordinasi berbasis perintah dan menetapkan alasan sistem produksi memerlukan orkestrasi grafik.

Arsitektur agen ADK (3A)

Di VibeStudio Workbench, buka Step 3 · Monolithic agent, lalu buka ADK agent architecture (3A). Tampilan ini menampilkan lapisan arsitektur inti agen ADK (LlmAgent):

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
)

Diagram interaktif mengelompokkan komponen agen ke dalam lima domain operasional:

  • Lapisan penalaran (Model): Model bahasa inti (seperti Gemini 3 Flash) yang menjalankan tugas kognitif, penalaran perintah, dan pemilihan alat. Semua hal lain dalam arsitektur akan menginformasikan atau membatasi model ini.
  • Lapisan konteks (Petunjuk dan Keterampilan): Perintah yang membentuk penalaran model. instruction menetapkan perintah sistem, kepribadian, dan aturan operasional permanen. skills memberikan panduan prosedural berversi (SKILL.md) untuk alur kerja yang dapat diulang.
  • Lapisan kolaborasi dan tindakan (Alat, Subagen, Alur Kerja, Skema Output): Antarmuka yang memungkinkan agen bertindak pada sistem eksternal dan memunculkan data yang diketik. tools menyediakan fungsi Python yang dapat dipanggil atau endpoint Model Context Protocol (MCP). subagents menjalankan tugas yang didelegasikan bawahan. workflow mengoordinasikan grafik multi-agen. output_schema menerapkan model Pydantic untuk menjamin konsumen downstream menerima JSON yang divalidasi, bukan teks tidak terstruktur.
  • Lapisan Interceptor (Callback Siklus Proses): Guardrail deterministik yang mengeksekusi kode kustom sebelum dan setelah eksekusi agen (before_agent/after_agent), giliran model individual (before_model/after_model), dan panggilan alat (before_tool/after_tool). Interceptor menerapkan aturan kebijakan tanpa mengandalkan kepatuhan model.
  • Status eksternal (Sesi dan Memori): Persistensi stateful yang dipisahkan dari logika agen. Session mempertahankan memori kerja sementara dan pelacakan peristiwa untuk thread eksekusi saat ini. Memory mempertahankan fakta dan preferensi lintas sesi yang tahan lama menggunakan layanan terkelola seperti GEAP Memory Bank.

Agen monolitik dalam langkah ini hanya mengimplementasikan tiga primitif ini: model, instruction, dan tools. Langkah-langkah berikutnya akan memperkenalkan alur kerja grafik, skema terstruktur, interceptor, dan layanan memori persisten.

Spesifikasi agen monolitik (3B)

Di workbench, lanjutkan ke Monolithic agent specification (3B). Buka stage0_prompt/agent.py untuk memeriksa definisi agen dasar pengukuran:

  • Petunjuk perintah tunggal: Perintah sistem meringkas lima tugas produksi yang berbeda menjadi prosa berkelanjutan: menemukan tren platform, meninjau ide backlog, mengusulkan konsep kreatif, menerapkan kebijakan subjek yang dilarang, dan menyusun daftar pengambilan gambar.
  • Sumber data pokok: Agen mereferensikan dua sumber yang ditentukan di samping grafik:
    • agent/trends.py: Mengambil sampel sepuluh tren format dan gaya aktif dari kumpulan 250 tren dengan skor popularitas dinamis.
    • agent/backlog.txt: Membaca catatan konsep mentah kreator baris demi baris.

Alat di Agen (3C)

Di workbench, lanjutkan ke Tools in Agent (3C).

Apa itu alat bagi agen?

Model bahasa pada dasarnya adalah mesin penalaran dunia tertutup: model ini hanya beroperasi berdasarkan bobot terlatih dan token yang ada di jendela konteks langsungnya. LLM tidak dapat membuat kueri database secara native, mengakses API real-time, atau menjalankan kode.

Alat menjembatani batas ini. Alat ini memberikan agensi eksternal kepada model, sehingga memungkinkannya mengambil informasi kebenaran nyata dan menjalankan tindakan deterministik di sistem eksternal.

03-3C

Panggilan alat mengikuti protokol lima tahap eksplisit antara model dan runtime ADK:

  1. Deklarasi skema: Developer menyediakan fungsi Python untuk agen. ADK memeriksa nama, anotasi jenis, dan docstring setiap fungsi untuk membuat deklarasi skema JSON yang kompatibel dengan OpenAPI yang menjelaskan parameter dan tujuannya.
  2. Penalaran model: Selama inferensi, model mengevaluasi apakah perintah pengguna memerlukan data eksternal. Jika diperlukan, model akan memunculkan peristiwa function_call terstruktur yang berisi nama fungsi target dan kamus argumen yang cocok dengan skema.
  3. Eksekusi runtime: Model itu sendiri tidak mengeksekusi kode. Runtime ADK menangkap function_call, menjalankan fungsi Python lokal yang sebenarnya menggunakan argumen yang disediakan, dan mengambil nilai yang ditampilkan.
  4. Injeksi ulang konteks: Runtime ADK mengemas nilai yang ditampilkan fungsi ke dalam peristiwa function_response dan menambahkannya ke histori sesi aktivitas aktif.
  5. Sintesis akhir: Model memproses output alat yang kini ada di jendela konteksnya dan menyelesaikan responsnya.

Di stage0_prompt/agent.py, kedua alat riset didefinisikan sebagai fungsi Python standar:

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()}

Pengeditan dan eksekusi langsung

Di editor kode workbench, tambahkan dua referensi fungsi ke daftar tools agen:

    tools=[check_trends, read_backlog],

Simpan perubahan. File akan diupdate di disk, dan baris verifikasi mengonfirmasi bahwa kedua alat telah terhubung.

Klik Open adk web untuk meluncurkan antarmuka pengembangan ADK tersemat. Kirim perintah ide yang disarankan:

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

Yang akan terjadi dan alasannya

Saat Anda mengirim perintah ini, amati urutan eksekusi berikut dalam rekaman aktivitas sesi:

  • Dua peristiwa eksekusi alat muncul sebelum respons: Anda melihat peristiwa function_call dan function_response untuk check_trends dan read_backlog.
    • Alasan: Gemini mengevaluasi arahan perintah sistem ("periksa apa yang sedang trending. lihat backlog ide Anda"), menyadari bahwa perintah tersebut tidak memiliki tren platform dan catatan channel dalam bobotnya, dan memanggil kedua fungsi untuk mendasari konteksnya.
  • Agen mengusulkan arah dan berhenti sejenak untuk menunggu konfirmasi: Respons menyarankan arah video yang menyintesis tren dan backlog, serta meminta Anda untuk mengonfirmasi.
    • Alasan: Arahan instruksi meminta model untuk menyetujui arah dengan kreator sebelum membuat skrip.
  • Melewati konfirmasi dalam giliran percakapan lanjutan: Kirim pesan kedua: skip the questions, just describe the video. Agen segera mengabaikan konfirmasi dan membuat draf judul serta pengambilan gambar.
    • Alasan: Petunjuk perintah adalah panduan saran, bukan batasan deterministik. Dalam agen monolitik, petunjuk pengguna dapat menggantikan aturan perintah sistem yang berlaku karena tidak ada alur kerja eksternal yang mengontrol alur eksekusi.

Batasan arsitektur perintah monolitik

Meskipun satu perintah dapat menghasilkan output yang dapat diterima untuk demo terisolasi, pengujian kondisi batas di verifikator workbench mengungkapkan batasan penting perusahaan:

  • Agregasi riset tidak terstruktur: Urutan eksekusi alat bersifat non-deterministik. Model ini meringkas data yang diambil menjadi prosa bentuk bebas, sehingga sistem downstream tidak dapat mengisolasi sumber mana yang menghasilkan klaim tertentu.
  • Penegakan kebijakan yang belum diverifikasi: Model mengevaluasi kepatuhan keamanannya sendiri. Jika model menentukan bahwa suatu topik aman, tidak ada logika deterministik eksternal yang memvalidasi temuan tersebut.
  • Jeda human-in-the-loop yang tidak diterapkan: Petunjuk perintah yang meminta konfirmasi kreator bersifat saran. Mengirim pesan tindak lanjut yang menginstruksikan model untuk mengabaikan pertanyaan akan menyebabkan model melewati persetujuan manusia sepenuhnya.

Kesenjangan arsitektur ini mendorong dekomposisi agen monolitik menjadi alur kerja grafik eksplisit yang dibangun pada langkah berikutnya.

4. Dasar-dasar Agentic Workflows

Di VibeStudio Workbench, buka Step 4 · Agentic workflow fundamentals, bagian 4A hingga 4D.

Langkah ini beralih dari dasar pengukuran agen tunggal ke orkestrasi grafik deterministik menggunakan Workflow ADK. Anda akan membangun fan-out riset paralel, menyinkronkan cabang dengan node gabungan, membuat kandidat materi iklan yang divalidasi skemanya, dan memperkenalkan gerbang persetujuan human-in-the-loop yang deterministik.

Arsitektur grafik dan rantai eksekusi (4A)

Di workbench, buka Graph architecture and execution chains (4A).

Workflow ADK menyusun eksekusi agen sebagai grafik terarah yang ditentukan oleh daftar edge:

  • Chains: Tuple berurutan menentukan eksekusi node linear ((node_a, node_b, node_c)).
  • Cabang paralel: Rantai independen yang berbagi node asal dieksekusi secara serentak.
  • Sinkronisasi: Rantai yang menyatu pada JoinNode menunggu hingga semua cabang masuk melaporkan sebelum dilepaskan.
  • Kontrol deterministik: Alur eksekusi diatur oleh struktur kode yang dideklarasikan, bukan disimpulkan dari teks perintah.

04-4A

Arketipe node di ADK

Alur kerja ADK terdiri dari beberapa jenis node khusus. Setiap arketipe menjalankan peran operasional tertentu dalam grafik, yang memisahkan eksekusi kode deterministik dari penalaran model generatif:

Arketipe Node

Penerapan

Peran dalam Pipeline

Function node

Fungsi Python yang menampilkan Event

Menjalankan logika deterministik, pengambilan data, dan mutasi status.

Node gabungan

Instance JoinNode bawaan

Menyinkronkan cabang serentak ke dalam kamus gabungan.

Node agen

Agent berjalan dalam mode single_turn

Mengevaluasi petunjuk terhadap input upstream dan memunculkan data yang divalidasi.

Router node

Fungsi yang menampilkan Event dengan tag route

Mengevaluasi logika kondisional untuk memilih cabang eksekusi downstream.

Node input manusia

Fungsi yang menghasilkan RequestInput

Menangguhkan status eksekusi hingga respons pengguna eksternal diterima.

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

Dalam konfigurasi ini, root_agent adalah instance Workflow, bukan Agent mandiri. ADK memperlakukan alur kerja sebagai agen kelas satu, sehingga seluruh grafik dapat dimuat, disajikan, dan diperiksa sebagai aplikasi terpadu. name mendaftarkan aplikasi di ADK Web, sedangkan daftar edges menentukan topologi eksekusinya.

Fan-out riset paralel (4B)

Di workbench, lanjutkan ke Parallel research fan-out (4B). Buka stage1_fanout/agent.py.

04-4B

Node fungsi dan penghalang sinkronisasi

Fase riset menggunakan dua node fungsi yang diimpor dari agent/graph.py:

  • scan_trends: Menampilkan Event(output={"trends": [...]}) yang berisi sepuluh tren platform yang diberi skor.
  • read_backlog: Menampilkan Event(output={"backlog": [...], "idea": "..."}) yang berisi lima belas ide backlog channel beserta perintah eksekusi awal.

Setiap fungsi menerima node_input (output node sebelumnya) dan menampilkan Event.

JoinNode berfungsi sebagai penghalang sinkronisasi: node ini akan dijeda hingga setiap rantai masuk mengirimkan peristiwa, lalu menggabungkan semua hasil cabang ke dalam kamus yang diberi kunci berdasarkan nama node ({"scan_trends": {...}, "read_backlog": {...}}).

Pengeditan langsung: menentukan tepi gabungan dan paralel

Di stage1_fanout/agent.py, buat instance JoinNode dan hubungkan dua rantai paralel yang dimulai dari START:

join_research = JoinNode(name="join_research")
    edges=[(START, scan_trends, join_research),
           (START, read_backlog, join_research)])

Simpan perubahan. Pemverifikasi workbench mengonfirmasi bahwa join dan edge telah terhubung. Jalankan tahap menggunakan Run Stage 1 atau melalui antarmuka Web ADK yang disematkan.

Yang akan terjadi dan alasannya

  • Eksekusi pembaca serentak: Dalam grafik eksekusi, scan_trends dan read_backlog dijalankan secara bersamaan.
    • Alasan: Kedua rantai berasal dari START. Mesin ADK menjadwalkan cabang independen secara serentak.
  • Output kamus gabungan: Alur kerja selesai pada join_research, yang menghasilkan kamus dengan entri untuk kedua pembaca.
    • Alasan: JoinNode memastikan pengambilan data selesai sebelum mengizinkan node berikutnya dieksekusi.

Node agen (4C)

Di workbench, lanjutkan ke Agent nodes (4C). Buka stage2_direction/agent.py.

04-4C

Mode operasi dan skema terstruktur

Saat disematkan dalam Workflow, Agent berjalan dalam mode single_turn secara default:

  • Node ini menerima output node sebelumnya sebagai input konteksnya.
  • API ini menjalankan satu panggilan inferensi tanpa percakapan bolak-balik.
  • Node ini menghasilkan data terstruktur ke node berikutnya.

Dengan menetapkan output_schema=Directions, agen menerapkan validasi Pydantic pada output model. Grafik downstream menerima objek yang diketik, bukan prosa yang tidak terstruktur:

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 mengarahkan model untuk mengusulkan empat kandidat dengan mengutip bukti dari tren dan backlog. Kandidat 1 hingga 3 menawarkan konsep channel yang layak. Kandidat 4 sengaja memperkenalkan konsep yang melanggar kebijakan untuk menguji gerbang keamanan pada langkah berikutnya.

Pengeditan langsung: menentukan node agen dan merangkai join

Di stage2_direction/agent.py, konfigurasikan propose_directions dan perluas tepi alur kerja:

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)])

Yang akan terjadi dan alasannya

  • Konsumsi kamus langsung: propose_directions menggunakan payload JSON yang dikeluarkan oleh join_research tanpa pemformatan manual.
  • Output kandidat yang diketik: Agen memunculkan objek Directions yang divalidasi yang berisi empat kandidat terpisah. Node hilir membaca kolom berdasarkan nama atribut (candidate.title) tanpa parsing string.

Human-in-the-loop (4D)

Di workbench, lanjutkan ke Human-in-the-loop (4D). Buka agent/graph.py.

04-4D

Petunjuk perintah versus penangguhan deterministik

Alur kerja produksi yang menimbulkan biaya finansial atau memublikasikan konten memerlukan pengawasan manusia pada titik keputusan penting. Dalam satu perintah, permintaan konfirmasi adalah petunjuk saran yang dapat dengan mudah diminta oleh pengguna untuk diabaikan oleh model. Dalam alur kerja ADK, persetujuan manusia diterapkan oleh mesin eksekusi: grafik berhenti di node yang ditentukan dan tidak dapat dilanjutkan hingga menerima input eksternal yang divalidasi skemanya:

  • Yielding RequestInput akan segera menangguhkan eksekusi alur kerja.
  • ADK mencatat panggilan interupsi terbuka di penyimpanan sesi dan mengeluarkan interrupt_id unik.
  • Proses eksekusi berhenti tanpa menggunakan token atau thread server.
  • Eksekusi grafik hanya akan dilanjutkan jika function_response yang valid dan cocok dengan skema serta ID interupsi dikirimkan.

Pengeditan langsung: menangguhkan eksekusi dengan RequestInput

Di agent/graph.py, implementasikan panggilan penangguhan di dalam direction_gate:

    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 mengonfigurasi tiga atribut:

  • message: Dialog ulasan yang ditampilkan kepada pengguna.
  • response_schema: Skema JSON yang dirender frontend sebagai formulir input, yang divalidasi oleh ADK saat dikirimkan.
  • payload: Metadata yang dipaketkan dengan permintaan (empat kandidat), sehingga antarmuka klien dapat merender kartu ulasan tanpa mengkueri status sesi.

Yang akan terjadi dan alasannya

  • Alur kerja berhenti di direction_gate: Di ADK Web atau antarmuka workbench, operasi akan dijeda dan menampilkan formulir pemilihan kandidat interaktif.
    • Alasan: Mesin menemukan RequestInput yang dihasilkan dan mempertahankan status eksekusi ke runs/sessions.db.
  • Lanjutan memerlukan input terstruktur: Mengirim teks chat arbitrer tidak akan memajukan grafik. Memilih opsi (1, 2, 3, atau 4) akan mengirimkan function_response yang diketik dan memenuhi response_schema serta melanjutkan eksekusi.

5. Status dan Router

Di VibeStudio Workbench, buka Step 5 · State and Router, bagian (5A) hingga (5C).

Anda akan mempertahankan pilihan pengguna ke dalam status sesi, menerapkan kebijakan keamanan channel menggunakan node perute deterministik, dan menyusun agen tugas iteratif untuk secara otomatis memperbaiki pelanggaran kebijakan sebelum membuat skrip video.

Status Alur Kerja (5A)

Di workbench, buka Workflow State (5A).

05-5A

Status sesi vs. output node

Dalam alur kerja ADK, data berpindah di seluruh grafik melalui dua mekanisme yang berbeda:

  • Output node (Event(output=...)): Data yang diarahkan secara ketat ke konsumen downstream langsung yang ditentukan dalam daftar edge.
  • Status sesi (Event(state=...)): Kamus nilai kunci bersama yang dapat diakses oleh node berikutnya dalam siklus proses eksekusi.

05-5A

Saat pengguna memilih kandidat di direction_gate, pilihan akan diterima sebagai indeks numerik ({"pick": "2"}). Node downstream memerlukan objek arahan lengkap: judul, sudut narasi, dan kalimat pembuka. Daripada meneruskan metadata panjang melalui setiap payload node perantara, persist_direction menulis kandidat yang diselesaikan ke status sesi bersama.

Node tidak perlu meneruskan seluruh kamus status sesi. Saat menghasilkan Event(state=...), node hanya menyediakan pasangan nilai kunci baru atau yang diperbarui. ADK otomatis menggabungkan update ini ke penyimpanan sesi:

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

Menghasilkan Event ini akan menyerahkan kontrol ke runtime Workflow, yang mempertahankan nilai baru ke jurnal sesi di runs/sessions.db.

Binding parameter

Node fungsi ADK membaca status sesi secara otomatis melalui pemeriksaan parameter. Jika tanda tangan fungsi mendeklarasikan nama parameter yang cocok dengan kunci status yang ada, ADK akan mengekstrak kunci tersebut dari status dan meneruskannya secara langsung:

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])

Di sini, candidates ditulis ke status sesi oleh direction_gate. ADK mengikatnya langsung ke persist_direction(node_input, candidates: list = []) tanpa memerlukan pencarian kamus eksplisit.

Kunci yang diawali dengan user: akan dipertahankan di seluruh sesi dalam penyimpanan tingkat pengguna, sehingga eksekusi alur kerja berikutnya dapat mengakses preferensi kreator.

Pengeditan langsung: mempertahankan status dan menghubungkan node

  1. Di agent/graph.py, di dalam persist_direction, ganti baris TODO: PERSIST_STATE dengan hasil peristiwa status:
    yield Event(state={"direction": chosen["title"], "angle": chosen.get("angle", ""),
                       "hook": hook, "user:prefs": {"last_direction": chosen["title"]}})
  1. Di stage3_router/agent.py, tambahkan persist_direction ke rantai ketiga dalam daftar edges:
           (join_research, propose_directions, direction_gate,
            persist_direction)

Simpan file Anda. Di workbench, pastikan state write in place dan persist_direction in the chain menampilkan tanda centang hijau.

Node router (5B)

Di workbench, buka The router node (5B).

05-5B

Pemilihan rute kebijakan deterministik

Router adalah node fungsi khusus yang mengevaluasi output upstream dan mengarahkan eksekusi di sepanjang cabang grafik bersyarat. Tidak seperti agen generatif, router menjalankan logika deterministik tanpa melakukan panggilan LLM.

Router menampilkan Event yang menentukan tag route:

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")

Dalam definisi alur kerja, target edge yang ditentukan sebagai kamus memetakan nama rute ke node tujuan:

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

Router alur kerja policy_check membaca frasa yang dilarang dari agent/policy_words.txt dan melakukan pencocokan kata utuh dengan judul dan sudut arah yang dipilih:

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

Menyimpan kebijakan sebagai data, bukan sebagai petunjuk yang dikodekan secara permanen, memungkinkan pembaruan tanpa mengubah grafik alur kerja: pembaruan file teks langsung diterapkan pada proses berikutnya. Karena evaluasi adalah pencocokan ekspresi reguler deterministik, evaluasi ini dijalankan dalam milidetik tanpa biaya token sebelum pembuatan skrip generatif dimulai.

Tujuan: Scripter dan Karantina

Router mengarahkan traffic ke salah satu dari dua node downstream:

  • scripter: Node agen single_turn yang mengonversi arahan yang disetujui menjadi skrip produksi terstruktur yang mematuhi skema Pydantic Script:
scripter = Agent(
    name="scripter",
    model=config.MODEL,
    instruction=SCRIPT_INSTRUCTION,
    output_schema=Script)
  • quarantine: Awalnya merupakan fungsi placeholder yang menghentikan petunjuk yang ditandai, diganti di bagian berikutnya oleh agen perbaikan mandiri.

Pengeditan langsung: mengarahkan pemeriksaan kebijakan

  1. Di agent/graph.py, di dalam policy_check, lengkapi pernyataan return:
    return Event(output=node_input, route="BLOCK" if bad else "OK")
  1. Di stage3_router/agent.py, perbarui edges untuk merutekan policy_check dan menggabungkan kembali cabang karantina ke scripter:
           (join_research, propose_directions, direction_gate,
            persist_direction, policy_check),
           (policy_check, {"OK": scripter, "BLOCK": quarantine}),
           (quarantine, scripter)])

Simpan file Anda. Di workbench, pastikan pemetaan edge router telah diverifikasi.

Mode agen dan node tugas (5C)

Di workbench, buka Agent modes and the task node (5C).

05-5C

Mode eksekusi agen

Instance ADK Agent mendukung tiga mode eksekusi yang disesuaikan dengan persyaratan pipeline tertentu:

Mode

Siklus Proses Eksekusi

Peran dalam Pipeline

chat

Loop percakapan multi-turn. Model menentukan kapan harus memanggil alat, meminta input, atau mengakhiri giliran.

Agen root yang berinteraksi dengan pengguna manusia.

single_turn

Panggilan inferensi model tunggal. Menerima input node sebelumnya dan memancarkan objek skema terstruktur.

Transformasi grafik berurutan (propose_directions, scripter).

task

Loop otonom dengan eksekusi alat. Agen melakukan iterasi hingga memanggil alat finish_task bawaan.

Remediasi dan pemeriksaan multilangkah (quarantine).

Perbaikan kebijakan otonom

Penulisan ulang arah yang ditandai memerlukan mode task karena jumlah iterasi perbaikan bervariasi. Agen menerima petunjuk yang ditandai, memanggil find_policy_hits untuk mendeteksi pelanggaran, meminta alternatif yang disetujui melalui suggest_replacement, menulis ulang petunjuk, dan memverifikasi kebersihan sebelum melanjutkan.

Kedua alat tersebut ditentukan di agent/cleanup_tools.py dengan tanda tangan dan docstring yang diketik:

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

Pengeditan langsung: merakit agen tugas karantina

Di stage3_router/agent.py, ganti fungsi placeholder quarantine dengan definisi agen tugas:

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

Mode tugas melengkapi agen dengan alat dan menghentikan eksekusi dengan memanggil finish_task. Saat mode="task" dikonfigurasi, ADK otomatis menyediakan finish_task dan memperoleh parameternya dari output_schema, sehingga memastikan node menghasilkan objek CleanedDirection yang diketik yang cocok dengan skema input node scripter.

05-5C

Yang akan terjadi dan alasannya

Uji kedua jalur eksekusi di ADK Web atau VibeStudio Workbench:

  • Rute yang disetujui (Kandidat 1, 2, atau 3):
    • Memilih rute kandidat yang disetujui dari policy_check langsung ke scripter (route="OK").
    • Penulis skrip membuat skrip produksi 3-shot yang mematuhi skema Script.
  • Rute perbaikan karantina (Kandidat 4):
    • Kandidat 4 berisi kosakata yang ditandai ("clickbait", "trik viral").
    • policy_check rute ke quarantine (route="BLOCK").
    • Dalam rekaman aktivitas sesi, amati quarantine yang memanggil find_policy_hits, memanggil suggest_replacement untuk setiap pelanggaran, menulis ulang judul, dan memanggil finish_task.
    • Eksekusi bergabung kembali dengan scripter, menghasilkan skrip dari arah yang telah disanitasi.

6. Memory Bank

Di VibeStudio Workbench, buka Step 6 · Memory Bank, bagian (6A) dan (6B).

Alur kerja saat ini beroperasi tanpa memori di seluruh sesi. Setiap eksekusi dimulai dari awal, tanpa mengetahui apa yang dipilih kreator sebelumnya atau genre yang mereka sukai. Pada langkah ini, Anda akan menghubungkan Vertex AI Agent Engine Memory Bank untuk menyimpan dan mengambil preferensi kreator di seluruh operasi.

Yang terpenting, memori diintegrasikan melalui callback siklus proses agen, bukan node pipeline. Karena ekstraksi dan pengambilan memori melayani agen individual, bukan tahap data perantara, melampirkan callback akan mempertahankan topologi grafik yang bersih dan terpisah.

Memory Bank (6A)

Di workbench, buka Memory Bank (6A).

06-6A

Memori tingkat pengguna terkelola

Memory Bank adalah layanan terkelola untuk memori pengguna jangka panjang. Fitur ini mengatur fakta tentang seseorang dalam cakupan yang ditentukan, yang di sini diidentifikasi oleh nama aplikasi dan ID pengguna:

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).",
}

Topik memori kustom menentukan batasan hal yang dicatat oleh bank:

  • Ekstraksi topik: Saat teks percakapan baru dikirimkan melalui memories.generate, layanan akan menerapkan model ekstraksi terhadap setiap deskripsi topik. Teks yang tidak cocok dengan topik tidak akan menghasilkan kenangan.
  • Konsolidasi dan penghapusan duplikat: Layanan ini mengonversi fakta yang baru diekstrak menjadi embeddings dan membandingkannya dengan memori yang ada dalam cakupan. Jika pengamatan sesuai dengan memori yang ada, layanan akan memperbarui memori tersebut. Jika informasi yang diberikan baru, layanan akan membuat entri baru. Proses konsolidasi ini memastikan beberapa sesi tentang suatu topik digabungkan menjadi ringkasan yang koheren, bukan menghasilkan entri yang redundan.
  • Pengambilan: Memanggil memories.retrieve dengan cakupan pengguna akan menampilkan fakta yang disimpan, diurutkan dari yang terlama.

Kedua operasi diimplementasikan di agent/platform/memory.py. Nama resource bank yang disediakan di-cache secara lokal di runs/memorybank.json.

Menyiapkan Memory Bank

Gunakan kontrol workbench atau jalankan perintah CLI di terminal Anda:

  1. Hubungkan dan sediakan bank:
    python -m agent.platform.bank
    
    Membuat instance Agent Engine serta mengonfigurasi topik CREATOR_TASTE dan CHANNEL_RULES.
  2. Menyisipkan sesi historis:
    python -m agent.platform.bank load
    
    Memuat empat sesi historis kreator (dua tema hewan dengan batasan gaya, satu tema gadget, dan satu tema fantasi terbaru).
  3. Memeriksa fakta gabungan:
    python -m agent.platform.bank list
    
    Periksa outputnya. Perhatikan bagaimana transkrip naratif dikonversi menjadi pernyataan fakta yang terstruktur dan terkonsolidasi.

Callback (6B)

Di workbench, buka Callbacks (6B). Buka stage4_memory/agent.py.

06-6A

Callback siklus proses agen ADK

Callback adalah fungsi yang diteruskan sebagai argumen ke Agent. ADK memanggil callback pada momen siklus proses yang telah ditentukan sebelumnya, dengan meneruskan konteks aktif. Menampilkan None akan melanjutkan eksekusi normal; menampilkan objek pengganti akan menggantikan atau mencegat operasi.

06-6A

ADK menyediakan tiga pasang callback:

Pasangan Callback

Titik Pemanggilan

Parameter yang Diterima

Perilaku Nilai yang Ditampilkan

before_agent_callback
after_agent_callback

Mengelilingi seluruh giliran agen

CallbackContext (status, sesi, pemanggilan)

Menampilkan Content akan menggantikan balasan agen; None akan melanjutkan proses secara normal.

before_model_callback
after_model_callback

Mengelilingi setiap panggilan inferensi LLM

LlmRequest atau LlmResponse

Menampilkan LlmResponse akan memotong atau melewati panggilan model; None akan melanjutkan.

before_tool_callback
after_tool_callback

Di sekitar setiap eksekusi alat

Definisi alat, argumen, hasil

Menampilkan dict akan mengganti output alat; None akan dilanjutkan.

Callback menyediakan lokasi yang bersih untuk injeksi konteks, guardrail, telemetri, dan pencarian cache tanpa memasukkan node asing ke dalam grafik alur kerja.

Pengeditan langsung: menghubungkan callback recall dan remember

  1. Di stage4_memory/agent.py, update propose_directions untuk melampirkan before_model_callback=recall_taste:
    output_schema=Directions,
    before_model_callback=recall_taste)

recall_taste dijalankan tepat sebelum Gemini membuat rute kandidat. Alat ini mengambil histori kreator dari Memory Bank, memformat memori dari yang terlama, dan menambahkannya ke LlmRequest keluar. Perintah ini mengarahkan model untuk mengarahkan kandidat 1 hingga 3 ke selera kreator saat ini, sekaligus memperlakukan aturan channel sebagai batasan yang ketat.

  1. Di stage4_memory/agent.py, perbarui scripter untuk melampirkan after_agent_callback=remember_pick:
    output_schema=Script,
    after_agent_callback=remember_pick)

remember_pick berjalan setelah scripter menyelesaikan gilirannya. Alat ini membaca arahan yang dipilih dari status sesi, menyintesis pernyataan ringkas yang merangkum keputusan kreator, dan memanggil memories.generate untuk memperbarui Memory Bank.

Yang akan terjadi dan alasannya

Uji alur kerja yang ditingkatkan dengan callback di workbench atau ADK Web:

  1. Jalankan eksekusi dengan perintah kosong:
    • Dalam rekaman aktivitas sesi, periksa LlmRequest untuk propose_directions. Perhatikan konteks memori yang ditambahkan yang menjelaskan preferensi kreator untuk tema fantasi dan tempo yang ringkas.
    • Amati saran arah: kandidat 1 hingga 3 sesuai dengan preferensi historis kreator meskipun tren menekankan topik lain.
  2. Pilih kandidat di direction_gate.
  3. Setelah scripter selesai, tinjau data Memory Bank:
    python -m agent.platform.bank list
    
    Bank kini mencerminkan pilihan terbaru, menggabungkannya dengan catatan selera sebelumnya.

7. Mesin RAG

Di VibeStudio Workbench, buka Step 7 · RAG Engine, bagian (7A) dan (7B).

07-7A

Video yang dipublikasikan mengumpulkan masukan penonton yang berkelanjutan. Tiga puluh komentar representatif dikumpulkan di agent/comments.md, yang mencakup pujian penonton, kritik terhadap kecepatan konten bersponsor, dan preferensi audio. Pada langkah ini, Anda akan mengindeks komentar ini menggunakan Vertex AI RAG Engine dan menghubungkan pengambilan semantik ke fan-out riset.

Pengambilan dokumen (7A)

Di workbench, buka RAG Engine (7A).

Memory Bank vs. Mesin RAG

Kedua alat ini mendasarkan alur kerja pada data eksternal, tetapi memiliki tujuan arsitektur yang berbeda:

Dimensi

Memory Bank

Mesin RAG

Kasus Penggunaan Utama

Preferensi pengguna jangka panjang dan aturan operasional

Pengambilan semantik pada koleksi dokumen yang besar

Cakupan

Ditetapkan ke ID pengguna dan nama aplikasi tertentu

Dicakupkan ke resource korpus bersama di semua pengguna

Pemrosesan Data

Ekstraksi, penyematan, dan konsolidasi semantik real-time

Chunking dokumen, embedding vektor, dan penelusuran tetangga terdekat

Integrasi Grafik

Callback siklus proses agen (before_model_callback, after_agent_callback)

Node fungsi khusus dalam fan-out riset (read_feedback)

07-7A

Pengelompokan dan penyematan dokumen

RAG Engine mengindeks dokumen dengan membagi teks menjadi bagian semantik dan menyimpan vektornya dalam database terkelola:

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)))
  • Ukuran potongan: Dikonfigurasi ke 120 token dengan tumpang-tindih 20 token. Hal ini mencakup dua hingga tiga komentar per bagian, sehingga memastikan setiap vektor merepresentasikan sentimen yang kohesif tanpa mengurangi makna di seluruh masukan yang tidak terkait.
  • Model embedding: text-embedding-005 mengonversi teks menjadi vektor berdimensi tinggi. Saat kueri dikirimkan, model akan mengonversi kueri menjadi vektor dan menemukan kecocokan terdekat berdasarkan jarak semantik. Komentar tentang naga kecil yang menjaga kaus kaki cocok dengan perintah tentang makhluk ajaib tanpa memerlukan kecocokan kata kunci yang sama persis.

Menyiapkan korpus RAG

Lakukan inisialisasi korpus menggunakan tombol workbench atau perintah terminal:

  1. Buat korpus:
    python -m agent.platform.rag
    
    Menyediakan database vektor terkelola dan mencatat ID resource di runs/ragcorpus.json.
  2. Mengupload dan mengindeks komentar: Mengupload agent/comments.md dengan konfigurasi chunking dan menunggu pengindeksan selesai.
  3. Membuat kueri korpus: Uji pengambilan kesamaan dengan kueri yang tidak memiliki kata yang sama persis dengan komentar (misalnya, kueri "makhluk ajaib kecil" untuk mengambil komentar tentang naga).

Node pengambilan (7B)

Di workbench, buka The third reader (7B). Buka stage5_rag/agent.py.

07-7B

Pengambilan sebagai node grafik

Masukan audiens merepresentasikan data riset yang dibagikan di seluruh alur kerja. Tidak seperti memori kreator pribadi, sentimen penonton dimasukkan langsung ke join_research bersama dengan tren dan data backlog. Oleh karena itu, node ini diimplementasikan sebagai node fungsi:

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 mengekstrak ide awal pengguna dan menjalankan kueri vektor terhadap korpus RAG Engine. Fungsi ini memunculkan komentar yang diambil dalam payload Event(output=...).

Pengeditan langsung: menghubungkan pembaca ketiga ke fan-out

Di stage5_rag/agent.py, perbarui edges untuk menambahkan read_feedback sebagai cabang paralel ketiga yang memasuki join_research:

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

Karena join_research adalah JoinNode, operator ini menyinkronkan semua cabang yang masuk, menunggu hingga scan_trends, read_backlog, dan read_feedback semuanya memunculkan peristiwa sebelum meneruskan paket gabungan ke downstream.

Yang akan terjadi dan alasannya

Jalankan alur kerja di workbench:

  1. Kirimkan perintah ide (seperti "naga mini yang menjaga meja dapur").
  2. Dalam trace eksekusi, pastikan ketiga node pembaca dijalankan secara serentak.
  3. Amati join_research: kamus outputnya kini berisi trends, backlog, dan feedback.
  4. Periksa kandidat yang dihasilkan dari propose_directions: model ini menggabungkan komentar penonton ke dalam proposalnya dan mereferensikan sentimen audiens di kolom bukti.
  5. Perhatikan bahwa pengambilan RAG bersifat deterministik (kueri yang sama akan menampilkan bagian komentar yang sama), sedangkan node proposal generatif menghasilkan variasi kreatif.

8. Pembuatan video asinkron dengan Veo

Di VibeStudio Workbench, buka Step 8 · The video, bagian (8A) dan (8B).

Membuat video definisi tinggi dengan Google Veo memerlukan waktu beberapa menit per rendering. Pemblokiran eksekusi grafik selama periode ini akan membuang-buang resource komputasi, mengunci kumpulan thread, dan membuat run rentan terhadap gangguan koneksi HTTP. Pada langkah ini, Anda akan membuat rendering video asinkron menggunakan LongRunningFunctionTool ADK.

Alat yang berjalan lama (8A)

Di workbench, buka A long-running tool (8A). Buka stage6_video/agent.py dan agent/deliver.py.

08-8A

Alat sinkron vs alat yang berjalan lama

Alat fungsi ADK standar dijalankan secara sinkron di dalam giliran agen: model memanggil alat, menunggu payload yang ditampilkan, dan menggabungkan hasilnya ke dalam giliran yang sedang berlangsung.

Rendering video tidak dapat diselesaikan dalam satu giliran. Sebagai gantinya, render_submit akan memulai tugas pembuatan dan segera menampilkan tanda terima operasional dengan status "pending":

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"]}

Jika digabungkan dengan LongRunningFunctionTool, ADK akan menangkap status "pending". Giliran agen berakhir, alur kerja ditangguhkan di node, dan metadata panggilan yang tertunda (termasuk ID panggilan dan tanda terima) dicatat di runs/sessions.db. Proses eksekusi keluar dengan bersih tanpa mempertahankan koneksi jaringan atau thread pekerja yang aktif.

Pengeditan langsung: membungkus alat rendering

Di stage6_video/agent.py, perbarui render_desk untuk menggabungkan render_submit di LongRunningFunctionTool:

    tools=[LongRunningFunctionTool(render_submit)])

Melanjutkan panggilan berdasarkan ID panggilan

Pola pelanjutan universal

ADK menerapkan mekanisme yang sama untuk menangguhkan dan melanjutkan alur kerja, baik untuk manusia maupun alat eksternal:

Pemicu Penangguhan

Memulai Konstruksi

Status Penangguhan Tersimpan

Peristiwa Lanjutan

Keputusan Manual

yield RequestInput(...)

Membuka perintah input di penyimpanan sesi

FunctionResponse yang membawa ID panggilan penangguhan

Alat yang Berjalan Lama

LongRunningFunctionTool(...) mengembalikan pending

Membuka panggilan alat di penyimpanan sesi

FunctionResponse yang membawa ID panggilan penangguhan

Dalam kedua skenario, alur kerja berhenti sepenuhnya dan hanya dilanjutkan saat peristiwa yang memiliki FunctionResponse yang cocok tiba dari sumber eksternal: antarmuka pengguna, webhook, atau worker latar belakang.

Pengeditan langsung: menyelesaikan respons pengiriman

Di agent/deliver.py, buat bagian FunctionResponse untuk melanjutkan:

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

Daemon pengiriman melakukan polling pada Veo hingga file video dibuat, lalu mengirimkan FunctionResponse ini ke sesi. ADK mencocokkan ID panggilan dan melanjutkan alur kerja langsung di node berikutnya. Node yang telah selesai tidak akan dieksekusi ulang, dan agen tidak akan mengambil giliran generatif lain.

Menetapkan STUDIO_REAL_VIDEO=0 di .env memungkinkan rendering tiruan: start menampilkan tanda terima pengujian langsung, dan check menyimulasikan penyelesaian dalam lima detik tanpa melakukan panggilan API Veo yang dapat ditagih.

Integrasi pipeline (8B)

Di workbench, buka render_desk di grafik (8B). Buka stage6_video/agent.py.

Node terminal dalam pipeline adalah store_video. Proses ini membaca informasi render yang telah selesai dari runs/state.json (tempat proses penayangan merekamnya) dan melakukan URL video serta status pembuatan ke status sesi bersama.

08-8B

Pengeditan langsung: menghubungkan seluruh pipeline video

Di stage6_video/agent.py, perbarui edges untuk menambahkan render_desk dan store_video:

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

Yang akan terjadi dan alasannya

Uji alur pembuatan asinkron di workbench:

  1. Jalankan alur kerja melalui pemilihan kandidat dan pembuatan skrip.
  2. Di render_desk, amati agen memanggil render_submit.
  3. Alur kerja akan segera ditangguhkan. Di workbench atau ADK Web, amati status tertunda: sesi menyimpan ID panggilan terbuka, dan tidak ada proses latar belakang yang menggunakan resource.
  4. Jalankan daemon penayangan menggunakan konsol workbench atau di terminal Anda:
    python -m agent.deliver
    
    Proses pengiriman memantau Veo hingga video siap, lalu mengirimkan peristiwa dimulainya kembali.
  5. Di ADK Web, muat ulang sesi: eksekusi dilanjutkan di store_video, melakukan URL video ke status sesi, dan menyelesaikan alur kerja.

9. Men-deploy ke Cloud Run

Di VibeStudio Workbench, buka Step 9 · Deploy.

Anda telah mengembangkan dan memverifikasi setiap komponen pipeline di seluruh sandbox khusus. Pada langkah ini, Anda akan menyusun pipeline produksi lengkap dan men-deploy-nya ke Google Cloud Run.

09-9A

ADK Runner

Dalam pengembangan, adk web mengorkestrasi grafik. Dalam produksi, aplikasi menghosting alur kerja menggunakan class Runner ADK:

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: Mendorong eksekusi alur kerja, menghasilkan peristiwa secara berurutan saat node dieksekusi dan menyimpan update ke layanan sesi.
  • Pelanjutan terpadu: Keputusan pengguna di direction_gate dan pengiriman video yang telah selesai dari Veo melanjutkan eksekusi melalui objek FunctionResponse identik yang dikirimkan ke run_async.

Arsitektur aplikasi produksi

Aplikasi produksi di vibestudio/ mengintegrasikan seluruh pipeline:

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
  • Streaming peristiwa tunggal: Backend FastAPI memublikasikan peristiwa di satu streaming Server-Sent Events (SSE). Frontend React memvisualisasikan progres grafik secara real time dan menangani koneksi yang terlambat tanpa kehilangan status.
  • Eksekusi yang dipisahkan: Aplikasi mengelola loop peristiwa. Grafik alur kerja sepenuhnya berfokus pada logika eksekusi, tanpa mengetahui antarmuka frontend.

Daftar edge alur kerja lengkap di agent/graph.py menggabungkan setiap pola arsitektur yang dibuat di sepanjang codelab ini:

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

Men-deploy ke Cloud Run

Google Cloud Run menyediakan hosting serverless dengan penskalaan otomatis, pemilihan rute permintaan, dan build container terintegrasi:

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=...
  • Build container: gcloud run deploy --source mengemas direktori vibestudio/, membangun image container menggunakan Cloud Build, dan men-deploy layanan dalam satu operasi.
  • Afinitas sesi: Mengarahkan permintaan dari pengguna yang sama ke instance container yang sama, dengan mempertahankan status sesi lokal di seluruh langkah iteratif.
  • Kemampuan observasi: Integrasi Cloud Trace mencatat span terdistribusi untuk setiap node, panggilan LLM, dan eksekusi alat, yang dapat diakses di Konsol Google Cloud di bagian Trace Explorer.

Klik tombol Deploy di workbench untuk menjalankan skrip deployment. Setelah build selesai, terminal akan menampilkan URL layanan aktif.

Aplikasi

10. Ringkasan

Di VibeStudio Workbench, buka Step 10 · Summary untuk meninjau arsitektur yang telah selesai.

10-summary

Langkah

Arsitektur & Konsep

Pola Penerapan

Satu perintah

Perintah tunggal, alat fungsi, loop chat berurutan

Agent(tools=[...]), function_call / function_response

Dasar-dasar Agentic Workflows

Alur kerja grafik, riset paralel, output skema, gerbang manusia

Workflow, START, JoinNode, output_schema, RequestInput

Status dan Router

Status sesi bersama, pengikatan parameter, perutean deterministik, agen tugas

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

Memory Bank

Memori jangka panjang tingkat pengguna, konsolidasi semantik, hook siklus proses

memories.generate / retrieve, before_model_callback, after_agent_callback

Mesin RAG

Pengambilan dokumen atas komentar audiens, embedding semantik

Node rag.create_corpus, RagEmbeddingModelConfig, read_feedback

Pembuatan video asinkron dengan Veo

Alat yang berjalan lama, tanda terima tertunda, daemon pengiriman eksternal

LongRunningFunctionTool, FunctionResponse(id=...) melanjutkan

Men-deploy ke Cloud Run

Orkestrasi terprogram, Peristiwa yang Dikirim Server, container serverless

Runner(agent=wf), run_async, deployment Cloud Run

Prinsip arsitektur inti

  1. Menangguhkan, bukan menunggu: Alur kerja dijeda dengan rapi untuk input manusia (RequestInput) atau operasi yang berjalan lama (LongRunningFunctionTool). Proses tidak menunggu tanpa aktivitas di thread atau soket jaringan.
  2. Lanjutan universal: Setiap penangguhan dilanjutkan melalui mekanisme yang identik: satu function_response yang membawa ID panggilan node yang ditangguhkan.
  3. Pengelolaan status yang dipisahkan: Node berbagi data melalui kunci status sesi bernama dan binding parameter, bukan payload perantara yang panjang dan terkait erat.
  4. Pemilihan rute deterministik sebelum biaya generatif: Router berbasis aturan dan filter ekspresi reguler mengevaluasi kebijakan tanpa biaya token sebelum model generatif dijalankan.
  5. Pemisahan fokus: Konteks khusus untuk setiap agen berada dalam callback siklus proses, sedangkan dependensi data bersama berada

10 output