Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Địa chỉ của một công cụ lấy từ một Secret — một máy chủ Model Context Protocol đọc khóa từ chính địa chỉ của nó

Một số máy chủ Model Context Protocol do bên khác vận hành đọc khóa từ chính địa chỉ của chúng — https://mcp.example.com/mcp?api_key=<key> — thay vì từ một header của yêu cầu. Một địa chỉ như vậy không thể được ghi vào công cụ theo cách một địa chỉ thông thường được ghi: công cụ công bố địa chỉ đúng như được viết, nên khóa sẽ đến mọi tệp mà địa chỉ đến.

Workspace này giữ địa chỉ thành hai phần. Công cụ, core/ai-tool/mcp, giữ địa chỉ mà không có phần mang khóa. Kết nối của agent đến công cụ giữ toàn bộ địa chỉ dưới dạng một secret, và Release chỉ ra nơi nó được lưu. Ví dụ này xây dựng cho Kubernetes và cho Docker Compose, và trên cả hai, không tệp được render nào mang khóa.

Agent được khai báo trong catalog riêng của workspace này, nên socket giữ địa chỉ được viết đầy đủ tại đây. Các runtime agent của thư viện chuẩn core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk và mastra, cùng các nền tảng core/ai-agent/flowise và n8n, khai báo một socket tools với cùng hai slot. Công cụ, hai Features về thông tin xác thực và các hiện thực của chúng được cung cấp trong catalog của thư viện chuẩn.

Những gì ví dụ này xây dựng

instanceComponent trong catalogvai trò ở đây
searchcore/ai-tool/mcpmột máy chủ Model Context Protocol do bên khác vận hành, được ánh xạ tới mcp-remote, vốn không chạy gì cả
agentlocal/ai-agent/mcp-clientagent, được nối với search qua socket tools của nó

Hai Releases dùng chung một Aggregate, mỗi Release có Manifest riêng:

ReleaseManifestđíchnguồn của địa chỉ đầy đủ
release-helm.yamlmanifest-helm.yamlKubernetesmột Secret mà namespace đã có sẵn: core/referenced-secret gắn với helm/k8s-existing-secret
release-compose.yamlmanifest-compose.yamlDocker Composemột tham chiếu biến Compose: core/secret-value gắn với compose/dotenv-secret

Tạo ví dụ

Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.

Ghi ví dụ vào một thư mục mới đặt theo tên của nó:

Terminal window
aggrega scaffold --example mcp-address-from-secret

Sau đó 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:

Terminal window
cd mcp-address-from-secret

Build

Terminal window
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/
aggrega build --release release-compose.yaml --auto-pull # → dist/local/

Mỗi Release ghi vào thư mục riêng của nó, nên hai cây kết xuất cùng tồn tại và có thể được so sánh song song.

.aggrega-config.yaml liệt kê catalog/ của chính workspace này, nơi chứa agent và hai Recipes của nó; mọi thứ khác được phân giải từ hub.aggrega.ai, registry mặc định mà tệp này chỉ định. Khi một bản checkout catalog thư viện chuẩn (lấy ở đâu) được chỉ định bằng --catalog, mọi entity đều được phân giải từ hai thư mục đó, nên bản build cũng hoàn tất với --offline, tùy chọn từ chối mọi truy cập mạng. --auto-pull ghi lockfile của mỗi Release trong quá trình build; các lockfile và đầu ra kết xuất được sinh ra, không được phân phối kèm.

Bản build Kubernetes in ra như sau, với <workspace> đại diện cho thư mục của ví dụ này:

Pull complete: release-helm.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/referenced-secret" at core/referenced-secret: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: 2 files written to <workspace>/dist

Bản build compose in ra cùng các dòng đó cho release-compose.yaml, với thông báo nêu tên core/secret-value, và ghi ra một tệp. Dòng notice: nói về Feature thông tin xác thực mà Release gắn vào: nó nhận bộ định vị của secret, origin, từ values của nhà phát triển hoặc infra của người vận hành, và thông báo tư vấn này báo rằng một nút lá được khai báo ở cả hai trụ cột. Nó không thay đổi kết luận nào và không thay đổi byte kết xuất nào.

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ũng có thể làm như vậy: hãy dán prompt này vào trợ lý.

Chỉ sử dụng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục không gian làm việc chưa chứa thư mục `mcp-address-from-secret`, hãy gọi công cụ `scaffold` một lần với `example` được đặt thành `mcp-address-from-secret` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `mcp-address-from-secret` mới. Sau đó gọi công cụ `build` một lần cho mỗi Release, theo thứ tự này — `release-helm.yaml` và `release-compose.yaml` — mỗi lần với `workspace_root` được đặt thành `mcp-address-from-secret`, `release` được đặt thành tệp đó, `auto_pull` được đặt thành true và `write` được đặt thành true. Hãy cho tôi biết mỗi bản build đã ghi những tệp nào; chúng nằm trong `mcp-address-from-secret/dist/`.

Công cụ giữ địa chỉ mà không có khóa của nó

Từ release-helm.yaml:

search:
infra:
endpoint: https://mcp.example.com/mcp

helm/mcp-remote đọc host, cổng và scheme mà nó công bố từ địa chỉ đó, rồi xuất ra một tệp cho công cụ: một Service ExternalName ánh xạ một tên trong cụm sang host. Toàn bộ spec của dist/kubernetes/helm/search-service.yaml:

spec:
type: ExternalName
externalName: mcp.example.com
ports:
- port: 443

Vì vậy, địa chỉ mà công cụ giữ cần ít nhất một scheme và một host, và không chứa gì của phần mang khóa. compose/mcp-remote hoàn toàn không định nghĩa service nào cho công cụ.

Kết nối của agent giữ toàn bộ địa chỉ

Component của agent khai báo hai slot bí mật trên socket tools của nó. Trích từ catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, đã lược bỏ phần mô tả:

tools:
selector: "component.aggrega.ai/category=ai-tool, tool.aggrega.ai/transport=http"
valueSchema:
unauthenticated:
type: boolean
default: false
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
endpoint:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

credential giữ một khóa mà agent trình ra trong một header của yêu cầu; endpoint giữ toàn bộ địa chỉ, dành cho một máy chủ đọc khóa của nó từ chính địa chỉ. unauthenticated là tuyên bố riêng của kết nối rằng công cụ của nó không nhận thông tin xác thực nào, và không thay đổi bất cứ thứ gì agent kết xuất. Cả ba nằm trên kết nối, nên một agent kết nối tới nhiều máy chủ sẽ giữ bí mật của từng máy chủ trên kết nối của máy chủ đó.

Release điền endpoint trên kết nối mà Aggregate đã nối. Trích từ release-helm.yaml:

agent:
uses:
tools:
search:
features:
endpoint:
type: core/referenced-secret
infra:
origin: search-mcp-address

Một Release không viết values, nên origin nằm trong infra, và khóa dữ liệu được đọc từ Secret là giá trị mặc định của Feature, value. Manifest gắn core/referenced-secret với helm/k8s-existing-secret, thành phần này đọc origin là tên của một Secret mà namespace đã có sẵn và không kết xuất gì cả. Secret được tạo bên ngoài Release, bởi người triển khai nó:

Terminal window
kubectl -n agents create secret generic search-mcp-address \
--from-literal=value='https://mcp.example.com/mcp?api_key=<key>'

Container của agent đọc địa chỉ từ đó. Phần env của dist/kubernetes/helm/agent-deployment.yaml:

env:
- name: MCP_URL_SEARCH
valueFrom:
secretKeyRef:
name: search-mcp-address
key: value
- name: MCP_HOST_SEARCH
value: mcp.example.com

MCP_URL_SEARCH là toàn bộ địa chỉ, được đọc từ Secret theo tên và khóa dữ liệu; MCP_HOST_SEARCH là host mà công cụ công bố. dist/kubernetes/helm/ chứa Deployment của agent và Service của công cụ, ngoài ra không có gì khác: không Secret nào được kết xuất, và không tệp nào mang khóa.

Trên Docker Compose

Compose không có tham chiếu bí mật, nên Release cho compose điền cùng slot đó bằng core/secret-value, với origin là một tham chiếu biến Compose. Trích từ release-compose.yaml:

agent:
uses:
tools:
search:
features:
endpoint:
type: core/secret-value
infra:
origin: "${SEARCH_MCP_URL}"

compose/dotenv-secret chuyển giao tham chiếu đúng như đã viết, và service của agent mang nó. Phần environment của service agent trong dist/local/compose/docker-compose.yaml, tệp định nghĩa service đó và không service nào khác:

environment:
MCP_HOST_SEARCH: mcp.example.com
MCP_URL_SEARCH: ${SEARCH_MCP_URL}

Docker Compose thay thế SEARCH_MCP_URL khi stack khởi động — từ môi trường shell, một tệp được chỉ định bằng --env-file, hoặc tệp .env trong thư mục dự án — nên tệp chỉ mang tham chiếu mà thôi.

Cách các Recipes của agent đọc slot

Mỗi kết nối trên socket tools trở thành các biến môi trường được đặt tên theo bí danh của kết nối viết hoa: MCP_HOST_<ALIAS> từ host mà tool công bố, và MCP_URL_<ALIAS> từ địa chỉ mà tool công bố — trừ khi kết nối mang một secret endpoint, khi đó MCP_URL_<ALIAS> là secret đó và địa chỉ được công bố hoàn toàn không được chuyển giao. Một kết nối mang credential sẽ thêm MCP_CREDENTIAL_<ALIAS>, và MCP_CREDENTIAL_HEADER_<ALIAS>, header yêu cầu mà tool công bố để trình bày credential đó.

  • Trên Kubernetes, secret là một mục attachment nêu tên kết nối và slot — connection: search, from: endpoint, as: env — mà provider chuyển thành secretKeyRef ở trên, đọc tên và data key của Secret từ những gì helm/k8s-existing-secret công bố.
  • Trên Docker Compose, secret đến trên inject pipe của agent dưới key mà chính attachment của nó đã chuyển giao, values.key, và Recipe ghi giá trị đó vào môi trường của service.

Nếu thay vào đó được ghi vào infra.endpoint của tool, key sẽ đi đến bất cứ đâu địa chỉ được công bố đi đến: MCP_URL_SEARCH của agent mang nó như một giá trị literal, trong Deployment trên Kubernetes và trong môi trường của service trong file Compose, vì bản hiện thực tham chiếu công bố địa chỉ đúng như đã viết.

Giới hạn

  • Trên Docker Compose, hai secret mà chỉ riêng Release gắn vào cùng một agent sẽ xung đột. Mỗi attachment core/secret-value mà một Release tạo ra đều chuyển giao dưới khóa mặc định của Feature là value, nên một attachment thứ hai trên cùng agent — địa chỉ của một server khác, hoặc một credential bên cạnh địa chỉ này — sẽ dừng quá trình build. Một Release gắn cả endpoint lẫn credential vào search sẽ in ra:

    [… omitted: what resolving the lockfile prints, the same halt among it, and the notice about core/secret-value]
    [OPS_ERROR E0318] release-compose.yaml at .spec.boundaries.main.components.agent.uses.tools.search.features.credential
    duplicate delivery key across two attachments: an attachment's FeatureRecipe writes a delivery key another attachment already delivered ("value", mechanism "env", attachment "search.credential", delivered first by attachment "search.endpoint"). Give one of the two attachments a key of its own, or attach one fewer: the key this attachment delivers under is chosen by its FeatureRecipe, which can read the attachment's own values and infra, and the other's is chosen the same way or by its own inject block where it delivered through one. A Release sets an attachment's infra and never its values, so where a key is chosen by a value, attach that attachment in the Aggregate with the value, and keep giving the rest from the Release.

    Khóa là một lá values, mà chỉ Aggregate ghi, nên một Aggregate khai báo một trong hai attachment và đặt tên cho values.key của nó sẽ tránh được điều này: Recipe compose của agent đọc mỗi secret dưới khóa mà chính attachment của nó đặt tên. Kubernetes không có giới hạn như vậy, vì ở đó mỗi secret là một tham chiếu tới một Secret theo tên và khóa dữ liệu, chứ không phải một giá trị được chuyển giao dưới một khóa.

  • Khóa nằm trong đường dẫn của địa chỉ. Khi server đọc khóa từ đường dẫn thay vì từ chuỗi truy vấn, địa chỉ của tool là địa chỉ đã bỏ phần đó của đường dẫn, và Secret giữ toàn bộ địa chỉ.

  • Host được ghi hai lần, dạng thuần trong địa chỉ của tool và bên trong Secret, và không có gì kiểm tra rằng hai giá trị khớp nhau, vì trình biên dịch không bao giờ đọc một Secret.

Việc ghép địa chỉ lúc chạy chỉ từ khóa, bằng một tham chiếu $(VAR) trong một biến thông thường, chỉ hoạt động trên Kubernetes: Kubernetes mở rộng tham chiếu như vậy từ các mục được liệt kê trước nó trong container, và provider helm liệt kê các mục nó đọc từ một Secret trước các biến thông thường, trong khi Docker Compose không mở rộng tham chiếu $(VAR) nào giữa các mục environment của một service.

Điều chỉnh ví dụ

  • Một máy chủ cũng kiểm tra một header. Gắn credential trên cùng kết nối. Agent nhận MCP_CREDENTIAL_SEARCH và header để trình nó dưới đó, MCP_CREDENTIAL_HEADER_SEARCH: Authorization, trừ khi Release nêu tên header riêng của máy chủ trong infra.credential_header của công cụ. Trên Docker Compose, hãy đặt tên khóa của một trong hai trong Aggregate, như ở trên.
  • Nhiều máy chủ. Nối một kết nối cho mỗi máy chủ trên socket tools. Các biến của mỗi kết nối mang alias của nó, và mỗi kết nối giữ các secret riêng của nó.
  • Một máy chủ chỉ đọc khóa của nó từ một header. Bỏ endpoint đi, và MCP_URL_<ALIAS> là địa chỉ mà công cụ công bố.

Tính tất định

Cả hai Releases đều build được với --verify-determinism, cờ này render mỗi nút hai lần và so sánh các byte được xuất ra:

Terminal window
aggrega build --release release-helm.yaml --verify-determinism

Build lại bất kỳ Release nào trong hai từ một cây sạch đều tái tạo đầu ra đã render của nó chính xác đến từng byte.

Các tệp

  • aggregate.yaml — công cụ và agent, được nối với nhau qua socket tools, không gắn secret nào.
  • manifest-helm.yaml, manifest-compose.yaml — công cụ tới mcp-remote, agent tới Recipe riêng của nó, và Feature thông tin xác thực mà mỗi target sử dụng.
  • release-helm.yaml, release-compose.yaml — địa chỉ của công cụ không kèm khóa, image của agent, và secret endpoint trên kết nối của agent.
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — agent: socket tools của nó với các slot credential và endpoint.
  • catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml, catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml — agent trên mỗi target.
  • .aggrega-config.yaml — ngăn xếp tìm kiếm catalog và registry.
  • build-release.sh — build một Release, in ra lệnh aggrega build tương đương.

Với một khóa mà agent trình bày trong header, được giữ trên chính kết nối mà nó được trình bày, xem connection-credentials. Mô hình đứng sau cả hai là Mô hình thông tin xác thực, và các hiện thực hóa của công cụ được mô tả cùng nhãn transport của công cụ trong Các Features AI.