未翻訳のページは英語で開き、英語と表示されます。
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.
エージェント Substrate
エージェント Substrate v1.0.0 と Loom の Helm チャートを同じ Kubernetes クラスターに配置する必要があります。Substrate のエグレスゲートウェイが、各エージェントの Loom トークンを MCP 呼び出しに付与します。
トークンがアクターのテンプレートやスナップショットに含まれることはありません。Substrate v1.0.0 には Kubernetes 1.37 以降と、ノード上の gVisor またはマイクロ VM ランタイムが必要です。以下の手順では、Substrate の Kubernetes 認証情報プロバイダーも必要です。これは ate-setup deploy ... --credential-provider='{"name":"k8s.io"}' でデプロイされます。
以下の Substrate の手順は、Substrate v1.0.0 の公式ドキュメントに従っています。このページの内容は実際のクラスターでエンドツーエンドでは実行していないため、お使いの Substrate のバージョンに照らして確認してください。
構成要素の連携
| 構成要素 | 実行場所 | 役割 |
|---|---|---|
| Loom | namespace loom での helm install loom |
メモリサーバー。その Service は loom.loom.svc.cluster.local:7777 |
| エージェント | atespace 内の Substrate アクター | プレースホルダーの Authorization ヘッダーを付けて、Loom の MCP エンドポイント /mcp を呼び出す |
| Egress ポリシー | Substrate のコントロールプレーン (kubectl ate)。atenet-egress が適用する |
アクターが Loom に到達することを許可する。ルールを追加しない限り、それ以外は許可しない |
| Loom トークン | Kubernetes Secret | エージェントごとに 1 つ。egress ゲートウェイがこれを Authorization ヘッダーに設定する |
すべてのリクエストは、Substrate の egress ゲートウェイ(ate-system 内の atenet-egress)を経由してアクターから送出されます。ゲートウェイは、アクターのポリシーで許可されていない egress をすべて拒否します。そのため、Loom に届く接続は、アクターからではなくゲートウェイの Pod からのものに見えます。各行にはトークンのサブジェクトが記録され、これによってアクターを区別できます。行の agent は MCP クライアントの名前であり、同じクライアントを実行しているアクター同士で共通になります。
1. クラスタに Loom をインストールする
Kubernetes の説明に従って、名前空間 loom、リリース名 loom でチャートをインストールします。これにより Service の名前は loom になります。エージェントに Ingress は不要です。エージェントはクラスタ内の DNS 名で Service に到達します。
チャートの NetworkPolicy は、デフォルトの networkPolicy.ingressFrom が空である間、すべての送信元を許可します。ここにピア(たとえばロードバランサのサブネット)を列挙する場合は、egress ゲートウェイもリストに加えてください。設定したリストはデフォルトに追加されるのではなく、デフォルトを置き換えるためです。
networkPolicy:
enabled: true
ingressFrom:
# ...the peers you already allow...
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: ate-system
podSelector:
matchLabels:
app: atenet-egress
2. エージェントごとのトークン
各エージェントに専用のトークンを発行します。サービスアカウントのサブジェクトには、atespace と Substrate のアクターの名前を付けます。Loom はエージェントが書き込む各行にこのサブジェクトを記録し、トークンの名前空間とロールによって、読み取りと書き込みの範囲が決まります(トークンと権限付与)。
署名鍵を保持する Loom の Pod でトークンを発行し、その atespace のトークンだけを置く名前空間の Secret に保存します。
TOKEN=$(kubectl -n loom exec deploy/loom -- \
loom mint-token --subject sa:research.research-agent --org acme \
--namespaces research --roles writer --ttl-days 30)
kubectl create namespace loom-tokens-research
kubectl -n loom-tokens-research create secret generic research-agent \
--from-literal=token="$TOKEN"
Substrate の Kubernetes credential provider は、atespace に許可された名前空間からのみ Secret を読み取ります。管理者は、プロバイダーの名前空間ポリシーでその atespace にトークン用の名前空間を許可し、プロバイダーを再起動します。プロバイダーはポリシーを起動時に読み込みます。
kubectl -n ate-system edit configmap k8s-credential-provider-namespace-policy
data:
namespace-policy.yaml: |
policies:
- atespace: research
allowedNamespaces:
- loom-tokens-research
kubectl -n ate-system rollout restart deployment/k8s-credential-provider
プロバイダーが atespace に許可する単位は個々の Secret ではなく名前空間全体です。そのため、ある名前空間を許可された atespace は、その中のすべてのトークンを使えます。atespace ごとに 1 つの名前空間を用意すれば、各 atespace は自分のエージェントのトークンだけを扱えます。
トークンは --ttl-days の経過後に失効します。失効する前に新しいトークンを発行し、Secret を置き換えてください。credential provider はリクエストのたびに Secret を読み取るため、次の呼び出しから新しいトークンが使われます。
TOKEN=$(kubectl -n loom exec deploy/loom -- \
loom mint-token --subject sa:research.research-agent --org acme \
--namespaces research --roles writer --ttl-days 30)
kubectl -n loom-tokens-research create secret generic research-agent \
--from-literal=token="$TOKEN" --dry-run=client -o yaml | kubectl apply -f -
3. エージェントを設定してそのアクターを作成する
Substrate のドキュメントには、アクター向けの MCP 設定は記載されていません。エージェントの MCP クライアントは、そのイメージ内で設定するか、アクターテンプレート内のリテラルな環境変数の値として設定します。サーバーエントリには Loom のエンドポイントとプレースホルダーのヘッダーを指定し、このヘッダーはゲートウェイが置き換えます。
{
"mcpServers": {
"loom": {
"type": "http",
"url": "http://loom.loom.svc.cluster.local:7777/mcp",
"headers": { "Authorization": "Bearer placeholder" }
}
}
}
キー名はクライアントに従います(各クライアントのエントリは MCP クライアントを参照してください)。トークンはテンプレートに含めないでください。Substrate はテンプレートとスナップショットを保存し、そのコンテナ環境にはリテラルな値しか指定できません。
次に、atespace、エージェントのイメージを持つアクターテンプレート、そのテンプレートから作成するアクターを作成します。テンプレートのフィールドについては Substrate の API ガイドで説明されています。ここでは、テンプレートの metadata で、名前を research-agent、atespace を research としています。テンプレートの workerSelector はクラスター内の WorkerPool に一致している必要があり、イメージはダイジェストで固定する必要があります。次の 3 つを作成します。
kubectl ate create atespace research
kubectl ate create actor-template -f template.yaml
kubectl ate create actor research-agent --template=research-agent -a research
4. トークンを使ってアクターが Loom に到達できるようにする
アクターには 1 つの egress ポリシーがあります。ここで示すポリシーは、上で作成したアクターに対して Loom の Service への HTTP を許可し、エージェントが送る Authorization ヘッダーを Secret の Bearer <token> に置き換えます。
kubectl ate create egress-policy research-agent -a research -f - <<'EOF'
rules:
- http:
hostnames: ["loom.loom.svc.cluster.local"]
ports:
numbers: [7777]
effects:
replaceHeaders:
- header: Authorization
prefix: "Bearer "
credentialUri: ate-secret://k8s.io/default/loom-tokens-research/research-agent/token
EOF
- ルールはリクエストのホストに対してマッチするため、MCP エントリの URL のホストである
loom.loom.svc.cluster.localを指定します。 - ゲートウェイは、すでに存在するヘッダーを置き換えます。
Authorizationヘッダーのないリクエストはそのまま送出され、Loom に拒否されます。 - Secret が存在しない場合や、atespace に権限が付与されていない場合、ゲートウェイはリクエストを拒否します。
- このガイドの
http://の URL とルールを使うには、tls.secretNameを設定していないチャートが必要です(設定すると、ポートは HTTPS のみで応答します)。この場合、チャートはクラスター内で HTTP を提供するため、このルールではトークンがゲートウェイから Loom まで暗号化されずに流れます。この区間を暗号化するには、公的に信頼された証明書を持つ、Loom の前段の TLS エンドポイント(チャートの Ingress ホストなど)をエージェントの接続先にし、そのホストをhttpsルールで許可します。この場合、ゲートウェイがエージェントの TLS を中継処理するため、アクターは Substrate のegress トラストバンドルをマウントし、MCP クライアントにそれを指定します(クライアントのランタイムに応じてSSL_CERT_FILE、NODE_EXTRA_CA_CERTS、REQUESTS_CA_BUNDLEを使います)。また、Loom に見える接続元はatenet-egressではなく Ingress コントローラーになります。
モデルプロバイダーなど、エージェントが必要とするその他の通信のルールも、同じポリシーに記述します。kubectl ate update egress-policy はすべてのルールを置き換え、メタデータが最新でないポリシーは拒否します。そのため、kubectl ate get egress-policy research-agent -a research -o yaml でポリシーを取得し、Loom のルールの隣にルールを追加して、そのファイルを kubectl ate update egress-policy ... -f で送り返してください。
ポリシーを設定したら、アクターを起動します。
kubectl ate resume actor research-agent -a research
複数のエージェント
- 同じ Loom 名前空間内のエージェントは、書き込んだものをすべて共有します。チームの名前空間を読み取れるが、書き込みは自分の名前空間だけにしたいサブエージェントには、名前空間ごとにロールを指定したトークンを発行します(
--namespace-role team=viewer --namespace-role research=writer、トークンの発行)。 - 各アクターは、それぞれ専用のトークン、Secret、egress ポリシーを持ちます。別の atespace のアクターには、その atespace 専用のトークン名前空間とグラントが割り当てられます(ステップ 2)。
- エージェント間で作業を引き継ぐには、タスクインボックスを使います。
関連情報
- エージェントフレームワークとオーケストレーター:共有 MCP マウントについて説明しています。
- Substrate のガイド:egress トラフィックと egress 認証情報の注入。