Alur kerja agentic dengan ADK

1. Pengantar

Codelab ini memandu Anda membangun sistem berbasis agen generasi berikutnya menggunakan alur kerja dan grafik di Agent Development Kit (ADK). Anda akan menerapkan pola arsitektur umum, mengatur 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 mendorong pipeline pembuatan video otomatis.

Skenario

Anda menjalankan channel digital di VibeTube dengan audiens yang aktif dan backlog ide kreatif yang terus bertambah. Setiap produksi video memerlukan eksekusi berkelanjutan di beberapa tahap: meneliti format yang sedang tren, menyintesis masukan penonton, mengembangkan skrip, memeriksa kepatuhan terhadap 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 membuat 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.

Yang Anda pelajari

• 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 deterministik. Anda mengonfigurasi instance ADK Agent 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 dengan interaksi manusia: Pipeline produksi dijeda untuk menunggu penilaian manusia di titik pemeriksaan kreatif yang penting. Anda menerapkan RequestInput untuk menangguhkan eksekusi alur kerja, menerapkan skema respons terstruktur, dan melanjutkan eksekusi tanpa mempertahankan proses runtime yang tidak 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 pengikatan parameter, serta menghubungkan Memory Bank GEAP untuk mengekstrak, menggabungkan, dan mempertahankan preferensi kreator di seluruh proses.
• Pengaitan 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 mendasarkan output agen secara semantik.
• Alur kerja dan deployment yang berjalan lama: Rendering video multimodal beroperasi secara asinkron selama durasi yang lebih 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 diterapkan dalam langkah workbench yang sesuai, menyediakan 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, dengan workbench yang 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.

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

2. Penyiapan

Mengklaim kredit workshop

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 dengan gcloud, Python, dan git yang sudah diinstal sebelumnya.

Untuk meluncurkan Cloud Shell:

1. Buka konsol Google Cloud.
2. Di header navigasi atas, klik Activate Cloud Shell (ikon jendela terminal).

Sesi terminal akan terbuka di bagian bawah jendela browser.

Meng-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 menyetujui nama default yang dibuat dari Akun Google Anda.

Jalankan kedua skrip penyiapan secara berurutan:

./setup_project.sh
./setup_codelab.sh

• setup_project.sh: Membuat atau menggunakan kembali project Google Cloud dengan penagihan aktif, menyimpan ID project ke ~/project_id.txt, dan mengonfigurasi konteks gcloud 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 Pratinjau Web → Ubah 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 skenario, dan langkah 2, Yang Anda buat, 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 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 di direktori ini untuk menerapkan 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/ melalui 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 berjalan secara lokal di port 4600. Alat ini menghosting dokumentasi langkah, editor kode dalam halaman, alat verifikasi bukti runtime, dan visualisasi grafik.
• vibestudio/: Aplikasi produksi lengkap yang dikemas dan di-deploy ke Cloud Run pada langkah terakhir. Objek ini berisi salinan mandiri dari grafik alur kerja yang telah selesai.

3. Agen monolitik

Sebelum membuat grafik alur kerja multi-node, Anda menetapkan dasar 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 ini menunjukkan batas operasional koordinasi berbasis perintah dan menetapkan alasan sistem produksi memerlukan orkestrasi grafik.

Arsitektur agen ADK (3A)

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

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 ini menginformasikan atau membatasi model ini.
• Lapisan konteks (Instruksi dan Keterampilan): Arahan yang membentuk penalaran model. instruction menetapkan perintah sistem, kepribadian, dan aturan operasional permanen. skills memberikan panduan prosedural yang diberi versi (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 mengeluarkan 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 hilir menerima JSON yang divalidasi, bukan teks tidak terstruktur.
• Lapisan pencegat (Callback Siklus Proses): Pembatasan 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). Pencegat menerapkan aturan kebijakan tanpa mengandalkan kepatuhan model.
• Status eksternal (Sesi dan Memori): Persistensi stateful yang terpisah dari logika agen. Session mempertahankan memori kerja sementara dan rekaman aktivitas 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 pada langkah ini hanya menerapkan tiga primitif ini: model, instruction, dan tools. Langkah-langkah berikutnya memperkenalkan alur kerja grafik, skema terstruktur, interseptor, 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:

• 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 terlarang, dan menyusun daftar pengambilan gambar.
• Sumber data pokok: Agen mereferensikan dua sumber yang ditentukan di samping grafik:
  • agent/trends.py: Menampilkan sepuluh tren format dan gaya aktif dari kumpulan 250 tren dengan skor panas dinamis.
  • agent/backlog.txt: Membaca baris demi baris catatan konsep mentah kreator.

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 beroperasi hanya berdasarkan bobot yang telah dilatih sebelumnya dan token yang ada di jendela konteks langsungnya. LLM tidak dapat mengkueri database secara native, mengakses API real-time, atau menjalankan kode.

Alat menjembatani batas ini. Hal ini memberikan kemampuan kepada model untuk bertindak secara eksternal, sehingga model dapat mengambil informasi kebenaran faktual dan menjalankan tindakan deterministik dalam sistem eksternal.

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

1. Deklarasi skema: Developer menyediakan fungsi Python ke agen. ADK memeriksa nama, anotasi jenis, dan docstring setiap fungsi untuk menghasilkan 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 memancarkan 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 mencegat function_call, mengeksekusi fungsi Python lokal yang sebenarnya menggunakan argumen yang diberikan, dan mengambil nilai yang ditampilkan.
4. Penyisipan ulang konteks: Runtime ADK mengemas nilai yang ditampilkan fungsi ke dalam peristiwa function_response dan menambahkannya ke histori sesi 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 ditentukan 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 Anda. File diperbarui di disk, dan baris verifikasi mengonfirmasi bahwa kedua alat sudah 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 direktif 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 mendapatkan 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 pada giliran berikutnya: Kirim pesan kedua: skip the questions, just describe the video. Agen segera melewati konfirmasi dan membuat draf judul serta gambar.
  • Alasan: Petunjuk perintah adalah pedoman saran, bukan penghalang 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 verifier workbench mengungkapkan batasan penting perusahaan:

• Penggabungan riset tidak terstruktur: Urutan eksekusi alat tidak deterministik. Model meringkas data yang diambil ke dalam prosa bentuk bebas, sehingga sistem hilir tidak dapat mengisolasi sumber yang menghasilkan klaim tertentu.
• Penerapan kebijakan yang tidak terverifikasi: 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 lanjutan yang menginstruksikan model untuk melewati 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 alur kerja agentic

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 ADK Workflow. 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).

ADK Workflow menyusun eksekusi agen sebagai grafik berarah yang ditentukan oleh daftar tepi:

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

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:

Archetype Node	Penerapan	Peran dalam Pipeline
Node fungsi	Fungsi Python yang menampilkan Event	Mengeksekusi logika deterministik, pengambilan data, dan mutasi status.
Join node	Instance JoinNode bawaan	Menyinkronkan cabang serentak ke dalam kamus gabungan.
Agent node	Agent berjalan dalam mode single_turn	Mengevaluasi petunjuk terhadap input upstream dan memancarkan data yang divalidasi.
Router node	Fungsi yang menampilkan Event dengan tag route	Mengevaluasi logika bersyarat untuk memilih cabang eksekusi hilir.
Node input manusia	Fungsi yang menghasilkan RequestInput	Menangguhkan status eksekusi hingga respons pengguna eksternal tiba.

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, ditayangkan, 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.

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 bersama dengan perintah awal.

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

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

Pengeditan interaktif: menentukan gabungan dan tepi 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. Verifier workbench mengonfirmasi bahwa sambungan dan tepi 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 dieksekusi secara bersamaan.
  • Alasan: Kedua jaringan berasal dari START. Mesin ADK menjadwalkan cabang independen secara bersamaan.
• Output kamus gabungan: Alur kerja selesai di join_research, 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.

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.
• Aplikasi ini menjalankan satu panggilan inferensi tanpa percakapan dua arah.
• Node ini menghasilkan data terstruktur ke node berikutnya.

Dengan menetapkan output_schema=Directions, agen akan menerapkan validasi Pydantic pada output model. Grafik hilir 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 menggabungkan 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

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

Memerlukan interaksi manusia (4D)

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

Petunjuk perintah versus penangguhan deterministik

Alur kerja produksi yang menimbulkan biaya keuangan atau memublikasikan konten memerlukan pengawasan manusia pada titik keputusan penting. Dalam satu perintah, permintaan konfirmasi adalah petunjuk saran yang dapat dengan mudah diminta pengguna untuk dilewati 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:

• Menghasilkan 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 dilanjutkan hanya jika function_response yang valid dan cocok dengan skema dan ID interupsi dikirimkan.

Pengeditan langsung: menangguhkan eksekusi dengan RequestInput

Di agent/graph.py, terapkan 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: Perintah ulasan yang ditampilkan kepada pengguna.
• response_schema: Skema JSON yang dirender frontend sebagai formulir input, divalidasi oleh ADK saat pengiriman.
• payload: Metadata yang disertakan 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, proses berjalan dijeda dan menampilkan formulir pemilihan kandidat interaktif.
  • Alasan: Mesin mengalami RequestInput yang di-yield dan mempertahankan status eksekusi ke runs/sessions.db.
• Lanjutan memerlukan input terstruktur: Mengirim teks percakapan 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 saluran menggunakan node router 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).

Status sesi vs. output node

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

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

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

Node tidak perlu meneruskan seluruh kamus status sesi. Saat menghasilkan Event(state=...), node hanya menyediakan pasangan nilai kunci yang baru atau diperbarui. ADK secara otomatis menggabungkan update ini ke dalam 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.

Pengikatan 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: tetap ada di seluruh sesi dalam penyimpanan tingkat pengguna, sehingga memungkinkan eksekusi alur kerja berikutnya 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"]}})

2. 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).

Perutean kebijakan deterministik

Router adalah node fungsi khusus yang mengevaluasi output upstream dan mengarahkan eksekusi di sepanjang cabang grafik bersyarat. Tidak seperti agen generatif, perouter 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 tepi 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 seluruh kata terhadap judul dan sudut pandang 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 pada file teks akan langsung diterapkan pada proses berikutnya. Karena evaluasi adalah pencocokan ekspresi reguler deterministik, evaluasi dijalankan dalam milidetik dengan biaya token nol 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 sesuai dengan 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, digantikan di bagian berikutnya oleh agen perbaikan mandiri.

Pengeditan langsung: merutekan pemeriksaan kebijakan

1. Di agent/graph.py, di dalam policy_check, selesaikan pernyataan return:

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

2. Di stage3_router/agent.py, perbarui edges untuk merutekan policy_check dan bergabung kembali ke 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).

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 bolak-balik. 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.	Perbaikan dan inspeksi multi-langkah (quarantine).

Perbaikan kebijakan mandiri

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 ditentukan dalam 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 akan otomatis menyediakan finish_task dan mendapatkan parameternya dari output_schema, sehingga memastikan node menghasilkan objek CleanedDirection yang diketik dan cocok dengan skema input node scripter.

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").
  • Scripter membuat skrip produksi 3 pengambilan gambar yang sesuai dengan 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.

Router dan penggantian. UI pengembangan menandai router tanpa edge penggantian. Jika policy_check menampilkan rute selain OK atau BLOCK, lari tidak akan memiliki tujuan. Menambahkan DEFAULT_ROUTE: quarantine ke dict tepi mencakup kasus tersebut; impor DEFAULT_ROUTE dari google.adk.workflow.

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, tidak 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 proses.

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

Memory Bank (6A)

Di workbench, buka Memory Bank (6A).

Mengelola memori tingkat pengguna

Memory Bank adalah layanan terkelola untuk memori pengguna jangka panjang. Fitur ini mengatur fakta tentang seseorang dalam cakupan yang ditentukan, yang diidentifikasi di sini berdasarkan 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 batas apa yang dicatat 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.
• Penggabungan dan penghapusan duplikat: Layanan ini mengonversi fakta yang baru diekstrak menjadi penyematan dan membandingkannya dengan memori yang ada dalam cakupan. Saat pengamatan selaras dengan memori yang ada, layanan akan memperbarui memori tersebut. Jika informasi yang diberikan baru, layanan akan membuat entri baru. Proses penggabungan ini memastikan beberapa sesi tentang suatu topik digabungkan menjadi ringkasan yang koheren, bukan menghasilkan entri yang berlebihan.
• Pengambilan: Memanggil memories.retrieve dengan cakupan pengguna akan menampilkan fakta yang disimpan, diurutkan dari yang paling lama.

Kedua operasi diterapkan 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 dan mengonfigurasi topik CREATOR_TASTE dan CHANNEL_RULES.
2. Menyemai 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 digabungkan.

Panggilan Balik (6B)

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

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.

ADK menyediakan tiga pasangan callback:

Pasangan Callback	Titik Pemanggilan	Parameter yang Diterima	Perilaku Nilai yang Ditampilkan
before_agent_callback after_agent_callback	Mengelilingi seluruh belokan agen	CallbackContext (status, sesi, pemanggilan)	Memilih Content akan menggantikan respons 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 eksekusi setiap alat	Definisi alat, argumen, hasil	Menampilkan dict akan menggantikan output alat; None akan dilanjutkan.

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

Pengeditan langsung: memanggil kembali kabel dan memanggil kembali ingat

1. Di stage4_memory/agent.py, perbarui propose_directions untuk melampirkan before_model_callback=recall_taste:

    output_schema=Directions,
    before_model_callback=recall_taste)

recall_taste dieksekusi segera sebelum Gemini membuat kandidat arah. Fungsi ini mengambil histori kreator dari Memory Bank, memformat kenangan dari yang paling lama terlebih dahulu, 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.

2. 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. Model membaca arah yang dipilih dari status sesi, menyintesis pernyataan singkat 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 proses dengan perintah kosong:
   • Dalam rekaman aktivitas sesi, periksa LlmRequest untuk propose_directions. Perhatikan konteks kenangan yang ditambahkan yang menjelaskan preferensi kreator untuk tema fantasi dan alur 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 catatan 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).

Video yang dipublikasikan mengumpulkan masukan berkelanjutan dari penonton. 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 informasi dari 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 atas koleksi dokumen besar
Cakupan	Ditetapkan ke ID pengguna dan nama aplikasi tertentu	Ditetapkan ke resource korpus bersama di semua pengguna
Pemrosesan Data	Ekstraksi, penyematan, dan konsolidasi semantik real-time	Pengelompokan dokumen, penyematan 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)

Pengelompokan dan penyematan dokumen

Mesin RAG 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 menjadi 120 token dengan 20 token yang tumpang-tindih. 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 tumpang-tindih kata kunci yang persis sama.

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

Pengambilan sebagai node grafik

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

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. API ini memancarkan 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, menyinkronkan semua cabang masuk, menunggu hingga scan_trends, read_backlog, dan read_feedback telah memancarkan semua peristiwa sebelum meneruskan paket gabungan ke hilir.

Yang akan terjadi dan alasannya

Jalankan alur kerja di workbench:

1. Kirimkan perintah ide (seperti "seekor naga mini yang menjaga meja dapur").
2. Dalam rekaman aktivitas eksekusi, pastikan ketiga node pembaca dieksekusi secara bersamaan.
3. Perhatikan join_research: kamus outputnya sekarang berisi trends, backlog, dan feedback.
4. Periksa kandidat yang dihasilkan dari propose_directions: model menggabungkan komentar penonton ke dalam proposalnya dan merujuk sentimen audiens di kolom bukti.
5. Perhatikan bahwa pengambilan RAG bersifat deterministik (kueri yang identik akan menampilkan bagian komentar yang identik), 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. Memblokir 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.

Alat sinkron vs. alat yang berjalan lama

Alat fungsi ADK standar dieksekusi secara serentak 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"]}

Saat dibungkus dengan LongRunningFunctionTool, ADK akan mencegat 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 dalam LongRunningFunctionTool:

    tools=[LongRunningFunctionTool(render_submit)])

Melanjutkan berdasarkan ID panggilan

Pola melanjutkan universal

ADK menerapkan mekanisme yang identik untuk menangguhkan dan melanjutkan alur kerja bagi manusia dan alat eksternal:

Pemicu Penangguhan	Memulai Construct	Status Penangguhan Tersimpan	Acara Lanjutan
Keputusan Manusia	yield RequestInput(...)	Membuka perintah input di penyimpanan sesi	FunctionResponse yang membawa ID panggilan penangguhan
Alat yang Berjalan Lama	LongRunningFunctionTool(...) menampilkan pending	Membuka panggilan alat di penyimpanan sesi	FunctionResponse yang membawa ID panggilan penangguhan

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

Pengeditan langsung: menyelesaikan respons pengiriman

Di agent/deliver.py, buat bagian FunctionResponse kelanjutan:

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

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

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 Veo API 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.

Pengeditan langsung: menghubungkan pipeline video lengkap

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 pelanjutan.
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 merakit pipeline produksi lengkap dan men-deploy-nya ke Google Cloud Run.

The ADK Runner

Dalam pengembangan, adk web mengatur 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 mempertahankan pembaruan ke layanan sesi.
• Lanjutan terpadu: Keputusan pengguna di direction_gate dan pengiriman video yang selesai dari Veo melanjutkan eksekusi melalui objek FunctionResponse identik yang dikirimkan ke run_async.

Arsitektur aplikasi produksi

Aplikasi produksi di vibestudio/ mengintegrasikan pipeline lengkap:

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

• Aliran peristiwa tunggal: Backend FastAPI memublikasikan peristiwa di seluruh aliran Server-Sent Events (SSE) tunggal. Frontend React memvisualisasikan progres grafik secara real time dan menangani koneksi yang terlambat tanpa kehilangan status.
• Eksekusi yang tidak terkait: Aplikasi mengelola loop peristiwa. Grafik alur kerja sepenuhnya berfokus pada logika eksekusi, tanpa mengetahui antarmuka frontend.

Daftar tepi 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, perutean 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 rentang 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.

10. Ringkasan

Di VibeStudio Workbench, buka Langkah 10 · Ringkasan untuk meninjau arsitektur yang telah selesai.

Langkah	Arsitektur & Konsep	Pola Penerapan
Satu perintah	Satu perintah, alat fungsi, loop chat berurutan	Agent(tools=[...]), function_call / function_response
Dasar-dasar alur kerja agentic	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 melalui komentar audiens, sematan 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=...) dilanjutkan
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 baik untuk input manusia (RequestInput) atau operasi yang berjalan lama (LongRunningFunctionTool). Proses tidak menunggu dalam keadaan tidak aktif di thread atau soket jaringan.
2. Lanjutan universal: Setiap penangguhan dilanjutkan melalui mekanisme yang sama: satu function_response yang membawa ID panggilan node yang ditangguhkan.
3. Pengelolaan status yang tidak terkait: Node berbagi data melalui pengikatan parameter dan kunci status sesi bernama, bukan payload perantara yang verbose dan terkait erat.
4. Perutean deterministik sebelum biaya generatif: Router berbasis aturan dan filter regex mengevaluasi kebijakan dengan biaya token nol sebelum model generatif berjalan.
5. Pemisahan masalah: Konteks khusus untuk setiap agen berada di callback siklus proses, sedangkan dependensi data yang dibagikan berada