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

Alamat tool dari sebuah Secret — server Model Context Protocol yang membaca kuncinya dari alamatnya

Beberapa server Model Context Protocol yang dijalankan pihak lain membaca kuncinya dari alamatnya sendiri — https://mcp.example.com/mcp?api_key=<key> — alih-alih dari header permintaan. Alamat seperti itu tidak dapat dituliskan ke dalam tool seperti alamat biasa: tool menerbitkan alamatnya sebagaimana tertulis, sehingga kunci tersebut akan sampai ke setiap berkas yang dicapai alamat itu.

Workspace ini menyimpan alamat dalam dua bagian. Tool, core/ai-tool/mcp, menyimpan alamat tanpa bagian yang membawa kunci. Koneksi agen ke tool menyimpan seluruh alamat sebagai rahasia, dan Release menyebutkan tempat rahasia itu berada. Workspace ini dibangun untuk Kubernetes dan untuk Docker Compose, dan pada keduanya tidak ada berkas hasil render yang membawa kunci.

Agen dideklarasikan dalam katalog milik workspace ini sendiri, sehingga socket yang menyimpan alamat dituliskan di sini secara lengkap. Runtime agen pustaka standar core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk dan mastra, serta platform core/ai-agent/flowise dan n8n, mendeklarasikan socket tools dengan dua slot yang sama. Tool, kedua Features kredensial, dan realisasinya disertakan dalam katalog pustaka standar.

Apa yang dibangunnya

instansComponent katalogperannya di sini
searchcore/ai-tool/mcpserver Model Context Protocol yang dijalankan pihak lain, dipetakan ke mcp-remote, yang tidak menjalankan apa pun
agentlocal/ai-agent/mcp-clientagen, yang dihubungkan ke search melalui soket tools miliknya

Dua Releases berbagi satu Aggregate yang sama, masing-masing dengan Manifest sendiri:

ReleaseManifesttargetasal alamat lengkapnya
release-helm.yamlmanifest-helm.yamlKubernetesSecret yang sudah ada di namespace: core/referenced-secret yang diikat ke helm/k8s-existing-secret
release-compose.yamlmanifest-compose.yamlDocker Composereferensi variabel Compose: core/secret-value yang diikat ke compose/dotenv-secret

Membuat contoh

Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.

Tulis contoh ke folder baru yang dinamai sesuai contoh itu:

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

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

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/

Setiap Release menulis ke direktorinya sendiri, sehingga kedua pohon hasil render dapat berdampingan dan dapat dibandingkan secara berdampingan.

.aggrega-config.yaml mencantumkan catalog/ milik workspace ini, yang memuat agen dan kedua Recipes-nya; semua hal lainnya diresolusi dari hub.aggrega.ai, registry default yang disebutnya. Dengan checkout katalog pustaka standar (cara mendapatkannya) yang disebut lewat --catalog, setiap entitas diresolusi dari kedua direktori tersebut, sehingga build juga selesai dengan --offline, yang menolak setiap akses jaringan. --auto-pull menulis lockfile setiap Release selama build; lockfile dan keluaran hasil render dihasilkan, bukan dikirimkan.

Build Kubernetes mencetak keluaran berikut, dengan <workspace> mewakili folder contoh ini:

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

Build compose mencetak baris yang sama untuk release-compose.yaml, dengan pemberitahuannya menyebut core/secret-value, dan menulis satu file. Baris notice: berkaitan dengan Feature kredensial yang dilampirkan Release: Feature tersebut menerima locator secret, origin, dari values milik pengembang atau infra milik operator, dan pemberitahuan tersebut melaporkan bahwa satu leaf dideklarasikan di kedua pilar. Hal ini tidak mengubah verdict apa pun dan tidak mengubah satu byte pun hasil render.

Dengan asisten AI

Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.

Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder ruang kerja belum berisi folder `mcp-address-from-secret`, panggil alat `scaffold` sekali dengan `example` diatur ke `mcp-address-from-secret` dan tanpa `dir`: alat ini menulis contoh ke folder `mcp-address-from-secret` yang baru. Kemudian panggil alat `build` sekali untuk setiap Release, dengan urutan ini — `release-helm.yaml` dan `release-compose.yaml` — setiap kali dengan `workspace_root` diatur ke `mcp-address-from-secret`, `release` diatur ke file tersebut, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis oleh setiap build; file tersebut berada di bawah `mcp-address-from-secret/dist/`.

Tool menyimpan alamat tanpa kuncinya

Dari release-helm.yaml:

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

helm/mcp-remote membaca host, port, dan skema yang dipublikasikannya dari alamat tersebut, lalu menghasilkan satu file untuk tool: sebuah Service ExternalName yang memetakan nama di dalam klaster ke host tersebut. Seluruh spec dari dist/kubernetes/helm/search-service.yaml:

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

Jadi, alamat yang disimpan tool setidaknya memerlukan skema dan host, dan tidak menyimpan sedikit pun bagian yang membawa kunci. compose/mcp-remote sama sekali tidak mendefinisikan layanan untuk tool tersebut.

Koneksi agen menyimpan seluruh alamat

Component milik agen mendeklarasikan dua slot rahasia pada soket tools-nya. Dari catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml, tanpa deskripsi:

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 menyimpan kunci yang disajikan agen dalam header permintaan; endpoint menyimpan seluruh alamat, untuk server yang membaca kuncinya dari alamat itu sendiri. unauthenticated adalah pernyataan koneksi itu sendiri bahwa alatnya tidak menerima kredensial, dan tidak mengubah apa pun yang dirender agen. Ketiganya berada pada koneksi, sehingga agen yang menjangkau beberapa server menyimpan rahasia setiap server pada koneksi server tersebut.

Release mengisi endpoint pada koneksi yang dirangkai oleh Aggregate. Dari release-helm.yaml:

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

Release tidak menulis values, sehingga origin berada di infra, dan kunci data yang dibaca dari Secret adalah nilai bawaan Feature, yaitu value. Manifest mengikat core/referenced-secret ke helm/k8s-existing-secret, yang membaca origin sebagai nama Secret yang sudah ada di namespace dan tidak merender apa pun. Secret tersebut dibuat di luar Release, oleh siapa pun yang men-deploy-nya:

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

Kontainer agen membaca alamat dari Secret tersebut. env dari 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 adalah seluruh alamat, dibaca dari Secret berdasarkan nama dan kunci data; MCP_HOST_SEARCH adalah host yang dipublikasikan alat. dist/kubernetes/helm/ hanya berisi Deployment agen dan Service alat: tidak ada Secret yang dirender, dan tidak ada file yang memuat kunci.

Pada Docker Compose

Compose tidak memiliki referensi rahasia, sehingga Release compose mengisi slot yang sama dengan core/secret-value, dengan origin berupa referensi variabel Compose. Dari release-compose.yaml:

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

compose/dotenv-secret menyampaikan referensi sebagaimana tertulis, dan layanan agen memuatnya. environment dari layanan agent dalam dist/local/compose/docker-compose.yaml, yang hanya mendefinisikan layanan tersebut:

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

Docker Compose menyubstitusi SEARCH_MCP_URL saat stack dimulai — dari lingkungan shell, file yang disebutkan dengan --env-file, atau file .env di direktori proyek — sehingga file hanya memuat referensinya.

Cara Recipes agen membaca slot

Setiap koneksi pada soket tools menjadi variabel lingkungan yang dinamai menurut alias koneksi dalam huruf kapital: MCP_HOST_<ALIAS> dari host yang dipublikasikan tool, dan MCP_URL_<ALIAS> dari alamat yang dipublikasikan tool — kecuali jika koneksi membawa secret endpoint, dalam hal ini MCP_URL_<ALIAS> adalah secret tersebut dan alamat yang dipublikasikan sama sekali tidak dikirimkan. Koneksi yang membawa credential menambahkan MCP_CREDENTIAL_<ALIAS>, dan MCP_CREDENTIAL_HEADER_<ALIAS>, yaitu header permintaan yang dipublikasikan tool untuk menyajikannya.

  • Di Kubernetes secret adalah entri lampiran yang menyebut koneksi dan slot — connection: search, from: endpoint, as: env — yang diubah oleh provider menjadi secretKeyRef di atas, dengan membaca nama Secret dan kunci datanya dari apa yang dipublikasikan helm/k8s-existing-secret.
  • Di Docker Compose secret tiba di pipa inject agen di bawah kunci tempat lampirannya sendiri mengirimkannya, values.key, dan Recipe menulis nilai tersebut ke dalam lingkungan layanan.

Jika ditulis ke dalam infra.endpoint milik tool, kunci akan ikut ke mana pun alamat yang dipublikasikan pergi: MCP_URL_SEARCH milik agen membawanya sebagai nilai literal, di Deployment pada Kubernetes dan di lingkungan layanan dalam berkas Compose, karena realisasi referensi memublikasikan alamat sebagaimana ditulis.

Batasan

  • Di Docker Compose, dua secret yang dilampirkan oleh Release saja ke satu agen saling bertabrakan. Setiap lampiran core/secret-value yang dibuat oleh Release dikirim di bawah kunci bawaan Feature, value, sehingga lampiran kedua pada agen yang sama — alamat server lain, atau kredensial di samping yang ini — menghentikan build. Sebuah Release yang melampirkan endpoint dan credential sekaligus ke search mencetak:

    [… 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.

    Kunci tersebut adalah daun values, yang hanya ditulis oleh Aggregate, sehingga Aggregate yang mendeklarasikan salah satu dari kedua lampiran itu dan menamai values.key-nya menghindarinya: Recipe compose milik agen membaca setiap secret di bawah kunci yang dinamai oleh lampirannya sendiri. Kubernetes tidak memiliki batasan seperti itu, karena setiap secret di sana adalah referensi ke sebuah Secret berdasarkan nama dan kunci data, bukan nilai yang dikirim di bawah sebuah kunci.

  • Kunci di path alamat. Jika server membaca kuncinya dari path dan bukan dari query string, alamat tool adalah alamat tersebut tanpa bagian path itu, dan Secret menyimpan alamat secara utuh.

  • Host ditulis dua kali, secara terbuka di alamat tool dan di dalam Secret, dan tidak ada yang memeriksa bahwa keduanya sama, karena compiler tidak pernah membaca Secret.

Menyusun alamat saat run time hanya dari kunci, dengan referensi $(VAR) di dalam variabel biasa, hanya berfungsi di Kubernetes: Kubernetes mengekspansi referensi seperti itu dari entri yang tercantum sebelumnya di dalam container, dan provider helm mencantumkan entri yang dibacanya dari Secret sebelum variabel biasa, sedangkan Docker Compose tidak mengekspansi referensi $(VAR) apa pun di antara entri environment sebuah service.

Menyesuaikannya

  • Server yang juga memeriksa header. Lampirkan credential pada koneksi yang sama. Agen menerima MCP_CREDENTIAL_SEARCH dan header tempat menyajikannya, MCP_CREDENTIAL_HEADER_SEARCH: Authorization, kecuali jika Release menyebutkan header milik server itu sendiri dalam infra.credential_header milik tool. Pada Docker Compose, sebutkan kunci salah satu dari keduanya di Aggregate, seperti di atas.
  • Beberapa server. Hubungkan satu koneksi per server pada soket tools. Variabel setiap koneksi membawa aliasnya, dan setiap koneksi menyimpan secret-nya sendiri.
  • Server yang membaca kuncinya hanya dari header. Jangan sertakan endpoint, dan MCP_URL_<ALIAS> adalah alamat yang dipublikasikan oleh tool.

Determinisme

Kedua Releases di-build dengan --verify-determinism, yang merender setiap node dua kali dan membandingkan byte yang dihasilkan:

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

Mem-build ulang salah satunya dari tree yang bersih menghasilkan kembali output rendernya secara identik byte demi byte.

Berkas

  • aggregate.yaml — tool dan agen, dihubungkan melalui socket tools, tanpa secret yang dilampirkan.
  • manifest-helm.yaml, manifest-compose.yaml — tool ke mcp-remote, agen ke Recipe miliknya sendiri, dan Feature kredensial yang digunakan setiap target.
  • release-helm.yaml, release-compose.yaml — alamat tool tanpa kuncinya, image agen, dan secret endpoint pada koneksi agen.
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — agen: socket tools miliknya dengan slot credential dan endpoint.
  • catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml, catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml — agen pada setiap target.
  • .aggrega-config.yaml — tumpukan pencarian katalog dan registri.
  • build-release.sh — membangun satu Release, sambil menampilkan perintah aggrega build yang setara.

Untuk kunci yang diberikan agen dalam sebuah header, yang disimpan pada koneksi tempat kunci itu diberikan, lihat connection-credentials. Model yang mendasari keduanya adalah Credential Model, dan realisasi tool dijelaskan dengan label transport tool di AI Features.