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:
aggrega scaffold --example import-google-adkKemudian 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:
cd import-google-adk
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.jsonname: support_agentmodel: gemini-2.5-flashdescription: 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_searchImpor 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.aiImpor 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:
cd sourceMenjalankan impor
Sebutkan direktori agen. Impor membaca root_agent.yaml miliknya:
aggrega import support_agent --target composePada keluaran standar, impor mencantumkan apa yang ditulisnya:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonPada 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 appliedmapped support_agent (agent) to core/ai-agent/google-adk as a reference, NONEmapped gemini-2.5-flash (model) to core/ai-model/gemini as a reference, NONEmade no choice for google_search (tool)Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)
- Baris
infomenyebutkan jawaban yang tidak digunakan oleh draf Docker Compose, yang disimpan di file jawaban untuk build bagi Kubernetes. - Baris
mappedmenyatakan bahwa agen adalah instans dari agen ADK pustaka standar,core/ai-agent/google-adk, dan bahwa model yang disebutkannya adalah instans daricore/ai-model/gemini. Tingkatnya bertuliskanNONE: impor ADK merujuk Components ini berdasarkan apa yang disebutkan konfigurasi, bukan dengan menimbang masing-masing terhadap katalog. - Baris
made no choicemenyatakan bahwa alat Google Search tidak menjadi apa pun dalam draf: alat itu disertakan ADK dan berjalan di dalam aplikasi. - Baris
Pull completeadalah impor yang mengambil apa yang menjadi dependensi Release yang dirancang, seperti yang dilakukanaggrega pull, ke dalamrelease.lock, sehingga draf dapat langsung divalidasi dan di-build. Dengan--offline, impor tidak mengambil apa pun dan menyebutkan perintahaggrega pullyang 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/v1beta1kind: Aggregatemetadata: 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/v1beta1kind: Releasemetadata: 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/v1beta1kind: Manifestmetadata: name: imported/support-agent version: 0.1.0spec: mappings: components: type: core/ai-agent/google-adk: compose/google-adk core/ai-model/gemini: compose/gemini features: type: core/secret-value: compose/dotenv-secretrelease.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
aggrega validate --release release.yamlaggrega build --release release.yaml

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>/distBaris 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: - composeAplikasi 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-slimRUN pip install --no-cache-dir google-adk==2.13.0COPY 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:
docker build -t support-agent:local .aggrega import support_agent --syncaggrega build --release release.yamlKemudian atur kunci di shell Anda dan mulai stack:
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:
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:
docker compose -p support-agent -f dist/compose/docker-compose.yaml downDi 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:
aggrega import support_agent --target helm --output-dir helmcd helmaggrega build --release release.yamlBuild 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:
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000Dari 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.