เวิร์กโฟลว์แบบเป็น Agent ด้วย ADK

1. บทนำ

VibeStudio

Codelab นี้จะแนะนำวิธีสร้างระบบแบบ Agent ยุคถัดไปด้วยเวิร์กโฟลว์และกราฟใน Agent Development Kit (ADK) คุณจะใช้รูปแบบสถาปัตยกรรมทั่วไป จัดการการโต้ตอบแบบมีมนุษย์ร่วม (HITL) และจัดการการดำเนินการแบบอะซิงโครนัสที่ใช้เวลานาน นอกจากนี้ คุณยังจะผสานรวมฐานความรู้ขององค์กรและหน่วยความจำแบบถาวรเพื่อปรับแต่งและพัฒนาพฤติกรรมของเอเจนต์ได้ด้วย สุดท้าย คุณจะเชื่อมต่อความสามารถเหล่านี้เพื่อขับเคลื่อนไปป์ไลน์การสร้างวิดีโออัตโนมัติ

สถานการณ์

คุณมีช่องดิจิทัลบน VibeTube ที่มีผู้ชมที่ใช้งานอยู่และมีไอเดียสร้างสรรค์ที่ยังไม่ได้ทำอีกมากมาย การผลิตวิดีโอแต่ละรายการต้องดำเนินการอย่างต่อเนื่องในหลายขั้นตอน ได้แก่ การค้นคว้าหาเทรนด์รูปแบบต่างๆ การสังเคราะห์ความคิดเห็นของผู้ชม การพัฒนาสคริปต์ การตรวจสอบการปฏิบัติตามนโยบาย และการสร้างวิดีโอคลิป โมเดล Generative สามารถร่างเนื้อหาแต่ละรายการได้ แต่การเผยแพร่ที่สอดคล้องกันต้องใช้สถาปัตยกรรม Agent ที่มีการประสานงานกัน

คุณจะสร้าง VibeStudio เพื่อทำให้วงจรนี้เป็นแบบอัตโนมัติ ไปป์ไลน์ของ Agent นี้จะดำเนินการวิจัยตามปกติแบบคู่ขนาน นำเสนอตัวเลือกที่คัดสรรมาแล้วเพื่อให้มนุษย์อนุมัติ ใช้เกตนโยบายอัตโนมัติก่อนสร้างวิดีโอ และรักษาบริบทในการดำเนินการผลิต

เวิร์กโฟลว์ที่คุณสร้างตั้งแต่ไอเดียไปจนถึงคลิปที่เผยแพร่

สิ่งที่คุณจะได้เรียนรู้

10-summary

  • พื้นฐานด้านวิศวกรรมกราฟ: สถาปัตยกรรมของ Agent แบบหลายขั้นตอนต้องมีโฟลว์การควบคุมที่ชัดเจนและเส้นทางการดำเนินการที่มีโครงสร้าง คุณสร้าง ADK Workflow โดยใช้ทูเพิลที่ขอบ START จุดแรกเข้า JoinNode สำหรับการรวบรวมแบบ Fan-Out แบบขนาน และโหนดเราเตอร์เชิงกำหนด เพื่อควบคุมการดำเนินการตามสถานะ
  • โหมด Agent และ Lifecycle Callback: งานเฉพาะทางต้องใช้ลักษณะการทำงานที่แตกต่างกันและ Guardrail เชิงกำหนด คุณกำหนดค่าอินสแตนซ์ Agent ของ ADK โดยใช้โหมด chat, single_turn และ task ที่เปิดใช้เครื่องมือเป็นโหนดเวิร์กโฟลว์ โดยใช้ตัวสกัดกั้นกับ before_model_callback และ after_agent_callback
  • การประสานงานแบบมีมนุษย์ร่วม: ไปป์ไลน์การผลิตจะหยุดชั่วคราวเพื่อรอการตัดสินใจของมนุษย์ที่จุดตรวจสอบครีเอทีฟโฆษณาที่สำคัญ คุณใช้ RequestInput เพื่อระงับการดำเนินการเวิร์กโฟลว์ บังคับใช้สคีมาการตอบกลับที่มีโครงสร้าง และดำเนินการต่อโดยไม่ต้องรักษากระบวนการรันไทม์ที่ไม่ได้ใช้งานให้ทำงานอยู่
  • หน่วยความจำของ Agent แบบลำดับชั้น: ระบบเวอร์ชันที่ใช้งานจริงจะแยกสถานะการดำเนินการชั่วคราวออกจากบริบทที่คงทนถาวร คุณจัดการสถานะเซสชันระยะสั้นโดยใช้ Event(state=...) และการเชื่อมโยงพารามิเตอร์ และเชื่อมต่อ GEAP Memory Bank เพื่อดึงข้อมูล รวม และคงค่ากำหนดของครีเอเตอร์ไว้ตลอดการเรียกใช้
  • การอิงตามฐานความรู้ขององค์กร: ตัวแทนอัตโนมัติต้องการบริบทโดเมนแบบไดนามิกและความรู้สึกของกลุ่มเป้าหมาย คุณเชื่อมต่อคลังข้อมูลของ GEAP RAG Engine เป็นโหนดการดึงข้อมูลเฉพาะภายใน Fan-Out แบบขนานเพื่อยึดเอาต์พุตของ Agent ตามความหมาย
  • เวิร์กโฟลว์และการติดตั้งใช้งานที่ใช้เวลานาน: การเรนเดอร์วิดีโอแบบมัลติโมดัลจะทำงานแบบไม่พร้อมกันเป็นระยะเวลานาน คุณใช้ LongRunningFunctionTool กับใบรับการโทรที่รอดำเนินการเพื่อระงับและกลับมาทำงานต่อในเวิร์กโฟลว์ตามรหัสการโทร และติดตั้งใช้งานไปป์ไลน์ที่เสร็จสมบูรณ์โดยใช้ Runner ของ ADK ใน Cloud Run

วิธีจัดระเบียบ Codelab นี้

Codelab นี้ทำหน้าที่เป็นข้อมูลอ้างอิงด้านแนวคิดและสถาปัตยกรรม แต่ละส่วนจะอธิบายโครงสร้าง ADK ที่ใช้ในขั้นตอนเวิร์กเบนช์ที่เกี่ยวข้อง ให้โค้ดอ้างอิง และกำหนดหลักการออกแบบหลัก โปรดอ่านแต่ละส่วนก่อนทำแบบฝึกหัดที่เกี่ยวข้องในเวิร์กเบนช์

การทำงานจริงจะเกิดขึ้นใน VibeStudio Workbench ซึ่งเป็นอินเทอร์เฟซเว็บที่มาพร้อมกับตัวแก้ไขโค้ดแบบอินเทอร์แอกทีฟ ตัวตรวจสอบรันไทม์ และเครื่องมือตรวจสอบ ADK แบบฝัง หมายเลขขั้นตอนใน Workbench จะสอดคล้องกับ Codelab นี้โดยตรงเพื่อให้ความคืบหน้าของคุณซิงค์กัน การแก้ไขกราฟพื้นฐานจะยังคงอยู่ตลอดขั้นตอนต่างๆ โดย Workbench จะตรวจสอบข้อกำหนดเบื้องต้นโดยอัตโนมัติเมื่อคุณดำเนินการต่อ

เมื่อทำแบบฝึกหัดใน Workbench เสร็จแล้ว คุณจะประกอบไปป์ไลน์แบบเป็น Agent ตั้งแต่ต้นจนจบ และทำให้แอปพลิเคชัน VibeStudio ที่ทำงานอยู่ใช้งานได้ใน Cloud Run เพื่อสร้างเนื้อหาวิดีโอ

สิ่งที่ทำงานในแต่ละส่วน: VibeStudio Workbench, แบ็กเอนด์ และบริการ Google Cloud

สภาพแวดล้อมประกอบด้วยคอมโพเนนต์หลัก 3 อย่าง ได้แก่ VibeStudio Workbench (อินเทอร์เฟซเว็บในเครื่องสำหรับการแก้ไขโค้ดและการยืนยันรันไทม์), แบ็กเอนด์ (ADK Workflow และแซนด์บ็อกซ์ของสเตจใน agent/) และ Google Cloud (โมเดล Gemini, GEAP Memory Bank, RAG Engine และการสร้างวิดีโอ Veo)

2. ตั้งค่า

รับเครดิตเวิร์กช็อป

หากคุณเข้าร่วมห้องปฏิบัติการที่นำโดยผู้สอน ผู้สอนจะแจกจ่ายเครดิตสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google ของคุณ ทำตามวิธีการของผู้สอนเพื่อแลกรับเครดิตและตรวจสอบว่าการเรียกเก็บเงินในบัญชีของคุณใช้งานได้ก่อนดำเนินการต่อ

เปิด Cloud Shell

Cloud Shell เป็นสภาพแวดล้อมในการพัฒนาซอฟต์แวร์บนเบราว์เซอร์ที่ติดตั้ง gcloud, Python และ git ไว้ล่วงหน้า

วิธีเปิดใช้ Cloud Shell

  1. ไปที่ Google Cloud Shell

เซสชันเทอร์มินัลจะเปิดขึ้นที่ด้านล่างของหน้าต่างเบราว์เซอร์

โคลนและเริ่มต้นที่เก็บ

เรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัล Cloud Shell เพื่อโคลนโปรเจ็กต์

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

พรอมต์การกำหนดค่า

ในระหว่างการตั้งค่า ระบบจะแจ้งให้คุณระบุรายละเอียดต่อไปนี้

  • รหัสโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google: เมื่อ setup_project.sh แจ้ง ให้กด Enter เพื่อสร้างโปรเจ็กต์ใหม่โดยอัตโนมัติ หากต้องการใช้โปรเจ็กต์ที่มีอยู่ (เช่น โปรเจ็กต์ที่กำหนดไว้ล่วงหน้า) ให้ป้อนรหัสโปรเจ็กต์และตรวจสอบว่าสะกดถูกต้องโดยมีการเรียกเก็บเงินที่ใช้งานอยู่
  • รหัสกิจกรรม: ป้อนรหัสห้องที่ผู้สอนให้มา หากไม่ได้รับ โปรดสอบถามผู้ช่วยสอนหรือเพื่อนบ้าน หากคุณกำลังทำแล็บนี้ที่บ้าน ให้กด Enter เพื่อยอมรับห้อง sandbox เริ่มต้น
  • ชื่อที่แสดงของช่อง: ป้อนชื่อหรือแฮนเดิลของช่องที่ต้องการเมื่อ setup_codelab.sh แจ้ง หรือกดEnterเพื่อยอมรับค่าเริ่มต้นที่สร้างจากบัญชี Google

เรียกใช้สคริปต์การตั้งค่า 2 รายการตามลำดับต่อไปนี้

./setup_project.sh
./setup_codelab.sh
  • setup_project.sh: สร้างหรือใช้โปรเจ็กต์ Google Cloud ซ้ำที่มีการเรียกเก็บเงินที่ใช้งานอยู่ บันทึกรหัสโปรเจ็กต์ลงใน ~/project_id.txt และกำหนดค่าบริบท gcloud ที่ใช้งานอยู่
  • setup_codelab.sh: ติดตั้ง uv และทรัพยากร Dependency ของ Python ลงใน .venv, เปิดใช้ Google Cloud API ที่จำเป็น, กำหนดการตั้งค่าช่องใน .env, ยืนยันสิทธิ์เข้าถึงโมเดลด้วย Gemini, จัดสรรทรัพยากร Memory Bank และ RAG, สร้างอินเทอร์เฟซ Workbench และเริ่มใช้ VibeStudio Workbench

สคริปต์จะเรียกใช้การตรวจสอบก่อนการทดสอบและเริ่ม VibeStudio Workbench ในเบื้องหลัง บรรทัดสุดท้ายจะแสดงลิงก์ที่จะเปิด

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

คลิกลิงก์นั้น ที่อยู่เดียวกันนี้จะอยู่ในส่วนตัวอย่างเว็บ → เปลี่ยนพอร์ต → 4600

หากต้องการตรวจสอบสภาพแวดล้อมอีกครั้งเมื่อใดก็ตาม ให้เรียกใช้ python scripts/preflight.py หากต้องการรีสตาร์ท Workbench ให้เรียกใช้ scripts/restart.sh หากต้องการตั้งค่าอีกครั้ง ให้เรียกใช้ ./setup_codelab.sh ซึ่งจะเก็บการกำหนดค่าและความคืบหน้าของคุณไว้

เมื่อเปิดแล้ว ให้อ่านขั้นตอนที่ 1 เรื่องราวสำหรับสถานการณ์ และขั้นตอนที่ 2 สิ่งที่คุณสร้างสำหรับรูปร่างของกราฟที่เสร็จสมบูรณ์ ทั้งสองไม่มีแบบฝึกหัด จากนั้นกลับมาที่นี่เพื่อทำขั้นตอนที่ 3

ทุกส่วนที่ต้องลงมือปฏิบัติจริงของ VibeStudio Workbench จะสิ้นสุดด้วยแผงการยืนยันที่อ่านอาร์ติแฟกต์จริง ได้แก่ ไฟล์ในดิสก์และเซสชันที่เขียนโดยการเรียกใช้

เลย์เอาต์ที่เก็บ

ที่เก็บได้รับการจัดโครงสร้างเป็นตรรกะเวิร์กโฟลว์หลัก, แซนด์บ็อกซ์แบบทีละขั้นตอน, สภาพแวดล้อมเวิร์กเบนช์ และแอปพลิเคชันเวอร์ชันที่ใช้งานจริง ดังนี้

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/: มีกราฟเวิร์กโฟลว์หลัก คุณจะแก้ไขไฟล์ในไดเรกทอรีนี้เพื่อใช้โหนดแฟนเอาต์ (Fan-Out) แบบขนาน การกำหนดเส้นทางนโยบายเชิงกำหนด คอลแบ็กหน่วยความจำ และเครื่องมือสร้างวิดีโอ
  • agent/platform/: เชื่อมต่อกับบริการของ Google Cloud ซึ่งรวมถึงโมเดล Gemini, GEAP Memory Bank, GEAP RAG Engine และการสังเคราะห์วิดีโอ Veo
  • stage0_prompt/ ถึง stage6_video/: สภาพแวดล้อมแซนด์บ็อกซ์แบบสมบูรณ์ในตัว แต่ละโฟลเดอร์จะส่งออก root_agent แบบสแตนด์อโลนเพื่อให้คุณเรียกใช้และตรวจสอบแต่ละขั้นตอนแยกกันได้ผ่านอินเทอร์เฟซการพัฒนา ADK แบบฝัง
  • server/ และ web/: แอปพลิเคชัน VibeStudio Workbench ที่ทำงานในเครื่องบนพอร์ต 4600 ซึ่งโฮสต์เอกสารประกอบของขั้นตอน ตัวแก้ไขโค้ดในหน้าเว็บ ตัวตรวจสอบหลักฐานรันไทม์ และการแสดงภาพกราฟ
  • vibestudio/: แอปพลิเคชันเวอร์ชันที่ใช้งานจริงที่สมบูรณ์ซึ่งจัดแพ็กเกจและติดตั้งใช้งานใน Cloud Run ในขั้นตอนสุดท้าย ซึ่งจะมีสำเนาแบบสแตนด์อโลนของกราฟเวิร์กโฟลว์ที่เสร็จสมบูรณ์แล้ว

3. Agent แบบโมโนลิธ

ก่อนสร้างกราฟเวิร์กโฟลว์แบบหลายโหนด คุณต้องสร้างพื้นฐานด้านสถาปัตยกรรมด้วยเอเจนต์เดียวใน stage0_prompt/agent.py Agent นี้อาศัยพรอมต์ระบบแบบโมโนลิธิกที่อธิบายไปป์ไลน์การผลิตเป็นข้อความธรรมดา โดยมีเครื่องมือฟังก์ชัน Python 2 รายการรองรับ

การประเมินพื้นฐานนี้แสดงให้เห็นขอบเขตการปฏิบัติงานของการประสานงานที่ขับเคลื่อนด้วยพรอมต์ และอธิบายว่าเหตุใดระบบการผลิตจึงต้องมีการจัดระเบียบกราฟ

สถาปัตยกรรม Agent ของ ADK (3A)

ใน VibeStudio Workbench ให้ไปที่ขั้นตอนที่ 3 · Monolithic agent แล้วเปิด ADK agent architecture (3A) มุมมองนี้แสดงเลเยอร์สถาปัตยกรรมหลักของ Agent ของ 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
)

แผนภาพแบบอินเทอร์แอกทีฟจะจัดกลุ่มคอมโพเนนต์ของเอเจนต์เป็น 5 โดเมนการทำงาน ดังนี้

  • เลเยอร์การให้เหตุผล (โมเดล): โมเดลภาษาหลัก (เช่น Gemini 3 Flash) ที่ทำกระบวนการเกี่ยวกับการรับรู้ การให้เหตุผลเกี่ยวกับพรอมต์ และการเลือกเครื่องมือ ส่วนอื่นๆ ทั้งหมดในสถาปัตยกรรมจะให้ข้อมูลหรือจำกัดโมเดลนี้
  • เลเยอร์บริบท (คำสั่งและทักษะ): คำสั่งที่กำหนดรูปแบบการให้เหตุผลของโมเดล instruction จะสร้างพรอมต์ระบบ บุคลิก และกฎการทำงานแบบถาวร skills ให้คำแนะนำแบบเป็นขั้นตอนและมีการควบคุมเวอร์ชัน (SKILL.md) สำหรับเวิร์กโฟลว์ที่ทำซ้ำได้
  • เลเยอร์การทำงานร่วมกันและการดำเนินการ (เครื่องมือ, Subagent, เวิร์กโฟลว์, สคีมาเอาต์พุต): อินเทอร์เฟซที่ช่วยให้เอเจนต์ดำเนินการในระบบภายนอกและส่งข้อมูลที่พิมพ์ tools มีฟังก์ชัน Python ที่เรียกใช้ได้หรือปลายทาง Model Context Protocol (MCP) subagents ดำเนินงานที่ได้รับมอบหมายจากผู้บังคับบัญชา workflow ประสานงานกราฟแบบหลาย Agent output_schema ใช้โมเดล Pydantic เพื่อรับประกันว่าผู้บริโภคปลายทางจะได้รับ JSON ที่ผ่านการตรวจสอบแล้วแทนข้อความที่ไม่มีโครงสร้าง
  • เลเยอร์ Interceptor (Lifecycle Callbacks): แนวทางเชิงกำหนดที่เรียกใช้โค้ดที่กำหนดเองก่อนและหลังการดำเนินการของเอเจนต์ (before_agent/after_agent), การตอบกลับของโมเดลแต่ละรายการ (before_model/after_model) และการเรียกใช้เครื่องมือ (before_tool/after_tool) Interceptor จะบังคับใช้กฎนโยบายโดยไม่ต้องอาศัยการปฏิบัติตามข้อกำหนดของโมเดล
  • สถานะภายนอก (เซสชันและหน่วยความจำ): ความคงอยู่แบบเก็บสถานะที่แยกจากตรรกะของ Agent Session จะเก็บรักษาหน่วยความจำที่ใช้งานชั่วคราวและการติดตามเหตุการณ์สำหรับชุดข้อความการดำเนินการปัจจุบัน Memory จะเก็บรักษาข้อเท็จจริงและค่ากำหนดที่คงทนข้ามเซสชันโดยใช้บริการที่มีการจัดการ เช่น GEAP Memory Bank

ในขั้นตอนนี้ เอเจนต์แบบ Monolithic จะใช้เฉพาะ Primitive 3 รายการ ได้แก่ model, instruction และ tools ขั้นตอนถัดไปจะแนะนำเวิร์กโฟลว์กราฟ สคีมาที่มีโครงสร้าง ตัวสกัดกั้น และบริการหน่วยความจำแบบถาวร

ข้อกำหนดของเอเจนต์แบบโมโนลิธ (3B)

ในเวิร์กเบนช์ ให้ไปที่ข้อกำหนดของเอเจนต์แบบ Monolithic (3B) เปิด stage0_prompt/agent.py เพื่อตรวจสอบคำจำกัดความของเอเจนต์พื้นฐาน

  • คำสั่งพรอมต์เดียว: พรอมต์ของระบบจะสรุปงานการผลิตที่แตกต่างกัน 5 งานให้เป็นข้อความต่อเนื่องกัน ได้แก่ การค้นหาเทรนด์ของแพลตฟอร์ม การตรวจสอบไอเดียที่ค้างอยู่ การเสนอแนวคิดเชิงสร้างสรรค์ การบังคับใช้นโยบายเกี่ยวกับหัวข้อต้องห้าม และการร่างรายการช็อต
  • แหล่งข้อมูลเบื้องหลัง: Agent อ้างอิงแหล่งข้อมูล 2 แหล่งที่ระบุไว้ข้างกราฟ ดังนี้
    • agent/trends.py: สุ่มตัวอย่างเทรนด์รูปแบบและสไตล์ที่ใช้งานอยู่ 10 รายการจากกลุ่ม 250 รายการที่มีคะแนนความนิยมแบบไดนามิก
    • agent/backlog.txt: อ่านบันทึกแนวคิดแบบดิบๆ ของครีเอเตอร์ทีละบรรทัด

เครื่องมือใน Agent (3C)

ใน Workbench ให้ไปที่เครื่องมือใน Agent (3C)

เครื่องมือคืออะไรสำหรับ Agent

โมเดลภาษาเป็นเครื่องมือการให้เหตุผลแบบปิดโดยเนื้อแท้ กล่าวคือทำงานโดยอาศัยน้ำหนักที่ฝึกไว้ล่วงหน้าและโทเค็นที่อยู่ในหน้าต่างบริบทปัจจุบันเท่านั้น โดยไม่สามารถค้นหาฐานข้อมูล เข้าถึง API แบบเรียลไทม์ หรือเรียกใช้โค้ดได้โดยตรง

เครื่องมือจะเชื่อมต่อขอบเขตนี้ ซึ่งจะให้สิทธิ์แก่เอเจนซีภายนอกของโมเดล ทำให้โมเดลสามารถดึงข้อมูลที่เป็นความจริงและดำเนินการเชิงกำหนดในระบบภายนอกได้

03-3C

การเรียกใช้เครื่องมือจะเป็นไปตามโปรโตคอล 5 ขั้นตอนที่ชัดเจนระหว่างโมเดลและรันไทม์ ADK ดังนี้

  1. การประกาศสคีมา: นักพัฒนาซอฟต์แวร์จะจัดเตรียมฟังก์ชัน Python ให้กับ Agent ADK จะตรวจสอบชื่อ คำอธิบายประกอบประเภท และ Docstring ของแต่ละฟังก์ชันเพื่อสร้างการประกาศสคีมา JSON ที่เข้ากันได้กับ OpenAPI ซึ่งอธิบายพารามิเตอร์และวัตถุประสงค์ของฟังก์ชัน
  2. การให้เหตุผลของโมเดล: ในระหว่างการอนุมาน โมเดลจะประเมินว่าพรอมต์ของผู้ใช้ต้องใช้ข้อมูลภายนอกหรือไม่ หากจำเป็น โมเดลจะส่งเหตุการณ์ function_call ที่มีโครงสร้างซึ่งมีชื่อฟังก์ชันเป้าหมายและพจนานุกรมอาร์กิวเมนต์ที่ตรงกับสคีมา
  3. การเรียกใช้รันไทม์: โมเดลเองไม่ได้เรียกใช้โค้ด รันไทม์ของ ADK จะสกัดกั้น function_call เรียกใช้ฟังก์ชัน Python ในเครื่องจริงโดยใช้อาร์กิวเมนต์ที่ระบุ และบันทึกค่าที่ส่งคืน
  4. การแทรกบริบทซ้ำ: รันไทม์ ADK จะแพ็กเกจค่าที่แสดงผลของฟังก์ชันเป็นเหตุการณ์ function_response และเพิ่มลงในประวัติเซสชันที่ใช้งานอยู่
  5. การสังเคราะห์ขั้นสุดท้าย: โมเดลจะประมวลผลเอาต์พุตของเครื่องมือที่แสดงอยู่ในหน้าต่างบริบทและสร้างคำตอบให้เสร็จสมบูรณ์

ใน stage0_prompt/agent.py เครื่องมือค้นคว้าทั้ง 2 รายการจะได้รับการกำหนดเป็นฟังก์ชัน Python มาตรฐาน ดังนี้

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

การแก้ไขและการดำเนินการด้วยตนเอง

ในตัวแก้ไขโค้ดของ Workbench ให้เพิ่มการอ้างอิงฟังก์ชัน 2 รายการลงในรายการ tools ของ Agent ดังนี้

    tools=[check_trends, read_backlog],

บันทึกการเปลี่ยนแปลง ไฟล์จะอัปเดตในดิสก์ และแถวการยืนยันจะยืนยันว่าเครื่องมือทั้ง 2 เชื่อมต่อกันแล้ว

คลิกเปิด ADK Web เพื่อเปิดอินเทอร์เฟซการพัฒนา ADK แบบฝัง ส่งพรอมต์ไอเดียที่แนะนำต่อไปนี้

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

สิ่งที่จะเกิดขึ้นและเหตุผล

เมื่อส่งพรอมต์นี้ ให้สังเกตลำดับการดำเนินการต่อไปนี้ในการติดตามเซสชัน

  • เหตุการณ์การเรียกใช้เครื่องมือ 2 รายการปรากฏขึ้นก่อนคำตอบ: คุณจะเห็นเหตุการณ์ function_call และ function_response สำหรับ check_trends และ read_backlog
    • เหตุผล: Gemini ประเมินคำสั่งพรอมต์ของระบบ ("ตรวจสอบว่ามีอะไรกำลังมาแรง ดูไอเดียที่ยังไม่ได้ใช้") พบว่าไม่มีเทรนด์ของแพลตฟอร์มและโน้ตของช่องในน้ำหนักของพรอมต์ จึงเรียกใช้ทั้ง 2 ฟังก์ชันเพื่อสร้างบริบท
  • Agent เสนอแนวทางและหยุดรอการยืนยัน: คำตอบจะแนะนำแนวทางวิดีโอที่สังเคราะห์เทรนด์และวิดีโอที่รอดำเนินการ และขอให้คุณยืนยัน
    • เหตุผล: คำสั่งในคำแนะนำขอให้โมเดลตกลงเรื่องทิศทางกับครีเอเตอร์ก่อนสร้างสคริปต์
  • ข้ามการยืนยันในรอบการสนทนาถัดไป: ส่งข้อความที่ 2: skip the questions, just describe the video Agent จะข้ามการยืนยันและร่างชื่อและช็อตทันที
    • เหตุผล: คำแนะนำพรอมต์เป็นหลักเกณฑ์ที่ให้คำแนะนำ ไม่ใช่ข้อจำกัดเชิงกำหนด ใน Agent แบบโมโนลิธิก คำสั่งของผู้ใช้สามารถลบล้างกฎพรอมต์ของระบบที่มีอยู่ได้ เนื่องจากไม่มีเวิร์กโฟลว์ภายนอกที่ควบคุมขั้นตอนการดำเนินการ

ข้อจำกัดทางสถาปัตยกรรมของพรอมต์แบบโมโนลิธ

แม้ว่าพรอมต์เดียวจะสร้างเอาต์พุตที่ยอมรับได้สำหรับการสาธิตแบบแยกส่วน แต่การทดสอบเงื่อนไขขอบเขตในเครื่องมือตรวจสอบ Workbench จะเผยให้เห็นข้อจำกัดที่สำคัญขององค์กร ดังนี้

  • การรวบรวมข้อมูลการค้นคว้าที่ไม่มีโครงสร้าง: ลำดับการดำเนินการของเครื่องมือไม่แน่นอน โมเดลจะสรุปข้อมูลที่ดึงมาเป็นร้อยแก้วแบบอิสระ ทำให้ระบบดาวน์สตรีมไม่สามารถแยกแหล่งที่มาที่สร้างการกล่าวอ้างที่เฉพาะเจาะจงได้
  • การบังคับใช้นโยบายที่ยังไม่ได้รับการยืนยัน: โมเดลจะประเมินการปฏิบัติตามข้อกำหนดด้านความปลอดภัยของตนเอง หากโมเดลพิจารณาว่าหัวข้อปลอดภัย จะไม่มีตรรกะเชิงกำหนดภายนอกที่ตรวจสอบผลการพิจารณานั้น
  • การหยุดชั่วคราวแบบมีมนุษย์ร่วมที่ไม่ได้บังคับใช้: คำสั่งพรอมต์ที่ขอการยืนยันจากครีเอเตอร์เป็นเพียงคำแนะนำ การส่งข้อความติดตามผลที่สั่งให้โมเดลข้ามคำถามจะทำให้โมเดลข้ามการอนุมัติจากมนุษย์ไปโดยสิ้นเชิง

ช่องว่างทางสถาปัตยกรรมเหล่านี้กระตุ้นให้เกิดการแยก Agent แบบโมโนลิธิกออกเป็นเวิร์กโฟลว์กราฟที่ชัดเจนซึ่งสร้างขึ้นในขั้นตอนถัดไป

4. พื้นฐานเวิร์กโฟลว์แบบ Agentic

ใน VibeStudio Workbench ให้ไปที่ขั้นตอนที่ 4 · พื้นฐานเวิร์กโฟลว์ Agentic ส่วนที่ 4A ถึง 4D

ขั้นตอนนี้จะเปลี่ยนจากเกณฑ์พื้นฐานของ Agent ตัวเดียวเป็นการจัดการกราฟเชิงกำหนดโดยใช้ ADK Workflow คุณจะสร้างการแยกย่อยการวิจัยแบบขนาน ซิงค์กิ่งกับโหนด Join สร้างครีเอทีฟโฆษณาที่ผ่านการตรวจสอบสคีมา และเปิดตัวเกตการอนุมัติแบบ Human-in-the-Loop ที่กำหนด

สถาปัตยกรรมกราฟและเชนการดำเนินการ (4A)

ใน Workbench ให้เปิดสถาปัตยกรรมกราฟและเชนการดำเนินการ (4A)

Workflow ของ ADK จะจัดโครงสร้างการดำเนินการของ Agent เป็นกราฟแบบมีทิศทางที่กำหนดโดยรายการ Edge ดังนี้

  • เชน: ทูเพิลตามลําดับจะกําหนดการเรียกใช้โหนดเชิงเส้น ((node_a, node_b, node_c))
  • กิ่งก้านแบบขนาน: เชนอิสระที่แชร์โหนดต้นทางจะดำเนินการพร้อมกัน
  • การซิงโครไนซ์: เชนที่บรรจบกันจะJoinNodeรอจนกว่ากิ่งขาเข้าทั้งหมดจะรายงานก่อนจึงจะเผยแพร่
  • การควบคุมเชิงกำหนด: โฟลว์การดำเนินการจะควบคุมโดยโครงสร้างโค้ดที่ประกาศไว้แทนที่จะอนุมานจากข้อความพรอมต์

04-4A

ต้นแบบโหนดใน ADK

เวิร์กโฟลว์ ADK ประกอบด้วยโหนดเฉพาะทางหลายประเภท อาร์คีไทป์แต่ละรายการจะมีบทบาทการทำงานเฉพาะในกราฟ โดยแยกการเรียกใช้โค้ดเชิงกำหนดออกจากการให้เหตุผลของโมเดล Generative ดังนี้

ต้นแบบของโหนด

การใช้งาน

บทบาทในไปป์ไลน์

โหนดฟังก์ชัน

ฟังก์ชัน Python ที่แสดงผล Event

เรียกใช้ตรรกะแบบดีเทอร์มินิสติก การดึงข้อมูล และการเปลี่ยนแปลงสถานะ

โหนดการรวม

อินสแตนซ์ JoinNode ในตัว

ซิงค์กิ่งที่พร้อมกันเป็นพจนานุกรมแบบรวม

โหนด Agent

Agent ทำงานในโหมด single_turn

ประเมินวิธีการเทียบกับอินพุตต้นทางและส่งออกข้อมูลที่ตรวจสอบแล้ว

โหนดเราเตอร์

ฟังก์ชันที่แสดงผล Event ที่มีแท็ก route

ประเมินตรรกะแบบมีเงื่อนไขเพื่อเลือกสาขาการดำเนินการปลายทาง

โหนดอินพุตจากมนุษย์

ฟังก์ชันให้ผลลัพธ์ RequestInput

ระงับสถานะการดำเนินการจนกว่าจะได้รับการตอบกลับจากผู้ใช้ภายนอก

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

ในการกำหนดค่านี้ root_agent เป็นอินสแตนซ์ของ Workflow แทนที่จะเป็น Agent แบบสแตนด์อโลน ADK จะถือว่าเวิร์กโฟลว์เป็นเอเจนต์ระดับเฟิร์สคลาส ซึ่งช่วยให้โหลด แสดง และตรวจสอบทั้งกราฟเป็นแอปพลิเคชันแบบรวมได้ name ลงทะเบียนแอปพลิเคชันใน ADK Web ขณะที่รายการ edges จะกำหนดโทโพโลยีการดำเนินการ

การวิจัยแบบขนาน (4B)

ในเวิร์กเบนช์ ให้ไปที่การแยกย่อยการวิจัยแบบคู่ขนาน (4B) เปิด stage1_fanout/agent.py

04-4B

โหนดฟังก์ชันและอุปสรรคในการซิงค์ข้อมูล

ระยะการค้นคว้าใช้โหนดฟังก์ชัน 2 โหนดที่นำเข้าจาก agent/graph.py ดังนี้

  • scan_trends: แสดง Event(output={"trends": [...]}) ที่มีเทรนด์แพลตฟอร์มที่ให้คะแนน 10 รายการ
  • read_backlog: การตอบกลับ Event(output={"backlog": [...], "idea": "..."}) ที่มีไอเดียสำหรับเนื้อหาที่ค้างไว้ในช่อง 15 รายการพร้อมกับพรอมต์การรันครั้งแรก

แต่ละฟังก์ชันจะยอมรับ node_input (เอาต์พุตของโหนดก่อนหน้า) และแสดงผล Event

JoinNode ทำหน้าที่เป็นอุปสรรคในการซิงค์ โดยจะหยุดชั่วคราวจนกว่าเชนขาเข้าทุกเชนจะส่งเหตุการณ์ จากนั้นจะรวบรวมผลลัพธ์ของทุกสาขาเป็นพจนานุกรมที่มีคีย์เป็นชื่อโหนด ({"scan_trends": {...}, "read_backlog": {...}})

การแก้ไขจริง: การกำหนดขอบที่เชื่อมต่อและขอบที่ขนานกัน

ใน stage1_fanout/agent.py ให้สร้างอินสแตนซ์ JoinNode และเชื่อมต่อเชนคู่ขนาน 2 รายการโดยเริ่มจาก START:

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

บันทึกการเปลี่ยนแปลง เครื่องมือตรวจสอบ Workbench จะยืนยันว่าการรวมและขอบได้รับการเชื่อมต่อแล้ว เรียกใช้ขั้นตอนโดยใช้เรียกใช้ขั้นตอนที่ 1 หรือผ่านอินเทอร์เฟซเว็บ ADK ที่ฝังไว้

สิ่งที่จะเกิดขึ้นและเหตุผล

  • การเรียกใช้โปรแกรมอ่านพร้อมกัน: ในกราฟการเรียกใช้ scan_trends และ read_backlog จะเรียกใช้พร้อมกัน
    • เหตุผล: ทั้ง 2 เชนมีต้นทางอยู่ที่ START เครื่องมือ ADK จะกำหนดเวลาสาขาอิสระพร้อมกัน
  • เอาต์พุตพจนานุกรมแบบรวม: เวิร์กโฟลว์จะเสร็จสมบูรณ์ที่ join_research โดยจะแสดงผลพจนานุกรมที่มีรายการสำหรับทั้งผู้อ่าน
    • เหตุผล: JoinNode ช่วยให้มั่นใจว่าระบบจะบันทึกข้อมูลทั้งหมดก่อนที่จะอนุญาตให้โหนดต่อๆ ไปทำงาน

โหนด Agent (4C)

ใน Workbench ให้ไปที่โหนด Agent (4C) เปิด stage2_direction/agent.py

04-4C

โหมดการทำงานและสคีมาที่มีโครงสร้าง

เมื่อฝังไว้ใน Workflow Agent จะทํางานในโหมด single_turn โดยค่าเริ่มต้น

  • โดยจะรับเอาต์พุตของโหนดก่อนหน้าเป็นอินพุตบริบท
  • โดยจะดำเนินการเรียกใช้การอนุมานครั้งเดียวโดยไม่มีการสนทนาไปมา
  • โดยจะแสดงผล Structured Data ไปยังโหนดถัดไป

การกำหนด output_schema=Directions จะทำให้ Agent บังคับใช้การตรวจสอบ Pydantic กับเอาต์พุตโมเดล กราฟดาวน์สตรีมจะได้รับออบเจ็กต์ที่พิมพ์แทนข้อความที่ไม่มีโครงสร้าง

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 สั่งให้โมเดลเสนอผู้สมัคร 4 คนโดยอ้างอิงหลักฐานจากทั้งเทรนด์และงานที่ค้างอยู่ ผู้สมัครรับเลือกตั้งหมายเลข 1-3 เสนอแนวคิดช่องที่ใช้ได้จริง ผู้สมัครคนที่ 4 จงใจนำเสนอแนวคิดที่ละเมิดนโยบายเพื่อทดสอบเกตความปลอดภัยในขั้นตอนถัดไป

การแก้ไขภาคปฏิบัติ: การกำหนดโหนด Agent และการเชื่อมโยงการเข้าร่วม

ใน stage2_direction/agent.py ให้กำหนดค่า propose_directions และขยายขอบเขตของเวิร์กโฟลว์ ดังนี้

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

สิ่งที่จะเกิดขึ้นและเหตุผล

  • การใช้พจนานุกรมโดยตรง: propose_directions ใช้เพย์โหลด JSON ที่ join_research ปล่อยออกมาโดยไม่ต้องจัดรูปแบบด้วยตนเอง
  • เอาต์พุตผู้สมัครที่พิมพ์: เอเจนต์จะปล่อยออบเจ็กต์ Directions ที่ตรวจสอบแล้วซึ่งมีผู้สมัครที่แยกกัน 4 ราย โหนดดาวน์สตรีมจะอ่านฟิลด์ตามชื่อแอตทริบิวต์ (candidate.title) โดยไม่มีการแยกวิเคราะห์สตริง

โมเดลแบบมีมนุษย์ร่วม (4D)

ในเวิร์กเบนช์ ให้ไปที่โมเดลแบบมีมนุษย์ร่วม (4D) เปิด agent/graph.py

04-4D

คำสั่งพรอมต์กับการระงับเชิงกำหนด

เวิร์กโฟลว์การผลิตที่ก่อให้เกิดค่าใช้จ่ายหรือเผยแพร่เนื้อหาต้องมีการกำกับดูแลโดยมนุษย์ในจุดตัดสินใจที่สำคัญ ในพรอมต์เดียว คำขอยืนยันเป็นคำแนะนำที่ผู้ใช้สามารถพรอมต์โมเดลให้ข้ามได้อย่างง่ายดาย ในเวิร์กโฟลว์ ADK เครื่องมือการดำเนินการจะบังคับใช้การอนุมัติจากเจ้าหน้าที่ โดยกราฟจะหยุดที่โหนดที่กำหนดและไม่สามารถดำเนินการต่อได้จนกว่าจะได้รับอินพุตภายนอกที่ตรวจสอบสคีมาแล้ว ดังนี้

  • การหยุดชั่วคราว RequestInput จะระงับการดำเนินการเวิร์กโฟลว์ทันที
  • ADK จะบันทึกการโทรที่ขัดจังหวะแบบเปิดในที่เก็บเซสชันและออก interrupt_id ที่ไม่ซ้ำกัน
  • กระบวนการดำเนินการจะหยุดลงโดยไม่ใช้โทเค็นหรือเทรดเซิร์ฟเวอร์
  • การดำเนินการกราฟจะกลับมาทำงานอีกครั้งก็ต่อเมื่อมีการส่ง function_response ที่ถูกต้องซึ่งตรงกับสคีมาและรหัสการขัดจังหวะ

การแก้ไขด้วยตนเอง: การระงับการดำเนินการด้วย RequestInput

ใน agent/graph.py ให้ใช้การเรียกใช้การระงับภายใน 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 กำหนดค่าแอตทริบิวต์ 3 รายการดังนี้

  • message: ข้อความแจ้งให้เขียนรีวิวที่แสดงต่อผู้ใช้
  • response_schema: สคีมา JSON ที่ส่วนหน้าแสดงเป็นแบบฟอร์มอินพุต ซึ่ง ADK จะตรวจสอบเมื่อส่ง
  • payload: ข้อมูลเมตาที่รวมมากับคำขอ (ผู้สมัคร 4 คน) ซึ่งช่วยให้อินเทอร์เฟซไคลเอ็นต์แสดงผลการ์ดรีวิวได้โดยไม่ต้องค้นหาสถานะเซสชัน

สิ่งที่จะเกิดขึ้นและเหตุผล

  • เวิร์กโฟลว์จะหยุดที่ direction_gate: ใน ADK Web หรืออินเทอร์เฟซ Workbench การเรียกใช้จะหยุดชั่วคราวและแสดงแบบฟอร์มการเลือกผู้สมัครแบบอินเทอร์แอกทีฟ
    • สาเหตุ: เครื่องมือพบ RequestInput ที่สร้างขึ้นและคงสถานะการดำเนินการไว้ที่ runs/sessions.db
  • การกลับมาทำงานต่อต้องใช้อินพุตที่มีโครงสร้าง: การส่งข้อความแชทที่กำหนดเองจะไม่ทำให้กราฟดำเนินต่อไป การเลือกตัวเลือก (1, 2, 3 หรือ 4) จะส่ง function_response ที่พิมพ์ซึ่งตรงตาม response_schema และดำเนินการต่อ

5. สถานะและเราเตอร์

ใน VibeStudio Workbench ให้ไปที่ขั้นตอนที่ 5 · สถานะและเราเตอร์ ส่วน (5A) ถึง (5C)

คุณจะคงการเลือกของผู้ใช้ไว้ในสถานะเซสชัน บังคับใช้นโยบายความปลอดภัยของช่องโดยใช้โหนดเราเตอร์เชิงกำหนด และประกอบเอเจนต์งานแบบวนซ้ำเพื่อแก้ไขการละเมิดนโยบายโดยอัตโนมัติก่อนที่จะสร้างสคริปต์วิดีโอ

สถานะเวิร์กโฟลว์ (5A)

ใน Workbench ให้ไปที่สถานะเวิร์กโฟลว์ (5A)

05-5A

สถานะเซสชันเทียบกับเอาต์พุตของโหนด

ในเวิร์กโฟลว์ ADK ข้อมูลจะเคลื่อนที่ผ่านกราฟด้วยกลไก 2 อย่างที่แตกต่างกัน ดังนี้

  • เอาต์พุตโหนด (Event(output=...)): ข้อมูลที่ส่งไปยังผู้ใช้ปลายทางที่อยู่ถัดไปโดยตรงตามที่กำหนดไว้ในรายการ Edge
  • สถานะเซสชัน (Event(state=...)): พจนานุกรมคีย์-ค่าที่ใช้ร่วมกันซึ่งโหนดที่ตามมาในวงจรการดำเนินการเข้าถึงได้

05-5A

เมื่อผู้ใช้เลือกตัวเลือกที่ direction_gate ระบบจะแสดงตัวเลือกเป็นดัชนีตัวเลข ({"pick": "2"}) โหนดปลายทางต้องมีออบเจ็กต์ทิศทางที่สมบูรณ์ ซึ่งประกอบด้วยชื่อ มุมมองการเล่าเรื่อง และประโยคเปิด แทนที่จะส่งข้อมูลเมตาแบบละเอียดผ่านเพย์โหลดโหนดระดับกลางทุกรายการ persist_direction จะเขียนผู้สมัครที่ได้รับการแก้ไขไปยังสถานะเซสชันที่แชร์

โหนดไม่จำเป็นต้องส่งพจนานุกรมสถานะเซสชันทั้งหมด เมื่อโหนดให้ผลลัพธ์ Event(state=...) โหนดจะให้เฉพาะคู่คีย์-ค่าใหม่หรือที่อัปเดตแล้ว ADK จะผสานการอัปเดตเหล่านี้เข้ากับที่เก็บเซสชันโดยอัตโนมัติ ดังนี้

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

การให้ Event นี้จะส่งต่อการควบคุมไปยังรันไทม์ Workflow ซึ่งจะคงค่าใหม่ไว้ในบันทึกเซสชันใน runs/sessions.db

การเชื่อมโยงพารามิเตอร์

โหนดฟังก์ชัน ADK จะอ่านสถานะเซสชันโดยอัตโนมัติผ่านการตรวจสอบพารามิเตอร์ หากลายเซ็นฟังก์ชันประกาศชื่อพารามิเตอร์ที่ตรงกับคีย์สถานะที่มีอยู่ ADK จะดึงคีย์ดังกล่าวจากสถานะและส่งต่อโดยตรง

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

ในกรณีนี้ direction_gate เขียน candidates ลงในสถานะเซสชัน ADK จะเชื่อมโยงกับ persist_direction(node_input, candidates: list = []) โดยตรงโดยไม่ต้องค้นหาพจนานุกรมอย่างชัดเจน

คีย์ที่ขึ้นต้นด้วย user: จะยังคงอยู่ตลอดเซสชันในพื้นที่เก็บข้อมูลระดับผู้ใช้ ซึ่งช่วยให้การเรียกใช้เวิร์กโฟลว์ในภายหลังเข้าถึงค่ากำหนดของครีเอเตอร์ได้

การแก้ไขจริง: การคงสถานะและการเชื่อมต่อโหนด

  1. ใน agent/graph.py ภายใน persist_direction ให้แทนที่บรรทัด TODO: PERSIST_STATE ด้วยผลลัพธ์ของเหตุการณ์สถานะ ดังนี้
    yield Event(state={"direction": chosen["title"], "angle": chosen.get("angle", ""),
                       "hook": hook, "user:prefs": {"last_direction": chosen["title"]}})
  1. ใน stage3_router/agent.py ให้เพิ่ม persist_direction ต่อท้ายเชนที่ 3 ในรายการ edges ดังนี้
           (join_research, propose_directions, direction_gate,
            persist_direction)

บันทึกไฟล์ ในเวิร์กเบนช์ ให้ตรวจสอบว่าทั้ง state write in place และ persist_direction in the chain แสดงเครื่องหมายถูกสีเขียว

โหนดเราเตอร์ (5B)

ใน Workbench ให้ไปที่โหนดเราเตอร์ (5B)

05-5B

การกำหนดเส้นทางตามนโยบายแบบดีเทอร์มินิสติก

เราเตอร์คือโหนดฟังก์ชันเฉพาะทางที่ประเมินเอาต์พุตอัปสตรีมและกำหนดทิศทางการดำเนินการตามสาขากราฟแบบมีเงื่อนไข เราเตอร์จะดำเนินการตามตรรกะเชิงกำหนดโดยไม่ต้องเรียกใช้ LLM ซึ่งต่างจาก Agent แบบ Generative

เราเตอร์จะแสดงผล Event ที่ระบุแท็ก 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")

ในคำจำกัดความของเวิร์กโฟลว์ เป้าหมาย Edge ที่กำหนดเป็นพจนานุกรมจะแสดงเส้นทางชื่อไปยังโหนดปลายทาง ดังนี้

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

เราเตอร์เวิร์กโฟลว์ policy_check จะอ่านวลีต้องห้ามจาก agent/policy_words.txt และทำการจับคู่ทั้งคำกับชื่อและมุมมองของทิศทางที่เลือก ดังนี้

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

การจัดเก็บนโยบายเป็นข้อมูลแทนที่จะเป็นวิธีการที่ฮาร์ดโค้ดช่วยให้สามารถอัปเดตได้โดยไม่ต้องแก้ไขกราฟเวิร์กโฟลว์ โดยการอัปเดตไฟล์ข้อความจะใช้กับการเรียกใช้ครั้งต่อๆ ไปทันที เนื่องจากการประเมินเป็นการจับคู่นิพจน์ทั่วไปเชิงกำหนด จึงใช้เวลาดำเนินการเพียงไม่กี่มิลลิวินาทีโดยไม่มีค่าใช้จ่ายโทเค็นก่อนที่การเขียนสคริปต์ Generative จะเริ่มต้นขึ้น

ปลายทาง: Scripter และกักเก็บ

เราเตอร์จะส่งการเข้าชมไปยังโหนดปลายทาง 1 ใน 2 โหนดต่อไปนี้

  • scripter: โหนด Agent single_turn ที่แปลงทิศทางที่ได้รับอนุมัติให้เป็นสคริปต์การผลิตที่มีโครงสร้างซึ่งเป็นไปตามสคีมา Pydantic Script ดังนี้
scripter = Agent(
    name="scripter",
    model=config.MODEL,
    instruction=SCRIPT_INSTRUCTION,
    output_schema=Script)
  • quarantine: เริ่มต้นด้วยฟังก์ชันตัวยึดตำแหน่งที่หยุดคำสั่งที่ถูกแจ้งว่าไม่เหมาะสม ซึ่งจะถูกแทนที่ในส่วนถัดไปโดย Agent การแก้ไขอัตโนมัติ

การแก้ไขแบบลงมือทำ: การกำหนดเส้นทางการตรวจสอบนโยบาย

  1. ใน agent/graph.py ภายใน policy_check ให้เขียนคำสั่ง "return" ให้สมบูรณ์
    return Event(output=node_input, route="BLOCK" if bad else "OK")
  1. ใน stage3_router/agent.py ให้อัปเดต edges เพื่อกำหนดเส้นทาง policy_check และรวมสาขาการกักบริเวณเข้ากับ scripter อีกครั้ง โดยทำดังนี้
           (join_research, propose_directions, direction_gate,
            persist_direction, policy_check),
           (policy_check, {"OK": scripter, "BLOCK": quarantine}),
           (quarantine, scripter)])

บันทึกไฟล์ ใน Workbench ให้ตรวจสอบว่าได้ยืนยันการจับคู่ Edge ของเราเตอร์แล้ว

โหมด Agent และโหนดงาน (5C)

ใน Workbench ให้ไปที่โหมดเอเจนต์และโหนดงาน (5C)

05-5C

โหมดการดำเนินการของ Agent

อินสแตนซ์ ADK Agent รองรับโหมดการดำเนินการ 3 โหมดที่ปรับให้เหมาะกับข้อกำหนดของไปป์ไลน์ที่เฉพาะเจาะจง ดังนี้

โหมด

วงจรการดำเนินการ

บทบาทในไปป์ไลน์

chat

ลูปการสนทนาแบบหลายรอบ โมเดลจะกำหนดเวลาที่จะเรียกใช้เครื่องมือ ขอข้อมูล หรือสิ้นสุดเทิร์น

ตัวแทนระดับรูทที่โต้ตอบกับผู้ใช้ที่เป็นมนุษย์

single_turn

การเรียกใช้การอนุมานโมเดลเดียว รับอินพุตของโหนดก่อนหน้าและส่งออบเจ็กต์สคีมาที่มีโครงสร้าง

การแปลงกราฟตามลําดับ (propose_directions, scripter)

task

ลูปอัตโนมัติที่มีการเรียกใช้เครื่องมือ ตัวแทนจะทำซ้ำจนกว่าจะเรียกใช้เครื่องมือ finish_task ในตัว

การแก้ไขและการตรวจสอบแบบหลายขั้นตอน (quarantine)

การแก้ไขนโยบายอัตโนมัติ

การเขียนคำสั่งที่ถูกแจ้งว่าไม่เหมาะสมใหม่ต้องใช้โหมด task เนื่องจากจำนวนการทำซ้ำเพื่อแก้ไขนั้นไม่แน่นอน ตัวแทนจะได้รับคำสั่งที่ถูกแจ้งว่าไม่เหมาะสม เรียกใช้ find_policy_hits เพื่อตรวจหาการละเมิด ขอทางเลือกที่ได้รับอนุมัติผ่าน suggest_replacement เขียนคำสั่งใหม่ และยืนยันความเหมาะสมก่อนดำเนินการต่อ

เครื่องมือทั้ง 2 รายการได้รับการกำหนดไว้ใน agent/cleanup_tools.py พร้อมลายเซ็นที่พิมพ์และ Docstring ดังนี้

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

การแก้ไขภาคปฏิบัติ: การประกอบเอเจนต์งานกักเก็บ

ใน stage3_router/agent.py ให้แทนที่ฟังก์ชันตัวยึดตำแหน่ง quarantine ด้วยคำจำกัดความของเอเจนต์งาน

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

โหมดงานจะจัดเตรียมเครื่องมือให้แก่ Agent และสิ้นสุดการดำเนินการโดยเรียกใช้ finish_task เมื่อกำหนดค่า mode="task" แล้ว ADK จะให้ finish_task โดยอัตโนมัติและรับพารามิเตอร์จาก output_schema เพื่อให้มั่นใจว่าโหนดจะสร้างออบเจ็กต์ CleanedDirection ที่พิมพ์แล้วซึ่งตรงกับสคีมาอินพุตของโหนดสคริปต์

05-5C

สิ่งที่จะเกิดขึ้นและเหตุผล

ทดสอบเส้นทางการดำเนินการทั้ง 2 เส้นทางใน ADK Web หรือ VibeStudio Workbench โดยทำดังนี้

  • เส้นทางที่ได้รับอนุมัติ (ผู้สมัคร 1, 2 หรือ 3):
    • การเลือกผู้สมัครที่ได้รับอนุมัติจะกำหนดเส้นทางจาก policy_check ไปยัง scripter (route="OK") โดยตรง
    • ผู้เขียนสคริปต์จะสร้างสคริปต์การผลิตแบบ 3 ช็อตตามสคีมา Script
  • เส้นทางการแก้ไขการกักกัน (ผู้สมัคร 4):
    • ผู้สมัครรายที่ 4 มีคำศัพท์ที่ถูกแจ้งว่าไม่เหมาะสม ("คลิกเบต" "เคล็ดลับที่กำลังเป็นไวรัล")
    • policy_check เส้นทางไปยัง quarantine (route="BLOCK")
    • ในร่องรอยของเซสชัน ให้สังเกตการเรียก quarantine การเรียก find_policy_hits การเรียก suggest_replacement สำหรับการละเมิดแต่ละครั้ง การเขียนชื่อใหม่ และการเรียก finish_task
    • การดำเนินการจะกลับมาที่ scripter โดยสร้างสคริปต์จากคำสั่งที่ผ่านการตรวจสอบแล้ว

6. Memory Bank

ใน VibeStudio Workbench ให้ไปที่ขั้นตอนที่ 6 · คลังความจำ ส่วน (6A) และ (6B)

ปัจจุบันเวิร์กโฟลว์ทำงานโดยไม่มีหน่วยความจำข้ามเซสชัน การดำเนินการแต่ละครั้งจะเริ่มต้นจากศูนย์ โดยไม่ทราบว่าครีเอเตอร์เลือกอะไรไว้ก่อนหน้านี้หรือชอบแนวเพลงใด ในขั้นตอนนี้ คุณจะเชื่อมต่อ Vertex AI Agent Engine Memory Bank เพื่อจัดเก็บและดึงข้อมูลค่ากำหนดของครีเอเตอร์ในการเรียกใช้แต่ละครั้ง

สิ่งสำคัญคือหน่วยความจำจะผสานรวมผ่าน Lifecycle Callback ของ Agent แทนโหนดไปป์ไลน์ เนื่องจากการแยกและการดึงข้อมูลในหน่วยความจำจะให้บริการแก่เอเจนต์แต่ละรายแทนที่จะเป็นขั้นตอนข้อมูลระดับกลาง การแนบการเรียกกลับจึงช่วยรักษาโทโพโลยีของกราฟที่สะอาดและแยกออกจากกัน

Memory Bank (6A)

ใน Workbench ให้ไปที่คลังหน่วยความจำ (6A)

06-6A

ความทรงจำระดับผู้ใช้ที่มีการจัดการ

Memory Bank เป็นบริการที่มีการจัดการสำหรับหน่วยความจำของผู้ใช้ในระยะยาว โดยจะจัดระเบียบข้อเท็จจริงเกี่ยวกับบุคคลภายใต้ขอบเขตที่กำหนด ซึ่งในที่นี้ระบุด้วยชื่อแอปพลิเคชันและรหัสผู้ใช้ ดังนี้

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

หัวข้อความทรงจำที่กำหนดเองจะกำหนดขอบเขตของสิ่งที่ธนาคารบันทึกไว้ ดังนี้

  • การดึงข้อมูลหัวข้อ: เมื่อมีการส่งข้อความการสนทนาใหม่ผ่าน memories.generate บริการจะใช้โมเดลการดึงข้อมูลกับคำอธิบายหัวข้อแต่ละรายการ ข้อความที่ไม่ตรงกับหัวข้อจะไม่สร้างความทรงจำ
  • การรวมและการกรองข้อมูลที่ซ้ำกันออก: บริการจะแปลงข้อเท็จจริงที่ดึงมาใหม่เป็นการฝังและเปรียบเทียบกับความทรงจำที่มีอยู่ในขอบเขต เมื่อข้อมูลที่สังเกตได้สอดคล้องกับความทรงจำที่มีอยู่ บริการจะอัปเดตความทรงจำนั้น เมื่อแสดงข้อมูลใหม่ บริการจะสร้างรายการใหม่ กระบวนการรวมนี้ช่วยให้มั่นใจได้ว่าเซสชันหลายรายการเกี่ยวกับหัวข้อหนึ่งๆ จะรวมเป็นสรุปที่สอดคล้องกันแทนที่จะสร้างรายการที่ซ้ำซ้อน
  • การดึงข้อมูล: การเรียกใช้ memories.retrieve ที่มีขอบเขตผู้ใช้จะแสดงข้อเท็จจริงที่จัดเก็บไว้ โดยเรียงจากเก่าที่สุดก่อน

การดำเนินการทั้ง 2 อย่างนี้จะดำเนินการใน agent/platform/memory.py ชื่อทรัพยากรธนาคารที่จัดสรรไว้จะแคชไว้ในเครื่องใน runs/memorybank.json

การตั้งค่าคลังความทรงจำ

ใช้ตัวควบคุมเวิร์กเบนช์หรือเรียกใช้คำสั่ง CLI ในเทอร์มินัล

  1. เชื่อมต่อและจัดสรรธนาคาร
    python -m agent.platform.bank
    
    สร้างอินสแตนซ์ Agent Engine และกำหนดค่าหัวข้อ CREATOR_TASTE และ CHANNEL_RULES
  2. เซสชันที่ผ่านมาของ Seed:
    python -m agent.platform.bank load
    
    โหลดเซสชันที่ผ่านมาของครีเอเตอร์ 4 เซสชัน (ธีมสัตว์ 2 ธีมที่มีข้อจำกัดด้านสไตล์ ธีมแกดเจ็ต 1 ธีม และธีมแฟนตาซีล่าสุด 1 ธีม)
  3. ตรวจสอบข้อเท็จจริงที่รวบรวมมา
    python -m agent.platform.bank list
    
    ตรวจสอบเอาต์พุต สังเกตว่าข้อความถอดเสียงแบบบรรยายได้รับการแปลงเป็นข้อความแสดงข้อเท็จจริงที่รวมกันและมีโครงสร้างอย่างไร

การติดต่อกลับ (6B)

ใน Workbench ให้ไปที่การติดต่อกลับ (6B) เปิด stage4_memory/agent.py

06-6A

Lifecycle Callback ของ ADK Agent

Callback คือฟังก์ชันที่ส่งเป็นอาร์กิวเมนต์ไปยัง Agent ADK จะเรียกใช้การเรียกกลับในช่วงเวลาของวงจรที่กำหนดไว้ล่วงหน้า โดยส่งบริบทที่ใช้งานอยู่ การส่งคืน None จะทำให้การดำเนินการเป็นไปตามปกติ ส่วนการส่งคืนออบเจ็กต์แทนที่จะเป็นการลบล้างหรือสกัดกั้นการดำเนินการ

06-6A

ADK มี Callback 3 คู่ ดังนี้

คู่ Callback

จุดเรียกใช้

พารามิเตอร์ที่ได้รับ

ลักษณะการทำงานของค่าที่แสดงผล

before_agent_callback
after_agent_callback

ครอบคลุมทั้งรอบการสนทนาของตัวแทน

CallbackContext (สถานะ เซสชัน การเรียกใช้)

การแสดงผล Content จะแทนที่การตอบกลับของ Agent ส่วน None จะดำเนินการตามปกติ

before_model_callback
after_model_callback

การเรียกใช้การอนุมาน LLM แต่ละครั้ง

LlmRequest หรือ LlmResponse

การกด Return LlmResponse จะขัดจังหวะหรือข้ามการเรียกใช้โมเดล ส่วนการกด None จะดำเนินการต่อ

before_tool_callback
after_tool_callback

เกี่ยวกับการดำเนินการของเครื่องมือแต่ละรายการ

คำจำกัดความของเครื่องมือ อาร์กิวเมนต์ ผลลัพธ์

การแสดงผล dict จะลบล้างเอาต์พุตของเครื่องมือ และ None จะดำเนินการต่อ

Callback เป็นตำแหน่งที่ชัดเจนสำหรับการแทรกบริบท การป้องกัน เทเลเมทรี และการค้นหาแคชโดยไม่ต้องเพิ่มโหนดที่ไม่เกี่ยวข้องลงในกราฟเวิร์กโฟลว์

การแก้ไขด้วยตนเอง: การเรียกคืนสายไฟและการเรียกกลับ

  1. ใน stage4_memory/agent.py ให้อัปเดต propose_directions เพื่อแนบ before_model_callback=recall_taste ดังนี้
    output_schema=Directions,
    before_model_callback=recall_taste)

recall_taste จะดำเนินการทันทีก่อนที่ Gemini จะสร้างเส้นทางที่เป็นไปได้ โดยจะดึงประวัติของครีเอเตอร์จาก Memory Bank จัดรูปแบบความทรงจำโดยเรียงจากเก่าที่สุดก่อน แล้วต่อท้ายในLlmRequestที่ส่งออก พรอมต์จะสั่งให้โมเดลปรับผู้สมัคร 1-3 ให้สอดคล้องกับรสนิยมปัจจุบันของครีเอเตอร์ ขณะเดียวกันก็ถือว่ากฎของช่องเป็นข้อจำกัดที่เข้มงวด

  1. ใน stage4_memory/agent.py ให้อัปเดต scripter เพื่อแนบ after_agent_callback=remember_pick ดังนี้
    output_schema=Script,
    after_agent_callback=remember_pick)

remember_pick จะทำงานหลังจาก scripter ทำงานเสร็จ โดยจะอ่านทิศทางที่เลือกจากสถานะเซสชัน สังเคราะห์ข้อความสรุปการตัดสินใจของครีเอเตอร์ และเรียกใช้ memories.generate เพื่ออัปเดตคลังความจำ

สิ่งที่จะเกิดขึ้นและเหตุผล

ทดสอบเวิร์กโฟลว์ที่เพิ่ม Callback ใน Workbench หรือ ADK Web โดยทำดังนี้

  1. เรียกใช้ด้วยพรอมต์ที่ว่างเปล่า:
    • ในการติดตามเซสชัน ให้ตรวจสอบ LlmRequest เพื่อหา propose_directions โปรดสังเกตบริบทความทรงจำที่ต่อท้ายซึ่งให้รายละเอียดเกี่ยวกับความชอบของครีเอเตอร์ในเรื่องธีมแฟนตาซีและจังหวะการเล่าเรื่องที่กระชับ
    • สังเกตทิศทางที่เสนอ: ผู้สมัคร 1 ถึง 3 สอดคล้องกับค่ากำหนดที่ผ่านมาของครีเอเตอร์ แม้ว่าเทรนด์จะเน้นหัวข้ออื่นๆ ก็ตาม
  2. เลือกผู้สมัครที่ direction_gate
  3. หลังจาก scripter เสร็จสมบูรณ์แล้ว ให้ตรวจสอบบันทึกของ Memory Bank ดังนี้
    python -m agent.platform.bank list
    
    ตอนนี้คลังจะแสดงตัวเลือกล่าสุด โดยรวมเข้ากับบันทึกรสนิยมก่อนหน้า

7. RAG Engine

ใน VibeStudio Workbench ให้ไปที่ขั้นตอนที่ 7 · เครื่องมือ RAG ส่วน (7A) และ (7B)

07-7A

วิดีโอที่เผยแพร่จะได้รับความคิดเห็นจากผู้ชมอย่างต่อเนื่อง ระบบรวบรวมความคิดเห็นที่เป็นตัวแทน 30 รายการไว้ใน agent/comments.md ซึ่งแสดงให้เห็นถึงคำชมจากผู้ชม การวิจารณ์เกี่ยวกับจังหวะการนำเสนอสปอนเซอร์ และความชอบด้านเสียง ในขั้นตอนนี้ คุณจะจัดทำดัชนีความคิดเห็นเหล่านี้โดยใช้ Vertex AI RAG Engine และเชื่อมต่อการดึงข้อมูลเชิงความหมายเข้ากับแฟนเอาต์ (Fan-Out) ของการค้นคว้า

การดึงข้อมูลผ่านเอกสาร (7A)

ใน Workbench ให้ไปที่ RAG Engine (7A)

Memory Bank เทียบกับ RAG Engine

เครื่องมือทั้ง 2 อย่างนี้จะอิงเวิร์กโฟลว์ตามข้อมูลภายนอก แต่มีวัตถุประสงค์ทางสถาปัตยกรรมที่แตกต่างกัน ดังนี้

มิติข้อมูล

Memory Bank

RAG Engine

กรณีการใช้งานหลัก

ค่ากำหนดของผู้ใช้ในระยะยาวและกฎการปฏิบัติงาน

การดึงข้อมูลเชิงความหมายจากคอลเล็กชันเอกสารขนาดใหญ่

ขอบเขต

กำหนดขอบเขตเป็นรหัสผู้ใช้และชื่อแอปพลิเคชันแต่ละรายการ

กำหนดขอบเขตเป็นทรัพยากรคลังข้อมูลที่แชร์กับผู้ใช้ทั้งหมด

การประมวลผลข้อมูล

การแยก การฝัง และการรวมความหมายแบบเรียลไทม์

การแบ่งเอกสารออกเป็นส่วนๆ การฝังเวกเตอร์ และการค้นหาเพื่อนบ้านที่ใกล้ที่สุด

การผสานรวมกราฟ

Lifecycle Callback ของ Agent (before_model_callback, after_agent_callback)

โหนดฟังก์ชันเฉพาะในการกระจายการค้นคว้า (read_feedback)

07-7A

การแบ่งเอกสารออกเป็นส่วนๆ และการฝัง

เครื่องมือ RAG จะจัดทำดัชนีเอกสารโดยแบ่งข้อความออกเป็นข้อความเชิงความหมายและจัดเก็บเวกเตอร์ไว้ในฐานข้อมูลที่มีการจัดการ ดังนี้

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)))
  • ขนาดก้อน: กำหนดค่าเป็น 120 โทเค็นโดยมีโทเค็นที่ทับซ้อนกัน 20 โทเค็น ซึ่งจะจับความคิดเห็น 2-3 รายการต่อข้อความ เพื่อให้เวกเตอร์แต่ละรายการแสดงความรู้สึกที่สอดคล้องกันโดยไม่ทำให้ความหมายของความคิดเห็นที่ไม่เกี่ยวข้องเจือจางลง
  • โมเดลการฝัง: text-embedding-005 แปลงข้อความเป็นเวกเตอร์ที่มีมิติสูง เมื่อส่งคำค้นหา โมเดลจะแปลงคำค้นหาเป็นเวกเตอร์และค้นหาการจับคู่ที่ใกล้ที่สุดตามระยะห่างเชิงความหมาย ความคิดเห็นเกี่ยวกับมังกรตัวเล็กที่เฝ้าถุงเท้าจะตรงกับพรอมต์เกี่ยวกับสิ่งมีชีวิตมหัศจรรย์โดยไม่จำเป็นต้องมีคีย์เวิร์ดที่ตรงกันทุกประการ

การตั้งค่าคลัง RAG

เริ่มต้น Corpus โดยใช้ปุ่มเวิร์กเบนช์หรือคำสั่งเทอร์มินัล

  1. สร้างคลังข้อความ
    python -m agent.platform.rag
    
    จัดสรรฐานข้อมูลเวกเตอร์ที่มีการจัดการและบันทึกรหัสทรัพยากรใน runs/ragcorpus.json
  2. อัปโหลดและจัดทำดัชนีความคิดเห็น: อัปโหลด agent/comments.md ด้วยการกำหนดค่าการแบ่งกลุ่มและรอให้การจัดทำดัชนีเสร็จสมบูรณ์
  3. ค้นหาคลังข้อมูล: ทดสอบการดึงข้อมูลที่คล้ายกันด้วยคำค้นหาที่ไม่มีคำตรงกับความคิดเห็น (เช่น ค้นหา "สัตว์วิเศษขนาดเล็ก" เพื่อดึงความคิดเห็นเกี่ยวกับมังกร)

โหนดการดึงข้อมูล (7B)

ใน Workbench ให้ไปที่ผู้อ่านคนที่ 3 (7B) เปิด stage5_rag/agent.py

07-7B

การดึงข้อมูลเป็นโหนดกราฟ

ความคิดเห็นของกลุ่มเป้าหมายแสดงถึงข้อมูลการวิจัยที่แชร์ในเวิร์กโฟลว์ ความรู้สึกของผู้ชมจะส่งไปยัง join_research โดยตรงพร้อมกับข้อมูลเทรนด์และข้อมูลแบ็กล็อก ซึ่งแตกต่างจากหน่วยความจำของครีเอเตอร์ส่วนตัว ดังนั้นจึงนำมาใช้เป็นโหนดฟังก์ชันดังนี้

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 จะดึงแนวคิดเริ่มต้นของผู้ใช้และดำเนินการค้นหาเวกเตอร์กับคลังข้อมูลของเครื่องมือ RAG โดยจะส่งความคิดเห็นที่ดึงมาในเพย์โหลด Event(output=...)

การแก้ไขภาคปฏิบัติ: การต่อสายรีดเดอร์ตัวที่ 3 เข้ากับ Fan-Out

ใน stage5_rag/agent.py ให้อัปเดต edges เพื่อเพิ่ม read_feedback เป็นสาขาคู่ขนานที่ 3 ที่เข้าสู่ join_research ดังนี้

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

เนื่องจาก join_research เป็น JoinNode จึงซิงโครไนซ์กิ่งขาเข้าทั้งหมด โดยรอจนกว่า scan_trends, read_backlog และ read_feedback จะปล่อยเหตุการณ์ทั้งหมดก่อนที่จะส่งต่อแพ็กเกจที่รวบรวมแล้วไปยังสตรีมปลายทาง

สิ่งที่จะเกิดขึ้นและเหตุผล

เรียกใช้เวิร์กโฟลว์ใน Workbench โดยทำดังนี้

  1. ส่งพรอมต์ไอเดีย (เช่น "มังกรจิ๋วเฝ้าเคาน์เตอร์ครัว")
  2. ในร่องรอยการดำเนินการ ให้ตรวจสอบว่าโหนดเครื่องอ่านทั้ง 3 รายการดำเนินการพร้อมกัน
  3. ดู join_research: ตอนนี้พจนานุกรมเอาต์พุตมี trends, backlog และ feedback
  4. ตรวจสอบผู้สมัครที่สร้างขึ้นจาก propose_directions: โมเดลจะรวมความคิดเห็นของผู้ชมไว้ในข้อเสนอและอ้างอิงความรู้สึกของผู้ชมในช่องหลักฐาน
  5. โปรดทราบว่าการดึงข้อมูล RAG เป็นแบบเชิงกำหนด (คำค้นหาที่เหมือนกันจะแสดงข้อความความคิดเห็นที่เหมือนกัน) ในขณะที่โหนดข้อเสนอ Generative จะสร้างรูปแบบที่สร้างสรรค์

8. การสร้างวิดีโอแบบอะซิงโครนัสด้วย Veo

ใน VibeStudio Workbench ให้ไปที่ขั้นตอนที่ 8 · วิดีโอ ส่วน (8A) และ (8B)

การสร้างวิดีโอความละเอียดสูงด้วย Google Veo ต้องใช้เวลาหลายนาทีต่อการแสดงผล 1 ครั้ง การบล็อกการเรียกใช้กราฟในช่วงนี้จะทำให้สิ้นเปลืองทรัพยากรการประมวลผล ล็อกพูลเธรด และทำให้การเรียกใช้เกิดการหลุดของการเชื่อมต่อ HTTP ในขั้นตอนนี้ คุณจะทำให้การแสดงผลวิดีโอเป็นแบบอะซิงโครนัสโดยใช้ LongRunningFunctionTool ของ ADK

เครื่องมือที่ใช้เวลานาน (8A)

ในเวิร์กเบนช์ ให้ไปที่เครื่องมือที่ทำงานเป็นเวลานาน (8A) เปิด stage6_video/agent.py และ agent/deliver.py

08-8A

เครื่องมือแบบซิงโครนัสเทียบกับเครื่องมือที่ทำงานเป็นเวลานาน

เครื่องมือฟังก์ชัน ADK มาตรฐานจะดำเนินการแบบซิงโครนัสภายในเทิร์นของ Agent โดยโมเดลจะเรียกใช้เครื่องมือ รอเพย์โหลดที่ส่งคืน และรวมผลลัพธ์เข้ากับเทิร์นที่กำลังดำเนินการ

การเรนเดอร์วิดีโอไม่สามารถดำเนินการให้เสร็จสมบูรณ์ได้ในครั้งเดียว แต่ render_submit จะเริ่มงานการสร้างและแสดงใบเสร็จการดำเนินการพร้อมสถานะ "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"]}

เมื่อห่อหุ้มด้วย LongRunningFunctionTool ADK จะสกัดกั้นสถานะ "pending" เมื่อถึงคิวของตัวแทน เวิร์กโฟลว์จะหยุดชั่วคราวที่โหนด และระบบจะบันทึกข้อมูลเมตาของการโทรที่รอดำเนินการ (รวมถึงรหัสการโทรและใบเสร็จ) ใน runs/sessions.db กระบวนการดำเนินการจะสิ้นสุดอย่างราบรื่นโดยไม่ต้องรักษาการเชื่อมต่อเครือข่ายที่ใช้งานอยู่หรือเทรดผู้ปฏิบัติงาน

การแก้ไขจริง: การรวมเครื่องมือแสดงผล

ใน stage6_video/agent.py ให้อัปเดต render_desk เพื่อรวม render_submit ไว้ใน LongRunningFunctionTool ดังนี้

    tools=[LongRunningFunctionTool(render_submit)])

กำลังกลับมาทำงานต่อตามรหัสการโทร

รูปแบบการกลับมาทำงานสากล

ADK ใช้กลไกเดียวกันในการระงับและกลับมาทำงานอีกครั้งสำหรับทั้งเวิร์กโฟลว์ของมนุษย์และเครื่องมือภายนอก

ทริกเกอร์การระงับ

กำลังเริ่มต้น Construct

สถานะการระงับที่จัดเก็บไว้

เหตุการณ์การกลับมาทำงานอีกครั้ง

การตัดสินใจโดยเจ้าหน้าที่

yield RequestInput(...)

เปิดพรอมต์อินพุตในที่เก็บเซสชัน

FunctionResponse ที่มีรหัสการโทรที่ถูกระงับ

เครื่องมือที่ใช้เวลานาน

LongRunningFunctionTool(...) ส่งคืน pending

เปิดการเรียกใช้เครื่องมือในที่เก็บเซสชัน

FunctionResponse ที่มีรหัสการโทรที่ถูกระงับ

ในทั้ง 2 กรณี เวิร์กโฟลว์จะหยุดโดยสมบูรณ์และจะกลับมาทำงานอีกครั้งเมื่อมีเหตุการณ์ที่มีFunctionResponseที่ตรงกันมาจากแหล่งที่มาภายนอก ได้แก่ อินเทอร์เฟซผู้ใช้ เว็บฮุก หรือ Worker ที่ทำงานเบื้องหลัง

การแก้ไขจริง: การตอบกลับการนำส่งให้เสร็จสมบูรณ์

ใน agent/deliver.py ให้สร้างส่วน FunctionResponse ของการดำเนินการต่อ ดังนี้

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

เดมอนการนำส่งจะสำรวจ Veo จนกว่าจะสร้างไฟล์วิดีโอ จากนั้นจะส่ง FunctionResponse นี้ไปยังเซสชัน ADK จะจับคู่รหัสการโทรและกลับมาทำงานในเวิร์กโฟลว์ต่อโดยตรงที่โหนดถัดไป โหนดที่เสร็จสมบูรณ์จะไม่ทำงานอีกครั้ง และ Agent จะไม่ดำเนินการสร้างสรรค์อีกครั้ง

การตั้งค่า STUDIO_REAL_VIDEO=0 ใน .env จะเปิดใช้การแสดงผลจำลอง: start จะแสดงใบเสร็จการทดสอบทันที และ check จะจำลองการดำเนินการให้เสร็จสมบูรณ์ใน 5 วินาทีโดยไม่ต้องเรียกใช้ Veo API ที่เรียกเก็บเงินได้

การผสานรวมไปป์ไลน์ (8B)

ในเวิร์กเบนช์ ให้ไปที่ render_desk ในกราฟ (8B) เปิด stage6_video/agent.py

โหนดเทอร์มินัลในไปป์ไลน์คือ store_video โดยจะอ่านข้อมูลการแสดงผลที่เสร็จสมบูรณ์จาก runs/state.json (ซึ่งเป็นตำแหน่งที่กระบวนการนำส่งบันทึกไว้) และคอมมิต URL ของวิดีโอและสถานะการสร้างไปยังสถานะเซสชันที่แชร์

08-8B

การแก้ไขภาคปฏิบัติ: การเชื่อมต่อท่อส่งวิดีโอที่สมบูรณ์

ใน stage6_video/agent.py ให้อัปเดต edges เพื่อต่อท้าย render_desk และ store_video ดังนี้

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

สิ่งที่จะเกิดขึ้นและเหตุผล

ทดสอบขั้นตอนการสร้างแบบอะซิงโครนัสใน Workbench โดยทำดังนี้

  1. ดำเนินการเวิร์กโฟลว์ผ่านการเลือกผู้สมัครและสร้างสคริปต์
  2. ที่ render_desk ให้สังเกต Agent เรียกใช้ render_submit
  3. เวิร์กโฟลว์จะหยุดชั่วคราวทันที ใน Workbench หรือ ADK Web ให้สังเกตสถานะรอดำเนินการ โดยเซสชันจะเก็บรหัสการโทรที่เปิดอยู่ และไม่มีกระบวนการเบื้องหลังที่ใช้ทรัพยากร
  4. เรียกใช้ Daemon การนำส่งโดยใช้คอนโซล Workbench หรือในเทอร์มินัล โดยทำดังนี้
    python -m agent.deliver
    
    กระบวนการนำส่งจะตรวจสอบ Veo จนกว่าวิดีโอจะพร้อม จากนั้นจะส่งเหตุการณ์การกลับมาทำงานอีกครั้ง
  5. ใน ADK Web ให้รีเฟรชเซสชัน: การดำเนินการจะกลับมาทำงานต่อที่ store_video, คอมมิต URL ของวิดีโอไปยังสถานะเซสชัน และเวิร์กโฟลว์จะเสร็จสมบูรณ์

9. ทำให้ใช้งานได้กับ Cloud Run

ใน VibeStudio Workbench ให้ไปที่ขั้นตอนที่ 9 · ติดตั้งใช้งาน

คุณได้พัฒนาและยืนยันแต่ละคอมโพเนนต์ของไปป์ไลน์ในแซนด์บ็อกซ์เฉพาะแล้ว ในขั้นตอนนี้ คุณจะประกอบไปป์ไลน์การผลิตที่สมบูรณ์และติดตั้งใช้งานใน Google Cloud Run

09-9A

ADK Runner

ในระหว่างการพัฒนา adk web ได้จัดระเบียบกราฟ ในเวอร์ชันที่ใช้งานจริง แอปพลิเคชันจะโฮสต์เวิร์กโฟลว์โดยใช้คลาส 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: ขับเคลื่อนการดำเนินการเวิร์กโฟลว์ โดยสร้างเหตุการณ์ตามลำดับเมื่อโหนดทำงานและคงการอัปเดตไว้ในบริการเซสชัน
  • การกลับมาทำงานต่อแบบรวม: ทั้งการตัดสินใจของผู้ใช้ที่ direction_gate และการนำส่งวิดีโอที่เสร็จสมบูรณ์จาก Veo จะกลับมาดำเนินการต่อผ่านออบเจ็กต์ FunctionResponse ที่เหมือนกันซึ่งส่งไปยัง run_async

สถาปัตยกรรมของแอปพลิเคชันเวอร์ชันที่ใช้งานจริง

แอปพลิเคชันเวอร์ชันที่ใช้งานจริงใน vibestudio/ จะผสานรวมไปป์ไลน์ที่สมบูรณ์ ดังนี้

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
  • สตรีมเหตุการณ์เดียว: แบ็กเอนด์ FastAPI จะเผยแพร่เหตุการณ์ในสตรีม Server-Sent Events (SSE) เดียว ส่วนหน้าของ React จะแสดงภาพความคืบหน้าของกราฟแบบเรียลไทม์และจัดการการเชื่อมต่อที่ล่าช้าโดยไม่สูญเสียสถานะ
  • การดำเนินการแบบแยกส่วน: แอปพลิเคชันจะจัดการวนรอบเหตุการณ์ กราฟเวิร์กโฟลว์จะมุ่งเน้นที่ตรรกะการดำเนินการโดยเฉพาะ โดยไม่ทราบอินเทอร์เฟซส่วนหน้า

รายการ Edge ของเวิร์กโฟลว์ที่สมบูรณ์ใน agent/graph.py จะรวมรูปแบบสถาปัตยกรรมทั้งหมดที่สร้างขึ้นตลอด Codelab นี้เข้าด้วยกัน

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

การติดตั้งใช้งานกับ Cloud Run

Google Cloud Run มีโฮสติ้งแบบ Serverless พร้อมการปรับขนาดอัตโนมัติ การกำหนดเส้นทางคำขอ และการสร้างคอนเทนเนอร์แบบผสานรวม ดังนี้

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=...
  • การสร้างคอนเทนเนอร์: gcloud run deploy --source จะแพ็กเกจไดเรกทอรี vibestudio/ สร้างอิมเมจคอนเทนเนอร์โดยใช้ Cloud Build และติดตั้งใช้งานบริการในการดำเนินการเดียว
  • เซสชันแอฟฟินิตี้: ส่งคำขอจากผู้ใช้รายเดียวกันไปยังอินสแตนซ์คอนเทนเนอร์เดียวกัน เพื่อรักษาสถานะเซสชันในเครื่องตลอดขั้นตอนที่ทำซ้ำ
  • ความสามารถในการสังเกต: การผสานรวม Cloud Trace จะบันทึก Span แบบกระจายสำหรับทุกโหนด การเรียก LLM และการดำเนินการเครื่องมือ ซึ่งเข้าถึงได้ในคอนโซล Google Cloud ในส่วน Trace Explorer

คลิกปุ่มติดตั้งใช้งานในเวิร์กเบนช์เพื่อเรียกใช้สคริปต์การติดตั้งใช้งาน เมื่อบิลด์เสร็จสมบูรณ์ เทอร์มินัลจะแสดง URL ของบริการที่ใช้งานอยู่

แอป

10. สรุป

ใน VibeStudio Workbench ให้ไปที่ขั้นตอนที่ 10 · สรุปเพื่อตรวจสอบสถาปัตยกรรมที่เสร็จสมบูรณ์

10-summary

ขั้นตอน

สถาปัตยกรรมและแนวคิด

รูปแบบการใช้งาน

พรอมต์เดียว

พรอมต์เดียว เครื่องมือฟังก์ชัน ลูปแชทตามลำดับ

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

พื้นฐานเวิร์กโฟลว์แบบ Agentic

เวิร์กโฟลว์กราฟ การวิจัยแบบคู่ขนาน เอาต์พุตสคีมา เกตของมนุษย์

Workflow START JoinNode output_schema RequestInput

สถานะและเราเตอร์

สถานะเซสชันที่แชร์, การเชื่อมโยงพารามิเตอร์, การกำหนดเส้นทางเชิงกำหนด, ตัวแทนงาน

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

Memory Bank

ความทรงจำระยะยาวระดับผู้ใช้ การรวมความหมาย ฮุกวงจร

memories.generate / retrieve, before_model_callback, after_agent_callback

RAG Engine

การดึงข้อมูลเอกสารจากความคิดเห็นของกลุ่มเป้าหมาย การฝังเชิงความหมาย

โหนด rag.create_corpus, RagEmbeddingModelConfig, read_feedback

การสร้างวิดีโอแบบอะซิงโครนัสด้วย Veo

เครื่องมือที่ทำงานเป็นเวลานาน ใบเสร็จที่รอดำเนินการ และ Daemon การนำส่งภายนอก

LongRunningFunctionTool, FunctionResponse(id=...) การกลับมาทำงานต่อ

ทำให้ใช้งานได้กับ Cloud Run

การจัดระเบียบแบบเป็นโปรแกรม, Server-Sent Events, คอนเทนเนอร์แบบไร้เซิร์ฟเวอร์

Runner(agent=wf), run_async, การติดตั้งใช้งาน Cloud Run

หลักการทางสถาปัตยกรรมที่สำคัญ

  1. ระงับแทนการรอ: เวิร์กโฟลว์จะหยุดชั่วคราวอย่างราบรื่นเพื่อรออินพุตจากมนุษย์ (RequestInput) หรือการดำเนินการที่ใช้เวลานาน (LongRunningFunctionTool) กระบวนการต่างๆ จะไม่รอเฉยๆ ในเธรดหรือซ็อกเก็ตเครือข่าย
  2. การกลับมาทำงานอีกครั้งแบบสากล: การระงับทุกครั้งจะกลับมาทำงานอีกครั้งผ่านกลไกเดียวกัน นั่นคือ function_response เดียวที่มีรหัสการเรียกของโหนดที่ถูกระงับ
  3. การจัดการสถานะแบบแยกส่วน: โหนดจะแชร์ข้อมูลที่แชร์ผ่านคีย์สถานะเซสชันที่มีชื่อและการเชื่อมโยงพารามิเตอร์ แทนที่จะใช้เพย์โหลดระดับกลางที่มีการเชื่อมต่อแบบแน่นและมีรายละเอียดมากเกินไป
  4. การกำหนดเส้นทางเชิงกำหนดก่อนต้นทุนการสร้าง: เราเตอร์ที่อิงตามกฎและตัวกรองนิพจน์ทั่วไปจะประเมินนโยบายโดยไม่มีค่าใช้จ่ายโทเค็นก่อนที่โมเดล Generative จะทำงาน
  5. การแยกความกังวล: บริบทเฉพาะสำหรับ Agent แต่ละรายการจะอยู่ใน Lifecycle Callback ส่วนทรัพยากร Dependency ของข้อมูลที่แชร์จะอยู่ใน

10 เอาต์พุต