Bir Google ADK ajanını içe aktarma
Bu adım adım kılavuz, Google’ın Agent Development Kit (ADK) üzerine kurulmuş bir uygulamanın Agent Config’ini — müşterilerin siparişleriyle ilgili sorularını yanıtlayan tek bir ajan — içe aktarır ve uygulamayı Docker Compose için derler. İçe aktarma, derlemenin okuduğu her dosyanın taslağını oluşturur: ajan ve Gemini modeli, ajanın modele bir değişken başvurusu olarak sunduğu anahtar ve her birinin gerçekleştirmeleri. Hiçbir yapılandırmanın içermediği tek değeri, yani uygulamanın içinde çalıştığı imajı bir kez sorar. Aşağıdaki her dosya ve her çıktı bloğu gerçek bir çalıştırmadan gelir; yapılandırma ve kılavuzun her aşaması import-google-adk örneğinde yer alır; orada bir denetim betiği içe aktarmayı yeniden çalıştırır, yazdıklarını, yazdırdıklarını ve bu sayfanın alıntıladığı blokları orada tutulan dosyalarla karşılaştırır ve içe aktarmanın yazdıklarını doğrulayıp derler.
Örneği oluşturun
Bu içe aktarmayı bu sayfadaki komutlarla çalıştırabilir ya da yapay zekâ asistanınıza sizin için çalıştırtabilirsiniz.
Örneği, adını taşıyan yeni bir klasöre yazın:
aggrega scaffold --example import-google-adkArdından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer; ondan sonraki, aşağıda, yeni klasörün içindeki, bu sayfanın içe aktardıklarını barındıran ve içe aktarmanın çalıştığı yer olan source klasörüne geçer:
cd import-google-adk
Proje
ADK, bir uygulamanın ajanlarını kod yerine Agent Config dosyalarında bildirebilir: adk create --type=config, kök ajanın yapılandırması olan root_agent.yaml dosyasını ve yanında bir ortam dosyasını yazar. Bu kılavuz için yazılan bu yapılandırma, Gemini’nin gemini-2.5-flash modeli üzerinde, ADK ile birlikte gelen Google Search aracına sahip tek bir ajan bildirir:
# 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_searchİçe aktarma, genellikle uygulamanın Gemini’ye gönderdiği anahtarı içeren ortam dosyasını hiçbir zaman okumaz; bu nedenle örnekte böyle bir dosya yoktur. Projenin kökünde bir .aggrega-config.yaml, klasörü bir çalışma alanı yapar:
# 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İçe aktarma, kataloğun ADK ajanı ve Gemini modeli Components’ine başvurur ve --target kataloğun Recipes’inden bir Manifest taslağı oluşturur. Çalışma alanı hiçbir katalog klasörü belirtmediği için içe aktarma, standart kütüphane kataloğunu içe aktarıcısını getirdiği kayıt defterinden okur. Bu, yayımlanmış kataloğun imzalı bir anlık görüntüsüdür: ilk içe aktarma onu getirir, doğrular ve çalışma alanının içerik önbelleğinde tutar; içe aktarmanın taslaklarının yanına yazdığı kayıt da onu özetiyle adlandırır. Kendi katalog klasörlerini AGGREGA_CATALOG_DIRS içinde veya workspace.catalog_dirs altında belirten bir çalışma alanı ise bunun yerine bunlara göre içe aktarır.
İçe aktarmanın sordukları
Bir Agent Config ajanın modelini adlandırır, uygulamanın içinde çalıştığı imajı asla adlandırmaz: o imajı kendi projenizden derlersiniz. Katalog, ADK üzerine kurulmuş bir uygulama için varsayılan bir imaj içermez; bu nedenle içe aktarma onu sorar. Bir terminalde sorar ve yanıtı taslaklara ve içe aktardığı support_agent/ dizinindeki yanıt dosyası import-answers.yaml’a yazar; böylece bir sonraki içe aktarma yanıtı oradan okur ve hiçbir şey sormaz. Terminal yoksa — sürekli entegrasyonda veya bir boru üzerinden — hiçbir şey sormaz: dosyayı anahtarı boş olarak yazar ve dosyayı adlandırarak durur. Örnek, imajın yanıtlandığı dosyayı zaten içerir; ghcr.io/example/support-agent:1.0.0, derlediğiniz imajın yerini tutar:
# 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"İkinci yanıt, --target helm ile Kubernetes için yapılan bir derleme içindir: orada ajan Gemini API anahtarını bir Kubernetes Secret’ından okur ve yanıt anahtarın kendisi değil, Secret’ın adı olan google-api-key’dir. Docker Compose için yapılan bir derleme ise anahtarı kabuğunuzdan okur; bu nedenle bu içe aktarma o yanıtı kullanmaz. İçe aktarma yanıt dosyası, dosyayı, soruları ve bir gizli bilginin yanıtına ilişkin kuralları açıklar.
aggrega import, komutun aldığı her bayrağı listeler; bunlar arasında başka bir yerde tutulan bir yanıtlar dosyasını adlandıran --answers da vardır.
source klasörüne geçin:
cd sourceİçe aktarmayı çalıştırma
Ajanın dizinini belirtin. İçe aktarma, onun root_agent.yaml dosyasını okur:
aggrega import support_agent --target composeStandart çıktıda yazdıklarını listeler:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonStandart hatada, <workspace> onu çalıştırdığınız klasörü temsil edecek şekilde:
[… 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)
infosatırı, Docker Compose taslaklarının kullanmadığı ve Kubernetes için bir derlemeye yönelik olarak yanıtlar dosyasında tutulan yanıtı adlandırır.mappedsatırları, ajanın standart kütüphanenin ADK ajanı olancore/ai-agent/google-adkbileşeninin bir örneği olduğunu ve adlandırdığı modelincore/ai-model/geminibileşeninin bir örneği olduğunu söyler. KademeleriNONEgösterir: ADK içe aktarması bu Components’e, her birini katalogla karşılaştırarak değil, yapılandırmanın adlandırdığı şeye göre başvurur.made no choicesatırı, Google Search aracının taslakta hiçbir şeye dönüşmediğini söyler: bu, ADK ile birlikte gelen bir araçtır ve uygulamanın içinde çalışır.Pull completesatırı, içe aktarmanın taslağı oluşturulan Release’in bağlı olduğu şeyleriaggrega pullgibirelease.lockiçine getirmesidir; böylece taslaklar hemen doğrulanır ve derlenir.--offlineile içe aktarma hiçbir şey çekmez ve çalıştırılacakaggrega pullkomutunu belirtir.
Ne yazar
Aggregate, Release ve Manifest, kök ajanın name değeri olan support_agent değerinin support-agent biçimine indirgenmesiyle imported/support-agent olarak adlandırılır ve içe aktarıcının target_namespace ayarının belirlediği ad alanı altında yer alır; bu ad alanı, başka birini ayarlamadığınız sürece imported olur (Ayarlar).
aggregate.yaml — sunduğu anahtar bağlantı üzerinde bildirilmiş olarak modele bağlanan ajan ve model; neyin okunduğunu ve neyin okunmadığını söyleyen yorumlarla başlar:
# 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 bir uygulamayı kök ajanından sunar; bu nedenle taslak, her ajan ağacı için kök ajanının adını taşıyan bir örnek içerir. Ajanın instruction alanı taşınmaz: uygulama onu, imajın içerdiği kendi yapılandırmasından okur.
ADK, gemini-2.5-flash modelini isteklerini Gemini API’sine gönderen Gemini sınıfı üzerinden sunar; bu yüzden taslak modeli, ajanın yalnızca Gemini API’sini kabul eden model soketine bağlar. Gemini barındırılan bir hizmettir; bu yüzden ajanın Component’i, ona giden ve hiçbir kimlik bilgisi taşımayan bir bağlantıyı reddeder; bağlantı, GOOGLE_API_KEY anahtarı altında bir kimlik bilgisi bildirir. ADK’nın başka herhangi bir yolla sunduğu bir model — ADK’nın kendine ait bir sınıf üzerinden sunduğu gpt-4o gibi bir ad ya da openai/gpt-4o gibi bir LiteLLM model dizesi — hiçbir şeye bağlanmaz: örnek nesnenin üstündeki bir yorum onu adlandırır ve bağlantı, Bir ajan ağacı neye dönüşür bölümünün açıkladığı gibi size bırakılır.
release.yaml — ortam, imaj, yayımlanan bağlantı noktası ve anahtarın nereden geldiği:
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: {}Ortam, development, hiçbir yapılandırma bir ortam adlandırmadığı için içe aktarmanın yazdığı bir varsayılandır; Release başka bir yere dağıtılıyorsa onu değiştirin. İmaj, içe aktarmanın support_agent/import-answers.yaml dosyasından okuduğu yanıttır. published_port, uygulamanın dinlediği bağlantı noktası olan 8000’dir; bu nedenle uygulama makinenizde http://127.0.0.1:8000 adresinde yanıt verir; yorumunun dediği gibi bu makinedeki her süreç ona oradan ulaşabilir ve başka hiçbir şey ulaşamaz; satırı silmek uygulamayı yalnızca yığının ağında tutar. Yapılandırma anahtar için hiçbir değişken adlandırmaz; bu yüzden bağlantı onu, Gemini API’sinin istemci kitaplıklarının okuduğu değişken olan ${GOOGLE_API_KEY} üzerinden, asla bir değer olarak değil, bir değişken başvurusu olarak okur.
manifest.yaml — her türün Compose Recipe’si ve anahtarın değişken başvurusunu Compose dosyasına yazıldığı gibi yazan gerçekleştirme:
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, Release’in çözümlendiği katalog varlıklarını özetleriyle (digest) kaydeder; .aggrega-import.json ise içe aktarmanın yazdıklarının kaydıdır ve sonraki bir aggrega import --sync onu okur.
Doğrulama ve derleme
aggrega validate --release release.yamlaggrega build --release release.yaml

Doğrulama şunu yazdırır:
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)ve derleme; burada <workspace>, onu çalıştırdığınız klasörü temsil eder:
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>/distnotice satırı yalnızca bilgilendirme amaçlıdır: gizli bilgi Feature’ı kendi origin değerini Aggregate’in values alanından ya da Release’in infra alanından kabul eder ve bildirim, bir yaprağın ikisinde de bildirildiğini raporlar. Hiçbir kararı değiştirmez.
dist/compose/docker-compose.yaml içindeki ajan hizmeti:
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: - composeUygulama, sunucusunun dinlediği bağlantı noktasını PORT olarak, anahtarı ise ADK’nin Gemini istemcisinin Gemini API’sine gönderdiği GOOGLE_API_KEY olarak alır. Model kendine ait bir hizmet almaz: istemci isteklerini Gemini API’sinin kendi adresine gönderir ve ortamından başka bir adres okumaz. Anahtar, yığın başladığında kabuğunuzdan doldurulan bir değişken başvurusudur. ADK ajanının Compose Recipe’i makinenizde yalnızca Release, ajanın infra alanında published_port ayarladığında bir bağlantı noktası yayımlar ve o durumda da yalnızca geri döngü adresi 127.0.0.1 üzerinde; bu ayar olmadan hizmete yalnızca yığının ağı üzerinden ulaşılır.
Bir yapay zekâ asistanıyla
Aggrega’nın araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.
Yalnızca Aggrega araçlarını kullanın ve kendiniz hiçbir klasör oluşturmayın. Workspace klasöründe henüz bir `import-google-adk` klasörü yoksa, `example` değeri `import-google-adk` olarak ayarlanmış ve `dir` olmadan `scaffold` aracını bir kez çağırın: araç örneği yeni bir `import-google-adk` klasörüne yazar; bu klasörün `source` klasörü bu sayfanın içe aktardıklarını içerir. Ardından `workspace_root` değeri `import-google-adk/source`, `source` değeri `support_agent` ve `target` değeri `compose` olarak ayarlanmış şekilde `import` aracını çağırın: araç ihtiyaç duyduğu yanıtları `support_agent` klasörünün içindeki `import-answers.yaml` dosyasından okur, taslaklarını `import-google-adk/source` içine yazar ve taslakların ihtiyaç duyduklarını çeker. Ardından `workspace_root` değeri `import-google-adk/source` ve `release` değeri `release.yaml` olarak ayarlanmış şekilde `validate` aracını, `workspace_root` değeri `import-google-adk/source`, `release` değeri `release.yaml` ve `write` değeri true olarak ayarlanmış şekilde `build` aracını çağırın. Derlemenin hangi dosyaları yazdığını bana söyleyin; bunlar `import-google-adk/source/dist/` altındadır.VS Code’da açın
Visual Studio Code için Aggrega uzantısı yüklüyken, içe aktarmanın taslaklarını yazdığı import-google-adk/source klasörünü VS Code’da açın. Klasörde tek bir Release, yani taslak release.yaml bulunur; bu nedenle düzenleyici onu sizin için seçer ve taslakları siz düzenlerken o Release’e göre denetler, bulduklarını dosyada ve Sorunlar panelinde işaretler. Komut Paleti’ndeki Aggrega: Show topology graph, Release’in bileşenlerini ve aralarındaki bağlantıları çizer. Aggrega: Build, Aggrega: Preview build ve Aggrega: Pull aynı Release üzerinde çalışır ve her biri etkinlik çubuğundaki Aggrega görünümünün Commands panelinde bir düğme olarak da bulunur; Build dosyalarını klasörün dist/ dizinine yazar. Aggrega’yı Visual Studio Code’da kullanma gerisini anlatır.
Çalıştırın
Docker Compose, imajınızı PORT dahil olmak üzere yukarıda oluşturulan hizmet olarak çalıştırır. İmaj, ADK’nın API sunucusunun varsayılan adresi olan 127.0.0.1 üzerinde değil, tüm arabirimlerde bu bağlantı noktasını dinlemelidir. ADK’nın kendi API sunucusu adk api_server, yapılandırma dizinini olduğu gibi sunar; bu nedenle imaj sizin yazdığınız herhangi bir koda ihtiyaç duymaz. Projenin kökünde, support_agent/ dizininin yanında bir Dockerfile:
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, belirttiği klasördeki ajan dizinlerini sunar ve komut ona PORT değerini aktarır. --auto_create_session, /run adresine gelen bir istek bir oturumu ilk kez adlandırdığında o oturumu açar; böylece tek bir istek ajana ulaşır. İmajı derleyin, adını support_agent/import-answers.yaml içinde ghcr.io/example/support-agent:1.0.0 yerine yazın ve yeni yanıtı taslaklara yazıp yeniden çeken --sync ile yeniden içe aktarın; ardından derleyin:
docker build -t support-agent:local .aggrega import support_agent --syncaggrega build --release release.yamlArdından anahtarı kabuğunuzda ayarlayın ve stack’i başlatın:
export GOOGLE_API_KEY='your Gemini API key'docker compose -p support-agent -f dist/compose/docker-compose.yaml up -d --wait-p, Bir içe aktarma nasıl çalışır bölümünün çalıştırma adımında açıklandığı gibi projeyi adlandırır. Derleme hizmete bir sağlık denetimi vermediğinden --wait kapsayıcı çalışır çalışmaz döner ve sunucu biraz sonra yanıt verir; bu nedenle sunucunun reddettiği bir isteği yineleyin.
Test edin
Ajana, published_port değerinin yayımladığı adres olan http://127.0.0.1:8000 üzerinden bir mesaj gönderin. İstek bir kullanıcı ve bir oturum belirtir ve /run, oturumu ilk mesajında açar:
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."}]}}'Yanıt, yani Gemini’nin yanıtı, turun oturuma eklediği olayların listesi olarak döner. Çalıştırma anahtar için bir yer tutucu kullandı, bu yüzden Gemini onu reddetti: istek HTTP 500, Internal Server Error ile yanıt verdi ve hizmetin günlüğü, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, nedeni belirtir:
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, sunucunun barındırdığı ajanları, yani ["support_agent"] yanıtını döndürür.
Stack’i şu komutla durdurun:
docker compose -p support-agent -f dist/compose/docker-compose.yaml downKubernetes üzerinde
Aynı ajan, --target helm ile Kubernetes için içe aktarılır. Bir küme imajlarını bir kayıt defterinden çeker; bu nedenle derlediğiniz imajı kümenizin okuduğu bir kayıt defterine gönderin ve support_agent/import-answers.yaml içinde yanıt olarak verilen imajın yerine onun adını yazın; çalıştırma imajı, kümenin kendi makinesindeki bir kayıt defterine localhost:5000/support-agent:1.0.0 olarak gönderdi. Oradaki ikinci yanıt, ajanın Gemini API anahtarını okuduğu Secret’ı, yani google-api-key değerini belirtir. Docker Compose taslakları zaten source içinde bulunduğundan, bunları ayrı bir klasöre taslak olarak oluşturun ve oradan derleyin:
aggrega import support_agent --target helm --output-dir helmcd helmaggrega build --release release.yamlDerleme, düz Kubernetes manifestolarını çalışma alanı kökü olan source içindeki dist/helm/ altına yazar; bu, helm klasöründen bakıldığında ../dist/helm/ olur. Uyguladığınız ad alanında google-api-key Secret’ını, anahtarı value veri anahtarı altında tutacak şekilde oluşturun ve klasörü Bir içe aktarma nasıl çalışır sayfasının çalıştırma adımının açıkladığı gibi uygulayın. Ajanın Service’i support-agent-default şeklindedir: ona yerel bir bağlantı noktası yönlendirin ve komutu çalışır durumda bırakın:
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000Başka bir terminalden, yukarıdaki mesaj ajana aynı adreste, değişmeden ulaşır. Çalıştırma aynı Internal Server Error yanıtını aldı ve kubectl logs -n <namespace> deploy/support-agent, yer tutucu anahtarın aynı şekilde reddedildiğini belirtir.