Quy trình công việc dựa trên tác nhân bằng ADK

1. Giới thiệu

Lớp học lập trình này hướng dẫn bạn cách xây dựng các hệ thống dựa trên tác nhân thế hệ tiếp theo bằng cách sử dụng quy trình công việc và biểu đồ trong Bộ công cụ phát triển tác nhân (ADK). Bạn sẽ triển khai các mẫu kiến trúc phổ biến, điều phối các lượt tương tác có sự tham gia của con người (HITL) và xử lý quá trình thực thi không đồng bộ kéo dài. Bạn cũng sẽ tích hợp cơ sở kiến thức doanh nghiệp và bộ nhớ liên tục để tuỳ chỉnh và phát triển hành vi của tác nhân. Cuối cùng, bạn sẽ kết nối các chức năng này để tạo một quy trình tạo video tự động.

Tình huống

Bạn điều hành một kênh kỹ thuật số trên VibeTube, có một cộng đồng khán giả đang hoạt động và một danh sách ngày càng dài các ý tưởng sáng tạo. Việc sản xuất mỗi video đòi hỏi phải thực hiện liên tục qua nhiều giai đoạn: nghiên cứu các định dạng đang thịnh hành, tổng hợp ý kiến phản hồi của người xem, phát triển kịch bản, kiểm tra việc tuân thủ chính sách và tạo đoạn video. Các mô hình tạo sinh có thể tạo bản nháp cho từng thành phần, nhưng để phát hành nhất quán, bạn cần có một kiến trúc tác nhân được phối hợp.

Để tự động hoá vòng đời này, bạn sẽ tạo VibeStudio. Quy trình này thực hiện nghiên cứu định kỳ song song, trình bày các lựa chọn được tuyển chọn để con người phê duyệt, áp dụng các cổng chính sách tự động trước khi tạo video và duy trì bối cảnh trong các lần chạy sản xuất.

Kiến thức bạn sẽ học được

• Nền tảng kỹ thuật đồ thị: Cấu trúc tác nhân nhiều bước yêu cầu luồng kiểm soát rõ ràng và đường dẫn thực thi có cấu trúc. Bạn tạo một ADK Workflow bằng cách sử dụng các bộ dữ liệu cạnh, điểm truy cập START, JoinNode để tổng hợp phân phối song song và các nút bộ định tuyến xác định để điều hướng quá trình thực thi dựa trên trạng thái.
• Chế độ tác nhân và lệnh gọi lại trong vòng đời: Các tác vụ chuyên biệt đòi hỏi hành vi hoạt động riêng biệt và các biện pháp bảo vệ có tính xác định. Bạn định cấu hình các phiên bản ADK Agent bằng cách sử dụng các chế độ chat, single_turn và task có hỗ trợ công cụ làm các nút quy trình công việc, áp dụng các trình chặn bằng before_model_callback và after_agent_callback.
• Điều phối có sự tham gia của con người: Các quy trình sản xuất tạm dừng để con người đánh giá tại các điểm kiểm tra quan trọng về mẫu quảng cáo. Bạn triển khai RequestInput để tạm ngưng quá trình thực thi quy trình công việc, thực thi các lược đồ phản hồi có cấu trúc và tiếp tục thực thi mà không cần duy trì các quy trình thời gian chạy ở trạng thái rảnh.
• Bộ nhớ tác nhân phân cấp: Các hệ thống sản xuất tách trạng thái thực thi tạm thời khỏi bối cảnh lâu dài. Bạn quản lý trạng thái phiên ngắn hạn bằng cách sử dụng Event(state=...) và liên kết tham số, đồng thời kết nối GEAP Memory Bank để trích xuất, hợp nhất và duy trì các lựa chọn ưu tiên của nhà sáng tạo trong các lần chạy.
• Căn cứ vào cơ sở kiến thức của doanh nghiệp: Các tác nhân tự động cần có bối cảnh miền linh động và cảm xúc của đối tượng. Bạn kết nối một tập hợp GEAP RAG Engine làm nút truy xuất chuyên dụng trong quá trình phân đầu ra song song để đặt cơ sở ngữ nghĩa cho đầu ra của tác nhân.
• Quy trình công việc và việc triển khai diễn ra trong thời gian dài: Quá trình kết xuất video đa phương thức diễn ra không đồng bộ trong thời gian dài. Bạn triển khai LongRunningFunctionTool bằng biên nhận cuộc gọi đang chờ xử lý để tạm ngưng và tiếp tục quy trình bằng mã nhận dạng cuộc gọi, đồng thời triển khai quy trình đã hoàn tất bằng ADK Runner trên Cloud Run.

Cách tổ chức lớp học lập trình này

Lớp học lập trình này đóng vai trò là tài liệu tham khảo về khái niệm và kiến trúc cho bạn. Mỗi phần giải thích các cấu trúc ADK được triển khai trong bước tương ứng của băng ghế dự bị, cung cấp mã tham chiếu và thiết lập các nguyên tắc thiết kế cốt lõi. Xem xét từng phần trước khi hoàn thành bài tập tương ứng trong môi trường làm việc.

Hoạt động thực hành diễn ra trong VibeStudio Workbench, một giao diện web đi kèm có trình chỉnh sửa mã tương tác, trình xác minh thời gian chạy và trình kiểm tra ADK được nhúng. Việc đánh số bước trong băng ghế dự bị sẽ hoàn toàn khớp với lớp học lập trình này để bạn luôn nắm bắt được tiến trình. Các nội dung chỉnh sửa biểu đồ cơ bản sẽ duy trì trong các bước, đồng thời băng ghế dự bị sẽ tự động xác minh các điều kiện tiên quyết khi bạn tiến hành.

Sau khi hoàn thành các bài tập trên băng ghế dự bị, bạn sẽ lắp ráp một quy trình đại lý từ đầu đến cuối và triển khai một ứng dụng VibeStudio đang chạy vào Cloud Run để tạo nội dung video.

Môi trường này bao gồm 3 thành phần chính: VibeStudio Workbench (giao diện web cục bộ để chỉnh sửa mã và xác minh thời gian chạy), phần phụ trợ (ADK Workflow và hộp cát giai đoạn trong agent/) và Google Cloud (các mô hình Gemini, GEAP Memory Bank, RAG Engine và tính năng tạo video Veo).

2. Thiết lập

Nhận khoản tín dụng cho hội thảo

Nếu bạn đang tham gia một lớp học có hướng dẫn, thì người hướng dẫn sẽ phân phối tín dụng cho dự án trên đám mây của bạn trên Google Cloud. Làm theo hướng dẫn của người hướng dẫn để sử dụng các khoản tín dụng và đảm bảo bạn đã bật tính năng thanh toán trong tài khoản trước khi tiếp tục.

Mở Cloud Shell

Cloud Shell là một môi trường phát triển dựa trên trình duyệt, trong đó đã cài đặt sẵn gcloud, Python và git.

Cách khởi chạy Cloud Shell:

1. Chuyển đến bảng điều khiển Google Cloud.
2. Trong tiêu đề điều hướng trên cùng, hãy nhấp vào Kích hoạt Cloud Shell (biểu tượng cửa sổ thiết bị đầu cuối).

Một phiên dòng lệnh sẽ mở ra ở cuối cửa sổ trình duyệt.

Tạo bản sao và khởi chạy kho lưu trữ

Chạy các lệnh sau trong cửa sổ dòng lệnh Cloud Shell để sao chép dự án:

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

Lời nhắc định cấu hình

Trong quá trình thiết lập, bạn sẽ được yêu cầu cung cấp những thông tin sau:

• Mã dự án trên Google Cloud: Khi setup_project.sh nhắc bạn, hãy nhấn Enter để tự động tạo một dự án mới. Nếu bạn muốn sử dụng một dự án hiện có (chẳng hạn như một dự án được chỉ định trước), hãy nhập mã dự án và đảm bảo bạn nhập đúng chính tả cũng như đã bật tính năng thanh toán.
• Mã sự kiện: Nhập mã phòng do người hướng dẫn cung cấp. Nếu bạn không nhận được, hãy hỏi trợ lý giảng dạy hoặc hàng xóm. Nếu bạn đang hoàn thành bài thực hành này tại nhà, hãy nhấn phím Enter để chấp nhận phòng sandbox mặc định.
• Tên hiển thị của kênh: Nhập tên hoặc tên người dùng kênh mà bạn muốn khi setup_codelab.sh nhắc bạn, hoặc nhấn phím Enter để chấp nhận tên hiển thị mặc định được tạo từ Tài khoản Google của bạn.

Chạy 2 tập lệnh thiết lập theo thứ tự:

./setup_project.sh
./setup_codelab.sh

• setup_project.sh: Tạo hoặc sử dụng lại một dự án trên đám mây của Google Cloud có hoạt động thanh toán, lưu mã dự án vào ~/project_id.txt và định cấu hình ngữ cảnh gcloud đang hoạt động.
• setup_codelab.sh: Cài đặt uv và các phần phụ thuộc Python vào .venv, bật các Cloud API cần thiết của Google Cloud, định cấu hình chế độ cài đặt kênh trong .env, xác minh quyền truy cập vào mô hình bằng Gemini, cung cấp tài nguyên Memory Bank và RAG, tạo giao diện của băng ghế dự bị và khởi động VibeStudio Workbench.

Tập lệnh này chạy quy trình kiểm tra trước chuyến bay và khởi động VibeStudio Workbench ở chế độ nền. Các dòng cuối cùng của tệp này hiển thị đường liên kết để mở.

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

Nhấp vào đường liên kết đó. Bạn có thể truy cập vào cùng một địa chỉ trong phần Web Preview → Change port → 4600 (Xem trước trên web → Thay đổi cổng → 4600).

Để kiểm tra lại môi trường bất cứ lúc nào, hãy chạy python scripts/preflight.py. Để khởi động lại băng ghế dự bị, hãy chạy scripts/restart.sh. Để thiết lập lại, hãy chạy ./setup_codelab.sh. Thao tác này sẽ giữ nguyên cấu hình và tiến trình của bạn.

Khi mở, hãy đọc bước 1, Câu chuyện để biết kịch bản và bước 2, Những gì bạn tạo để biết hình dạng của biểu đồ đã hoàn tất. Không có bài tập nào. Sau đó, hãy quay lại đây để thực hiện bước 3.

Mọi phần thực hành của VibeStudio Workbench đều kết thúc bằng một bảng xác minh đọc các cấu phần phần mềm thực: tệp trên đĩa và các phiên do các lần chạy ghi.

Bố cục kho lưu trữ

Kho lưu trữ được cấu trúc thành logic quy trình làm việc cốt lõi, các hộp cát từng bước, môi trường bàn làm việc và ứng dụng sản xuất:

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/: Chứa biểu đồ quy trình làm việc cốt lõi. Bạn sẽ chỉnh sửa các tệp trong thư mục này để triển khai các nút phân đầu ra song song, định tuyến chính sách xác định, lệnh gọi lại bộ nhớ và các công cụ tạo video.
• agent/platform/: Tương tác với các dịch vụ của Google Cloud, bao gồm cả các mô hình Gemini, Ngân hàng bộ nhớ GEAP, Công cụ RAG GEAP và tính năng tổng hợp video của Veo.
• stage0_prompt/ đến stage6_video/: Môi trường hộp cát độc lập. Mỗi thư mục xuất một root_agent độc lập để bạn có thể chạy và kiểm tra từng bước riêng biệt thông qua giao diện phát triển ADK được nhúng.
• server/ và web/: Ứng dụng VibeStudio Workbench chạy cục bộ trên cổng 4600. Nền tảng này lưu trữ tài liệu về các bước, trình chỉnh sửa mã trong trang, trình xác minh bằng chứng thời gian chạy và hình ảnh trực quan về biểu đồ.
• vibestudio/: Ứng dụng sản xuất hoàn chỉnh được đóng gói và triển khai lên Cloud Run ở bước cuối cùng. Nút này chứa bản sao độc lập của biểu đồ quy trình công việc đã hoàn tất.

3. Tác nhân nguyên khối

Trước khi tạo một biểu đồ quy trình công việc có nhiều nút, bạn sẽ thiết lập một đường cơ sở về cấu trúc với một tác nhân duy nhất trong stage0_prompt/agent.py. Tác nhân này dựa vào một câu lệnh hệ thống nguyên khối mô tả quy trình sản xuất bằng văn xuôi, được hỗ trợ bởi 2 công cụ hàm Python.

Việc đánh giá đường cơ sở này minh hoạ các ranh giới hoạt động của hoạt động điều phối dựa trên câu lệnh và xác định lý do hệ thống sản xuất cần có hoạt động điều phối biểu đồ.

Cấu trúc tác nhân ADK (3A)

Trong VibeStudio Workbench, hãy chuyển đến Bước 3: Tác nhân nguyên khối rồi mở Cấu trúc tác nhân ADK (3A). Khung hiển thị này trình bày các lớp kiến trúc cốt lõi của một tác nhân 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
)

Biểu đồ tương tác này nhóm các thành phần của tác nhân thành 5 miền hoạt động:

• Lớp suy luận (Mô hình): Mô hình ngôn ngữ cốt lõi (chẳng hạn như Gemini 3 Flash) thực hiện các nhiệm vụ nhận thức, suy luận dựa trên câu lệnh và lựa chọn công cụ. Mọi thứ khác trong cấu trúc đều cung cấp thông tin hoặc hạn chế mô hình này.
• Lớp bối cảnh (Chỉ dẫn và Kỹ năng): Chỉ thị định hình khả năng suy luận của mô hình. instruction thiết lập lời nhắc hệ thống, nhân cách và quy tắc hoạt động cố định. skills cung cấp hướng dẫn theo quy trình và có phiên bản (SKILL.md) cho các quy trình công việc có thể lặp lại.
• Lớp cộng tác và hành động (Công cụ, Trợ lý ảo, Quy trình làm việc, Lược đồ đầu ra): Các giao diện cho phép trợ lý ảo hành động trên các hệ thống bên ngoài và phát dữ liệu đã nhập. tools cung cấp các hàm Python có thể gọi hoặc các điểm cuối Giao thức ngữ cảnh mô hình (MCP). subagents thực hiện các nhiệm vụ được uỷ quyền cấp dưới. workflow điều phối các biểu đồ có nhiều tác nhân. output_schema áp dụng các mô hình Pydantic để đảm bảo người dùng nhận được JSON đã xác thực thay vì văn bản không có cấu trúc.
• Lớp chặn (Lệnh gọi lại vòng đời): Các rào chắn có tính xác định thực thi mã tuỳ chỉnh trước và sau khi thực thi tác nhân (before_agent/after_agent), các lượt mô hình riêng lẻ (before_model/after_model) và các lệnh gọi công cụ (before_tool/after_tool). Các lớp chặn thực thi các quy tắc chính sách mà không phụ thuộc vào việc tuân thủ mô hình.
• Trạng thái bên ngoài (Phiên và Bộ nhớ): Tính liên tục có trạng thái tách biệt với logic của tác nhân. Session lưu giữ bộ nhớ hoạt động tạm thời và dấu vết sự kiện cho luồng thực thi hiện tại. Memory duy trì các thông tin và lựa chọn ưu tiên bền vững trên nhiều phiên bằng cách sử dụng các dịch vụ được quản lý như Ngân hàng bộ nhớ GEAP.

Tác nhân nguyên khối trong bước này chỉ triển khai 3 trong số các nguyên tắc cơ bản này: model, instruction và tools. Các bước tiếp theo sẽ giới thiệu quy trình làm việc theo biểu đồ, lược đồ có cấu trúc, trình chặn và các dịch vụ bộ nhớ liên tục.

Quy cách tác nhân nguyên khối (3B)

Trong băng ghế dự bị, hãy chuyển sang Quy cách tác nhân nguyên khối (3B). Mở stage0_prompt/agent.py để kiểm tra định nghĩa cơ bản về tác nhân:

• Hướng dẫn bằng một câu lệnh: Câu lệnh hệ thống cô đọng 5 nhiệm vụ sản xuất riêng biệt thành văn xuôi liên tục: khám phá các xu hướng trên nền tảng, xem xét các ý tưởng tồn đọng, đề xuất các ý tưởng sáng tạo, thực thi các chính sách về chủ đề bị cấm và soạn thảo danh sách cảnh quay.
• Nguồn dữ liệu cơ bản: Tác nhân tham chiếu đến 2 nguồn được xác định bên cạnh biểu đồ:
  • agent/trends.py: Lấy mẫu 10 xu hướng định dạng và phong cách đang hoạt động trong số 250 xu hướng có điểm số mức độ phổ biến linh động.
  • agent/backlog.txt: Đọc từng dòng ghi chú thô về ý tưởng của nhà sáng tạo.

Công cụ trong Agent (3C)

Trong môi trường làm việc, hãy chuyển đến Công cụ trong tác nhân (3C).

Công cụ là gì đối với một tác nhân?

Về bản chất, mô hình ngôn ngữ là một công cụ suy luận trong thế giới khép kín: mô hình này chỉ hoạt động dựa trên các trọng số được huấn luyện trước và các mã thông báo có trong cửa sổ ngữ cảnh tức thì của mô hình. Công cụ này không thể truy vấn cơ sở dữ liệu, truy cập vào các API theo thời gian thực hoặc thực thi mã một cách tự nhiên.

Công cụ sẽ giúp bạn vượt qua ranh giới này. Công cụ này cấp cho mô hình quyền truy cập vào các tác nhân bên ngoài, cho phép mô hình truy xuất thông tin thực tế và thực hiện các hành động có tính xác định trong các hệ thống bên ngoài.

Tính năng gọi công cụ tuân theo một giao thức gồm 5 giai đoạn rõ ràng giữa mô hình và thời gian chạy ADK:

1. Khai báo giản đồ: Nhà phát triển cung cấp các hàm Python cho tác nhân. ADK kiểm tra tên, chú thích loại và chuỗi tài liệu của từng hàm để tạo một khai báo lược đồ JSON tương thích với OpenAPI, mô tả các tham số và mục đích của hàm.
2. Lý luận của mô hình: Trong quá trình suy luận, mô hình đánh giá xem câu lệnh của người dùng có yêu cầu dữ liệu bên ngoài hay không. Nếu cần, mô hình sẽ phát ra một sự kiện function_call có cấu trúc chứa tên hàm đích và từ điển đối số khớp với giản đồ.
3. Thực thi thời gian chạy: Bản thân mô hình không thực thi mã. Thời gian chạy ADK chặn function_call, thực thi hàm Python cục bộ thực tế bằng các đối số được cung cấp và ghi lại giá trị trả về.
4. Tiêm lại bối cảnh: Thời gian chạy ADK đóng gói giá trị trả về của hàm vào một sự kiện function_response và nối giá trị đó vào nhật ký phiên hoạt động.
5. Tổng hợp cuối cùng: Mô hình xử lý đầu ra của công cụ hiện có trong cửa sổ ngữ cảnh và hoàn tất phản hồi.

Trong stage0_prompt/agent.py, hai công cụ nghiên cứu được xác định là các hàm Python tiêu chuẩn:

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

Chỉnh sửa và thực thi trong thực tế

Trong trình chỉnh sửa mã của băng ghế dự bị, hãy thêm 2 tham chiếu hàm vào danh sách tools của tác nhân:

    tools=[check_trends, read_backlog],

Lưu thay đổi. Tệp sẽ cập nhật trên ổ đĩa và hàng xác minh sẽ xác nhận rằng cả hai công cụ đều được kết nối.

Nhấp vào Open adk web (Mở adk web) để chạy giao diện phát triển ADK được nhúng. Gửi câu lệnh về ý tưởng được đề xuất:

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

Những điều cần biết và lý do

Khi bạn gửi câu lệnh này, hãy quan sát trình tự thực thi sau đây trong dấu vết phiên:

• Hai sự kiện thực thi công cụ xuất hiện trước câu trả lời: Bạn sẽ thấy các sự kiện function_call và function_response cho check_trends và read_backlog.
  • Lý do: Gemini đã đánh giá chỉ thị của lời nhắc hệ thống ("kiểm tra xu hướng, xem xét danh sách ý tưởng"), nhận ra rằng chỉ thị này thiếu các xu hướng trên nền tảng và ghi chú về kênh trong các trọng số của chỉ thị, đồng thời gọi cả hai hàm để làm cơ sở cho ngữ cảnh của chỉ thị.
• Tác nhân đề xuất một hướng đi và tạm dừng để chờ bạn xác nhận: Câu trả lời đề xuất một hướng đi cho video dựa trên các xu hướng và nội dung tồn đọng, đồng thời yêu cầu bạn xác nhận.
  • Lý do: Chỉ thị hướng dẫn yêu cầu mô hình thống nhất với nhà sáng tạo về hướng đi trước khi tạo kịch bản.
• Bỏ qua bước xác nhận trong lượt trò chuyện tiếp theo: Gửi tin nhắn thứ hai: skip the questions, just describe the video. Nhân viên này sẽ bỏ qua bước xác nhận và soạn thảo tiêu đề cũng như cảnh quay ngay lập tức.
  • Lý do: Hướng dẫn trong câu lệnh là các nguyên tắc tư vấn thay vì các rào cản mang tính quyết định. Trong một tác nhân nguyên khối, hướng dẫn của người dùng có thể ghi đè các quy tắc nhắc nhở hệ thống hiện hành vì không có quy trình làm việc bên ngoài nào kiểm soát luồng thực thi.

Các hạn chế về kiến trúc của một câu lệnh nguyên khối

Mặc dù một câu lệnh duy nhất có thể tạo ra kết quả chấp nhận được cho các bản minh hoạ riêng lẻ, nhưng việc kiểm thử các điều kiện biên trong trình xác minh của băng ghế dự bị cho thấy những hạn chế quan trọng đối với doanh nghiệp:

• Tổng hợp nghiên cứu phi cấu trúc: Thứ tự thực thi công cụ là không xác định. Mô hình này tóm tắt dữ liệu đã truy xuất thành văn xuôi tự do, khiến các hệ thống hạ nguồn không thể tách biệt nguồn nào đã tạo ra các tuyên bố cụ thể.
• Thực thi chính sách chưa được xác minh: Mô hình tự đánh giá mức độ tuân thủ các quy định an toàn. Nếu mô hình xác định một chủ đề là an toàn, thì không có logic tất định bên ngoài nào xác thực kết quả đó.
• Tạm dừng không bắt buộc có sự tham gia của con người: Các hướng dẫn nhắc nhở yêu cầu nhà sáng tạo xác nhận chỉ mang tính chất khuyến nghị. Việc gửi một tin nhắn tiếp theo hướng dẫn mô hình bỏ qua các câu hỏi khiến mô hình hoàn toàn bỏ qua bước phê duyệt của con người.

Những khoảng trống về cấu trúc này thúc đẩy việc phân tách tác nhân nguyên khối thành quy trình công việc đồ thị rõ ràng được tạo ở bước tiếp theo.

4. Nguyên tắc cơ bản về quy trình làm việc dựa trên tác nhân

Trong VibeStudio Workbench, hãy chuyển đến Bước 4 – Kiến thức cơ bản về quy trình công việc dựa trên tác nhân, phần 4A đến 4D.

Bước này chuyển từ đường cơ sở một tác nhân sang điều phối biểu đồ tất định bằng cách sử dụng ADK Workflow. Bạn sẽ tạo một nhánh nghiên cứu song song, đồng bộ hoá các nhánh bằng một nút kết hợp, tạo các đề xuất mẫu quảng cáo được xác thực theo lược đồ và giới thiệu một cổng phê duyệt có sự tham gia của con người mang tính xác định.

Cấu trúc đồ thị và chuỗi thực thi (4A)

Trong workbench, hãy mở Graph architecture and execution chains (4A) (Cấu trúc đồ thị và chuỗi thực thi (4A)).

ADK Workflow cấu trúc quá trình thực thi tác nhân dưới dạng một biểu đồ có hướng do danh sách cạnh xác định:

• Chuỗi: Các bộ tuần tự xác định việc thực thi nút tuyến tính ((node_a, node_b, node_c)).
• Các nhánh song song: Các chuỗi độc lập dùng chung một nút nguồn sẽ thực thi đồng thời.
• Đồng bộ hoá: Các chuỗi hội tụ trên một JoinNode sẽ đợi cho đến khi tất cả các nhánh đến báo cáo rồi mới phát hành.
• Quyền kiểm soát mang tính xác định: Luồng thực thi chịu sự điều chỉnh của các cấu trúc mã đã khai báo thay vì được suy luận từ văn bản lời nhắc.

Các hình mẫu nút trong ADK

Quy trình ADK bao gồm nhiều loại nút chuyên biệt. Mỗi nguyên mẫu đóng một vai trò hoạt động cụ thể trong biểu đồ, tách biệt quá trình thực thi mã xác định với quá trình suy luận mô hình tạo sinh:

Nguyên mẫu nút	Triển khai	Vai trò trong quy trình
Nút hàm	Hàm Python trả về một Event	Thực thi logic xác định, truy xuất dữ liệu và đột biến trạng thái.
Nút kết hợp	Thực thể JoinNode tích hợp	Đồng bộ hoá các nhánh đồng thời thành một từ điển tổng hợp.
Nút tác nhân	Agent đang chạy ở chế độ single_turn	Đánh giá các chỉ dẫn dựa trên dữ liệu đầu vào ở nguồn và phát dữ liệu đã xác thực.
Nút bộ định tuyến	Hàm trả về Event có thẻ route	Đánh giá logic có điều kiện để chọn các nhánh thực thi hạ lưu.
Nút đầu vào của người dùng	Hàm tạo RequestInput	Tạm dừng trạng thái thực thi cho đến khi nhận được phản hồi của người dùng bên ngoài.

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

Trong cấu hình này, root_agent là một thực thể của Workflow thay vì là một Agent độc lập. ADK coi quy trình làm việc là các tác nhân hạng nhất, cho phép toàn bộ biểu đồ được tải, phân phát và kiểm tra dưới dạng một ứng dụng hợp nhất. name đăng ký ứng dụng trong ADK Web, trong khi danh sách edges xác định cấu trúc liên kết thực thi của ứng dụng.

Phân đầu ra nghiên cứu song song (4B)

Trong bảng điều khiển, hãy chuyển sang Parallel research fan-out (4B) (Phân đầu ra nghiên cứu song song 4B). Mở stage1_fanout/agent.py.

Nút chức năng và rào cản đồng bộ hoá

Giai đoạn nghiên cứu sử dụng 2 nút chức năng được nhập từ agent/graph.py:

• scan_trends: Trả về Event(output={"trends": [...]}) chứa 10 xu hướng được tính điểm trên nền tảng.
• read_backlog: Trả về Event(output={"backlog": [...], "idea": "..."}) chứa 15 ý tưởng về nội dung tồn đọng của kênh cùng với câu lệnh chạy ban đầu.

Mỗi hàm chấp nhận node_input (đầu ra của nút trước đó) và trả về một Event.

JoinNode đóng vai trò là rào cản đồng bộ hoá: nó tạm dừng cho đến khi mọi chuỗi đến gửi một sự kiện, sau đó tổng hợp tất cả kết quả của nhánh thành một từ điển được khoá theo tên nút ({"scan_trends": {...}, "read_backlog": {...}}).

Chỉnh sửa thực tế: xác định các cạnh song song và cạnh nối

Trong stage1_fanout/agent.py, hãy khởi tạo JoinNode và kết nối hai chuỗi song song bắt đầu từ START:

join_research = JoinNode(name="join_research")

    edges=[(START, scan_trends, join_research),
           (START, read_backlog, join_research)])

Lưu thay đổi. Trình xác minh trên bàn làm việc xác nhận rằng đường nối và các cạnh đã được nối dây. Chạy giai đoạn bằng cách sử dụng Run Stage 1 (Chạy giai đoạn 1) hoặc thông qua giao diện ADK Web được nhúng.

Những điều cần biết và lý do

• Thực thi trình đọc đồng thời: Trong biểu đồ thực thi, scan_trends và read_backlog thực thi đồng thời.
  • Lý do: Cả hai chuỗi đều bắt nguồn từ START. Công cụ ADK lên lịch các nhánh độc lập đồng thời.
• Đầu ra từ điển tổng hợp: Quy trình công việc hoàn tất tại join_research, xuất ra một từ điển có các mục cho cả hai người đọc.
  • Lý do: JoinNode đảm bảo chụp dữ liệu đầy đủ trước khi cho phép các nút tiếp theo thực thi.

Nút tác nhân (4C)

Trong môi trường làm việc, hãy chuyển đến Agent nodes (4C) (Nút tác nhân (4C)). Mở stage2_direction/agent.py.

Chế độ hoạt động và giản đồ có cấu trúc

Khi được nhúng trong một Workflow, Agent sẽ chạy ở chế độ single_turn theo mặc định:

• Nút này nhận đầu ra của nút trước đó làm đầu vào ngữ cảnh.
• Ứng dụng này thực hiện một lệnh gọi suy luận duy nhất mà không cần tương tác qua lại.
• Nút này xuất dữ liệu có cấu trúc sang nút tiếp theo.

Bằng cách chỉ định output_schema=Directions, tác nhân sẽ thực thi quy trình xác thực Pydantic đối với đầu ra của mô hình. Biểu đồ hạ lưu nhận các đối tượng được nhập thay vì văn bản không có cấu trúc:

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 hướng dẫn mô hình đề xuất 4 đề xuất dựa trên bằng chứng từ cả xu hướng và danh sách tồn đọng. Các đề xuất từ 1 đến 3 đều là những ý tưởng khả thi cho kênh. Ứng viên 4 cố tình đưa ra một khái niệm vi phạm chính sách để kiểm tra biện pháp bảo vệ an toàn ở bước tiếp theo.

Chỉnh sửa thực tế: xác định nút tác nhân và liên kết thao tác kết hợp

Trong stage2_direction/agent.py, hãy định cấu hình propose_directions và mở rộng các cạnh của quy trình:

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

Những điều cần biết và lý do

• Sử dụng trực tiếp từ điển: propose_directions sử dụng tải trọng JSON do join_research phát ra mà không cần định dạng theo cách thủ công.
• Đầu ra đề xuất có phân loại: Tác nhân phát ra một đối tượng Directions đã xác thực, chứa 4 đề xuất riêng biệt. Các nút hạ lưu đọc các trường theo tên thuộc tính (candidate.title) mà không cần phân tích cú pháp chuỗi.

Con người nằm trong quy trình (4D)

Trong môi trường làm việc, hãy chuyển sang Con người tham gia vào quy trình (4D). Mở agent/graph.py.

Hướng dẫn về câu lệnh so với việc tạm ngưng có tính xác định

Quy trình sản xuất phát sinh chi phí tài chính hoặc xuất bản nội dung cần có sự giám sát của con người tại các điểm đưa ra quyết định quan trọng. Trong một câu lệnh duy nhất, yêu cầu xác nhận là hướng dẫn mang tính tư vấn mà người dùng có thể dễ dàng nhắc mô hình bỏ qua. Trong quy trình ADK, công cụ thực thi sẽ thực thi quy trình phê duyệt của con người: biểu đồ dừng ở một nút được chỉ định và không thể tiến hành cho đến khi nhận được dữ liệu đầu vào bên ngoài đã được xác thực bằng lược đồ:

• Thao tác tạo RequestInput sẽ tạm ngưng việc thực thi quy trình làm việc ngay lập tức.
• ADK ghi lại một lệnh gọi ngắt mở trong kho lưu trữ phiên và phát hành một interrupt_id duy nhất.
• Quá trình thực thi sẽ dừng mà không tiêu thụ mã thông báo hoặc luồng máy chủ.
• Quá trình thực thi biểu đồ chỉ tiếp tục khi một function_response hợp lệ khớp với giản đồ và mã nhận dạng gián đoạn được gửi.

Chỉnh sửa trực tiếp: tạm dừng thực thi bằng RequestInput

Trong agent/graph.py, hãy triển khai lệnh gọi tạm ngưng bên trong 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 định cấu hình 3 thuộc tính:

• message: Câu hỏi đánh giá mà người dùng nhìn thấy.
• response_schema: Một giản đồ JSON mà giao diện người dùng kết xuất dưới dạng biểu mẫu nhập, được ADK xác thực khi gửi.
• payload: Siêu dữ liệu đi kèm với yêu cầu (4 đề xuất), cho phép các giao diện máy khách hiển thị thẻ đánh giá mà không cần truy vấn trạng thái phiên.

Những điều cần biết và lý do

• Quy trình dừng tại direction_gate: Trong ADK Web hoặc giao diện của băng ghế dự bị, quá trình chạy sẽ tạm dừng và hiển thị một biểu mẫu lựa chọn đề xuất tương tác.
  • Lý do: Công cụ gặp phải một RequestInput đã tạo và duy trì trạng thái thực thi thành runs/sessions.db.
• Việc tiếp tục yêu cầu thông tin đầu vào có cấu trúc: Việc gửi văn bản trò chuyện tuỳ ý sẽ không làm tiến trình đồ thị đi tiếp. Khi chọn một lựa chọn (1, 2, 3 hoặc 4), bạn sẽ gửi một function_response đã nhập đáp ứng response_schema và tiếp tục thực thi.

5. Trạng thái và Bộ định tuyến

Trong VibeStudio Workbench, hãy chuyển đến Bước 5 · State and Router (Bước 5 · Trạng thái và bộ định tuyến), phần (5A) đến (5C).

Bạn sẽ duy trì lựa chọn của người dùng vào trạng thái phiên, thực thi các chính sách an toàn của kênh bằng cách sử dụng các nút bộ định tuyến xác định và tập hợp một tác nhân tác vụ lặp lại để tự động khắc phục các lỗi vi phạm chính sách trước khi tạo kịch bản video.

Trạng thái quy trình công việc (5A)

Trong Workbench, hãy chuyển đến Trạng thái quy trình công việc (5A).

Trạng thái phiên so với đầu ra của nút

Trong quy trình ADK, dữ liệu di chuyển trên biểu đồ thông qua 2 cơ chế riêng biệt:

• Đầu ra của nút (Event(output=...)): Dữ liệu được chuyển hướng hoàn toàn đến những người tiêu dùng hạ nguồn trực tiếp được xác định trong danh sách cạnh.
• Trạng thái phiên (Event(state=...)): Từ điển khoá-giá trị dùng chung mà mọi nút tiếp theo trong vòng đời thực thi đều có thể truy cập.

Khi người dùng chọn một đề xuất tại direction_gate, lựa chọn sẽ xuất hiện dưới dạng chỉ mục dạng số ({"pick": "2"}). Các nút xuôi dòng cần có đối tượng chỉ đường hoàn chỉnh: tiêu đề, góc kể chuyện và câu dẫn. Thay vì truyền siêu dữ liệu chi tiết thông qua mọi tải trọng nút trung gian, persist_direction sẽ ghi ứng cử viên đã phân giải vào trạng thái phiên dùng chung.

Các nút không cần truyền toàn bộ từ điển trạng thái phiên. Khi một nút tạo ra Event(state=...), nút đó chỉ cung cấp các cặp khoá-giá trị mới hoặc đã cập nhật. ADK sẽ tự động hợp nhất các bản cập nhật này vào kho lưu trữ phiên:

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

Việc tạo ra Event sẽ chuyển quyền kiểm soát cho thời gian chạy Workflow, duy trì các giá trị mới cho nhật ký phiên trong runs/sessions.db.

Liên kết tham số

Các nút chức năng ADK tự động đọc trạng thái phiên thông qua quy trình kiểm tra tham số. Nếu chữ ký hàm khai báo một tên tham số khớp với khoá trạng thái hiện có, thì ADK sẽ trích xuất khoá đó từ trạng thái và truyền trực tiếp:

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

Ở đây, candidates được direction_gate ghi vào trạng thái phiên. ADK liên kết trực tiếp vào persist_direction(node_input, candidates: list = []) mà không yêu cầu tra cứu từ điển rõ ràng.

Các khoá có tiền tố user: vẫn tồn tại trong các phiên ở bộ nhớ cấp người dùng, cho phép các lần chạy quy trình công việc tiếp theo truy cập vào lựa chọn ưu tiên của nhà sáng tạo.

Chỉnh sửa thực tế: duy trì trạng thái và kết nối nút

1. Trong agent/graph.py, bên trong persist_direction, hãy thay thế dòng TODO: PERSIST_STATE bằng sự kiện trạng thái yield:

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

2. Trong stage3_router/agent.py, hãy thêm persist_direction vào chuỗi thứ ba trong danh sách edges:

           (join_research, propose_directions, direction_gate,
            persist_direction)

Lưu tệp. Trong workbench, hãy xác minh rằng cả state write in place và persist_direction in the chain đều có dấu kiểm màu xanh lục.

Nút bộ định tuyến (5B)

Trong workbench, hãy chuyển đến Nút bộ định tuyến (5B).

Định tuyến theo chính sách có tính xác định

Bộ định tuyến là một nút chức năng chuyên biệt, đánh giá đầu ra ở luồng dữ liệu đầu vào và hướng dẫn việc thực thi dọc theo các nhánh đồ thị có điều kiện. Không giống như các tác nhân tạo sinh, bộ định tuyến thực thi logic xác định mà không cần gọi LLM.

Bộ định tuyến trả về một Event chỉ định thẻ 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")

Trong định nghĩa quy trình, đích đến của cạnh được xác định dưới dạng một từ điển ánh xạ tên tuyến đường đến các nút đích đến:

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

Bộ định tuyến quy trình công việc policy_check đọc các cụm từ bị cấm từ agent/policy_words.txt và thực hiện so khớp toàn bộ từ với tiêu đề và góc của hướng đã chọn:

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

Việc lưu trữ chính sách dưới dạng dữ liệu thay vì hướng dẫn được mã hoá cứng cho phép cập nhật mà không cần sửa đổi biểu đồ quy trình công việc: việc cập nhật tệp văn bản sẽ áp dụng ngay cho các lần chạy tiếp theo. Vì quá trình đánh giá là quá trình so khớp biểu thức chính quy có tính xác định, nên quá trình này sẽ thực thi trong vài mili giây với chi phí bằng 0 trước khi quá trình tạo tập lệnh bắt đầu.

Đích đến: Scripter và Quarantine

Bộ định tuyến chuyển hướng lưu lượng truy cập đến một trong hai nút xuôi dòng:

• scripter: Một nút tác nhân single_turn chuyển đổi chỉ đạo đã được phê duyệt thành một kịch bản sản xuất có cấu trúc tuân thủ lược đồ Script Pydantic:

scripter = Agent(
    name="scripter",
    model=config.MODEL,
    instruction=SCRIPT_INSTRUCTION,
    output_schema=Script)

• quarantine: Ban đầu là một hàm giữ chỗ tạm dừng các chỉ dẫn được gắn cờ, được thay thế trong phần tiếp theo bằng một tác nhân khắc phục tự động.

Chỉnh sửa thực tế: định tuyến quy trình kiểm tra chính sách

1. Trong agent/graph.py, bên trong policy_check, hãy hoàn tất câu lệnh trả về:

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

2. Trong stage3_router/agent.py, hãy cập nhật edges để định tuyến policy_check và kết hợp lại nhánh cách ly vào scripter:

           (join_research, propose_directions, direction_gate,
            persist_direction, policy_check),
           (policy_check, {"OK": scripter, "BLOCK": quarantine}),
           (quarantine, scripter)])

Lưu tệp. Trong bảng điều khiển, hãy xác minh rằng các mục ánh xạ cạnh của bộ định tuyến đã được xác minh.

Các chế độ của tác nhân và nút tác vụ (5C)

Trong môi trường làm việc, hãy chuyển đến Các chế độ của tác nhân và nút tác vụ (5C).

Chế độ thực thi tác nhân

Các phiên bản ADK Agent hỗ trợ 3 chế độ thực thi phù hợp với các yêu cầu cụ thể về quy trình:

Chế độ	Vòng đời thực thi	Vai trò trong quy trình
chat	Vòng lặp trò chuyện nhiều lượt. Mô hình này xác định thời điểm gọi các công cụ, yêu cầu thông tin đầu vào hoặc kết thúc lượt tương tác.	Nhân viên hỗ trợ gốc tương tác với người dùng là con người.
single_turn	Lệnh gọi suy luận mô hình đơn. Chấp nhận dữ liệu đầu vào của nút trước và phát ra một đối tượng giản đồ có cấu trúc.	Phép biến đổi đồ thị tuần tự (propose_directions, scripter).
task	Vòng lặp tự động với việc thực thi công cụ. Tác nhân sẽ lặp lại cho đến khi gọi công cụ finish_task tích hợp.	Quy trình khắc phục và kiểm tra nhiều bước (quarantine).

Khắc phục chính sách tự động

Việc viết lại chỉ dẫn bị gắn cờ yêu cầu chế độ task vì số lần lặp lại để khắc phục là không cố định. Tác nhân nhận được chỉ dẫn bị gắn cờ, gọi find_policy_hits để phát hiện lỗi vi phạm, yêu cầu các lựa chọn thay thế đã được phê duyệt thông qua suggest_replacement, viết lại chỉ dẫn và xác minh tính phù hợp trước khi tiếp tục.

Cả hai công cụ này đều được xác định trong agent/cleanup_tools.py bằng chữ ký được nhập và chuỗi tài liệu:

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

Chỉnh sửa thực tế: lắp ráp tác nhân nhiệm vụ cách ly

Trong stage3_router/agent.py, hãy thay thế hàm giữ chỗ quarantine bằng định nghĩa tác nhân tác vụ:

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

Chế độ tác vụ trang bị cho tác nhân các công cụ và chấm dứt quá trình thực thi bằng cách gọi finish_task. Khi mode="task" được định cấu hình, ADK sẽ tự động cung cấp finish_task và lấy các tham số của từ output_schema, đảm bảo nút tạo ra một đối tượng CleanedDirection được nhập khớp với giản đồ đầu vào của nút scripter.

Những điều cần biết và lý do

Kiểm thử cả hai đường dẫn thực thi trong ADK Web hoặc VibeStudio Workbench:

• Tuyến đường được phê duyệt (Thí sinh 1, 2 hoặc 3):
  • Chọn một tuyến đường đề xuất đã được phê duyệt từ policy_check đến thẳng scripter (route="OK").
  • Người viết kịch bản tạo một kịch bản sản xuất gồm 3 cảnh tuân thủ giản đồ Script.
• Lộ trình khắc phục cách ly (Ứng viên 4):
  • Ứng viên 4 có chứa từ ngữ bị gắn cờ ("câu kéo", "thủ thuật lan truyền").
  • policy_check tuyến đường đến quarantine (route="BLOCK").
  • Trong dấu vết phiên, hãy quan sát quarantine gọi find_policy_hits, gọi suggest_replacement cho từng lỗi vi phạm, viết lại tiêu đề và gọi finish_task.
  • Quá trình thực thi sẽ kết hợp lại scripter, tạo ra một tập lệnh từ chỉ dẫn đã được làm sạch.

Bộ định tuyến và phương án dự phòng. Giao diện người dùng phát triển gắn cờ một bộ định tuyến không có cạnh dự phòng. Nếu policy_check trả về một tuyến đường khác với OK hoặc BLOCK, thì lượt chạy sẽ không có đích đến. Việc thêm DEFAULT_ROUTE: quarantine vào từ điển cạnh sẽ bao gồm trường hợp đó; nhập DEFAULT_ROUTE từ google.adk.workflow.

6. Ngân hàng bộ nhớ

Trong VibeStudio Workbench, hãy chuyển đến Bước 6 – Ngân hàng bộ nhớ, phần (6A) và (6B).

Quy trình hiện hoạt động mà không có bộ nhớ trên các phiên. Mỗi lần thực thi đều bắt đầu từ đầu, không biết người sáng tạo đã chọn nội dung gì trước đó hoặc thể loại nào họ thích. Ở bước này, bạn kết nối Vertex AI Agent Engine Memory Bank để lưu trữ và truy xuất các lựa chọn ưu tiên của nhà sáng tạo trong các lần chạy.

Điều quan trọng là bộ nhớ được tích hợp thông qua các lệnh gọi lại trong vòng đời của tác nhân thay vì các nút trong quy trình. Vì quá trình trích xuất và truy xuất bộ nhớ phục vụ các tác nhân riêng lẻ thay vì các giai đoạn dữ liệu trung gian, nên việc đính kèm lệnh gọi lại sẽ duy trì một cấu trúc liên kết đồ thị rõ ràng và tách biệt.

Ngân hàng bộ nhớ (6A)

Trong băng ghế dự bị, hãy chuyển đến Ngân hàng bộ nhớ (6A).

Bộ nhớ cấp người dùng được quản lý

Memory Bank là một dịch vụ được quản lý để lưu trữ bộ nhớ dài hạn của người dùng. Nó sắp xếp các thông tin về một người trong một phạm vi xác định, được xác định bằng tên ứng dụng và mã nhận dạng người dùng:

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

Các chủ đề bộ nhớ tuỳ chỉnh xác định ranh giới của những gì ngân hàng ghi lại:

• Trích xuất chủ đề: Khi văn bản trò chuyện mới được gửi qua memories.generate, dịch vụ sẽ áp dụng một mô hình trích xuất cho từng nội dung mô tả chủ đề. Văn bản không khớp với một chủ đề sẽ không tạo ra kỷ niệm.
• Hợp nhất và loại bỏ dữ liệu trùng lặp: Dịch vụ này chuyển đổi các dữ kiện mới trích xuất thành các thành phần nhúng và so sánh chúng với những thông tin đã lưu trữ hiện có trong phạm vi. Khi một quan sát trùng khớp với một kỷ niệm hiện có, dịch vụ sẽ cập nhật kỷ niệm đó. Khi thông tin đó là thông tin mới, dịch vụ sẽ tạo một mục mới. Quy trình hợp nhất này đảm bảo nhiều phiên về một chủ đề sẽ hợp nhất thành một bản tóm tắt mạch lạc thay vì tạo ra các mục nhập dư thừa.
• Truy xuất: Việc gọi memories.retrieve với phạm vi người dùng sẽ trả về các dữ kiện đã lưu trữ, được sắp xếp theo thứ tự từ cũ nhất đến mới nhất.

Cả hai thao tác đều được triển khai trong agent/platform/memory.py. Tên tài nguyên ngân hàng được cung cấp sẽ được lưu vào bộ nhớ đệm cục bộ trong runs/memorybank.json.

Thiết lập Ngân hàng kỷ niệm

Sử dụng các chế độ điều khiển của workbench hoặc chạy các lệnh CLI trong cửa sổ dòng lệnh:

1. Kết nối và cung cấp ngân hàng:

   python -m agent.platform.bank
   

   Tạo thực thể Agent Engine và định cấu hình các chủ đề CREATOR_TASTE và CHANNEL_RULES.
2. Gieo hạt các phiên trong quá khứ:

   python -m agent.platform.bank load
   

   Tải 4 phiên sáng tạo trước đây (2 chủ đề về động vật có hạn chế về phong cách, 1 chủ đề về thiết bị và 1 chủ đề về thế giới giả tưởng gần đây).
3. Kiểm tra thông tin tổng hợp:

   python -m agent.platform.bank list
   

   Kiểm tra kết quả đầu ra. Lưu ý cách bản chép lời dạng tường thuật được chuyển đổi thành các câu phát biểu có cấu trúc và cô đọng về sự kiện.

Lệnh gọi lại (6B)

Trong băng ghế dự bị, hãy chuyển đến Callbacks (6B). Mở stage4_memory/agent.py.

Phương thức gọi lại trong vòng đời của tác nhân ADK

Lệnh gọi lại là một hàm được truyền dưới dạng đối số đến một Agent. ADK gọi các lệnh gọi lại tại những thời điểm được xác định trước trong vòng đời, truyền ngữ cảnh đang hoạt động. Trả về None tiếp tục thực thi bình thường; trả về một đối tượng thay thế sẽ ghi đè hoặc chặn thao tác.

ADK cung cấp 3 cặp lệnh gọi lại:

Cặp gọi lại	Điểm gọi	Các tham số nhận được	Hành vi của giá trị trả về
before_agent_callback after_agent_callback	Bao quanh toàn bộ lượt tương tác của tác nhân	CallbackContext (trạng thái, phiên, lệnh gọi)	Nhấn Content để thay thế câu trả lời của trợ lý; nhấn None để tiếp tục như bình thường.
before_model_callback after_model_callback	Xung quanh mỗi lệnh gọi suy luận LLM	LlmRequest hoặc LlmResponse	Trả về LlmResponse sẽ chặn hoặc bỏ qua lệnh gọi mô hình; None sẽ tiếp tục.
before_tool_callback after_tool_callback	Xung quanh mỗi lần thực thi công cụ	Định nghĩa, đối số, kết quả của công cụ	Việc trả về một dict sẽ ghi đè đầu ra của công cụ; None sẽ tiếp tục.

Lệnh gọi lại cung cấp một vị trí rõ ràng để chèn ngữ cảnh, các biện pháp bảo vệ, đo từ xa và tra cứu bộ nhớ đệm mà không cần đưa các nút thừa vào biểu đồ quy trình công việc.

Chỉnh sửa thực tế: gọi lại và ghi nhớ các lệnh gọi lại

1. Trong stage4_memory/agent.py, hãy cập nhật propose_directions để đính kèm before_model_callback=recall_taste:

    output_schema=Directions,
    before_model_callback=recall_taste)

recall_taste sẽ thực thi ngay trước khi Gemini tạo các chỉ dẫn đề xuất. Thao tác này sẽ tìm nạp nhật ký của nhà sáng tạo từ Memory Bank, định dạng các kỷ niệm theo thứ tự từ cũ nhất đến mới nhất và thêm các kỷ niệm đó vào LlmRequest đang gửi đi. Câu lệnh này hướng dẫn mô hình nghiêng các đề xuất từ 1 đến 3 theo sở thích hiện tại của nhà sáng tạo, đồng thời coi các quy tắc của kênh là những ràng buộc nghiêm ngặt.

2. Trong stage4_memory/agent.py, hãy cập nhật scripter để đính kèm after_agent_callback=remember_pick:

    output_schema=Script,
    after_agent_callback=remember_pick)

remember_pick chạy sau khi scripter hoàn tất lượt của mình. Thao tác này đọc hướng đã chọn từ trạng thái phiên, tổng hợp một câu ngắn gọn tóm tắt quyết định của nhà sáng tạo và gọi memories.generate để cập nhật Ngân hàng bộ nhớ.

Những điều cần biết và lý do

Kiểm thử quy trình làm việc được tăng cường bằng lệnh gọi lại trong băng ghế dự bị hoặc ADK Web:

1. Thực thi một lượt chạy bằng câu lệnh trống:
   • Trong dấu vết phiên, hãy kiểm tra LlmRequest để tìm propose_directions. Lưu ý đến ngữ cảnh kỷ niệm được thêm vào, trong đó nêu rõ lựa chọn ưu tiên của nhà sáng tạo đối với các chủ đề giả tưởng và nhịp độ súc tích.
   • Quan sát các hướng đề xuất: các đề xuất từ 1 đến 3 phù hợp với lựa chọn ưu tiên trước đây của nhà sáng tạo, ngay cả khi các xu hướng nhấn mạnh những chủ đề khác.
2. Chọn một ứng cử viên tại direction_gate.
3. Sau khi scripter hoàn tất, hãy xem xét các bản ghi trong Memory Bank:

   python -m agent.platform.bank list
   

   Giờ đây, ngân hàng này phản ánh lựa chọn mới nhất, hợp nhất lựa chọn đó với các bản ghi về sở thích trước đây.

7. Công cụ RAG

Trong VibeStudio Workbench, hãy chuyển đến Bước 7: Công cụ RAG, phần (7A) và (7B).

Các video đã xuất bản sẽ liên tục nhận được ý kiến phản hồi của người xem. Chúng tôi thu thập 30 bình luận tiêu biểu trong agent/comments.md, ghi lại những lời khen ngợi của người xem, ý kiến phê bình về nhịp độ của nội dung được tài trợ và sở thích về âm thanh. Trong bước này, bạn sẽ lập chỉ mục các bình luận này bằng Công cụ RAG của Vertex AI và kết nối tính năng truy xuất ngữ nghĩa vào tính năng phân đầu ra nghiên cứu.

Truy xuất qua tài liệu (7A)

Trong Workbench, hãy chuyển đến RAG Engine (7A).

Ngân hàng bộ nhớ so với Công cụ RAG

Cả hai công cụ này đều dựa vào dữ liệu bên ngoài trong quy trình làm việc, nhưng chúng phục vụ các mục đích kiến trúc riêng biệt:

Phương diện	Ngân hàng bộ nhớ	Công cụ RAG
Trường hợp sử dụng chính	Lựa chọn ưu tiên của người dùng và quy tắc vận hành trong dài hạn	Truy xuất ngữ nghĩa trên các bộ sưu tập tài liệu lớn
Phạm vi	Phạm vi áp dụng cho từng mã nhận dạng người dùng và tên ứng dụng	Phạm vi áp dụng cho các tài nguyên trong kho ngữ liệu dùng chung của tất cả người dùng
Xử lý dữ liệu	Trích xuất, nhúng và hợp nhất ngữ nghĩa theo thời gian thực	Phân đoạn tài liệu, nhúng vectơ và tìm kiếm lân cận
Tích hợp biểu đồ	Lệnh gọi lại trong vòng đời của tác nhân (before_model_callback, after_agent_callback)	Nút hàm chuyên dụng trong tính năng phân đầu ra nghiên cứu (read_feedback)

Phân đoạn và nhúng tài liệu

Công cụ RAG lập chỉ mục tài liệu bằng cách chia văn bản thành các đoạn ngữ nghĩa và lưu trữ vectơ của các đoạn đó trong một cơ sở dữ liệu được quản lý:

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

• Kích thước khối: Được định cấu hình thành 120 mã thông báo với 20 mã thông báo trùng lặp. Điều này giúp ghi lại từ 2 đến 3 bình luận cho mỗi đoạn, đảm bảo mỗi vectơ thể hiện một cảm xúc nhất quán mà không làm giảm ý nghĩa của các ý kiến phản hồi không liên quan.
• Mô hình nhúng: text-embedding-005 chuyển đổi văn bản thành vectơ nhiều chiều. Khi một truy vấn được gửi, mô hình sẽ chuyển đổi truy vấn đó thành một vectơ và tìm các kết quả khớp gần nhất dựa trên khoảng cách ngữ nghĩa. Một bình luận về một con rồng nhỏ canh giữ những chiếc tất khớp với một câu lệnh về sinh vật huyền diệu mà không cần phải có từ khoá trùng khớp chính xác.

Thiết lập tập hợp RAG

Khởi động tập hợp dữ liệu bằng các nút trên băng ghế hoặc lệnh trên thiết bị đầu cuối:

1. Tạo ngữ liệu:

   python -m agent.platform.rag
   

   Cung cấp cơ sở dữ liệu vectơ được quản lý và ghi lại mã nhận dạng tài nguyên trong runs/ragcorpus.json.
2. Tải bình luận lên và lập chỉ mục: Tải agent/comments.md lên bằng cấu hình phân đoạn và chờ quá trình lập chỉ mục hoàn tất.
3. Truy vấn kho ngữ liệu: Kiểm thử khả năng truy xuất thông tin tương tự bằng những cụm từ tìm kiếm không có từ chính xác giống với bình luận (ví dụ: truy vấn "sinh vật nhỏ bé có phép thuật" để truy xuất bình luận về rồng).

Nút truy xuất (7B)

Trong băng ghế dự bị, hãy chuyển đến Người đọc thứ ba (7B). Mở stage5_rag/agent.py.

Truy xuất dưới dạng một nút trong biểu đồ

Ý kiến phản hồi của khán giả là dữ liệu nghiên cứu được chia sẻ trong quy trình làm việc. Không giống như bộ nhớ cá nhân của nhà sáng tạo, cảm xúc của người xem sẽ được đưa trực tiếp vào join_research cùng với dữ liệu về xu hướng và dữ liệu tồn đọng. Do đó, hàm này được triển khai dưới dạng một nút hàm:

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 trích xuất ý tưởng ban đầu của người dùng và thực thi một truy vấn vectơ đối với tập hợp RAG Engine. Thao tác này sẽ phát ra các bình luận đã truy xuất trong tải trọng Event(output=...).

Chỉnh sửa thực tế: nối đầu đọc thứ ba vào bộ phân đầu ra

Trong stage5_rag/agent.py, hãy cập nhật edges để thêm read_feedback làm nhánh song song thứ ba nhập join_research:

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

Vì join_research là một JoinNode, nên nó sẽ đồng bộ hoá tất cả các nhánh đến, đợi cho đến khi scan_trends, read_backlog và read_feedback phát ra tất cả các sự kiện trước khi truyền gói tổng hợp xuống luồng.

Những điều cần biết và lý do

Chạy quy trình công việc trong băng ghế dự bị:

1. Gửi một câu lệnh ý tưởng (chẳng hạn như "một con rồng thu nhỏ đang canh giữ một quầy bếp").
2. Trong dấu vết thực thi, hãy xác minh rằng cả 3 nút đọc đều thực thi đồng thời.
3. Quan sát join_research: từ điển đầu ra của nó hiện chứa trends, backlog và feedback.
4. Kiểm tra các đề xuất được tạo từ propose_directions: mô hình này kết hợp bình luận của người xem vào các đề xuất và tham khảo ý kiến của khán giả trong các trường bằng chứng.
5. Xin lưu ý rằng hoạt động truy xuất RAG mang tính xác định (các truy vấn giống nhau sẽ trả về các đoạn bình luận giống nhau), trong khi nút đề xuất tạo sinh tạo ra các biến thể sáng tạo.

8. Tạo video không đồng bộ bằng Veo

Trong VibeStudio Workbench, hãy chuyển đến Bước 8 – Video, phần (8A) và (8B).

Để tạo video có độ phân giải cao bằng Google Veo, bạn cần mất vài phút cho mỗi lần kết xuất. Việc chặn quá trình thực thi biểu đồ trong khoảng thời gian này sẽ lãng phí tài nguyên điện toán, khoá các nhóm luồng và khiến quá trình chạy gặp phải tình trạng rớt kết nối HTTP. Trong bước này, bạn sẽ kết xuất video không đồng bộ bằng LongRunningFunctionTool của ADK.

Công cụ chạy trong thời gian dài (8A)

Trong workbench, hãy chuyển đến A long-running tool (8A) (Một công cụ chạy trong thời gian dài (8A)). Mở stage6_video/agent.py và agent/deliver.py.

Công cụ đồng bộ so với công cụ chạy trong thời gian dài

Các công cụ hàm ADK tiêu chuẩn thực thi đồng bộ trong một lượt của tác nhân: mô hình gọi công cụ, chờ tải trọng trả về và kết hợp kết quả vào lượt đang diễn ra.

Quá trình kết xuất video không thể hoàn tất trong một lượt. Thay vào đó, render_submit sẽ bắt đầu tác vụ tạo và ngay lập tức trả về biên nhận hoạt động có trạng thái "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"]}

Khi được bao bọc bằng LongRunningFunctionTool, ADK sẽ chặn trạng thái "pending". Lượt của trợ lý kết thúc, quy trình công việc tạm dừng tại nút và siêu dữ liệu cuộc gọi đang chờ xử lý (bao gồm cả mã nhận dạng cuộc gọi và biên nhận) được ghi lại trong runs/sessions.db. Quá trình thực thi thoát một cách gọn gàng mà không duy trì các kết nối mạng đang hoạt động hoặc các luồng worker.

Chỉnh sửa thực tế: bao bọc công cụ kết xuất

Trong stage6_video/agent.py, hãy cập nhật render_desk để gói render_submit trong LongRunningFunctionTool:

    tools=[LongRunningFunctionTool(render_submit)])

Tiếp tục bằng mã nhận dạng cuộc gọi

Mẫu tiếp tục chung

ADK áp dụng một cơ chế giống hệt nhau để tạm ngưng và tiếp tục quy trình làm việc cho cả con người và các công cụ bên ngoài:

Điều kiện kích hoạt tạm ngưng	Đang khởi tạo Construct	Trạng thái tạm ngưng đã lưu	Sự kiện tiếp tục
Quyết định của con người	yield RequestInput(...)	Mở câu lệnh nhập trong bộ nhớ phiên	FunctionResponse có mã nhận dạng cuộc gọi tạm ngưng
Công cụ chạy trong thời gian dài	LongRunningFunctionTool(...) trả lại pending	Mở lệnh gọi công cụ trong bộ nhớ phiên	FunctionResponse có mã nhận dạng cuộc gọi tạm ngưng

Trong cả hai trường hợp, quy trình công việc sẽ dừng hoàn toàn và chỉ tiếp tục khi một sự kiện có FunctionResponse phù hợp đến từ một nguồn bên ngoài: giao diện người dùng, webhook hoặc worker nền.

Chỉnh sửa thực tế: hoàn tất phản hồi giao hàng

Trong agent/deliver.py, hãy tạo phần FunctionResponse tiếp tục:

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

Trình nền phân phối sẽ thăm dò Veo cho đến khi tệp video được tạo, sau đó gửi FunctionResponse này đến phiên. ADK so khớp mã nhận dạng cuộc gọi và tiếp tục quy trình làm việc ngay tại nút tiếp theo. Các nút đã hoàn tất sẽ không thực thi lại và tác nhân sẽ không thực hiện lượt tạo nội dung khác.

Việc thiết lập STUDIO_REAL_VIDEO=0 trong .env cho phép kết xuất mô phỏng: start trả về biên nhận kiểm thử ngay lập tức và check mô phỏng quá trình hoàn tất trong 5 giây mà không thực hiện các lệnh gọi API Veo có tính phí.

Tích hợp quy trình (8B)

Trong băng ghế dự bị, hãy chuyển đến render_desk trong biểu đồ (8B). Mở stage6_video/agent.py.

Nút cuối cùng trong quy trình là store_video. Thao tác này đọc thông tin kết xuất đã hoàn tất từ runs/state.json (nơi quá trình phân phối đã ghi lại thông tin này) và xác nhận URL video cũng như trạng thái tạo vào trạng thái phiên dùng chung.

Chỉnh sửa thực tế: kết nối toàn bộ quy trình xử lý video

Trong stage6_video/agent.py, hãy cập nhật edges để nối render_desk và store_video:

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

Những điều cần biết và lý do

Kiểm thử quy trình tạo không đồng bộ trong băng ghế dự bị:

1. Thực hiện quy trình thông qua việc chọn ứng viên và tạo tập lệnh.
2. Tại render_desk, hãy quan sát tác nhân gọi render_submit.
3. Quy trình công việc sẽ tạm ngưng ngay lập tức. Trong băng ghế dự bị hoặc ADK Web, hãy quan sát trạng thái đang chờ xử lý: phiên này giữ mã nhận dạng lệnh gọi mở và không có quy trình nền nào tiêu thụ tài nguyên.
4. Chạy trình nền phân phối bằng bảng điều khiển của băng ghế dự bị hoặc trong thiết bị đầu cuối:

   python -m agent.deliver
   

   Quá trình phân phối sẽ theo dõi Veo cho đến khi video sẵn sàng, sau đó gửi sự kiện tiếp tục.
5. Trong ADK Web, hãy làm mới phiên: quá trình thực thi tiếp tục tại store_video, xác nhận URL video vào trạng thái phiên và hoàn tất quy trình.

9. Triển khai lên Cloud Run

Trong VibeStudio Workbench, hãy chuyển đến Bước 9: Triển khai.

Bạn đã phát triển và xác minh từng thành phần của quy trình trên các hộp cát chuyên dụng. Trong bước này, bạn sẽ lắp ráp quy trình sản xuất hoàn chỉnh và triển khai quy trình đó vào Google Cloud Run.

Trình chạy ADK

Trong quá trình phát triển, adk web đã điều phối biểu đồ. Trong bản phát hành chính thức, ứng dụng sẽ lưu trữ quy trình bằng cách sử dụng lớp Runner của 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: Điều khiển quá trình thực thi quy trình công việc, tạo ra các sự kiện tuần tự khi các nút thực thi và duy trì các bản cập nhật cho dịch vụ phiên.
• Tiếp tục hợp nhất: Cả quyết định của người dùng tại direction_gate và các video đã hoàn tất được phân phối từ Veo đều tiếp tục thực thi thông qua các đối tượng FunctionResponse giống hệt nhau được gửi đến run_async.

Cấu trúc ứng dụng phát hành công khai

Ứng dụng phát hành công khai trong vibestudio/ tích hợp toàn bộ quy trình:

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

• Luồng sự kiện đơn: Phần phụ trợ FastAPI xuất bản các sự kiện trên một luồng Sự kiện do máy chủ gửi (SSE). Giao diện người dùng React trực quan hoá tiến trình đồ thị theo thời gian thực và xử lý các kết nối trễ mà không làm mất trạng thái.
• Thực thi tách biệt: Ứng dụng quản lý vòng lặp sự kiện. Biểu đồ quy trình làm việc hoàn toàn tập trung vào logic thực thi, không nhận biết được giao diện người dùng.

Danh sách cạnh quy trình làm việc hoàn chỉnh trong agent/graph.py kết hợp mọi mẫu kiến trúc được tạo trong suốt lớp học lập trình này:

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

Triển khai lên Cloud Run

Google Cloud Run cung cấp dịch vụ lưu trữ không máy chủ với khả năng tự động mở rộng quy mô, định tuyến yêu cầu và tích hợp các bản dựng vùng chứa:

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

• Tạo vùng chứa: gcloud run deploy --source đóng gói thư mục vibestudio/, tạo hình ảnh vùng chứa bằng Cloud Build và triển khai dịch vụ trong một thao tác duy nhất.
• Mối liên kết phiên: Chuyển các yêu cầu từ cùng một người dùng đến cùng một phiên bản vùng chứa, duy trì trạng thái phiên cục bộ qua các bước lặp lại.
• Khả năng quan sát: Tính năng tích hợp Cloud Trace ghi lại các khoảng thời gian phân tán cho mọi nút, lệnh gọi LLM và quá trình thực thi công cụ, có thể truy cập trong Google Cloud Console trong mục Trình khám phá dấu vết.

Nhấp vào nút Triển khai trong bảng điều khiển để thực thi tập lệnh triển khai. Khi quá trình tạo bản dựng hoàn tất, thiết bị đầu cuối sẽ hiển thị URL dịch vụ trực tiếp.

10. Tóm tắt

Trong VibeStudio Workbench, hãy chuyển đến Bước 10: Tóm tắt để xem xét kiến trúc đã hoàn thành.

Bước	Kiến trúc và khái niệm	Mẫu triển khai
Một câu lệnh duy nhất	Câu lệnh đơn, công cụ hàm, vòng lặp trò chuyện tuần tự	Agent(tools=[...]), function_call / function_response
Nguyên tắc cơ bản về quy trình làm việc dựa trên tác nhân	Quy trình làm việc theo biểu đồ, nghiên cứu song song, đầu ra lược đồ, cổng kiểm soát của con người	Workflow, START, JoinNode, output_schema, RequestInput
Trạng thái và Bộ định tuyến	Trạng thái phiên dùng chung, liên kết tham số, định tuyến xác định, tác nhân tác vụ	Event(state=...), Event(route=...), mode="task", finish_task
Ngân hàng bộ nhớ	Bộ nhớ dài hạn ở cấp người dùng, hợp nhất ngữ nghĩa, các hook vòng đời	memories.generate / retrieve, before_model_callback, after_agent_callback
Công cụ RAG	Truy xuất tài liệu dựa trên bình luận của khán giả, các câu nhúng ngữ nghĩa	Nút rag.create_corpus, RagEmbeddingModelConfig, read_feedback
Tạo video không đồng bộ bằng Veo	Công cụ chạy trong thời gian dài, biên nhận đang chờ xử lý, trình nền phân phối bên ngoài	LongRunningFunctionTool, FunctionResponse(id=...) tiếp tục
Triển khai lên Cloud Run	Điều phối theo chương trình, Sự kiện được gửi bởi máy chủ, vùng chứa không máy chủ	Runner(agent=wf), run_async, Triển khai Cloud Run

Nguyên tắc cốt lõi về cấu trúc

1. Tạm ngưng thay vì chờ: Quy trình công việc tạm dừng một cách rõ ràng để chờ người dùng nhập dữ liệu (RequestInput) hoặc các thao tác chạy trong thời gian dài (LongRunningFunctionTool). Các quy trình không chờ ở trạng thái rảnh trên các luồng hoặc ổ cắm mạng.
2. Tiếp tục trên diện rộng: Mọi hoạt động tạm ngưng đều tiếp tục thông qua một cơ chế giống nhau: một function_response duy nhất mang mã nhận dạng lệnh gọi của nút bị tạm ngưng.
3. Quản lý trạng thái tách biệt: Các nút chia sẻ dữ liệu thông qua các khoá trạng thái phiên được đặt tên và liên kết tham số thay vì tải trọng trung gian chi tiết, liên kết chặt chẽ.
4. Định tuyến xác định trước chi phí tạo: Bộ định tuyến dựa trên quy tắc và bộ lọc biểu thức chính quy đánh giá chính sách với chi phí bằng 0 trước khi các mô hình tạo chạy.
5. Phân tách các mối lo ngại: Bối cảnh dành riêng cho một tác nhân thuộc về các phương thức gọi lại trong vòng đời, trong khi các phần phụ thuộc dữ liệu được chia sẻ thuộc về