İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Bir aracın adresinin bir Secret'tan alınması — anahtarını kendi adresinden okuyan bir Model Context Protocol sunucusu

Başkası tarafından çalıştırılan bazı Model Context Protocol sunucuları anahtarlarını bir istek başlığından değil, kendi adreslerinden okur — https://mcp.example.com/mcp?api_key=<key>. Böyle bir adres, sıradan bir adres gibi araca yazılamaz: araç, adresini yazıldığı gibi yayımlar; bu nedenle anahtar, adresin ulaştığı her dosyaya ulaşırdı.

Bu çalışma alanı adresi iki parça hâlinde tutar. Araç, yani core/ai-tool/mcp, adresi anahtarı taşıyan kısım olmadan tutar. Ajanın araca olan bağlantısı ise adresin tamamını bir gizli değer olarak tutar ve Release bu değerin nerede bulunduğunu belirtir. Kubernetes ve Docker Compose için oluşturulur ve her ikisinde de işlenen hiçbir dosya anahtarı taşımaz.

Ajan bu çalışma alanının kendi kataloğunda bildirilir; bu nedenle adresi tutan soket burada eksiksiz olarak yazılmıştır. Standart kütüphanedeki ajan çalışma ortamları core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk ve mastra ile core/ai-agent/flowise ve n8n platformları, aynı iki yuvaya sahip bir tools soketi bildirir. Araç, iki kimlik bilgisi Features’ı ve bunların gerçekleştirimleri standart kütüphane kataloğuyla birlikte gelir.

Ne oluşturur

örnekkatalog Component’iburada ne olduğu
searchcore/ai-tool/mcpbaşka birinin çalıştırdığı, hiçbir şey çalıştırmayan mcp-remote’a eşlenmiş bir Model Context Protocol sunucusu
agentlocal/ai-agent/mcp-clienttools soketi üzerinden search’e bağlanan ajan

İki Release, her biri kendi Manifest’ine sahip olarak tek Aggregate’i paylaşır:

ReleaseManifesthedefadresin tamamının geldiği yer
release-helm.yamlmanifest-helm.yamlKubernetesad alanının zaten barındırdığı bir Secret: helm/k8s-existing-secret’e bağlanan core/referenced-secret
release-compose.yamlmanifest-compose.yamlDocker Composebir Compose değişken başvurusu: compose/dotenv-secret’e bağlanan core/secret-value

Örneği oluşturun

Bu örneği aşağıdaki komutlarla derleyebilir ya da yapay zekâ asistanınıza sizin için derletebilirsiniz.

Örneği, adını taşıyan yeni bir klasöre yazın:

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

Ardından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:

Terminal window
cd mcp-address-from-secret

Derleme

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

Her Release kendi dizinine yazar; böylece işlenmiş iki ağaç bir arada bulunur ve yan yana karşılaştırılabilir.

.aggrega-config.yaml, bu çalışma alanının ajanı ve onun iki Recipes’ini barındıran kendi catalog/ dizinini listeler; geri kalan her şey bu dosyanın adlandırdığı varsayılan kayıt defteri olan hub.aggrega.ai’den çözümlenir. Standart kitaplık kataloğunun bir çalışma kopyası (nereden edinilir) --catalog ile adlandırıldığında her varlık bu iki dizinden çözümlenir; böylece derleme, her ağ erişimini reddeden --offline ile de tamamlanır. --auto-pull her Release’in kilit dosyasını derleme sırasında yazar; kilit dosyaları ve işlenmiş çıktı üretilir, dağıtılmaz.

Kubernetes derlemesi, <workspace> bu örneğin klasörünü temsil edecek şekilde şunu yazdırır:

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

Compose derlemesi release-compose.yaml için aynı satırları, bildirimi core/secret-value’yu adlandırarak yazdırır ve tek bir dosya yazar. notice: satırı, Release’in eklediği kimlik bilgisi Feature’ı ile ilgilidir: bu Feature gizli bilginin konum belirtecini, origin’i, geliştiricinin values’undan ya da operatörün infra’sından kabul eder ve tavsiye niteliğindeki bildirim, bir yaprağın her iki sütunda da bildirildiğini raporlar. Hiçbir kararı ve işlenmiş hiçbir baytı değiştirmez.

Bir yapay zekâ asistanıyla

Aggrega 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 klasör oluşturmayın. Çalışma alanı klasöründe henüz `mcp-address-from-secret` klasörü yoksa `scaffold` aracını `example` değeri `mcp-address-from-secret` olacak şekilde ve `dir` olmadan bir kez çağırın: araç örneği yeni bir `mcp-address-from-secret` klasörüne yazar. Ardından `build` aracını her Release için bir kez, şu sırayla — `release-helm.yaml` ve `release-compose.yaml` — her seferinde `workspace_root` değeri `mcp-address-from-secret`, `release` değeri o dosya, `auto_pull` değeri true ve `write` değeri true olacak şekilde çağırın. Her derlemenin hangi dosyaları yazdığını bana söyleyin; dosyalar `mcp-address-from-secret/dist/` altındadır.

Araç, adresi anahtarı olmadan tutar

release-helm.yaml dosyasından:

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

helm/mcp-remote, yayımladığı ana makineyi, portu ve şemayı bu adresten okur ve araç için tek bir dosya üretir: küme içi bir adı ana makineye eşleyen bir ExternalName Service. dist/kubernetes/helm/search-service.yaml dosyasının spec bölümünün tamamı:

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

Dolayısıyla aracın tuttuğu adresin en azından bir şemaya ve bir ana makineye ihtiyacı vardır ve adres, anahtarı taşıyan kısımdan hiçbir şey tutmaz. compose/mcp-remote, araç için hiçbir servis tanımlamaz.

Ajanın bağlantısı adresin tamamını tutar

Ajanın Component’i, tools soketinde iki gizli bilgi yuvası bildirir. Açıklamalar çıkarılmış olarak catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml dosyasından:

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, ajanın bir istek başlığında sunduğu anahtarı tutar; endpoint ise anahtarını adresin kendisinden okuyan bir sunucu için adresin tamamını tutar. unauthenticated, bağlantının, aracının kimlik bilgisi almadığına dair kendi beyanıdır ve ajanın işlediği hiçbir şeyi değiştirmez. Üçü de bağlantı üzerinde bulunur; bu nedenle birkaç sunucuya erişen bir ajan, her sunucunun gizli bilgisini o sunucunun bağlantısında tutar.

Release, Aggregate’in bağladığı bağlantıdaki endpoint yuvasını doldurur. release-helm.yaml dosyasından:

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

Bir Release values yazmaz; bu nedenle origin, infra içindedir ve Secret’tan okunan veri anahtarı Feature’ın varsayılanı olan value’dur. Manifest, core/referenced-secret’i helm/k8s-existing-secret’e bağlar; bu da origin’i ad alanında zaten bulunan bir Secret’ın adı olarak okur ve hiçbir şey işlemez. Secret, Release’in dışında, onu dağıtan kişi tarafından oluşturulur:

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

Ajanın konteyneri adresi buradan okur. dist/kubernetes/helm/agent-deployment.yaml dosyasının env bölümü:

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

MCP_URL_SEARCH, Secret’tan adı ve veri anahtarıyla okunan adresin tamamıdır; MCP_HOST_SEARCH ise aracın yayımladığı ana makinedir. dist/kubernetes/helm/, ajanın Deployment’ını ve aracın Service’ini tutar, başka hiçbir şeyi tutmaz: hiçbir Secret işlenmez ve hiçbir dosya anahtarı taşımaz.

Docker Compose üzerinde

Compose’da gizli bilgi referansı yoktur; bu nedenle compose Release’i aynı yuvayı, kaynağı bir Compose değişken referansı olan core/secret-value ile doldurur. release-compose.yaml dosyasından:

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

compose/dotenv-secret referansı yazıldığı gibi iletir ve ajanın servisi onu taşır. Yalnızca o servisi tanımlayan dist/local/compose/docker-compose.yaml dosyasındaki agent servisinin environment bölümü:

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

Docker Compose, SEARCH_MCP_URL değişkenini yığın başlatıldığında yerine koyar — kabuk ortamından, --env-file ile belirtilen bir dosyadan ya da proje dizinindeki .env dosyasından — bu nedenle dosya yalnızca referansı taşır.

Ajanın Recipes’i yuvayı nasıl okur

tools soketindeki her bağlantı, bağlantının takma adının büyük harfli hâliyle adlandırılan ortam değişkenlerine dönüşür: aracın yayımladığı ana makineden MCP_HOST_<ALIAS> ve aracın yayımladığı adresten MCP_URL_<ALIAS>; ancak bağlantı bir endpoint gizli değeri taşıyorsa MCP_URL_<ALIAS> o gizli değerdir ve yayımlanan adres hiç iletilmez. Bir credential taşıyan bağlantı MCP_CREDENTIAL_<ALIAS> değişkenini ve aracın, kimlik bilgisinin altında sunulması için yayımladığı istek başlığı olan MCP_CREDENTIAL_HEADER_<ALIAS> değişkenini ekler.

  • Kubernetes’te gizli değer, bağlantıyı ve yuvayı adlandıran bir ek girdisidir (connection: search, from: endpoint, as: env); sağlayıcı bunu, Secret’ın adını ve veri anahtarını helm/k8s-existing-secret öğesinin yayımladığından okuyarak yukarıdaki secretKeyRef yapısına dönüştürür.
  • Docker Compose’da gizli değer, ajanın inject borusuna, kendi ekinin onu ilettiği anahtar olan values.key altında ulaşır ve Recipe bu değeri servisin ortamına yazar.

Anahtar bunun yerine aracın infra.endpoint alanına yazılırsa, yayımlanan adres nereye giderse oraya gider: ajanın MCP_URL_SEARCH değişkeni onu Kubernetes’te Deployment içinde, Compose dosyasında ise servisin ortamında düz bir değer olarak taşır; çünkü başvuru gerçekleştirimi adresi yazıldığı gibi yayımlar.

Sınırlar

  • Docker Compose üzerinde, Release’in tek başına bir ajana eklediği iki gizli değer çakışır. Bir Release’in yaptığı her core/secret-value eklemesi değeri Feature’ın varsayılan anahtarı olan value altında iletir; bu nedenle aynı ajana yapılan ikinci bir ekleme — başka bir sunucunun adresi ya da bunun yanındaki bir kimlik bilgisi — derlemeyi durdurur. search’e hem bir endpoint hem de bir credential ekleyen bir Release şunu yazdırır:

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

    Anahtar bir values yaprağıdır ve onu yalnızca Aggregate yazar; bu nedenle iki eklemeden birini bildiren ve onun values.key değerini adlandıran bir Aggregate bu sorundan kaçınır: ajanın compose Recipe’i her gizli değeri kendi eklemesinin adlandırdığı anahtar altında okur. Kubernetes’te böyle bir sınır yoktur, çünkü orada her gizli değer bir anahtar altında iletilen bir değer değil, bir Secret’a adı ve veri anahtarıyla yapılan bir başvurudur.

  • Adresin yolunda bir anahtar. Sunucu anahtarını sorgu dizesinden değil de yoldan okuyorsa, aracın adresi yolun o kısmı çıkarılmış adrestir ve Secret adresin tamamını tutar.

  • Ana makine iki kez yazılır: aracın adresinde açıkça ve Secret’ın içinde; ikisinin uyuştuğunu hiçbir şey denetlemez, çünkü derleyici bir Secret’ı hiçbir zaman okumaz.

Adresi çalışma zamanında yalnızca anahtardan, düz bir değişkendeki bir $(VAR) başvurusuyla birleştirmek yalnızca Kubernetes üzerinde çalışır: Kubernetes böyle bir başvuruyu kapsayıcıda kendisinden önce listelenen girdilerden genişletir ve helm provider’ı bir Secret’tan okuduğu girdileri düz değişkenlerden önce listeler; Docker Compose ise bir servisin ortam girdileri arasında hiçbir $(VAR) başvurusunu genişletmez.

Uyarlama

  • Bir header’ı da denetleyen bir sunucu. Aynı bağlantıya credential ekleyin. Agent, MCP_CREDENTIAL_SEARCH değerini ve bunu sunacağı header’ı, MCP_CREDENTIAL_HEADER_SEARCH değerini alır: Release, aracın infra.credential_header alanında sunucunun kendi header’ını belirtmedikçe bu Authorization olur. Docker Compose’da, yukarıda olduğu gibi, ikisinden birinin anahtarını Aggregate’te belirtin.
  • Birden çok sunucu. tools soketinde her sunucu için bir bağlantı kurun. Her bağlantının değişkenleri kendi takma adını taşır ve her bağlantı kendi gizli değerlerini tutar.
  • Anahtarını yalnızca bir header’dan okuyan bir sunucu. endpoint eklemeyin; bu durumda MCP_URL_<ALIAS>, aracın yayımladığı adres olur.

Determinizm

Her iki Releases de --verify-determinism ile derlenir; bu seçenek her düğümü iki kez işler ve üretilen baytları karşılaştırır:

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

Herhangi birini temiz bir ağaçtan yeniden derlemek, işlenmiş çıktısını bayt bayt aynı şekilde yeniden üretir.

Dosyalar

  • aggregate.yaml — araç ve ajan, tools soketi üzerinden bağlanmış, hiçbir secret eklenmemiş.
  • manifest-helm.yaml, manifest-compose.yaml — aracı mcp-remote’e, ajanı kendi Recipe’sine eşler ve her hedefin kullandığı kimlik bilgisi Feature’ını belirtir.
  • release-helm.yaml, release-compose.yaml — aracın anahtarı olmayan adresi, ajanın imajı ve ajanın bağlantısındaki endpoint secret’ı.
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — ajan: credential ve endpoint yuvalarıyla birlikte tools soketi.
  • catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml, catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml — her hedefteki ajan.
  • .aggrega-config.yaml — katalog arama yığını ve kayıt defteri.
  • build-release.sh — tek bir Release derler ve eşdeğer aggrega build komutunu yazdırır.

Ajanın bir başlıkta sunduğu ve sunulduğu bağlantıda tutulan bir anahtar için connection-credentials sayfasına bakın. Her ikisinin ardındaki model Kimlik Bilgisi Modeli’dir ve aracın gerçekleştirimleri AI Features bölümünde araç aktarım etiketiyle açıklanmıştır.