Nhập một tác tử Google ADK
Hướng dẫn từng bước này nhập Agent Config của một ứng dụng được xây dựng trên Agent Development Kit (ADK) của Google — một tác tử trả lời câu hỏi của khách hàng về đơn hàng của họ — và build ứng dụng cho Docker Compose. Quá trình nhập soạn nháp mọi tệp mà bản build đọc: tác tử và mô hình Gemini của nó, khóa mà tác tử trình cho mô hình dưới dạng một tham chiếu biến, và các hiện thực của từng thứ. Nó hỏi một lần duy nhất giá trị duy nhất mà không cấu hình nào chứa, đó là image mà ứng dụng chạy trong đó. Mọi tệp và mọi khối đầu ra bên dưới đều đến từ một lần chạy thật; cấu hình và từng giai đoạn của hướng dẫn nằm trong ví dụ import-google-adk, nơi một script kiểm tra chạy lại quá trình nhập, so sánh những gì nó ghi, những gì nó in ra và các khối mà trang này trích dẫn với các tệp được lưu ở đó, rồi xác thực và build những gì quá trình nhập đã ghi.
Tạo ví dụ
Bạn có thể chạy lần nhập này bằng các lệnh trên trang này, hoặc để trợ lý AI của bạn chạy giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example import-google-adkSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới; lệnh tiếp sau đó, ở bên dưới, chuyển vào thư mục source của thư mục mới, nơi chứa những gì trang này nhập và là nơi chạy lệnh nhập:
cd import-google-adk
Dự án
ADK có thể khai báo các tác tử của một ứng dụng trong các tệp Agent Config thay vì trong mã: adk create --type=config ghi root_agent.yaml, cấu hình của tác tử gốc, và một tệp môi trường bên cạnh. Tệp này, được viết cho hướng dẫn này, khai báo một tác tử trên gemini-2.5-flash của Gemini, với công cụ Google Search đi kèm 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_searchQuá trình nhập không bao giờ đọc tệp môi trường, vốn thường chứa khóa mà ứng dụng gửi tới Gemini, vì vậy ví dụ không có tệp nào như vậy. Tại thư mục gốc của dự án, một .aggrega-config.yaml biến thư mục thành một không gian làm việc:
# 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.aiQuá trình nhập tham chiếu các Components tác tử ADK và mô hình Gemini của danh mục, và --target soạn nháp một Manifest từ các Recipes của danh mục đó. Không gian làm việc không chỉ định thư mục danh mục nào, vì vậy quá trình nhập đọc danh mục thư viện chuẩn từ registry mà từ đó nó tải trình nhập của mình về: một bản chụp nhanh có chữ ký của danh mục đã phát hành, được lần nhập đầu tiên tải về, xác minh và lưu trong bộ nhớ đệm nội dung của không gian làm việc, và được nêu tên theo digest của nó trong bản ghi mà quá trình nhập ghi bên cạnh các bản nháp. Một không gian làm việc chỉ định các thư mục danh mục riêng — trong AGGREGA_CATALOG_DIRS, hoặc dưới workspace.catalog_dirs — thì thay vào đó nhập dựa trên các thư mục đó.
Quá trình nhập hỏi những gì
Một Agent Config nêu tên mô hình của tác tử, không bao giờ nêu image mà ứng dụng chạy trong đó: bạn build image đó từ dự án của mình. Danh mục không có image mặc định nào cho một ứng dụng xây dựng trên ADK, vì vậy quá trình nhập hỏi nó. Tại một terminal, nó hỏi và ghi câu trả lời vào các bản nháp và vào tệp câu trả lời, import-answers.yaml, bên trong thư mục mà nó nhập, support_agent/, để lần nhập tiếp theo đọc câu trả lời từ đó và không hỏi gì. Khi không có terminal — trong tích hợp liên tục, hoặc qua một pipe — nó không hỏi gì: nó ghi tệp với khóa để trống, rồi dừng lại, nêu tên tệp. Ví dụ đã có sẵn tệp này, với image đã được trả lời, ghcr.io/example/support-agent:1.0.0, đại diện cho image mà bạn build:
# 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"Câu trả lời thứ hai dành cho một bản build cho Kubernetes, với --target helm: ở đó tác tử đọc khóa API Gemini từ một Secret của Kubernetes, và câu trả lời là tên của Secret, google-api-key, không bao giờ là khóa. Một bản build cho Docker Compose thì đọc khóa từ shell của bạn, vì vậy lần nhập này không dùng câu trả lời đó. Tệp câu trả lời của quá trình nhập mô tả tệp, các câu hỏi và các quy tắc cho câu trả lời của một bí mật.
aggrega import liệt kê mọi cờ mà lệnh nhận, trong đó có --answers, cờ nêu tên một tệp câu trả lời được lưu ở nơi khác.
Chuyển vào source:
cd sourceChạy lệnh nhập
Chỉ định thư mục của tác tử. Quá trình nhập đọc root_agent.yaml của nó:
aggrega import support_agent --target composeTrên đầu ra chuẩn, nó liệt kê những gì đã ghi:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonTrên luồng lỗi chuẩn, với <workspace> đại diện cho thư mục nơi bạn đã chạy nó:
[… 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)
- Dòng
infonêu tên câu trả lời mà các bản nháp Docker Compose không dùng, được giữ trong tệp câu trả lời cho một bản dựng cho Kubernetes. - Các dòng
mappedcho biết tác tử là một thể hiện của tác tử ADK trong thư viện chuẩn,core/ai-agent/google-adk, và mô hình mà nó nêu tên là một thể hiện củacore/ai-model/gemini. Bậc của chúng ghiNONE: quá trình nhập ADK tham chiếu các Components này theo những gì cấu hình nêu tên, thay vì đối chiếu từng cái với danh mục. - Dòng
made no choicecho biết công cụ Google Search không được soạn nháp thành gì cả: đó là một công cụ đi kèm ADK, và nó chạy bên trong ứng dụng. - Dòng
Pull completelà quá trình nhập đang tải những gì mà Release bản nháp phụ thuộc vào, nhưaggrega pulllàm, vàorelease.lock, để các bản nháp được xác thực và build ngay lập tức. Với--offline, quá trình nhập không tải gì và nêu lệnhaggrega pullcần chạy.
Những gì được ghi
Aggregate, Release và Manifest được đặt tên imported/support-agent, theo name của tác tử gốc, support_agent, rút gọn thành support-agent, dưới namespace mà thiết lập target_namespace của trình nhập đặt ra, là imported trừ khi bạn đặt namespace khác (Thiết lập).
aggregate.yaml — tác tử, được nối với mô hình với khóa mà nó xuất trình được khai báo trên kết nối, và mô hình, mở đầu bằng các chú thích cho biết những gì đã được đọc và những gì không:
# 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 phục vụ một ứng dụng từ tác tử gốc của nó, vì vậy bản nháp chứa một thể hiện cho mỗi cây tác tử, được đặt tên theo tác tử gốc. instruction của tác tử không được mang theo: ứng dụng đọc nó từ cấu hình riêng của mình, nằm trong image.
ADK phục vụ gemini-2.5-flash thông qua lớp Gemini của nó, lớp này gửi các yêu cầu tới Gemini API, vì vậy bản nháp nối mô hình vào socket model của agent, socket chỉ chấp nhận Gemini API. Gemini là một dịch vụ được lưu trữ, vì vậy Component của agent từ chối một kết nối tới nó mà không mang thông tin xác thực nào; kết nối khai báo một thông tin xác thực, dưới khóa GOOGLE_API_KEY. Một mô hình mà ADK phục vụ theo bất kỳ cách nào khác — một tên như gpt-4o mà ADK phục vụ qua một lớp riêng, hoặc một chuỗi mô hình LiteLLM như openai/gpt-4o — không được nối với gì cả: một chú thích phía trên instance nêu tên nó, và việc kết nối được để lại cho bạn, như Một cây agent trở thành gì mô tả.
release.yaml — môi trường, image, cổng được công bố và nguồn của khóa:
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: {}Môi trường, development, là giá trị mặc định mà quá trình nhập ghi ra vì không cấu hình nào nêu tên một môi trường; hãy thay đổi nó khi Release được triển khai ở nơi khác. Image là câu trả lời mà quá trình nhập đã đọc từ support_agent/import-answers.yaml. published_port là 8000, cổng mà ứng dụng lắng nghe, nên ứng dụng trả lời tại http://127.0.0.1:8000 trên máy của bạn; như chú thích của nó cho biết, mọi tiến trình trên máy này đều có thể truy cập nó ở đó và không gì khác có thể, và xóa dòng đó sẽ giữ ứng dụng chỉ trên mạng của stack. Cấu hình không nêu tên biến nào cho khóa, vì vậy kết nối đọc nó từ ${GOOGLE_API_KEY}, biến mà các thư viện máy khách của Gemini API đọc, dưới dạng tham chiếu biến và không bao giờ là một giá trị.
manifest.yaml — Recipe Compose của mỗi loại, và phần hiện thực hóa ghi tham chiếu biến của khóa vào tệp Compose đúng như đã viết:
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 ghi lại, theo digest, các thực thể danh mục mà Release đã được phân giải tới, và .aggrega-import.json là bản ghi về những gì quá trình nhập đã ghi, được một lệnh aggrega import --sync sau đó đọc.
Xác thực và dựng
aggrega validate --release release.yamlaggrega build --release release.yaml

Bước xác thực in ra:
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)và bản dựng, với <workspace> đại diện cho thư mục mà bạn đã chạy nó:
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>/distDòng notice chỉ mang tính tham khảo: Feature bí mật chấp nhận origin của nó từ values của Aggregate hoặc infra của Release, và thông báo cho biết có một lá được khai báo ở cả hai. Nó không thay đổi phán quyết nào.
Dịch vụ của agent trong 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Ứng dụng nhận cổng mà máy chủ của nó lắng nghe dưới dạng PORT, và khóa dưới dạng GOOGLE_API_KEY, mà client Gemini của ADK gửi tới Gemini API. Mô hình không có dịch vụ riêng: client gửi các yêu cầu tới chính địa chỉ của Gemini API, và không đọc địa chỉ nào khác từ môi trường của nó. Khóa là một tham chiếu biến, được điền từ shell của bạn khi stack khởi động. Recipe Compose của agent ADK chỉ công bố một cổng trên máy của bạn khi Release đặt published_port trong infra của agent, và khi đó chỉ trên địa chỉ loopback, 127.0.0.1; nếu không có thiết lập này, dịch vụ chỉ truy cập được trên mạng của stack.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega có thể làm điều tương tự: dán prompt này vào nó.
Chỉ sử dụng các công cụ Aggrega và không tự tạo thư mục nào. Nếu thư mục Workspace chưa có thư mục `import-google-adk`, hãy gọi công cụ `scaffold` một lần với `example` được đặt thành `import-google-adk` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `import-google-adk` mới, trong đó thư mục `source` chứa những gì trang này nhập. Sau đó gọi công cụ `import` với `workspace_root` được đặt thành `import-google-adk/source`, `source` được đặt thành `support_agent` và `target` được đặt thành `compose`: công cụ này đọc các câu trả lời cần thiết từ `import-answers.yaml` bên trong thư mục `support_agent`, ghi các bản nháp vào `import-google-adk/source` và pull những gì chúng cần. Sau đó gọi công cụ `validate` với `workspace_root` được đặt thành `import-google-adk/source` và `release` được đặt thành `release.yaml`, và công cụ `build` với `workspace_root` được đặt thành `import-google-adk/source`, `release` được đặt thành `release.yaml` và `write` được đặt thành true. Hãy cho tôi biết bản build đã ghi những tệp nào; chúng nằm trong `import-google-adk/source/dist/`.Mở trong VS Code
Khi đã cài đặt tiện ích mở rộng Aggrega cho Visual Studio Code, hãy mở thư mục import-google-adk/source trong VS Code, nơi quá trình nhập đã ghi các bản nháp. Thư mục chứa một Release, tệp release.yaml bản nháp, nên trình soạn thảo chọn nó cho bạn và kiểm tra các bản nháp theo Release đó khi bạn chỉnh sửa, đánh dấu những gì nó tìm thấy trong tệp và trong bảng Problems. Aggrega: Show topology graph, trong Command Palette, vẽ các thành phần của Release và các kết nối giữa chúng. Aggrega: Build, Aggrega: Preview build và Aggrega: Pull tác động lên cùng Release đó, và mỗi lệnh cũng là một nút trên bảng Commands của chế độ xem Aggrega trong thanh hoạt động; Build ghi các tệp của nó vào dist/ của thư mục. Sử dụng Aggrega trong Visual Studio Code trình bày phần còn lại.
Chạy thử
Docker Compose chạy image của bạn như dịch vụ đã được kết xuất ở trên, bao gồm cả PORT. Image phải lắng nghe trên cổng đó ở mọi giao diện mạng, không phải trên 127.0.0.1, địa chỉ mặc định của máy chủ API của ADK. Máy chủ API của chính ADK, adk api_server, phục vụ thư mục cấu hình nguyên trạng, nên image không cần mã nào của bạn. Một Dockerfile ở thư mục gốc của dự án, bên cạnh 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 phục vụ các thư mục agent trong thư mục mà nó chỉ định, và lệnh truyền PORT cho nó. --auto_create_session mở một phiên vào lần đầu tiên một yêu cầu tới /run nêu tên phiên đó, nên chỉ một yêu cầu là đến được agent. Hãy build image, ghi tên của nó thay cho ghcr.io/example/support-agent:1.0.0 trong support_agent/import-answers.yaml, rồi nhập lại với --sync, tùy chọn này ghi câu trả lời mới vào các bản nháp và pull lại; sau đó build:
docker build -t support-agent:local .aggrega import support_agent --syncaggrega build --release release.yamlSau đó đặt khóa trong shell của bạn và khởi động stack:
export GOOGLE_API_KEY='your Gemini API key'docker compose -p support-agent -f dist/compose/docker-compose.yaml up -d --wait-p đặt tên cho dự án, như bước chạy trong Cách một lần nhập diễn ra giải thích. --wait trả về ngay khi container chạy, vì bản build không cấp cho dịch vụ bước kiểm tra tình trạng nào, và máy chủ phản hồi một lúc sau đó, nên hãy lặp lại yêu cầu bị nó từ chối.
Kiểm thử
Gửi cho agent một tin nhắn tại http://127.0.0.1:8000, địa chỉ mà published_port công bố. Yêu cầu nêu tên một người dùng và một phiên, và /run mở phiên đó ở tin nhắn đầu tiên của nó:
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."}]}}'Câu trả lời, của Gemini, được trả về dưới dạng danh sách các sự kiện mà lượt đó đã thêm vào phiên. Lần chạy đã dùng một giá trị giữ chỗ cho khóa, nên Gemini đã từ chối nó: yêu cầu trả lời HTTP 500, Internal Server Error, và nhật ký của dịch vụ, docker compose -p support-agent -f dist/compose/docker-compose.yaml logs support-agent, nêu lý do:
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 trả lời ["support_agent"], tức các agent mà máy chủ chứa.
Dừng stack bằng:
docker compose -p support-agent -f dist/compose/docker-compose.yaml downTrên Kubernetes
Cùng agent đó được nhập cho Kubernetes bằng --target helm. Một cluster kéo image của nó từ một registry, vì vậy hãy push image bạn đã build lên một registry mà cluster của bạn đọc, và ghi tên của nó thay cho image được trả lời trong support_agent/import-answers.yaml; lần chạy đã push nó lên một registry trên chính máy của cluster, dưới dạng localhost:5000/support-agent:1.0.0. Câu trả lời thứ hai ở đó nêu tên Secret mà agent đọc khóa API Gemini từ đó, google-api-key. Các bản nháp cho Docker Compose đã nằm sẵn trong source, vì vậy hãy tạo các bản nháp này vào một thư mục riêng, và build từ đó:
aggrega import support_agent --target helm --output-dir helmcd helmaggrega build --release release.yamlBản build ghi các manifest Kubernetes thuần trong dist/helm/ tại thư mục gốc của workspace, source, mà từ helm là ../dist/helm/. Hãy tạo Secret google-api-key trong namespace bạn áp dụng vào, giữ khóa dưới khóa dữ liệu value, và áp dụng thư mục như bước chạy của Cách một lần nhập chạy giải thích. Service của agent là support-agent-default: hãy chuyển tiếp một cổng cục bộ tới nó, và để lệnh tiếp tục chạy:
kubectl port-forward -n <namespace> svc/support-agent-default 8000:8000Từ một terminal khác, tin nhắn ở trên đến được agent tại cùng địa chỉ, không thay đổi. Lần chạy nhận được cùng Internal Server Error, và kubectl logs -n <namespace> deploy/support-agent nêu cùng sự từ chối khóa giữ chỗ.