Membangun Generator Saran Lagu Agentik: Orkestrasi, Evaluasi, dan Analisis dengan Google Cloud

1. Pengantar

banner kelas master agen

Pelajari cara membangun mesin multi-agen multimodal yang mengambil ringkasan topik mentah dan mengatur pembuatan aset media sosial yang sangat menarik. Dengan menggunakan Agent Development Kit (ADK) Google dan protokol Agent2Agent (A2A), Anda akan menyusun micro-agent otonom, mengemas aturan merek sebagai keterampilan agen yang dapat digunakan kembali, men-deploy layanan agen ke Cloud Run, dan memberi skor pada visual utama yang dihasilkan untuk kepatuhan merek dengan fungsi AI BigQuery.

Yang akan Anda lakukan

Dalam codelab ini, Anda akan mempelajari cara melakukan tugas-tugas berikut:

  • Mengorkestrasi beberapa agen ADK dengan alur kerja grafik deterministik.
  • Mengemas pedoman merek sebagai keahlian agen yang hanya dimuat saat diperlukan.
  • Lengkapi agen dengan alat pembuatan gambar yang menyimpan outputnya sebagai artefak.
  • Mengekspos agen sebagai layanan A2A dan memanggilnya dari agen lain sebagai node jarak jauh.
  • Deploy Visual Director ke Cloud Run dan panggil alur kerja melalui A2A.
  • Beri skor visual utama yang dihasilkan untuk kesesuaian merek di BigQuery dengan fungsi AI.

Yang Anda butuhkan

  • Browser web (seperti Chrome).
  • Akun Google Cloud dan Project Google Cloud dengan penagihan diaktifkan.

2. Sebelum memulai

Buat Project Google Cloud

  1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
  2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Mulai Cloud Shell

Anda akan menggunakan Google Cloud Shell untuk mendownload kode, menjalankan skrip penyiapan, dan men-deploy aplikasi.

  1. Buka Google Cloud Shell di browser Anda (atau klik Activate Cloud Shell di bagian atas Konsol Google Cloud):
    https://shell.cloud.google.com/
    Klik Lanjutkan jika diberi pemberitahuan tambahan.Tunggu hingga terminal dan editor dimuat sepenuhnya. Proses ini mungkin memerlukan waktu satu atau dua menit.
  2. Konfigurasi Project ID dan region Google Cloud Anda (misalnya, us-central1) di lingkungan Anda dengan menempelkan di terminal (ganti dan dengan nilai Anda):
    export PROJECT_ID="<YOUR_PROJECT_ID>"
export REGION="<YOUR_REGION>"
gcloud config set project $PROJECT_ID
    Menempel di terminalAnda akan melihat pesan yang mirip dengan:
    Your active configuration is: [cloudshell-####]
Updated property [core/project]
  3. Aktifkan Google Cloud API yang diperlukan untuk project Anda:
    gcloud services enable \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com \
  aiplatform.googleapis.com \
  storage.googleapis.com \
  storage-component.googleapis.com \
  bigqueryconnection.googleapis.com \
  bigquery.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  iap.googleapis.com \
  iam.googleapis.com

Membuat Clone Repositori

Kita memiliki template kode untuk membantu Anda memulai codelab. Ukurannya relatif kecil, tetapi repositori GitHub tempatnya berada cukup besar. Untuk mempercepat clone, dan menghemat ruang disk, biasanya kita akan menggunakan git clone dengan opsi --filter=blob:none, dan git sparse-checkout, serta beberapa perintah lainnya.

Ini terdengar sangat rumit, tetapi Antigravity dapat melakukan semuanya untuk kita.

Pertama, mari kita konfigurasi Antigravity CLI agar dapat langsung menyelesaikan masalah kita, lalu luncurkan.

Di Cloud Shell, jalankan perintah ini:

source <(curl -fsSL https://github.com/GoogleCloudPlatform/devrel-demos/raw/refs/heads/vladkol/cloud-shell-configure-agy/codelabs/labs-scripts/bwg-multi-agent-pitch-generator/cloud_shell_configure_agy.sh)

Perintah ini mengonfigurasi Antigravity CLI dan meluncurkannya di terminal yang sama. Saat keluar dari Antigravity CLI, Anda akan kembali ke perintah Cloud Shell.

Antigravity CLI

Kita hanya memerlukan folder codelabs/bwg-multi-agent-pitch-generator di repositori. Minta Antigravity untuk mendownload folder tersebut saja, dan menyimpannya secara lokal di ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/.

Berikan tugas ini ke Antigravity CLI:

Download files from under `https://github.com/GoogleCloudPlatform/devrel-demos/tree/main/codelabs/bwg-multi-agent-pitch-generator`
to folder `~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/`.
If `devrel-demos` folder already exists, rename it with a `.backup` suffix.

Perintah Antigravity CLI

Antigravity akan menjalankan tugas. Anda akan diminta memberikan izin untuk menjalankan beberapa perintah. Setelah kode didownload, keluar dari Antigravity CLI dengan menjalankan perintah /exit:

/exit

Keluar dari Antigravity CLI

Membuka ruang kerja repositori

Sekarang, mari kita buka ruang kerja kode di Cloud Shell. Jalankan perintah ini di terminal Cloud Shell:

cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/
cloudshell workspace .

Jalankan skrip penyiapan

Untuk membuat pengalaman ini lebih lancar, jalankan skrip penyiapan dari repositori. Skrip ini mengonfigurasi variabel lingkungan, menginstal agents-cli, membuat bucket Cloud Storage untuk artefak, membuat koneksi Resource Cloud BigQuery, dan memberikan izin IAM yang diperlukan ke akun layanannya dengan percobaan ulang otomatis.

Skrip penyiapan juga memanggil setenv.sh, helper kecil yang mendapatkan variabel yang dibutuhkan kedua agen — GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_REGION, GOOGLE_CLOUD_LOCATION, dan GOOGLE_GENAI_USE_VERTEXAI — dari PROJECT_ID dan REGION yang Anda ekspor di atas. Skrip ini juga menyimpan kedua nilai tersebut ke file .env di direktori beranda Anda sehingga Anda dapat memulihkannya nanti.

  1. Di Cloud Shell, buat skrip penyiapan dapat dieksekusi dan jalankan:
    chmod +x codelab-setup.sh setenv.sh
./codelab-setup.sh
  2. Proses ini akan memerlukan waktu sekitar satu menit. Anda akan melihat pesan ini yang menunjukkan keberhasilan: "🎉 🦄 Script execution complete."berhasil
  3. Skrip penyiapan berjalan di shell-nya sendiri, sehingga variabelnya tidak mencapai terminal Anda. Memuatnya ke sesi Anda:
    source ./setenv.sh
    Anda akan melihat project, region, dan lokasi Anda ditampilkan kembali.

3. Mengorkestrasi agen dengan alur kerja grafik

Dalam tugas ini, Anda akan membuat project pembuat saran lagu dan membangun alur kerja grafik yang menjalankan dua agen serta menggabungkan outputnya.

Saran lagu memerlukan konsep, yang berarti ide dan aset yang menjual konsep tersebut. Dalam kasus penggunaan ini, kita akan mendesain agen yang memiliki tanggung jawab berbeda dalam cakupan pekerjaan, yang menunjukkan cara Anda dapat memisahkan tugas yang kompleks dan mendelegasikannya ke agen yang berbeda dengan tanggung jawab yang berbeda, sehingga lebih mudah dikelola.

Membagi jenis pekerjaan ini di antara spesialis memerlukan sesuatu untuk mengoordinasikan saat setiap agen berjalan. Anda dapat memilih untuk membiarkan agen Anda memutuskan kapan harus memanggil setiap sub-agen atau menerapkan pendekatan yang lebih deterministik. Dalam codelab ini, Anda akan menggunakan pendekatan deterministik dengan alur kerja grafik.

Buat struktur project agen pertama

  1. Di Cloud Shell, buat project dengan menempelkan di terminal:
    cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator
agents-cli create pitch-generator \
  --agent adk \
  --agent-directory pitch_generator \
  --deployment-target cloud_run \
  --session-type in_memory \
  --cicd-runner skip \
  --region <YOUR_REGION> \
  --auto-approve
    Tindakan ini akan menulis project yang lengkap dan dapat dijalankan: agen, Dockerfile, pengujian, Terraform untuk nanti, dan file .env dengan template .env.example-nya. Ada dua bagian penting untuk codelab ini:
    • pitch_generator/agent.py adalah agen, dan file yang Anda tulis ulang.
    • pitch_generator/ adalah nama paket, yang ditetapkan oleh --agent-directory.
    Agen membaca project dan regionnya dari lingkungan yang Anda ekspor dengan setenv.sh, jadi tidak ada yang perlu dikonfigurasi di sini.
  2. Instal dependensi:
    cd pitch-generator
agents-cli update -y && agents-cli install && uv sync --upgrade-package google-adk
    Catatan: Scaffold juga menghubungkan project untuk menayangkan A2A, protokol yang digunakan nanti dalam codelab ini. Jangan sentuh file tersebut untuk saat ini.

Memahami grafik

ADK v2.x mendukung alur kerja grafik. Grafik dibuat dari node, yang merupakan unit kerja, dan tepi, yang menghubungkannya. Node biasanya berupa agen, meskipun fungsi Python biasa juga berfungsi. Edge menyatakan bahwa saat satu node selesai, node lain akan berjalan berikutnya.

Tepi ditulis sebagai daftar, dan ADK akan menentukan urutannya:

edges=[
    ("START", creative_director),        ## the graph begins here
    (creative_director, copywriter),     ## then this
]

Penyusunan bertingkat memberikan makna pada tepi:

Edge

Arti

(a, b, c)

Rantai. a, lalu b, lalu c, satu demi satu

(a, (b, c))

Fan-out. a, lalu b dan c secara bersamaan

((a, b), c)

Fan-in. c menunggu a dan b

Untuk fan-in, Anda menggunakan JoinNode, yang menunggu setiap pendahulunya dan meneruskan outputnya bersama-sama.

Dalam tugas ini, kita akan membangun alur kerja berikut:

grafik alur kerja awal

Membangun pipeline

  1. Buka file agen dengan menempelkan di terminal ini:
    cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/pitch-generator
cloudshell edit pitch_generator/agent.py
    Anda akan melihat agent.py yang di-scaffold di editor Cloud Shell.💡 Petunjuk: Kapan saja, Anda dapat memilih kode dan menggunakan ikon bohlam untuk meminta Gemini menjelaskannya. Anda juga dapat bertanya kepada Antigravity CLI.Menggunakan Gemini Code Assist
  2. Ganti seluruh file di pitch_generator/agent.py di editor dengan kode berikut:
    import mimetypes
import os

from dotenv import load_dotenv
from google.adk.agents import Agent
from google.adk.agents.context import Context
from google.adk.agents.remote_a2a_agent import (
   AGENT_CARD_WELL_KNOWN_PATH,
   RemoteA2aAgent,
)
from google.adk.apps import App
from google.adk.events.event import Event
from google.adk.models import Gemini
from google.adk.workflow import JoinNode, Workflow
from google.genai import types

load_dotenv()

MODEL = "gemini-3.8-flash"

def _model() -> Gemini:
   return Gemini(
      model=MODEL,
      client_kwargs={"location": "global"},
      retry_options=types.HttpRetryOptions(attempts=3),
   )

""" ⬇️ Configure visual-director RemoteA2aAgent agent below this comment """


creative_director = Agent(
   name="creative_director",
   model=_model(),
   description="Turns a raw idea into a campaign concept.",
   instruction=(
      "You are the Creative Director. Turn the idea you are given into ONE "
      "punchy campaign concept line with the rationale explanation behind it."
   ),
   output_key="creative_director",
)

copywriter = Agent(
   name="copywriter",
   model=Gemini(model=MODEL, retry_options=types.HttpRetryOptions(attempts=3)),
   description="Writes social copy for a campaign concept.",
   instruction=(
      "You are the Copywriter. Write ONE short social caption for the "
      "campaign concept you are given. Under 25 words."
   ),
)

""" Waits for every node wired into it, then hands their outputs on together."""
assemble = JoinNode(name="assemble")

def package(node_input: dict):
   """Render the joined branches as the finished pitch.
   """

   pitch = "\n\n".join(
      [
            f"CONCEPT\n{node_input['creative_director']}",
            f"COPY\n{node_input['copywriter']}",
      ]
   )
   """ The first event is what the user sees. The second is the node's output,
   which any downstream node would receive."""
   yield Event(content=types.Content(role="model", parts=[types.Part(text=pitch)]))
   yield Event(output=pitch)

""" we put creative_director before `assemble`  so that we can
   gather the `Concept` output at assemble"""
root_agent = Workflow(
   name="pitch_generator",
   edges=[
      ("START", creative_director),
      (creative_director, copywriter),
      ((creative_director, copywriter), assemble),
      (assemble, package),
   ],
)

app = App(
   root_agent=root_agent,
   name="pitch_generator",
)
  3. agents-cli menyertakan UI pengembangan web bawaan yang disebut playground untuk inspeksi, mirip dengan ADK. Untuk memulai ruang kreasi:
    agents-cli playground --port 8080
    Anda akan ditanya apakah Anda ingin mengaktifkan telemetri. Ketik n, lalu tekan Enter.
  4. Klik Web Preview, ikon mata di kanan atas terminal, lalu pilih Preview on port 8080.klik pratinjau web
  5. Anda akan melihat antarmuka berikut untuk melakukan chat dengan agen. Coba kirim perintah "Papan seluncur terbang untuk kucing". Anda akan melihat respons seperti yang ditunjukkan di bawah, tempat Anda juga dapat memeriksa grafik alur kerja lengkap.alur kerja demoPeriksa cara jawaban tersebut dibuat. Playground menampilkan setiap langkah yang dilakukan grafik, secara berurutan: creative_director, lalu copywriter, lalu assemble, lalu package. Urutan tersebut adalah grafik yang Anda hubungkan, dan dengan cara ini Anda dapat dengan cepat mengonfirmasi grafik yang baru saja Anda buat.
  6. Kembali ke terminal dan hentikan proses agents-cli playground yang sedang berjalan dengan menekan Ctrl+C dua kali.

4. Memberi agen keahlian

Dalam tugas ini, Anda akan membuat agen kedua dan memberinya sekumpulan pedoman merek yang dikemas sebagai keahlian.

Pipeline menulis kata. Gambar memerlukan gaya visual: palet, cara pencahayaan, komposisi yang Anda gunakan dan yang tidak pernah Anda gunakan. Halaman tersebut adalah halaman aturan, dan halaman aturan memerlukan mekanisme yang lebih baik untuk dikelola. Salah satu cara untuk melakukannya adalah dengan mengemasnya sebagai "keterampilan agen".

Keahlian adalah folder yang berisi file SKILL.md. Struktur direktori keterampilan terlihat seperti contoh berikut (menggunakan visual_director, agen berikutnya yang akan Anda buat):

visual_director/
   ...
   agent.py
   skills/
      brand-guidelines/
         SKILL.md          ## required: frontmatter + instructions
         references/       ## optional: longer supporting documents
         assets/           ## optional: templates, images, data
         scripts/          ## optional: executable helpers
   ...

Titik entri kemampuan agen adalah file SKILL.md, yang mencakup bagian frontmatter YAML seperti yang ditunjukkan di bawah:

---
name: brand-guidelines
description: The house brand rules for a key visual. Load this before writing art direction, so the visual looks like it came from this brand.
---

## Brand guidelines

Deep indigo and slate as the ground. One warm accent, amber or terracotta...

Frontmatter adalah label. Deskripsi adalah semua yang dilihat agen di awal, itulah sebabnya deskripsi harus menyatakan kapan skill layak dimuat. body adalah konten, dan konten tersebut tetap berada di luar konteks hingga agen memanggil load_skill.

Perbedaan itulah intinya. Perintah tetap singkat, agen menarik aturan hanya saat diperlukan, dan mengubah gaya berarti mengedit satu file, bukan mencari-cari string perintah.

Kita akan mulai membangun agen kedua, visual-director, dengan memanfaatkan keterampilan agen seperti yang ditunjukkan dalam diagram di bawah:

melengkapi agen kedua dengan keahlian

Menyiapkan Visual Director

Anda akan membuat agen khusus untuk menangani komponen visual, visual-director. Project ini merupakan project terpisah karena nantinya akan menjadi layanannya sendiri untuk mendemonstrasikan cara beberapa agen berkomunikasi satu sama lain menggunakan A2A protocol. Anda akan mendapatkan dua project yang berdampingan:

bwg-multi-agent-pitch-generator/
├── pitch-generator/              ## built in the last task
│   ├── pitch_generator/
│   │   ├── agent.py              ## the graph you wrote
│   │   ├── app_utils/            ## generated, A2A wiring
│   │   └── fast_api_app.py       ## generated, serves the agent
│   └── pyproject.toml
└── visual-director/              ## created below
    └── ...                       ## the same shape again
  1. Buat project dan instal dependensinya dengan menempelkan di terminal:
    cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator
agents-cli create visual-director \
  --agent adk \
  --agent-directory visual_director \
  --deployment-target cloud_run \
  --session-type in_memory \
  --cicd-runner skip \
  --region <YOUR_REGION> \
  --auto-approve
cd visual-director
agents-cli update -y && agents-cli install && uv sync --upgrade-package google-adk

Menulis pedoman merek

  1. Buat folder keterampilan dan buka file:
    mkdir -p visual_director/skills/brand-guidelines
cloudshell edit visual_director/skills/brand-guidelines/SKILL.md
  2. Tempelkan konten berikut ke dalam file SKILL.md yang terbuka di Editor, lalu simpan:Badge
    ---
name: brand-guidelines
description: The house brand rules for a key visual — palette, light, composition, subject treatment, and what never appears. Load this before writing art direction or rendering an image, so the visual looks like it came from this brand rather than from a generic image model.
---

## Brand guidelines

House style for campaign key visuals. Every rule here beats a preference in the
brief. If the brief asks for something forbidden below, follow the brief for the
subject and the guidelines for the treatment.

## Palette

Deep indigo and slate as the ground. One warm accent — amber or terracotta —
carrying the eye to the subject. Nothing neon, nothing fluorescent.

At most three colors with any weight. A fourth reads as clutter.

## Light

One dominant source, low and raking. Long shadows are wanted. Golden hour or a
single hard studio key, never flat overhead light and never a ring light.

Rim light is allowed on the subject only, and only to separate it from the
ground.

## Composition

Subject off-center, roughly a third in. Generous negative space on the opposite
side — copy lands there later, so leave it genuinely empty.

Eye level or slightly below. No top-down flat lays. No fisheye, no Dutch tilt.

## Subject

One subject. If the idea implies a crowd, pick the one that carries it.

Photographic realism with a shallow depth of field. Not illustration, not 3D
render, not clay, not pixel art.

## Never

- Text, logos, watermarks, or signage anywhere in the frame
- Collage or split-screen layouts
- Chrome, lens flare, bokeh sparkle
- Cool-toned neon cyan or magenta

## Rendering the prompt

When you turn art direction into an image prompt, state the palette, the light,
and the composition explicitly. An image model will not infer them from the
subject alone. Put the "Never" items in as plain description of what the frame
does contain, not as negatives — image models handle a positive description far
better than a list of prohibitions.

Mengubah visual_director/agent.py

Perbarui file agent.py dan konfigurasikan agar dilengkapi dengan skill yang ditentukan sebelumnya.

  1. Buka file agen:
    cloudshell edit ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/visual-director/visual_director/agent.py
  2. Ganti seluruh konten file visual_director/agent.py dengan kode berikut:
    import mimetypes
from pathlib import Path

from google import genai
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.skills import load_skill_from_dir
from google.adk.tools import ToolContext
from google.adk.tools.skill_toolset import SkillToolset
from google.genai import types
MODEL = "gemini-3.8-flash"

## Configure the `brand-guidelines` skill for the agent
BRAND_SKILL = load_skill_from_dir(Path(__file__).parent / "skills" / "brand-guidelines")

## Add definition of `generate_key_visual` tool below this comment

root_agent = Agent(
   name="visual_director",
   model=Gemini(
      model=MODEL,
      client_kwargs={"location": "global"},
      retry_options=types.HttpRetryOptions(attempts=3),
   ),
   description="Turns a campaign concept into art direction and a key visual.",
   instruction="""You are the Visual Director on a campaign pitch team.

   Call `load_skill` for `brand-guidelines` before you write anything. The house
   style is not optional and it is not in this prompt.

   You are given a campaign concept. Then, in order:

   1. Write art direction for ONE key visual that sells it, obeying the brand
   guidelines: subject, composition, lighting, color, mood. Three or four
   sentences.
   2. Call `generate_key_visual` with exactly that art direction.

   Your final reply is the art direction itself and nothing else. No preamble, no
   alternatives, no questions back. Do not mention the skill, the tool, or the
   image file — the image travels on its own.""",
   tools=[
      SkillToolset(skills=[BRAND_SKILL]),
      ## Supply the `generate_key_visual` tool below this comment
   ],
)

app = App(
   root_agent=root_agent,
   name="visual_director",
)
    Agen visual-director kini dikonfigurasi dengan benar dengan keahlian agen. Sebelum mengujinya, Anda akan melengkapi agen ini dengan alat untuk membuat aset gambar sebagai salah satu kemampuan utamanya.

5. Membekali agen dengan alat pembuatan gambar

Dalam tugas ini, Anda akan memberi Direktur Visual alat yang merender arahan artistik sebagai gambar dan menyimpannya sebagai artefak. Artefak adalah bagian data biner atau konten file yang diberi nama dan memiliki versi yang dibuat, diubah, atau digunakan oleh agen AI selama tugas.

alat dan artefak yang ditulisnya

Terapkan dan tambahkan alat ke agen

  1. Buka file agen:
    cloudshell edit ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/visual-director/visual_director/agent.py
  2. Salin alat generate_key_visual berikut sebelum definisi root_agent:
    async def generate_key_visual(art_direction: str, tool_context: ToolContext) -> dict:
   """Render the art direction as the campaign's key visual.

   Args:
      art_direction: The art direction to render, in full.

   Returns:
      The saved artifact's filename, version, size and media type.
   """
   IMAGE_MODEL = "gemini-3.1-flash-lite-image"

   response = await genai.Client(location="global").aio.models.generate_content(
      model=IMAGE_MODEL, contents=art_direction
   )

   ## The image arrives as inline bytes on one of the response parts.
   image = next(
      (
         part.inline_data
         for part in response.candidates[0].content.parts or []
         if part.inline_data
      ),
      None,
   )
   if image is None:
      raise ValueError(f"{IMAGE_MODEL} returned no image for: {art_direction[:120]}")

   filename = "key_visual" + (
      mimetypes.guess_extension(image.mime_type or "") or ".bin"
   )
   version = await tool_context.save_artifact(filename, types.Part(inline_data=image))

   ## Return the artifact filename and version
   return {
      "filename": filename,
      "version": version,
      "bytes": len(image.data),
      "mime_type": image.mime_type,
   }
  3. Tambahkan generate_key_visual di bawah SkillToolset untuk melengkapi agen dengan alat:
       tools=[
      SkillToolset(skills=[BRAND_SKILL]),
      ## Supply the `generate_key_visual` tool below this comment
      generate_key_visual,
   ],
  4. agents-cli menyertakan UI pengembangan web bawaan yang disebut playground untuk inspeksi, mirip dengan ADK. Untuk memulai ruang kreasi:
    agents-cli playground --port 8080
  5. Klik Web Preview, ikon mata di kanan atas terminal, lalu pilih Preview on port 8080.klik pratinjau web
  6. Anda akan melihat antarmuka berikut untuk melakukan chat dengan agen. Coba kirim perintah "Sembilan nyawa. Tanpa gravitasi."alur kerja demoAnda dapat memeriksa dari interaksi bagaimana agen visual_director menjalankan load_skill("brand-guidelines") untuk membaca keterampilan pedoman merek, lalu menjalankan generate_key_visual untuk mulai membuat gambar. Image yang dihasilkan disimpan sebagai artefak, yang juga ditampilkan di UI dan dapat diperiksa dengan mudah.
  7. Kembali ke terminal dan hentikan proses agents-cli playground yang sedang berjalan dengan menekan Ctrl+C dua kali.

6. Arsitektur multi-agen dengan A2A Protocol

Dalam tugas ini, Anda akan mengekspos Visual Director sebagai layanan yang dapat dipanggil oleh agen lain, dan mengonfigurasinya untuk merespons dengan gambar yang dihasilkan.

Agent2Agent (A2A) adalah protokol terbuka bagi satu agen untuk memanggil agen lain melalui jaringan. Bagian utamanya adalah kartu agen, dokumen JSON yang dipublikasikan agen tentang dirinya sendiri melalui URL yang terkenal, yang memberikan nama, deskripsi, dan kemampuannya. Pemanggil mengambil kartu dan tahu cara berbicara dengan agen di baliknya, tanpa kode sumber, dependensi, atau bahasa yang sama.

A2A protocol

agents-cli sudah menyambungkan ini secara default. Scaffold yang dihasilkan visual_director/app_utils/a2a.py, yang membangun kartu dari agen Anda dan memasang rute, dan visual_director/fast_api_app.py, yang menayangkannya. Anda hanya memerlukan sedikit modifikasi agar dapat mengirimkan kembali artefak ke klien.

Arsitekturnya akan terlihat seperti yang ditunjukkan di bawah. Perhatikan bahwa agen belum diintegrasikan ke dalam alur kerja awal kita:

menyiapkan server A2A

Scaffold server A2A agents-cli

Kode dan modul berikut sudah disediakan saat kita melakukan inisialisasi agen visual-director menggunakan agents-cli. Buka file ini dengan menempelkan perintah berikut di terminal:

cloudshell edit visual_director/fast_api_app.py
cloudshell edit visual_director/app_utils/a2a.py

visual_director/fast_api_app.py memulai agen dan memasang rute A2A di bawah jalur yang dibuat dari nama aplikasi:

await attach_a2a_routes(
    app,
    agent=root_agent,
    runner=runner,
    rpc_path=f"/a2a/{adk_app.name}",   ## becomes /a2a/visual_director
)

visual_director/app_utils/a2a.py akan melakukan sisanya dalam tiga langkah.

Pertama, kartu agen dibuat dari agen itu sendiri. Nama, deskripsi, dan setiap alat menjadi entri yang dapat dibaca pemanggil:

agent_card = await AgentCardBuilder(
    agent=agent,
    rpc_url=f"{resolved_app_url}{rpc_path}",
).build()

Kedua, protokol ini menempatkan eksekutor di antara protokol dan agen Anda. Permintaan A2A yang masuk diterjemahkan menjadi eksekusi ADK, dan hasilnya diterjemahkan kembali:

request_handler = DefaultRequestHandler(
    agent_executor=A2aAgentExecutor(runner=runner, force_new_version=True),
    task_store=task_store,
    agent_card=agent_card,
)

Ketiga, aplikasi ini memasang dua rute: satu untuk menayangkan kartu, satu untuk menerima panggilan.

Rute

Tujuan

/a2a/visual_director/.well-known/agent-card.json

Kartu. Penelepon membaca bagian ini terlebih dahulu untuk mempelajari apa yang dapat dilakukan agen

/a2a/visual_director

Endpoint JSON-RPC. Tujuan permintaan sebenarnya

Membiarkan artefak melintasi batas

Secara default, respons A2A membawa teks. Image adalah artefak, dan artefak tetap berada di penyimpanan agen penayangan kecuali jika Anda mengonfigurasinya agar disertakan.

  1. Buka file A2A yang dibuat:
    cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/visual-director
cloudshell edit visual_director/app_utils/a2a.py
  2. Temukan impor AgentCardBuilder dan tambahkan impor A2aAgentExecutorConfig dan include_artifacts_in_a2a_event_interceptor di bawahnya:
    ## ...
## from google.adk.a2a.utils.agent_card_builder import AgentCardBuilder
## Add the following two below `AgentCardBuilder` import
from google.adk.a2a.executor.config import A2aAgentExecutorConfig
from google.adk.a2a.executor.interceptors.include_artifacts_in_a2a_event import (
   include_artifacts_in_a2a_event_interceptor,
)
  3. Temukan baris agent_executor=A2aAgentExecutor(runner=runner), dan ganti dengan kode berikut (tambahkan A2aAgentExecutorConfig):
             agent_executor=A2aAgentExecutor(
            runner=runner,
            force_new_version=True,
            config=A2aAgentExecutorConfig(
               execute_interceptors=[include_artifacts_in_a2a_event_interceptor]
            ),
         ),

Mulai layanan dan baca kartu A2A yang dipublikasikan

  1. Mulai server di latar belakang. Anda harus mendeklarasikan APP_URL, karena ini adalah alamat yang diiklankan kartu sebagai alamatnya sendiri. Tempelkan ini di terminal:
    APP_URL=http://localhost:8801 nohup uv run uvicorn visual_director.fast_api_app:app --port 8801 > /tmp/visual-director.log 2>&1 &
  2. Tunggu beberapa detik hingga dimulai, lalu konfirmasi bahwa layanan sudah berjalan:
    sleep 10
tail -2 /tmp/visual-director.log
    Anda akan melihat:
    INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8801 (Press CTRL+C to quit)
  3. Baca kartu yang kini dipublikasikan agen:
    curl -s http://localhost:8801/a2a/visual_director/.well-known/agent-card.json | python3 -m json.tool
    Kartu ini mencantumkan nama, deskripsi, URL, dan keterampilan agen, termasuk generate_key_visual. Respons ini dibuat langsung dari definisi agen dalam kode.
    {
   "name": "visual_director",
   "description": "Turns a campaign concept into art direction and a key visual.",
   "skills": [
        {
            "id": "visual_director",
            "name": "model",
            "tags": [
                "llm"
            ]
        },
        {
            "id": "visual_director-generate_key_visual",
            "name": "generate_key_visual",
            "description": "Render the art direction as the campaign's key visual.\n\nArgs:\n   art_direction: The art direction to render, in full.\n\nReturns:\n   The saved artifact's filename, version, size and media type.",
            "tags": [
                "llm",
                "tools"
            ]
        }
   ],
   "preferredTransport": "JSONRPC",
   "protocolVersion": "0.3",
   "url": "http://localhost:8801/a2a/visual_director"
}
    Anda siap menyematkan agen visual-director ke dalam alur kerja pitch-generator utama.

7. Menyematkan agen jarak jauh A2A dalam alur kerja

Dalam tugas ini, Anda akan menambahkan agen jarak jauh ke grafik sebagai cabang ketiga.

Agen jarak jauh di-wrap dalam RemoteA2aAgent dan ditempatkan dalam grafik seperti node lainnya. Tepi mempertahankan bentuk yang sama, dan koordinator tidak mengetahui node mana yang lokal.

Arahkan koordinator ke layanan dan perbarui alur kerja grafik

  1. Buka file agen:
    cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/pitch-generator
cloudshell edit pitch_generator/agent.py
  2. Tambahkan impor ini di bagian atas file, bersama dengan impor yang ada:
    import asyncio

import subprocess
import google.auth.transport.requests
import google.oauth2.id_token
import httpx
from google.adk.a2a.converters.part_converter import convert_genai_part_to_a2a_part
  3. Tambahkan definisi RemoteA2aAgent berikut di atas deklarasi creative_director:
    VISUAL_DIRECTOR_URL = os.getenv("VISUAL_DIRECTOR_URL", "http://localhost:8801")

## For deployment on Cloud Run
def _cloud_run_client() -> httpx.AsyncClient | None:
   """An httpx client that signs each request with a Cloud Run ID token.

   Cloud Run deploys private, so both the agent-card fetch and the A2A calls
   need one.
   """
   if not VISUAL_DIRECTOR_URL.startswith("https://"):
      return None

   async def sign(request: httpx.Request) -> None:
      token = None
      try:
         token = await asyncio.to_thread(
               google.oauth2.id_token.fetch_id_token,
               google.auth.transport.requests.Request(),
               VISUAL_DIRECTOR_URL,
         )
      except Exception:
         token = subprocess.check_output(
            ["gcloud", "auth", "print-identity-token", "-q"],
            stderr=subprocess.PIPE
         ).decode().strip()
      if not token:
            raise Exception("Failed to fetch ID token")
      request.headers["Authorization"] = f"Bearer {token}"

   return httpx.AsyncClient(event_hooks={"request": [sign]}, timeout=600)

## Keep the approval's tool traffic out of the A2A request
def _pitch_parts_only(part: types.Part):
   """Sends the Visual Director text and media only.

   RemoteA2aAgent replays the session on every call, and the Visual Director
   runs downstream of the human approval, so the approval's function_response
   would travel alongside the concept text. An ADK server reads a function
   response as "resume the paused invocation" and rejects a message that also
   carries text, so drop the tool parts here.
   """
   if part.function_call or part.function_response:
      return None
   return convert_genai_part_to_a2a_part(part)

visual_director = RemoteA2aAgent(
   name="visual_director",
   description="Turns a campaign concept into art direction for one key visual.",
   agent_card=(
      f"{VISUAL_DIRECTOR_URL}/a2a/visual_director{AGENT_CARD_WELL_KNOWN_PATH}"
   ),
   httpx_client=_cloud_run_client(),
   genai_part_converter=_pitch_parts_only,
)
  4. Timpa atau ganti fungsi Python node package dengan definisi berikut:
    async def package(ctx: Context, node_input: dict):
   """Render the joined branches as the finished pitch."""
   empty = [name for name, value in node_input.items() if not value]
   if empty:
      raise ValueError(f"nothing reached the join from: {', '.join(empty)}")

   def _key_visual(ctx: Context) -> types.Blob | None:
      """The image the Visual Director sent back, or None if it sent none."""
      for event in reversed(ctx.session.events):
         if event.author != "visual_director" or not event.content:
               continue
         for part in event.content.parts or []:
               if part.inline_data and part.inline_data.data:
                  return part.inline_data
      return None

   image = _key_visual(ctx)
   if image is None:
      raise ValueError("the Visual Director returned art direction but no image")

   suffix = mimetypes.guess_extension(image.mime_type or "") or ".bin"
   filename = f"key_visual{suffix}"
   await ctx.save_artifact(filename, types.Part(inline_data=image))

   pitch = "\n\n".join(
      [
         f"CONCEPT\n{node_input['creative_director']}",
         f"COPY\n{node_input['copywriter']}",
         f"ART DIRECTION\n{node_input['visual_director']}",
         f"KEY VISUAL\n{filename}, {len(image.data)} bytes, {image.mime_type}",
      ]
   )
   yield Event(
      content=types.Content(
         role="model",
         parts=[types.Part(text=pitch), types.Part(inline_data=image)],
      )
   )
   yield Event(output=pitch)
  5. Tambahkan Gerbang Persetujuan Manusia sebelum generasi hilir dilanjutkan. Di pitch_generator/agent.py, tentukan node persetujuan di atas root_agent:
    @node(rerun_on_resume=False)
async def approve_concept(ctx: Context):
    yield RequestInput(
        message="Please approve the campaign concept (yes/no).",
        response_schema=str
    )

@node(rerun_on_resume=True)
async def user_approval(ctx: Context):
   user_response = await ctx.run_node(approve_concept)
   if str(user_response).lower() in ("yes", "y"):
      approved_concept = f"## Approved Concept\n\n{ctx.session.state['creative_director']}"
      yield Event(
         content=types.Content(
            role="model",
            parts=[types.Part(text=approved_concept)]
         )
      )
   else:
      raise ValueError("User rejected the concept")
  6. Terakhir, perbarui impor di bagian atas untuk menyertakan RequestInput dan node dari google.adk.events dan google.adk.workflow:
    from google.adk.events import Event, RequestInput
from google.adk.workflow import JoinNode, Workflow, node
    dan ubah alur kerja root_agent edges agar dirutekan melalui user_approval:
        edges=[
        ("START", creative_director),
        (creative_director, user_approval, (copywriter, visual_director)),
        ((creative_director, copywriter, visual_director), assemble),
        (assemble, package),
    ],
    Beberapa detail yang perlu diperhatikan:
    • Persetujuan Human-in-the-Loop (HITL): approve_concept menghasilkan RequestInput. Saat alur kerja mencapai node ini, eksekusi akan dijeda dan memancarkan interupsi ke pemanggil. Cabang hilir (copywriter dan visual_director) tidak akan berjalan hingga persetujuan pengguna dikonfirmasi.
    • visual_director muncul di tepi persis seperti copywriter, meskipun yang satu adalah panggilan fungsi dan yang lainnya berada di seluruh jaringan.
    • Gambar yang ditampilkan dibaca dari peristiwa sesi, bukan dari node_input, karena saat ini hanya teks yang dipromosikan ke output node. Gambar melintasi batas melalui interseptor A2A, tetapi tiba terlampir pada peristiwa agen jarak jauh, sehingga fungsi bantuan _key_visual mengambilnya dari sana.

Menguji integrasi

Sekarang Anda akan menguji bahwa Visual Director (yang berjalan di latar belakang) dan Pitch Generator dapat berkomunikasi melalui protokol A2A.

  1. Pastikan Visual Director masih berjalan di latar belakang:
    curl -s -o /dev/null -w "visual director: %{http_code}\n" http://localhost:8801/a2a/visual_director/.well-known/agent-card.json
    Anda akan mendapatkan hasil visual director: 200 di sini.Jika Anda mendapatkan status lain, jalankan perintah berikut untuk memulai ulang:
    fuser -k 8801/tcp 2>/dev/null || true
cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/visual-director
APP_URL=http://localhost:8801 nohup uv run uvicorn visual_director.fast_api_app:app --port 8801 > /tmp/visual-director.log 2>&1 &
cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/pitch-generator
sleep 10
curl -s -o /dev/null -w "visual director: %{http_code}\n" http://localhost:8801/a2a/visual_director/.well-known/agent-card.json
  2. Mulai pratinjau:
    cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/pitch-generator/pitch_generator
agents-cli playground --port 8080
  3. Klik Web Preview, ikon mata di kanan atas terminal, lalu pilih Preview on port 8080.klik pratinjau web
  4. Anda akan melihat antarmuka untuk melakukan chat dengan agen. Coba kirim perintah "Papan seluncur terbang untuk kucing".alur kerja demoalur kerja demoAnda akan melihat interaksi lengkap saat alur kerja dimulai dan setiap agen berjalan. Setelah creative_director membuat draf konsep, alur kerja akan dijeda di gerbang persetujuan dan meminta Anda mengonfirmasi: "Setujui konsep kampanye (ya/tidak)." Masukkan "yes" di kolom input untuk melanjutkan.Setelah disetujui, grafik akan melebar: Anda dapat melihat kapan agen visual-director mulai memuat skill, dan di tengah pembuatan gambar, agen copywriter selesai membuat teks media sosial—yang menunjukkan bahwa kedua agen berjalan secara paralel tanpa saling menunggu. Setelah keduanya selesai, node assemble menggabungkan hasil dengan konsep yang disetujui yang dihasilkan oleh creative_director, sehingga memfinalisasi penayangan konten saran dalam fungsi package.dua layanan, yang terhubung melalui A2A

8. Mempertahankan visual utama di Cloud Storage

Sejauh ini, setiap elemen visual utama telah ada dalam memori. Saat proses berhenti, gambar akan hilang, yang tidak masalah untuk uji coba dan tidak berguna untuk kampanye. Dalam tugas ini, Anda akan memberi alur kerja bucket untuk menulis, dan membuat set data BigQuery yang akan digunakan dalam tugas terakhir.

ADK memutuskan ke mana artefak akan ditempatkan saat startup. app_utils/services.py yang dihasilkan membaca satu variabel lingkungan:

def get_artifact_service():
    """Process-wide artifact service: GCS when a bucket is set, else in-memory."""
    if bucket := os.environ.get("LOGS_BUCKET_NAME"):
        return GcsArtifactService(bucket_name=bucket)
    return InMemoryArtifactService()

Jika Anda menetapkan LOGS_BUCKET_NAME, setiap panggilan save_artifact akan mendarat di Cloud Storage.

mengintegrasikan layanan artefak dengan bucket GCS

Membuat set data BigQuery

  1. Di Cloud Shell, jalankan perintah berikut untuk membuat set data BigQuery:
    bq mk --dataset --location=<YOUR_REGION> --project_id=<YOUR_PROJECT_ID> bwg
  2. Arahkan penyimpanan artefak koordinator ke bucket:
    export LOGS_BUCKET_NAME="<YOUR_PROJECT_ID>-bwg"
    GcsArtifactService menggunakan nama bucket kosong, tanpa awalan gs://. Seperti variabel lainnya, variabel ini ada di shell Anda, dan tugas deployment akan meneruskannya ke Cloud Run.
  3. Periksa isi bucket Anda. Di tab browser baru, buka URL berikut:
    https://console.cloud.google.com/storage/browser?project=<YOUR_PROJECT_ID>
    Klik bucket. Bergantung pada pengujian sebelumnya, galeri ini dapat berisi gambar yang dibuat sebelumnya.

9. Men-deploy agen Visual Director ke Cloud Run

Sejauh ini, semuanya berjalan di satu komputer, dengan Visual Director dapat diakses di localhost:8801. Dalam tugas ini, Anda akan men-deploy agen Visual Director sebagai layanan Cloud Run-nya sendiri dan membiarkan generator saran berbicara dengannya di seluruh jaringan menggunakan protokol Agent2Agent (A2A).

Direktur Visual mendapatkan URL https:// yang sebenarnya, sehingga _cloud_run_client yang Anda tulis sebelumnya mulai menandatangani permintaan, bukan menampilkan None. Selain itu, Cloud Run men-deploy secara pribadi secara default.

kedua agen sebagai layanan Cloud Run

Men-deploy Visual Director

  1. Hentikan layanan latar belakang lokal dan playground jika masih berjalan:
    fuser -k 8801/tcp 2>/dev/null || true
fuser -k 8000/tcp 2>/dev/null || true
  2. Deploy agen. Tindakan ini akan membangun dan mengirimkan container.⏰ Proses ini akan memerlukan waktu beberapa menit.
    cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/visual-director
source .env
agents-cli deploy \
  --service-name visual-director \
  --project <YOUR_PROJECT_ID> \
  --region <YOUR_REGION> \
  --no-confirm-project \
  --labels dev-tutorial=bwg001-devlab-1 \
  --update-env-vars "LOGS_BUCKET_NAME=$LOGS_BUCKET_NAME,GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_REGION=$GOOGLE_CLOUD_REGION"

Jalankan Pitch Generator yang menggunakan Visual Director yang di-deploy ke Cloud Run

  1. Baca URL Visual Director, lalu jalankan Pitch Generator yang menggunakannya:
    cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/pitch-generator
source .env
export VISUAL_DIRECTOR_URL=$(gcloud run services list \
  --project <YOUR_PROJECT_ID> \
  --region <YOUR_REGION> \
  --flatten='spec.template.spec.containers[0].env' \
  --filter='metadata.name=visual-director AND spec.template.spec.containers[0].env.name=APP_URL' \
  --format='value(spec.template.spec.containers[0].env.value)')
echo "Visual Director is at $VISUAL_DIRECTOR_URL"
APP_URL=http://localhost:8000 nohup uv run uvicorn pitch_generator.fast_api_app:app --port 8000 > /tmp/visual-pitch_generator.log 2>&1 &

Memanggil alur kerja yang di-deploy

Kedua agen mendukung protokol A2A. Repositori ini mengirimkan klien kecil untuk memanggil Pitch Generator melalui A2A.

PITCH_GENERATOR_URL harus disetel ke URL Pitch Generator yang berjalan secara lokal. Sementara itu, Visual Director berjalan di Cloud Run, dan Pitch Generator berkomunikasi dengannya melalui A2A.

  1. Salin klien ke project Anda, lalu jalankan:
    cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/pitch-generator
cp ../solution/pitch-generator/call_agent.py .
PITCH_GENERATOR_URL=http://localhost:8000 uv run python call_agent.py "Flying skateboards for cats" --save-image ./key_visual.png
    Karena alur kerja berisi Gerbang Persetujuan Manual, skrip akan dijeda setelah membuat konsep draf:
    === HUMAN APPROVAL REQUIRED ===

[DRAFT CONCEPT]
Concept Line: "Gravity is a Suggestion."
...

Please approve the campaign concept (yes/no):
    Ketik yes, lalu tekan Enter untuk menyetujui dan melanjutkan alur kerja. (Anda juga dapat meneruskan -y atau --auto-approve untuk menyetujui secara otomatis).
  2. Buka call_agent.py dan periksa cara berinteraksi dengan agen menggunakan a2a-sdk:
    • ClientFactory membangun penargetan Client A2A resmi https://SERVICE_URL/a2a/pitch_generator.
    • generate_pitch_async mengirim SendMessageRequest awal. Saat respons ditampilkan dengan TaskState.TASK_STATE_INPUT_REQUIRED, respons akan mendeteksi bagian adk_request_input, menampilkan konsep draf, mengumpulkan persetujuan Anda, dan mengirim permintaan melanjutkan yang membawa respons Anda kembali ke tugas.
    • Loop parsing membaca bagian CONCEPT, COPY, dan ART DIRECTION dari artefak tugas yang telah selesai, lalu menyimpan gambar biner ke key_visual.png.
    Anda akan melihat tiga bagian teks yang dicetak, dan gambar yang disimpan ke key_visual.png.
  3. Upload visual utama ke bucket Anda, di bawah awalan yang dapat dituju BigQuery:
    gcloud storage cp ./key_visual.png gs://<YOUR_PROJECT_ID>-bwg/key-visuals/cats.png
  4. Buat saran lagu kedua agar Anda memiliki sesuatu untuk dibandingkan, lalu upload juga:
    PITCH_GENERATOR_URL=http://localhost:8000 uv run python call_agent.py "A commuter bike built for rainy cities" --save-image ./bike.png
gcloud storage cp ./bike.png gs://<YOUR_PROJECT_ID>-bwg/key-visuals/bike.png

10. Memberi skor visual utama untuk kesesuaian merek di BigQuery

Sekarang Anda memiliki gambar dalam bucket dan pedoman merek yang seharusnya membentuknya. Dalam tugas ini, Anda akan menggabungkan keduanya: mereferensikan gambar dari BigQuery, lalu meminta model Gemini untuk menilai setiap gambar berdasarkan pedoman, tanpa memindahkan satu byte pun dari Cloud Storage.

Dua fitur BigQuery yang melakukan pekerjaan ini:

  • ObjectRef adalah nilai yang mengarah ke objek Cloud Storage. OBJ.MAKE_REF membangunnya dari URI ditambah koneksi yang memberikan akses yang didelegasikan BigQuery ke bucket. pitch-connection yang dibuat oleh skrip penyiapan adalah koneksi tersebut, dan sudah memiliki Storage Object Viewer dan Agent Platform User.
  • AI.SCORE menggunakan perintah dan menampilkan FLOAT64. Perintah dapat mencampurkan string dengan nilai ObjectRef, sehingga model melihat rubrik dan gambar Anda secara bersamaan.

BigQuery membaca bucket

Buat tabel visual utama

  1. Buka BigQuery Studio di tab browser baru:
    https://console.cloud.google.com/bigquery?project=<YOUR_PROJECT_ID>
  2. Klik Create new query (ikon +), lalu tempel dan Run yang berikut (ganti dan dengan project ID dan region Anda). Tabel ini membuat satu baris per visual utama, yang memadukan konsep kampanye dengan referensi ke gambar:
    SET @@location = '<YOUR_REGION>';

CREATE OR REPLACE TABLE bwg.key_visuals AS
SELECT
  campaign,
  concept,
  OBJ.FETCH_METADATA(
    OBJ.MAKE_REF(uri, '<YOUR_REGION>.pitch-connection')
  ) AS key_visual
FROM UNNEST([
  STRUCT(
    'cats' AS campaign,
    'Flying skateboards for cats' AS concept,
    'gs://<YOUR_PROJECT_ID>-bwg/key-visuals/cats.png' AS uri
  ),
  STRUCT(
    'bike',
    'A commuter bike built for rainy cities',
    'gs://<YOUR_PROJECT_ID>-bwg/key-visuals/bike.png'
  )
]);
    bqOBJ.MAKE_REF membangun referensi dari URI dan koneksi. OBJ.FETCH_METADATA kemudian menghubungi Cloud Storage dan mengisi ukuran, jenis konten, dan generasi objek. Panggilan kedua ini juga merupakan cara tercepat untuk membuktikan bahwa koneksi Anda berfungsi: jika izin salah, kolom details akan menampilkan error, bukan metadata.
  3. Periksa apa yang Anda simpan. Ganti kueri sebelumnya dengan kueri ini, lalu jalankan:
    SELECT campaign, concept, key_visual.uri, key_visual.details
FROM bwg.key_visuals;
    Tabel ini menyimpan penunjuk dan metadatanya, bukan gambar. Byte tidak pernah keluar dari bucket.

Beri nilai setiap gambar berdasarkan pedoman merek

Direktur Visual diperintahkan untuk mematuhi palet, aturan pencahayaan, dan aturan komposisi. Apakah sebenarnya dilakukan atau tidak adalah keputusan penilaian, dan itulah fungsi AI.SCORE.

  1. Jalankan kueri berikut (ganti dengan region Anda). Perintahnya adalah tuple: rubrik Anda, konsep kampanye, dan ObjectRef untuk gambar:
    SELECT
  campaign,
  concept,
  AI.SCORE(
    ('''You are the brand guardian reviewing a campaign key visual.
Score the attached image from 1 to 10 on how closely it follows these house rules:
- Palette: deep indigo and slate, with one warm accent of amber or terracotta. Nothing neon.
- Light: one dominant low, raking source with long shadows. No flat overhead light.
- Composition: subject off-center with generous empty negative space on the opposite side.
- Subject: one subject only, photographic realism, shallow depth of field.
- Never: text, logos, or watermarks anywhere in the frame.
A 10 obeys every rule. A 1 ignores them. The campaign concept is: ''',
      concept,
      key_visual),
    connection_id => '<YOUR_REGION>.pitch-connection',
    endpoint => 'gemini-3.5-flash'
  ) AS brand_fit
FROM bwg.key_visuals
ORDER BY brand_fit DESC;
  2. Ubah skor menjadi putusan yang dapat ditindaklanjuti tim Anda:
    CREATE OR REPLACE TABLE bwg.brand_review AS
SELECT
  campaign,
  concept,
  brand_fit,
  IF(brand_fit >= 7, 'on brand', 'needs another pass') AS verdict
FROM (
  SELECT
    campaign,
    concept,
    AI.SCORE(
      ('''Score this campaign key visual from 1 to 10 on how closely it follows the house
brand rules: deep indigo and slate palette with a single warm accent and nothing neon; one
low raking light source with long shadows; the subject off-center with empty negative space
opposite; a single photographic subject; and no text, logos, or watermarks in the frame.
The campaign concept is: ''',
          concept,
          key_visual),
      connection_id => '<YOUR_REGION>.pitch-connection',
      endpoint => 'gemini-3.5-flash'
    ) AS brand_fit
  FROM bwg.key_visuals
);

SELECT * FROM bwg.brand_review ORDER BY brand_fit DESC;
    AI.SCORE menampilkan FLOAT64 dan tidak ada yang lain, sehingga nilai minimum berada di SQL biasa yang dapat Anda sesuaikan tanpa mengubah perintah. Pemberian skor dilakukan per baris, yang berarti rubrik yang sama diterapkan ke setiap aset yang dihasilkan kampanye, bukan hanya dua aset yang Anda buat di sini.

11. Langkah berikutnya

Membuat Evaluasi

Evaluasi agentic atau "evaluasi" adalah pengujian otomatis yang digunakan untuk mengukur seberapa baik agen AI otonom menalar, merencanakan, menggunakan alat, dan menyelesaikan alur kerja multilangkah. Pengujian ini mirip dengan pengujian unit untuk agen, tetapi mempertimbangkan sifat non-deterministiknya.

Salah satu agen kami menyertakan Human in the loop, yang berarti agen tersebut menunggu input. Anda harus mengizinkan Antigravity melakukan modifikasi pada kode saat ini agar perilaku ini tidak menghalangi evaluasi otomatis.

Salah satu cara terbaik untuk memulai adalah dengan bertanya kepada Antigravity CLI.

Ketik perintah berikut ke Cloud Shell untuk memulai CLI:

cd ~/devrel-demos/codelabs/bwg-multi-agent-pitch-generator/
agy

Berikut perintah awal:

Explore this repository (`pitch-generator` and `visual-director`), including their agent instructions, tools, and `SKILL.md` files. Design and implement a creative `agents-cli eval` evaluation suite under `tests/eval/` that stress-tests the agent's behavior.

Anda juga dapat menemukan contoh evaluasi dan petunjuk untuk menjalankannya di repositori yang di-clone.

12. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini, hapus project (direkomendasikan) atau hapus setiap resource yang dibuat selama codelab:

gcloud run services delete visual-director --region=<YOUR_REGION> --project=<YOUR_PROJECT_ID> --quiet
bq rm -r -f -d <YOUR_PROJECT_ID>:bwg
bq rm --connection --location=<YOUR_REGION> --project_id=<YOUR_PROJECT_ID> pitch-connection
gcloud storage rm -r gs://<YOUR_PROJECT_ID>-bwg

13. Selamat!

Dalam codelab ini, Anda telah membuat generator saran kampanye multi-agen dengan Agent Development Kit. Anda menghubungkan tiga agen ke alur kerja grafik deterministik, mengemas pedoman merek sebagai kemampuan agen yang dimuat sesuai permintaan, dan memberi agen alat pembuatan gambar yang menyimpan outputnya sebagai artefak. Kemudian, Anda membagi Visual Director menjadi layanan A2A-nya sendiri, menyematkannya kembali ke grafik sebagai node jarak jauh, men-deploy-nya ke Cloud Run, dan memanggil seluruh alur kerja melalui A2A dari koordinator yang berjalan secara lokal. Terakhir, Anda mereferensikan visual utama yang dihasilkan dari BigQuery dengan ObjectRef dan menggunakan AI.SCORE untuk menilainya berdasarkan pedoman merek Anda sendiri.