Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Mengimpor agen Google ADK

Panduan langkah demi langkah ini mengimpor Agent Config dari sebuah aplikasi yang dibangun di atas Agent Development Kit (ADK) milik Google — satu agen yang menjawab pertanyaan pelanggan tentang pesanan mereka — dan membangun aplikasi tersebut untuk Docker Compose. Impor membuat draf setiap file yang dibaca build: agen dan model Gemini-nya, kunci yang diberikan agen kepada model sebagai referensi variabel, serta realisasi masing-masing. Impor menanyakan satu kali satu-satunya nilai yang tidak dimuat oleh konfigurasi mana pun, yaitu image tempat aplikasi berjalan. Setiap file dan setiap blok keluaran di bawah ini berasal dari eksekusi nyata; konfigurasi dan setiap tahap panduan ini ada dalam contoh import-google-adk, tempat skrip pemeriksa menjalankan impor lagi, membandingkan apa yang ditulisnya, apa yang dicetaknya, dan blok-blok yang dikutip halaman ini dengan file yang disimpan di sana, serta memvalidasi dan membangun apa yang ditulis impor.

Membuat contoh

Anda dapat menjalankan impor ini dengan perintah di halaman ini, atau meminta asisten AI Anda menjalankannya untuk Anda.

Tulis contoh ke folder baru yang dinamai sesuai contoh itu:

Terminal window
aggrega scaffold --example import-google-adk

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru; perintah sesudahnya, di bawah, berpindah ke folder source milik folder baru itu, yang berisi apa yang diimpor halaman ini dan merupakan tempat impor dijalankan:

Terminal window
cd import-google-adk

Folder source dari contoh hasil scaffold terbuka di Visual Studio Code, menampilkan konfigurasi agen: support_agent pada gemini-2.5-flash dengan alat google_search.

Proyek

ADK dapat mendeklarasikan agen-agen sebuah aplikasi dalam file Agent Config, bukan dalam kode: adk create --type=config menulis root_agent.yaml, konfigurasi agen akar, dan sebuah file lingkungan di sampingnya. Konfigurasi ini, yang ditulis untuk panduan ini, mendeklarasikan satu agen pada gemini-2.5-flash milik Gemini, dengan alat Google Search yang disertakan ADK:

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: support_agent
model: gemini-2.5-flash
description: Answers a customer's question about their order.
instruction: |
You answer customers' questions about their orders. When a customer asks
where a parcel is, search the web for the tracking page of the company
shipping it.
tools:
- name: google_search

Impor tidak pernah membaca file lingkungan, yang biasanya berisi kunci yang dikirim aplikasi ke Gemini, sehingga contoh ini tidak menyertakannya. Di akar proyek, sebuah .aggrega-config.yaml menjadikan folder tersebut ruang kerja:

# The workspace key marks this directory as the workspace root, so an import run
# here writes its drafts beside support_agent/.
workspace: {}
# The registry the importer is fetched from the first time an import needs it.
default_registry: hub.aggrega.ai

Impor merujuk Components agen ADK dan model Gemini dari katalog, dan --target menyusun draf Manifest dari Recipes katalog tersebut. Ruang kerja tidak menyebutkan folder katalog apa pun, jadi impor membaca katalog pustaka standar dari registry tempat impor mengambil importer-nya: snapshot bertanda tangan dari katalog yang diterbitkan, yang diambil, diverifikasi, dan disimpan di cache konten ruang kerja oleh impor pertama, serta disebutkan melalui digest-nya dalam catatan yang ditulis impor di samping draf-drafnya. Ruang kerja yang menyebutkan folder katalognya sendiri — di AGGREGA_CATALOG_DIRS, atau di bawah workspace.catalog_dirs — mengimpor terhadap folder-folder itu sebagai gantinya.

Apa yang ditanyakan impor

Agent Config menyebutkan model agen, tidak pernah image tempat aplikasi berjalan: Anda membangun image itu dari proyek Anda. Katalog tidak memuat image default untuk aplikasi yang dibangun di atas ADK, sehingga impor menanyakannya. Di terminal, impor bertanya dan menulis jawabannya ke dalam draf dan ke file jawaban, import-answers.yaml, di dalam direktori yang diimpornya, support_agent/, sehingga impor berikutnya membacanya dari sana dan tidak menanyakan apa pun. Tanpa terminal — dalam integrasi berkelanjutan, atau melalui pipe — impor tidak menanyakan apa pun: impor menulis file dengan kunci kosong, lalu berhenti sambil menyebutkan file tersebut. Contoh ini sudah memuat file tersebut, dengan image yang sudah dijawab, ghcr.io/example/support-agent:1.0.0, yang mewakili image yang Anda bangun:

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
release.yaml:
# Container image running the application built on ADK, serving its API on infra.port on every
# interface.
spec.components.support-agent.infra.image: "ghcr.io/example/support-agent:1.0.0"
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.support-agent.uses.model.gemini-2-5-flash.features.credential.infra.origin: "google-api-key"

Jawaban kedua ditujukan untuk build bagi Kubernetes, dengan --target helm: di sana agen membaca kunci API Gemini dari Kubernetes Secret, dan jawabannya adalah nama Secret tersebut, google-api-key, tidak pernah kuncinya. Build untuk Docker Compose membaca kunci dari shell Anda sebagai gantinya, sehingga impor ini tidak menggunakan jawaban tersebut. File jawaban impor menjelaskan file tersebut, pertanyaannya, dan aturan untuk jawaban sebuah rahasia.

aggrega import mencantumkan setiap flag yang diterima perintah ini, termasuk --answers, yang menyebutkan file jawaban yang disimpan di tempat lain.

Pindah ke source:

Terminal window
cd source

Menjalankan impor

Sebutkan direktori agen. Impor membaca root_agent.yaml miliknya:

Terminal window
aggrega import support_agent --target compose

Pada keluaran standar, impor mencantumkan apa yang ditulisnya:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Pada galat standar, dengan <workspace> mewakili folder tempat Anda menjalankannya:

[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]
read as the google-adk format, with drafted paths relative to <workspace>
info: the answers file <workspace>/support_agent/import-answers.yaml also answers spec.components.support-agent.uses.model.gemini-2-5-flash.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not applied
mapped support_agent (agent) to core/ai-agent/google-adk as a reference, NONE
mapped gemini-2.5-flash (model) to core/ai-model/gemini as a reference, NONE
made no choice for google_search (tool)
Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)

Impor yang dijalankan dari editor: Aggregate, Release, dan Manifest hasil draf muncul di samping konfigurasi agen, output Aggrega mencantumkan bagaimana agen dan modelnya dipetakan serta file yang ditulis, dan sebuah notifikasi menyatakan impor membuat draf 3 file, dikenali sebagai google-adk.

  • Baris info menyebutkan jawaban yang tidak digunakan oleh draf Docker Compose, yang disimpan di file jawaban untuk build bagi Kubernetes.
  • Baris mapped menyatakan bahwa agen adalah instans dari agen ADK pustaka standar, core/ai-agent/google-adk, dan bahwa model yang disebutkannya adalah instans dari core/ai-model/gemini. Tingkatnya bertuliskan NONE: impor ADK merujuk Components ini berdasarkan apa yang disebutkan konfigurasi, bukan dengan menimbang masing-masing terhadap katalog.
  • Baris made no choice menyatakan bahwa alat Google Search tidak menjadi apa pun dalam draf: alat itu disertakan ADK dan berjalan di dalam aplikasi.
  • Baris Pull complete adalah impor yang mengambil apa yang menjadi dependensi Release yang dirancang, seperti yang dilakukan aggrega pull, ke dalam release.lock, sehingga draf dapat langsung divalidasi dan di-build. Dengan --offline, impor tidak mengambil apa pun dan menyebutkan perintah aggrega pull yang perlu dijalankan.

Apa yang ditulisnya

Aggregate, Release, dan Manifest diberi nama imported/support-agent, berdasarkan name milik agen akar, support_agent, yang disingkat menjadi support-agent, di bawah namespace yang ditetapkan oleh pengaturan target_namespace milik pengimpor, yaitu imported kecuali Anda menetapkan yang lain (Pengaturan).

aggregate.yaml — agen, yang terhubung ke model dengan kunci yang disajikannya dideklarasikan pada koneksi, dan model itu, diawali dengan komentar yang menyatakan apa yang dibaca dan apa yang tidak:

# Google ADK agent configurations read:
# - root_agent.yaml
# Not read: the application's code, which defines the tools, callbacks and agents a configuration names by their code, nor the environment file ADK's scaffold writes beside root_agent.yaml; the application runs in the image the Release names for each instance, and loads its configurations itself.
# ADK states that its Agent Config is experimental. An agent's model is a Gemini model by default; ADK serves some other providers' models by name through classes of its own, such as claude-sonnet-4-5 and gpt-4o, and others through a LiteLLM model string.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-agent
version: 0.1.0
description: Draft Aggregate imported from a source in the google-adk format.
spec:
components:
# The agent tree of root_agent.yaml, served from its root agent support_agent.
# Tools ADK ships, which run inside the application, drafted as no Component: google_search.
support-agent:
type: core/ai-agent/google-adk
values:
description: "Answers a customer's question about their order."
uses:
model:
gemini-2-5-flash:
target: gemini-2-5-flash
# For the compose target, the lines below declare credential on gemini-2-5-flash: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
features:
credential:
type: core/secret-value
values:
key: GOOGLE_API_KEY
# The model gemini-2.5-flash.
gemini-2-5-flash:
type: core/ai-model/gemini
values:
model: "gemini-2.5-flash"

ADK menyajikan aplikasi dari agen akarnya, sehingga draf berisi satu instans per pohon agen, yang dinamai sesuai agen akarnya. instruction milik agen tidak dibawa: aplikasi membacanya dari konfigurasinya sendiri, yang ada di dalam image.

ADK menyajikan gemini-2.5-flash melalui kelas Gemini-nya, yang mengirim permintaannya ke Gemini API, sehingga draf menghubungkan model ke soket model milik agen, yang hanya menerima Gemini API. Gemini adalah layanan yang di-hosting, sehingga Component milik agen menolak koneksi ke sana yang tidak membawa kredensial; koneksi tersebut mendeklarasikan satu, di bawah kunci GOOGLE_API_KEY. Model yang disajikan ADK dengan cara lain apa pun — nama seperti gpt-4o yang disajikan ADK melalui kelasnya sendiri, atau string model LiteLLM seperti openai/gpt-4o — tidak dihubungkan ke apa pun: sebuah komentar di atas instans menyebutkannya, dan koneksinya diserahkan kepada Anda, seperti yang dijelaskan Menjadi apa pohon agen.

release.yaml — lingkungan, image, port yang dipublikasikan, dan asal kunci:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/support-agent
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the google-adk format.
spec:
aggregate: imported/support-agent
manifest: imported/support-agent
components:
support-agent:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on ADK, holding its configurations
image: "ghcr.io/example/support-agent:1.0.0"
# Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal.
published_port: 8000
uses:
model:
gemini-2-5-flash:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential support-agent presents to gemini-2-5-flash on its model connection (the source names no variable for it, so it is read from the one Google's Gemini API's client libraries read the API key from), read from the variable GOOGLE_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${GOOGLE_API_KEY}"
gemini-2-5-flash: {}

Lingkungan, development, adalah nilai bawaan yang ditulis impor karena tidak ada konfigurasi yang menyebutkannya; ubah nilai itu jika Release di-deploy ke tempat lain. Image adalah jawaban yang dibaca impor dari support_agent/import-answers.yaml. published_port adalah 8000, port tempat aplikasi mendengarkan, sehingga aplikasi menjawab di http://127.0.0.1:8000 di mesin Anda; seperti kata komentarnya, proses apa pun di mesin ini dapat menjangkaunya di sana dan tidak ada yang lain yang bisa, dan menghapus baris itu membuat aplikasi tetap hanya di jaringan stack. Konfigurasi tidak menyebutkan variabel untuk kunci tersebut, sehingga koneksi membacanya dari ${GOOGLE_API_KEY}, variabel yang dibaca oleh pustaka klien Gemini API, sebagai referensi variabel dan tidak pernah sebagai nilai.

manifest.yaml — Recipe Compose untuk setiap tipe, dan realisasi yang menulis referensi variabel kunci ke dalam file Compose apa adanya:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/support-agent
version: 0.1.0
spec:
mappings:
components:
type:
core/ai-agent/google-adk: compose/google-adk
core/ai-model/gemini: compose/gemini
features:
type:
core/secret-value: compose/dotenv-secret

release.lock mencatat entitas katalog tempat Release diselesaikan, berdasarkan digest, dan .aggrega-import.json adalah catatan tentang apa yang ditulis impor, yang dibaca oleh aggrega import --sync berikutnya.

Validasi dan build

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

Release draf yang terbuka di editor setelah divalidasi, dengan output Aggrega dan sebuah notifikasi yang sama-sama melaporkan tidak ada masalah yang ditemukan.

Build Release draf: folder dist muncul di Explorer, output Aggrega mencantumkan file Docker Compose yang ditulis, dan sebuah notifikasi menyatakan 1 file telah ditulis.

Validasi mencetak:

notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
release dependency validation passed: release.yaml (schema-pillar + dependency pillars)

dan build, dengan <workspace> mewakili folder tempat Anda menjalankannya:

notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 1 file written to <workspace>/dist

Baris notice hanya bersifat informatif: Feature rahasia menerima nilai origin miliknya dari values milik Aggregate atau infra milik Release, dan pemberitahuan itu melaporkan bahwa satu daun dideklarasikan di keduanya. Pemberitahuan ini tidak mengubah putusan apa pun.

Layanan agen di dist/compose/docker-compose.yaml:

services:
support-agent:
image: ghcr.io/example/support-agent:1.0.0
environment:
PORT: "8000"
GOOGLE_API_KEY: ${GOOGLE_API_KEY}
ports:
- 127.0.0.1:8000:8000
[… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version]
networks:
- compose

Aplikasi menerima port tempat servernya mendengarkan sebagai PORT, dan kunci sebagai GOOGLE_API_KEY, yang dikirim klien Gemini milik ADK ke API Gemini. Model tidak mendapat layanan tersendiri: klien mengirim permintaannya ke alamat API Gemini sendiri, dan tidak membaca alamat lain dari lingkungannya. Kunci adalah referensi variabel, yang diisi dari shell Anda saat stack dimulai. Recipe Compose milik agen ADK memublikasikan port di mesin Anda hanya jika Release menetapkan published_port di infra milik agen, dan itu pun hanya pada alamat loopback, 127.0.0.1; tanpa itu, layanan hanya dapat dijangkau di jaringan stack.

Dengan asisten AI

Asisten AI yang disiapkan dengan alat-alat Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke dalamnya.

Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder Workspace belum berisi folder `import-google-adk`, panggil alat `scaffold` sekali dengan `example` diatur ke `import-google-adk` dan tanpa `dir`: alat ini menulis contoh ke folder `import-google-adk` baru, yang folder `source`-nya berisi apa yang diimpor halaman ini. Lalu panggil alat `import` dengan `workspace_root` diatur ke `import-google-adk/source`, `source` diatur ke `support_agent`, dan `target` diatur ke `compose`: alat ini membaca jawaban yang dibutuhkannya dari `import-answers.yaml` di dalam folder `support_agent`, menulis drafnya ke `import-google-adk/source`, dan menarik apa yang dibutuhkan draf tersebut. Lalu panggil alat `validate` dengan `workspace_root` diatur ke `import-google-adk/source` dan `release` diatur ke `release.yaml`, serta alat `build` dengan `workspace_root` diatur ke `import-google-adk/source`, `release` diatur ke `release.yaml`, dan `write` diatur ke true. Beri tahu saya file mana saja yang ditulis build; file-file itu ada di bawah `import-google-adk/source/dist/`.

Membukanya di VS Code

Dengan ekstensi Aggrega untuk Visual Studio Code terpasang, buka folder import-google-adk/source di VS Code, tempat impor menulis drafnya. Folder itu berisi satu Release, release.yaml hasil draf, sehingga editor memilihnya untuk Anda, dan editor memeriksa draf terhadap Release tersebut saat Anda mengeditnya, menandai apa yang ditemukannya di file dan di panel Problems. Aggrega: Show topology graph, di Command Palette, menggambar komponen Release dan koneksi di antara komponen-komponen itu. Aggrega: Build, Aggrega: Preview build, dan Aggrega: Pull bekerja pada Release yang sama, dan masing-masing juga merupakan tombol di panel Commands pada tampilan Aggrega di activity bar; Build menulis file-filenya ke dist/ di folder itu. Menggunakan Aggrega di Visual Studio Code membahas sisanya.

Menjalankannya

Docker Compose menjalankan image Anda sebagai layanan yang dirender di atas, termasuk PORT. Image harus mendengarkan pada port tersebut di semua antarmuka, bukan di 127.0.0.1, alamat default server API ADK. Server API milik ADK sendiri, adk api_server, menyajikan direktori konfigurasi apa adanya, sehingga image tidak memerlukan kode buatan Anda. Sebuah Dockerfile di root proyek, di samping support_agent/:

FROM python:3.12-slim
RUN pip install --no-cache-dir google-adk==2.13.0
COPY support_agent/ /app/agents/support_agent/
CMD ["sh", "-c", "exec adk api_server --host 0.0.0.0 --port \"$PORT\" --auto_create_session /app/agents"]

adk api_server menyajikan direktori agen di dalam folder yang disebutkannya, dan perintah tersebut meneruskan PORT kepadanya. --auto_create_session membuka sesi saat pertama kali permintaan ke /run menyebutkannya, sehingga satu permintaan sudah mencapai agen. Build image tersebut, tulis namanya sebagai pengganti ghcr.io/example/support-agent:1.0.0 di support_agent/import-answers.yaml, lalu impor lagi dengan --sync, yang menulis jawaban baru ke dalam draf dan melakukan pull lagi; kemudian jalankan build:

Terminal window
docker build -t support-agent:local .
aggrega import support_agent --sync
aggrega build --release release.yaml

Kemudian atur kunci di shell Anda dan mulai stack:

Terminal window
export GOOGLE_API_KEY='your Gemini API key'
docker compose -p support-agent -f dist/compose/docker-compose.yaml up -d --wait

-p memberi nama proyek, seperti dijelaskan pada langkah menjalankan di Cara impor berjalan. --wait kembali segera setelah kontainer berjalan, karena build tidak memberi layanan pemeriksaan kesehatan apa pun, dan server baru menjawab sesaat kemudian, jadi ulangi permintaan yang ditolaknya.

Mengujinya

Kirim pesan ke agen di http://127.0.0.1:8000, alamat yang dipublikasikan published_port. Permintaan menyebutkan seorang pengguna dan sebuah sesi, dan /run membuka sesi itu pada pesan pertamanya:

Terminal window
curl -sS -X POST http://127.0.0.1:8000/run -H 'Content-Type: application/json' \
-d '{"app_name": "support_agent", "user_id": "u1", "session_id": "s1", "new_message": {"role": "user", "parts": [{"text": "Where is my order 1234? Answer in one short sentence."}]}}'

Balasan, dari Gemini, kembali sebagai daftar peristiwa yang ditambahkan giliran tersebut ke sesi. Eksekusi menggunakan placeholder untuk kunci, sehingga Gemini menolaknya: permintaan dijawab dengan HTTP 500, Internal Server Error, dan log layanan, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, menyebutkan alasannya:

google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'API key not valid. Please pass a valid API key.', 'status': 'INVALID_ARGUMENT', [… omitted: the error's details]}}

curl -sS http://127.0.0.1:8000/list-apps menjawab ["support_agent"], yaitu agen-agen yang dimuat server.

Hentikan stack dengan:

Terminal window
docker compose -p support-agent -f dist/compose/docker-compose.yaml down

Di Kubernetes

Agen yang sama diimpor untuk Kubernetes dengan --target helm. Sebuah klaster menarik image-nya dari registry, jadi push image yang Anda build ke registry yang dibaca klaster Anda, lalu tulis namanya sebagai pengganti image yang dijawab di support_agent/import-answers.yaml; eksekusi mem-push-nya ke registry di mesin klaster itu sendiri, sebagai localhost:5000/support-agent:1.0.0. Jawaban kedua di sana menyebutkan Secret tempat agen membaca kunci API Gemini, google-api-key. Draf untuk Docker Compose sudah berada di source, jadi buat draf ini di folder tersendiri, lalu build dari sana:

Terminal window
aggrega import support_agent --target helm --output-dir helm
cd helm
aggrega build --release release.yaml

Build menulis manifes Kubernetes biasa di bawah dist/helm/ di root workspace, source, yang dari helm adalah ../dist/helm/. Buat Secret google-api-key di namespace tempat Anda menerapkan, yang menyimpan kunci di bawah kunci data value, lalu terapkan folder tersebut seperti yang dijelaskan langkah eksekusi di Cara impor berjalan. Service agen adalah support-agent-default: teruskan port lokal ke sana, dan biarkan perintah tetap berjalan:

Terminal window
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000

Dari terminal lain, pesan di atas mencapai agen di alamat yang sama, tanpa perubahan. Eksekusi mendapatkan Internal Server Error yang sama, dan kubectl logs -n <namespace> deploy/support-agent menyebutkan penolakan yang sama terhadap kunci placeholder.