Skip to content

Agent Mesh

testnets: the SDK examples run as canaries beside the sam-node ones

Antonio Ojea35ca6d4600f6
diff --git a/.dockerignore b/.dockerignore
index ca4acce1..05a6cf7b 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -33,6 +33,7 @@ __pycache__/
*.out
coverage.*
mobile/sam-node-app/build/
+sdk/js/build/
site/public/
site/resources/
rootfs.ext4
diff --git a/.github/k8s/sam-probe-cronjob-template.yaml b/.github/k8s/sam-probe-cronjob-template.yaml
index b3053864..2b3943de 100644
--- a/.github/k8s/sam-probe-cronjob-template.yaml
+++ b/.github/k8s/sam-probe-cronjob-template.yaml
@@ -1,9 +1,10 @@
# The cold path, on a schedule: a node with no identity enrolls with the
# control plane, authenticates to a router, finds a service on the mesh and
-# speaks MCP to it through the mesh, then exits. The long-lived canaries only
-# do this when a pod restarts, so between rollouts nobody re-checks that a new
-# user could still join. Each run enrolls a fresh identity; the control
-# plane's --node-retention sweep reclaims the rows.
+# speaks MCP to it through the mesh, then reaches the services the SDK
+# canaries serve, and exits. The long-lived canaries only do this when a pod
+# restarts, so between rollouts nobody re-checks that a new user could still
+# join. Each run enrolls a fresh identity; the control plane's
+# --node-retention sweep reclaims the rows.
apiVersion: batch/v1
kind: CronJob
metadata:
@@ -19,8 +20,9 @@ spec:
# One attempt: a retry would hide exactly the flakiness this exists to
# measure. A failed Job is the signal.
backoffLimit: 0
- # 180s to be ready plus 120s to reach a provider, with headroom.
- activeDeadlineSeconds: 360
+ # 180s to be ready, 120s to reach a provider, 120s for the SDK
+ # canaries, with headroom.
+ activeDeadlineSeconds: 480
template:
metadata:
labels:
@@ -78,6 +80,10 @@ spec:
# The everything canary's MCP server (sam-node-everything-template.yaml):
# a real server, so the node advertises it and initialize succeeds.
value: everything
+ - name: SDK_SERVICES
+ # What the SDK canaries publish (sam-sdk-canary-template.yaml),
+ # each with a `greet` tool and an A2A endpoint.
+ value: "greeter-js greeter-py"
resources:
requests:
cpu: 10m
@@ -157,8 +163,57 @@ spec:
done
REACH_S=$(( $(date +%s) - REACH_START ))
- printf '{"probe":"sam-cold-path","ok":true,"ready_s":%d,"router_latency_ms":%s,"connected_peers":%s,"reach_s":%d,"providers_tried":%d,"call_s":%s,"provider":"%s","elapsed_s":%d}\n' \
- "$READY_S" "${ROUTER_MS:-null}" "${PEERS:-null}" "$REACH_S" "$TRIED" "$CALL_S" "$PEER" "$(( $(date +%s) - START ))"
+ # 4. A service an SDK member serves (sam-sdk-canary-template.yaml)
+ # is reachable from a node the way an agent behind a node
+ # reaches it: its MCP tool through the node's own MCP API
+ # (call_remote_tool opens /sam/mcp/1.0.0 to the provider), and
+ # its A2A endpoint through the egress proxy. The node's MCP
+ # endpoint is stateful, so one session is opened first.
+ MCP=http://localhost/mcp
+ SESSION=""
+ mcp_post() {
+ curl -s --unix-socket "$SOCK" -o "$2" -D /tmp/mcp.hdr -X POST "$MCP" \
+ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
+ ${SESSION:+-H "Mcp-Session-Id: $SESSION"} -d "$1"
+ }
+ mcp_post '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"sam-probe","version":"0"}}}' /tmp/mcp-init.out \
+ || fail sdk "initialize on the node's MCP API failed"
+ SESSION=$(grep -i '^mcp-session-id:' /tmp/mcp.hdr | tr -d '\r' | cut -d' ' -f2)
+ [ -n "$SESSION" ] || fail sdk "the node's MCP API returned no session"
+ mcp_post '{"jsonrpc":"2.0","method":"notifications/initialized"}' /dev/null
+
+ SDK_START=$(date +%s)
+ SDK_PROVIDERS=""
+ for svc in ${SDK_SERVICES}; do
+ SDK_PEER=""
+ LAST_ERR=""
+ while [ -z "$SDK_PEER" ]; do
+ if curl -sf --unix-socket "$SOCK" -o /tmp/sdk-providers.json \
+ "http://localhost/sam/service/discover?type=mcp&name=${svc}&timeout=20s"; then
+ for p in $(grep -oE '"peer_id":"[^"]+"' /tmp/sdk-providers.json | cut -d'"' -f4); do
+ mcp_post '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"call_remote_tool","arguments":{"peer_id":"'"$p"'","tool_name":"mcp://'"$svc"'/greet","arguments":{"name":"sam-probe"}}}}' /tmp/sdk-call.out
+ if grep -q 'hello sam-probe' /tmp/sdk-call.out; then
+ CODE=$(curl -s --unix-socket "$SOCK" -o /tmp/sdk-card.out -w '%{http_code}' "http://localhost/sam/${p}/a2a/${svc}/card")
+ if [ "$CODE" = "200" ] && grep -q '"caller"' /tmp/sdk-card.out; then
+ SDK_PEER=$p
+ break
+ fi
+ LAST_ERR="${p}: a2a card HTTP ${CODE} $(head -c 120 /tmp/sdk-card.out | tr -d '"\n')"
+ else
+ LAST_ERR="${p}: $(head -c 160 /tmp/sdk-call.out | tr -d '"\n')"
+ fi
+ done
+ fi
+ [ -n "$SDK_PEER" ] && break
+ [ $(( $(date +%s) - SDK_START )) -ge 120 ] && fail sdk "no provider of ${svc} answered greet and its card in 120s (last: ${LAST_ERR:-none discovered})"
+ sleep 5
+ done
+ SDK_PROVIDERS="${SDK_PROVIDERS}${SDK_PROVIDERS:+,}\"${svc}\":\"${SDK_PEER}\""
+ done
+ SDK_S=$(( $(date +%s) - SDK_START ))
+
+ printf '{"probe":"sam-cold-path","ok":true,"ready_s":%d,"router_latency_ms":%s,"connected_peers":%s,"reach_s":%d,"providers_tried":%d,"call_s":%s,"provider":"%s","sdk_s":%d,"sdk_providers":{%s},"elapsed_s":%d}\n' \
+ "$READY_S" "${ROUTER_MS:-null}" "${PEERS:-null}" "$REACH_S" "$TRIED" "$CALL_S" "$PEER" "$SDK_S" "$SDK_PROVIDERS" "$(( $(date +%s) - START ))"
volumes:
- name: config-volume
configMap:
diff --git a/.github/k8s/sam-sdk-canary-template.yaml b/.github/k8s/sam-sdk-canary-template.yaml
new file mode 100644
index 00000000..16fb75d7
--- /dev/null
+++ b/.github/k8s/sam-sdk-canary-template.yaml
@@ -0,0 +1,124 @@
+# Two members with no sam-node beside them: the JavaScript and Python SDK
+# example servers (sdk/js/examples/serve.ts, sdk/python/examples/serve.py),
+# unchanged, each publishing mcp://greeter-<lang> and a2a://greeter-<lang>.
+# They enroll with the pod's projected service account token, the way every
+# other canary does, and keep their identity in an emptyDir, so a restart
+# resumes and a new pod enrolls afresh. What the mesh sees from them is what a
+# user of the packages gets.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: js-canary-${ENV_NAME}
+ namespace: sam-canary-${ENV_NAME}
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: js-canary-${ENV_NAME}
+ template:
+ metadata:
+ labels:
+ app: js-canary-${ENV_NAME}
+ sam-canary: "true"
+ spec:
+ serviceAccountName: sam-node-sa
+ containers:
+ - name: sdk
+ image: ghcr.io/google/sam-sdk-js:${IMAGE_TAG}
+ args: ["build/examples/serve.js", "greeter-js"]
+ env:
+ - name: SAM_CONTROL_PLANE_URL
+ value: "http://sam-control-plane-${ENV_NAME}.${NAMESPACE}.svc.cluster.local:8080"
+ - name: SAM_INSECURE_CONTROL_PLANE
+ value: "true"
+ - name: SAM_JWT_PATH
+ value: /var/run/secrets/tokens/sam-token
+ - name: SAM_STATE_DIR
+ value: /var/run/sam/state
+ securityContext:
+ allowPrivilegeEscalation: false
+ capabilities:
+ drop: ["ALL"]
+ resources:
+ requests:
+ cpu: 50m
+ memory: 128Mi
+ limits:
+ cpu: 500m
+ memory: 512Mi
+ volumeMounts:
+ - name: sam-token
+ mountPath: /var/run/secrets/tokens
+ readOnly: true
+ - name: sam-state
+ mountPath: /var/run/sam
+ volumes:
+ - name: sam-state
+ emptyDir: {}
+ - name: sam-token
+ projected:
+ sources:
+ - serviceAccountToken:
+ path: sam-token
+ expirationSeconds: 3600
+ audience: "sam-control-plane-audience"
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: python-canary-${ENV_NAME}
+ namespace: sam-canary-${ENV_NAME}
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: python-canary-${ENV_NAME}
+ template:
+ metadata:
+ labels:
+ app: python-canary-${ENV_NAME}
+ sam-canary: "true"
+ spec:
+ serviceAccountName: sam-node-sa
+ containers:
+ - name: sdk
+ image: ghcr.io/google/sam-sdk-python:${IMAGE_TAG}
+ args: ["examples/serve.py", "greeter-py"]
+ env:
+ - name: SAM_CONTROL_PLANE_URL
+ value: "http://sam-control-plane-${ENV_NAME}.${NAMESPACE}.svc.cluster.local:8080"
+ - name: SAM_INSECURE_CONTROL_PLANE
+ value: "true"
+ - name: SAM_JWT_PATH
+ value: /var/run/secrets/tokens/sam-token
+ - name: SAM_STATE_DIR
+ value: /var/run/sam/state
+ - name: PYTHONUNBUFFERED
+ value: "1"
+ securityContext:
+ allowPrivilegeEscalation: false
+ capabilities:
+ drop: ["ALL"]
+ resources:
+ requests:
+ cpu: 50m
+ memory: 128Mi
+ limits:
+ cpu: 500m
+ memory: 512Mi
+ volumeMounts:
+ - name: sam-token
+ mountPath: /var/run/secrets/tokens
+ readOnly: true
+ - name: sam-state
+ mountPath: /var/run/sam
+ volumes:
+ - name: sam-state
+ emptyDir: {}
+ - name: sam-token
+ projected:
+ sources:
+ - serviceAccountToken:
+ path: sam-token
+ expirationSeconds: 3600
+ audience: "sam-control-plane-audience"
diff --git a/.github/k8s/sam-sdk-probe-cronjob-template.yaml b/.github/k8s/sam-sdk-probe-cronjob-template.yaml
new file mode 100644
index 00000000..a02239b9
--- /dev/null
+++ b/.github/k8s/sam-sdk-probe-cronjob-template.yaml
@@ -0,0 +1,183 @@
+# The cold path through the SDKs, on a schedule: a fresh identity enrolls with
+# the control plane through each SDK, joins through a router, and calls out
+# across every implementation boundary a user can cross: an MCP service a
+# sam-node serves (the everything canary), and an MCP tool and an A2A endpoint
+# the other language's SDK serves (the sdk canaries). The programs are the
+# examples the READMEs embed, unchanged; the shell around them only retries
+# discovery, which a member that joined seconds ago can miss, and prints one
+# verdict line. Each run enrolls a fresh identity per language; the control
+# plane's --node-retention sweep reclaims the rows.
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+ name: sam-sdk-probe-${ENV_NAME}
+ namespace: sam-canary-${ENV_NAME}
+spec:
+ schedule: "7,22,37,52 * * * *"
+ concurrencyPolicy: Forbid
+ successfulJobsHistoryLimit: 3
+ failedJobsHistoryLimit: 5
+ jobTemplate:
+ spec:
+ # One attempt: a retry would hide exactly the flakiness this exists to
+ # measure. A failed Job is the signal; both containers must succeed.
+ backoffLimit: 0
+ # Three calls with up to 120s of discovery each, plus enrollment.
+ activeDeadlineSeconds: 480
+ template:
+ metadata:
+ labels:
+ app: sam-sdk-probe-${ENV_NAME}
+ spec:
+ # Bound to the sam-canary role by deploy.yaml's policy seed, which
+ # is what lets the probe call the canaries' services.
+ serviceAccountName: sam-node-sa
+ restartPolicy: Never
+ containers:
+ - name: js
+ image: ghcr.io/google/sam-sdk-js:${IMAGE_TAG}
+ env:
+ - name: SAM_CONTROL_PLANE_URL
+ value: "http://sam-control-plane-${ENV_NAME}.${NAMESPACE}.svc.cluster.local:8080"
+ - name: SAM_INSECURE_CONTROL_PLANE
+ value: "true"
+ - name: SAM_JWT_PATH
+ value: /var/run/secrets/tokens/sam-token
+ - name: SAM_STATE_DIR
+ value: /var/run/sam/js
+ - name: PROBE
+ value: sam-sdk-js
+ - name: CALL
+ value: "node build/examples/call.js"
+ - name: PEER_SERVICE
+ # The other SDK's canary (sam-sdk-canary-template.yaml).
+ value: greeter-py
+ securityContext:
+ allowPrivilegeEscalation: false
+ capabilities:
+ drop: ["ALL"]
+ resources:
+ requests:
+ cpu: 50m
+ memory: 128Mi
+ limits:
+ cpu: 500m
+ memory: 512Mi
+ volumeMounts:
+ - name: sam-token
+ mountPath: /var/run/secrets/tokens
+ readOnly: true
+ - name: sam-state
+ mountPath: /var/run/sam
+ - name: probe-script
+ mountPath: /etc/sam-probe
+ readOnly: true
+ command: ["/bin/sh", "/etc/sam-probe/probe.sh"]
+ - name: python
+ image: ghcr.io/google/sam-sdk-python:${IMAGE_TAG}
+ env:
+ - name: SAM_CONTROL_PLANE_URL
+ value: "http://sam-control-plane-${ENV_NAME}.${NAMESPACE}.svc.cluster.local:8080"
+ - name: SAM_INSECURE_CONTROL_PLANE
+ value: "true"
+ - name: SAM_JWT_PATH
+ value: /var/run/secrets/tokens/sam-token
+ - name: SAM_STATE_DIR
+ value: /var/run/sam/python
+ - name: PYTHONUNBUFFERED
+ value: "1"
+ - name: PROBE
+ value: sam-sdk-python
+ - name: CALL
+ value: "python examples/call.py"
+ - name: PEER_SERVICE
+ value: greeter-js
+ securityContext:
+ allowPrivilegeEscalation: false
+ capabilities:
+ drop: ["ALL"]
+ resources:
+ requests:
+ cpu: 50m
+ memory: 128Mi
+ limits:
+ cpu: 500m
+ memory: 512Mi
+ volumeMounts:
+ - name: sam-token
+ mountPath: /var/run/secrets/tokens
+ readOnly: true
+ - name: sam-state
+ mountPath: /var/run/sam
+ - name: probe-script
+ mountPath: /etc/sam-probe
+ readOnly: true
+ command: ["/bin/sh", "/etc/sam-probe/probe.sh"]
+ volumes:
+ - name: sam-state
+ emptyDir: {}
+ - name: probe-script
+ configMap:
+ name: sam-sdk-probe-script-${ENV_NAME}
+ - name: sam-token
+ projected:
+ sources:
+ - serviceAccountToken:
+ path: sam-token
+ expirationSeconds: 3600
+ audience: "sam-control-plane-audience"
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: sam-sdk-probe-script-${ENV_NAME}
+ namespace: sam-canary-${ENV_NAME}
+data:
+ probe.sh: |
+ #!/bin/sh
+ # Runs the SDK's call example against three services and prints one JSON
+ # verdict line. PROBE names the run, CALL is the example's command line,
+ # PEER_SERVICE is the other SDK's canary. Discovery is retried: a member
+ # that joined seconds ago has a thin routing table, and a provider record
+ # can name a pod a rollout just replaced. The first call enrolls with the
+ # projected token; the later ones resume from SAM_STATE_DIR.
+ set -u
+ START=$(date +%s)
+
+ fail() {
+ printf '{"probe":"%s","ok":false,"stage":"%s","error":"%s","elapsed_s":%d}\n' \
+ "$PROBE" "$1" "$(printf '%s' "$2" | tr -d '"\n' | cut -c1-300)" "$(( $(date +%s) - START ))"
+ exit 1
+ }
+
+ # call <stage> <expected substring> <example arguments...>; sets PROVIDER.
+ call() {
+ stage=$1; want=$2; shift 2
+ stage_start=$(date +%s)
+ attempts=0
+ while :; do
+ attempts=$((attempts + 1))
+ out=$($CALL "$@" 2>&1); rc=$?
+ if [ $rc -eq 0 ] && printf '%s' "$out" | grep -q "$want"; then
+ PROVIDER=$(printf '%s' "$out" | grep -o 'is served by [^ ]*' | tail -1 | cut -d' ' -f4)
+ return 0
+ fi
+ [ $(( $(date +%s) - stage_start )) -ge 120 ] && fail "$stage" "no answer with '$want' in 120s ($attempts attempts; last: $(printf '%s' "$out" | tail -c 200))"
+ sleep 5
+ done
+ }
+
+ # 1. Enroll, join and call an MCP service a sam-node serves.
+ call node-mcp 'Echo: sam-sdk-probe' mcp://everything echo '{"message": "sam-sdk-probe"}'
+ NODE_PEER=$PROVIDER
+ NODE_S=$(( $(date +%s) - START ))
+
+ # 2. The other SDK's MCP tool, then its A2A endpoint over /libp2p-http.
+ SDK_START=$(date +%s)
+ call sdk-mcp 'hello sam-sdk-probe' "mcp://${PEER_SERVICE}" greet '{"name": "sam-sdk-probe"}'
+ SDK_PEER=$PROVIDER
+ call sdk-a2a '"caller"' "a2a://${PEER_SERVICE}" /card
+ SDK_S=$(( $(date +%s) - SDK_START ))
+
+ printf '{"probe":"%s","ok":true,"node_s":%d,"node_provider":"%s","sdk_s":%d,"sdk_provider":"%s","elapsed_s":%d}\n' \
+ "$PROBE" "$NODE_S" "$NODE_PEER" "$SDK_S" "$SDK_PEER" "$(( $(date +%s) - START ))"
diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
index b6b40def..84425cc3 100644
--- a/.github/workflows/deploy.yaml
+++ b/.github/workflows/deploy.yaml
@@ -208,6 +208,54 @@ jobs:
tags: ${{ steps.meta-sam-one.outputs.tags }}
labels: ${{ steps.meta-sam-one.outputs.labels }}
+ # The SDK images carry the example programs the docs embed, as the
+ # testnet canaries and probes run them. Built from the commit, not from
+ # npm or PyPI, so bananas exercises the SDK at the same commit as the
+ # Go components it talks to.
+ - name: Extract metadata for sam-sdk-js
+ id: meta-sdk-js
+ uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+ with:
+ images: ${{ env.REGISTRY }}/google/sam-sdk-js
+ tags: |
+ type=ref,event=branch
+ type=ref,event=tag
+ type=raw,value=${{ github.sha }}
+ type=raw,value=latest,enable={{is_default_branch}}
+ type=raw,value=stable,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+
+ - name: Build and push sam-sdk-js image
+ uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+ with:
+ context: .
+ file: Dockerfile.sam-sdk-js
+ platforms: ${{ github.ref_type == 'tag' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
+ push: true
+ tags: ${{ steps.meta-sdk-js.outputs.tags }}
+ labels: ${{ steps.meta-sdk-js.outputs.labels }}
+
+ - name: Extract metadata for sam-sdk-python
+ id: meta-sdk-python
+ uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+ with:
+ images: ${{ env.REGISTRY }}/google/sam-sdk-python
+ tags: |
+ type=ref,event=branch
+ type=ref,event=tag
+ type=raw,value=${{ github.sha }}
+ type=raw,value=latest,enable={{is_default_branch}}
+ type=raw,value=stable,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+
+ - name: Build and push sam-sdk-python image
+ uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+ with:
+ context: .
+ file: Dockerfile.sam-sdk-python
+ platforms: ${{ github.ref_type == 'tag' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
+ push: true
+ tags: ${{ steps.meta-sdk-python.outputs.tags }}
+ labels: ${{ steps.meta-sdk-python.outputs.labels }}
+
deploy:
name: Deploy to GKE
runs-on: ubuntu-latest
@@ -758,6 +806,35 @@ jobs:
exit 1
}
+ # Two members with no sam-node: the SDK example servers, each
+ # publishing an MCP tool and an A2A endpoint. What the probes below
+ # reach from a node and from the other SDK.
+ - name: Deploy SDK Canaries
+ env:
+ VAR_ENV_NAME: ${{ vars.ENV_NAME }}
+ VAR_IMAGE_TAG: ${{ env.IMAGE_TAG }}
+ run: |
+ export ENV_NAME="${VAR_ENV_NAME}"
+ export CANARY_NAMESPACE="sam-canary-${ENV_NAME}"
+ export NAMESPACE="sam-${ENV_NAME}"
+ export IMAGE_TAG="${VAR_IMAGE_TAG}"
+
+ envsubst '${ENV_NAME} ${NAMESPACE} ${IMAGE_TAG}' < .github/k8s/sam-sdk-canary-template.yaml | kubectl apply -f -
+ for lang in js python; do
+ kubectl rollout status deployment/${lang}-canary-${ENV_NAME} -n ${CANARY_NAMESPACE} --timeout=180s || {
+ echo "${lang} SDK canary deployment failed!"
+ kubectl describe deployment/${lang}-canary-${ENV_NAME} -n ${CANARY_NAMESPACE} || true
+ kubectl get pods -n ${CANARY_NAMESPACE} -l app=${lang}-canary-${ENV_NAME} -o wide || true
+ kubectl describe pods -n ${CANARY_NAMESPACE} -l app=${lang}-canary-${ENV_NAME} || true
+ kubectl logs -n ${CANARY_NAMESPACE} -l app=${lang}-canary-${ENV_NAME} --tail=-1 || true
+
+ echo "Rolling back ${lang} SDK canary deployment..."
+ kubectl rollout undo deployment/${lang}-canary-${ENV_NAME} -n ${CANARY_NAMESPACE}
+ kubectl rollout status deployment/${lang}-canary-${ENV_NAME} -n ${CANARY_NAMESPACE} || true
+ exit 1
+ }
+ done
+
- name: Deploy OpenRouter Node to Testnet
env:
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -857,3 +934,47 @@ jobs:
;;
esac
+ # The same cold path through each SDK: a fresh identity enrolls with
+ # the JavaScript and the Python SDK, reaches the everything canary's
+ # MCP server (a sam-node) and the other SDK's canary, MCP and A2A. With
+ # the node probe above, every pair of implementations is crossed in
+ # both directions on every rollout and every 15 minutes after.
+ - name: Deploy and run the SDK cold-path probe
+ env:
+ VAR_ENV_NAME: ${{ vars.ENV_NAME }}
+ VAR_IMAGE_TAG: ${{ env.IMAGE_TAG }}
+ run: |
+ export ENV_NAME="${VAR_ENV_NAME}"
+ export CANARY_NAMESPACE="sam-canary-${ENV_NAME}"
+ export NAMESPACE="sam-${ENV_NAME}"
+ export IMAGE_TAG="${VAR_IMAGE_TAG}"
+ JOB="sam-sdk-probe-rollout-${ENV_NAME}"
+
+ envsubst '${ENV_NAME} ${NAMESPACE} ${IMAGE_TAG}' < .github/k8s/sam-sdk-probe-cronjob-template.yaml | kubectl apply -f -
+
+ kubectl delete job "${JOB}" -n "${CANARY_NAMESPACE}" --ignore-not-found
+ kubectl create job --from="cronjob/sam-sdk-probe-${ENV_NAME}" "${JOB}" -n "${CANARY_NAMESPACE}"
+
+ for _ in $(seq 1 96); do
+ status=$(kubectl get job "${JOB}" -n "${CANARY_NAMESPACE}" -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}')
+ case "${status}" in
+ *Complete=True*) break ;;
+ *Failed=True*) break ;;
+ esac
+ sleep 5
+ done
+
+ for lang in js python; do
+ echo "==== ${lang} SDK probe output ===="
+ kubectl logs "job/${JOB}" -n "${CANARY_NAMESPACE}" -c "${lang}" --tail=-1 || true
+ done
+
+ case "${status:-}" in
+ *Complete=True*) echo "SDK cold-path probe passed." ;;
+ *)
+ echo "SDK cold-path probe did not pass: an SDK could not enroll, reach a router, or call a service a node or the other SDK serves."
+ kubectl describe job "${JOB}" -n "${CANARY_NAMESPACE}" || true
+ exit 1
+ ;;
+ esac
+
diff --git a/.github/workflows/sdk.yml b/.github/workflows/sdk.yml
index 21044d87..1e83b8bf 100644
--- a/.github/workflows/sdk.yml
+++ b/.github/workflows/sdk.yml
@@ -30,6 +30,7 @@ on:
- 'hack/verify-sdk-generated.sh'
- 'site/content/docs/guides/native-sdks.md'
- 'tests/integration/sdk_*_test.go'
+ - 'Dockerfile.sam-sdk-*'
- '.github/workflows/sdk.yml'
pull_request:
branches: [main]
@@ -41,6 +42,7 @@ on:
- 'hack/verify-sdk-generated.sh'
- 'site/content/docs/guides/native-sdks.md'
- 'tests/integration/sdk_*_test.go'
+ - 'Dockerfile.sam-sdk-*'
- '.github/workflows/sdk.yml'
permissions:
@@ -88,3 +90,13 @@ jobs:
- name: Both SDKs and the documented examples on a mesh with a real control plane, router and sam-node
run: go test ./tests/integration -run TestNativeSDK -count=1 -v
+
+ # The images the testnets run the examples from (deploy.yaml builds and
+ # pushes them on main); built here so a broken Dockerfile fails the
+ # pull request, not the deploy.
+ - name: SDK canary images build
+ run: |
+ docker build -f Dockerfile.sam-sdk-js -t sam-sdk-js:ci .
+ docker build -f Dockerfile.sam-sdk-python -t sam-sdk-python:ci .
+ docker run --rm sam-sdk-js:ci build/examples/call.js 2>&1 | grep -q 'exactly one of'
+ docker run --rm sam-sdk-python:ci examples/call.py 2>&1 | grep -q 'exactly one of'
diff --git a/Dockerfile.sam-sdk-js b/Dockerfile.sam-sdk-js
new file mode 100644
index 00000000..c9b6fd0a
--- /dev/null
+++ b/Dockerfile.sam-sdk-js
@@ -0,0 +1,26 @@
+# The JavaScript SDK with its example programs, as the testnet canaries run
+# them: `node build/examples/serve.js <name>` publishes services on the mesh,
+# `node build/examples/call.js <service> <tool|path> [args]` calls one. The
+# examples import "@sam-mesh/sdk" by name and resolve it through the package's
+# own exports, so the image keeps the package layout: package.json, dist/,
+# build/examples/ and the production node_modules/.
+
+# Stage 1: Build
+FROM node:22-bookworm-slim@sha256:43ac6c60b8f89723f746e8a92ce91abd5017e627ce1ddfe4238355d3a30b772c AS builder
+WORKDIR /src
+COPY sdk/js/package.json sdk/js/package-lock.json sdk/js/.npmrc ./
+RUN npm ci --no-fund --no-audit
+COPY sdk/js/ ./
+RUN npm run build && npm run examples && npm prune --omit=dev --no-fund --no-audit
+
+# Stage 2: Final
+FROM node:22-bookworm-slim@sha256:43ac6c60b8f89723f746e8a92ce91abd5017e627ce1ddfe4238355d3a30b772c
+WORKDIR /app
+COPY --from=builder --chown=node:node /src/package.json ./
+COPY --from=builder --chown=node:node /src/dist ./dist
+COPY --from=builder --chown=node:node /src/build/examples ./build/examples
+COPY --from=builder --chown=node:node /src/node_modules ./node_modules
+USER node
+ENV HOME=/home/node
+ENTRYPOINT ["node"]
+CMD ["build/examples/serve.js"]
diff --git a/Dockerfile.sam-sdk-python b/Dockerfile.sam-sdk-python
new file mode 100644
index 00000000..d7ba4094
--- /dev/null
+++ b/Dockerfile.sam-sdk-python
@@ -0,0 +1,23 @@
+# The Python SDK with its example programs, as the testnet canaries run them:
+# `python examples/serve.py <name>` publishes services on the mesh,
+# `python examples/call.py <service> <tool|path> [args]` calls one. fastecdsa,
+# a py-libp2p dependency, builds from source against GMP, so the build stage
+# carries a compiler and the final image only libgmp10.
+
+# Stage 1: Build
+FROM python:3.12-slim-bookworm@sha256:392307d22300de8b5986851a12d9176dfc0fc073e65bf6523ebd7dcbeb23564e AS builder
+RUN apt-get update && apt-get install -y --no-install-recommends gcc libgmp-dev python3-dev && rm -rf /var/lib/apt/lists/*
+COPY sdk/python /src
+RUN python -m venv /opt/venv && /opt/venv/bin/pip install --no-cache-dir /src
+
+# Stage 2: Final
+FROM python:3.12-slim-bookworm@sha256:392307d22300de8b5986851a12d9176dfc0fc073e65bf6523ebd7dcbeb23564e
+RUN apt-get update && apt-get install -y --no-install-recommends libgmp10 && rm -rf /var/lib/apt/lists/* \
+ && groupadd --gid 65532 nonroot && useradd --uid 65532 --gid nonroot --create-home nonroot
+WORKDIR /app
+COPY --from=builder --chown=nonroot:nonroot /opt/venv /opt/venv
+COPY --chown=nonroot:nonroot sdk/python/examples ./examples
+USER nonroot:nonroot
+ENV PATH=/opt/venv/bin:$PATH
+ENTRYPOINT ["python"]
+CMD ["examples/serve.py"]
diff --git a/sdk/README.md b/sdk/README.md
index b3d1cf7f..98791462 100644
--- a/sdk/README.md
+++ b/sdk/README.md
@@ -436,6 +436,22 @@ holds against the control plane's records.
that verifies only under the new one, and still authenticating with the
`sam-node`.
+### On the testnets
+
+Both testnets run the example programs, unchanged, as canaries beside the
+`sam-node` ones (`.github/k8s/sam-sdk-canary-template.yaml`): the JavaScript
+and the Python `serve` publish `mcp://greeter-js` / `a2a://greeter-js` and
+`…-py`, enrolled with the pod's projected service account token through
+`SAM_JWT_PATH`. Two CronJobs cross every implementation boundary every 15
+minutes and once per rollout: the `sam-node` cold-path probe now also calls
+both greeters (node → SDK, MCP through `call_remote_tool` and A2A through
+the egress proxy), and the SDK cold-path probe
+(`sam-sdk-probe-cronjob-template.yaml`) runs each SDK's `call` against the
+everything canary (SDK → node) and the other SDK's greeter (SDK → SDK). The
+images (`Dockerfile.sam-sdk-js`, `Dockerfile.sam-sdk-python`) are built per
+commit by `deploy.yaml`, so `bananas` runs the SDKs at the same commit as
+the Go components they talk to.
+
### Later
- The connector interface for platforms (issue #480): `Attach`, `Detach`,
diff --git a/sdk/js/README.md b/sdk/js/README.md
index 4a526932..135390d5 100644
--- a/sdk/js/README.md
+++ b/sdk/js/README.md
@@ -38,10 +38,11 @@ Find a service and call it:
// node call.js a2a://greeter /card
// node call.js inference://ollama /v1/models
//
-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-// holding the token the mesh operator gave you; the first run spends it and
-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-// there without it.
+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or
+// SAM_JWT_PATH (a workload identity token your platform issues, such as a
+// Kubernetes projected service account token), and keeps the identity and
+// credential in SAM_STATE_DIR; later runs resume from there without it.
import { homedir } from "node:os";
import { AgentMesh } from "@sam-mesh/sdk";
@@ -50,7 +51,10 @@ const [service = "mcp://greeter", toolOrPath = "greet", args = '{"name": "world"
const mesh = await AgentMesh.enroll({
controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,
+ jwtPath: process.env.SAM_JWT_PATH,
stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/caller`,
+ // A plaintext http:// control plane is otherwise accepted only on loopback.
+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",
});
const session = await mesh.join();
console.log(`on the mesh as ${session.peerId}`);
@@ -85,31 +89,38 @@ Publish services of your own:
// members may call; the SDK turns the others away before anything reaches
// this code or Ollama.
//
-// node serve.js
+// node serve.js # publishes mcp://greeter and a2a://greeter
+// node serve.js greeter-2 # the same under another name
//
-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-// holding the token the mesh operator gave you; the first run spends it and
-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-// there without it.
+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or
+// SAM_JWT_PATH (a workload identity token your platform issues, such as a
+// Kubernetes projected service account token), and keeps the identity and
+// credential in SAM_STATE_DIR; later runs resume from there without it.
import { homedir } from "node:os";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { AgentMesh } from "@sam-mesh/sdk";
import { z } from "zod";
+const [name = "greeter"] = process.argv.slice(2);
+
const mesh = await AgentMesh.enroll({
controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,
- stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/greeter`,
+ jwtPath: process.env.SAM_JWT_PATH,
+ stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/${name}`,
+ // A plaintext http:// control plane is otherwise accepted only on loopback.
+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",
});
const session = await mesh.join();
await session.serve({
type: "mcp",
- name: "greeter",
+ name,
createServer: () => {
- const server = new McpServer({ name: "greeter", version: "1.0.0" });
- server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name }) => ({
- content: [{ type: "text", text: `hello ${name}` }],
+ const server = new McpServer({ name, version: "1.0.0" });
+ server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name: who }) => ({
+ content: [{ type: "text", text: `hello ${who}` }],
}));
return server;
},
@@ -117,8 +128,8 @@ await session.serve({
await session.serve({
type: "a2a",
- name: "greeter",
- target: (request, caller) => Response.json({ name: "greeter", path: new URL(request.url).pathname, caller: caller.peerId }),
+ name,
+ target: (request, caller) => Response.json({ name, path: new URL(request.url).pathname, caller: caller.peerId }),
});
if (process.env.OLLAMA_URL !== undefined) {
diff --git a/sdk/js/examples/call.ts b/sdk/js/examples/call.ts
index ddccacb6..124003c4 100644
--- a/sdk/js/examples/call.ts
+++ b/sdk/js/examples/call.ts
@@ -5,10 +5,11 @@
// node call.js a2a://greeter /card
// node call.js inference://ollama /v1/models
//
-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-// holding the token the mesh operator gave you; the first run spends it and
-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-// there without it.
+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or
+// SAM_JWT_PATH (a workload identity token your platform issues, such as a
+// Kubernetes projected service account token), and keeps the identity and
+// credential in SAM_STATE_DIR; later runs resume from there without it.
import { homedir } from "node:os";
import { AgentMesh } from "@sam-mesh/sdk";
@@ -17,7 +18,10 @@ const [service = "mcp://greeter", toolOrPath = "greet", args = '{"name": "world"
const mesh = await AgentMesh.enroll({
controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,
+ jwtPath: process.env.SAM_JWT_PATH,
stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/caller`,
+ // A plaintext http:// control plane is otherwise accepted only on loopback.
+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",
});
const session = await mesh.join();
console.log(`on the mesh as ${session.peerId}`);
diff --git a/sdk/js/examples/serve.ts b/sdk/js/examples/serve.ts
index a3c3fca0..18a75a69 100644
--- a/sdk/js/examples/serve.ts
+++ b/sdk/js/examples/serve.ts
@@ -4,31 +4,38 @@
// members may call; the SDK turns the others away before anything reaches
// this code or Ollama.
//
-// node serve.js
+// node serve.js # publishes mcp://greeter and a2a://greeter
+// node serve.js greeter-2 # the same under another name
//
-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-// holding the token the mesh operator gave you; the first run spends it and
-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-// there without it.
+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or
+// SAM_JWT_PATH (a workload identity token your platform issues, such as a
+// Kubernetes projected service account token), and keeps the identity and
+// credential in SAM_STATE_DIR; later runs resume from there without it.
import { homedir } from "node:os";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { AgentMesh } from "@sam-mesh/sdk";
import { z } from "zod";
+const [name = "greeter"] = process.argv.slice(2);
+
const mesh = await AgentMesh.enroll({
controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,
- stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/greeter`,
+ jwtPath: process.env.SAM_JWT_PATH,
+ stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/${name}`,
+ // A plaintext http:// control plane is otherwise accepted only on loopback.
+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",
});
const session = await mesh.join();
await session.serve({
type: "mcp",
- name: "greeter",
+ name,
createServer: () => {
- const server = new McpServer({ name: "greeter", version: "1.0.0" });
- server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name }) => ({
- content: [{ type: "text", text: `hello ${name}` }],
+ const server = new McpServer({ name, version: "1.0.0" });
+ server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name: who }) => ({
+ content: [{ type: "text", text: `hello ${who}` }],
}));
return server;
},
@@ -36,8 +43,8 @@ await session.serve({
await session.serve({
type: "a2a",
- name: "greeter",
- target: (request, caller) => Response.json({ name: "greeter", path: new URL(request.url).pathname, caller: caller.peerId }),
+ name,
+ target: (request, caller) => Response.json({ name, path: new URL(request.url).pathname, caller: caller.peerId }),
});
if (process.env.OLLAMA_URL !== undefined) {
diff --git a/sdk/js/src/mesh.test.ts b/sdk/js/src/mesh.test.ts
index 500234bd..53206dd6 100644
--- a/sdk/js/src/mesh.test.ts
+++ b/sdk/js/src/mesh.test.ts
@@ -24,6 +24,8 @@ import {
AuthFrameSchema,
AuthResponseSchema,
BootstrapEnrollResponseSchema,
+ EnrollRequestSchema,
+ EnrollResponseSchema,
EnrollmentStatus,
KeysResponseSchema,
TokenRefreshResponseSchema,
@@ -66,6 +68,22 @@ function fakeControlPlane(keysOk = true): { fetch: typeof fetch; issued: number
case "POST /refresh":
state.issued++;
return proto(toBinary(TokenRefreshResponseSchema, create(TokenRefreshResponseSchema, { biscuitToken: text(`biscuit-${state.issued}`), expireTime: timestampFromMs(Date.now() + 7200_000) })));
+ case "POST /register": {
+ // The biscuit names the JWT that was presented, so a test can see which.
+ const jwt = fromBinary(EnrollRequestSchema, new Uint8Array(await req.arrayBuffer())).jwt;
+ state.issued++;
+ return proto(
+ toBinary(
+ EnrollResponseSchema,
+ create(EnrollResponseSchema, {
+ biscuitToken: text(`biscuit-for-${jwt}`),
+ controlPlanePublicKey: cpKey.publicKeyRaw,
+ routerAddresses: ["/dns4/router.example/tcp/4001/p2p/12D3KooWP8iKhDf3iCMo2H3butNVfdTUtYwYWYQ75jTGnynXPFMp"],
+ expireTime: timestampFromMs(Date.now() + 3600_000),
+ }),
+ ),
+ );
+ }
case "GET /keys":
return keysOk ? proto(toBinary(KeysResponseSchema, signedKeys())) : new Response("boom", { status: 500 });
default:
@@ -161,9 +179,24 @@ test("enroll refuses ambiguous credentials", async () => {
const cp = fakeControlPlane();
await assert.rejects(AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", fetch: cp.fetch }), /exactly one of/);
await assert.rejects(AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "a", jwt: "b", fetch: cp.fetch }), /exactly one of/);
+ await assert.rejects(AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", jwt: "a", jwtPath: "/nonexistent", fetch: cp.fetch }), /exactly one of/);
assert.equal(cp.issued, 0);
});
+test("enroll reads a workload identity token from jwtPath", async () => {
+ const dir = await mkdtemp(join(tmpdir(), "sam-sdk-"));
+ try {
+ const cp = fakeControlPlane();
+ const jwtPath = join(dir, "token");
+ await writeFile(jwtPath, "eyJ.projected.token\n");
+ const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", jwtPath, fetch: cp.fetch });
+ assert.deepEqual(mesh.credential.biscuit, text("biscuit-for-eyJ.projected.token"));
+ await assert.rejects(AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", jwtPath: join(dir, "missing"), fetch: cp.fetch }), /ENOENT/);
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
test("authFrame is the AuthFrame protobuf with this member's biscuit", async () => {
const cp = fakeControlPlane();
const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt_secret", fetch: cp.fetch });
diff --git a/sdk/js/src/mesh.ts b/sdk/js/src/mesh.ts
index 85cbafab..d5192207 100644
--- a/sdk/js/src/mesh.ts
+++ b/sdk/js/src/mesh.ts
@@ -51,6 +51,12 @@ export interface EnrollOptions extends AgentMeshOptions {
bootstrapTokenPath?: string | undefined;
/** An OIDC ID token, for meshes that enroll identities interactively. */
jwt?: string | undefined;
+ /**
+ * Path of a file holding an OIDC ID token or a platform's workload identity
+ * token, such as a Kubernetes projected service account token. Preferred
+ * over a value; the file is read at enrollment.
+ */
+ jwtPath?: string | undefined;
/** Bounds the wait for an operator to approve a pending enrollment. */
signal?: AbortSignal;
/** Overrides the control plane's suggested poll interval while pending. */
@@ -104,8 +110,8 @@ export class AgentMesh {
* plane for the saved identity, that member is returned and no token is
* needed, so a program can call enroll on every start and read the token
* from its environment only on the first. Otherwise exactly one of
- * bootstrapToken, bootstrapTokenPath or jwt must be given. Delete the
- * state directory to enroll afresh, for instance with other labels.
+ * bootstrapToken, bootstrapTokenPath, jwt or jwtPath must be given. Delete
+ * the state directory to enroll afresh, for instance with other labels.
*/
static async enroll(options: EnrollOptions): Promise<AgentMesh> {
const saved = await loadIdentity(options.stateDir);
@@ -117,16 +123,17 @@ export class AgentMesh {
return new AgentMesh(identity, controlPlane, credential, options.stateDir);
}
}
- const given = [options.bootstrapToken, options.bootstrapTokenPath, options.jwt].filter((v) => v !== undefined).length;
+ const given = [options.bootstrapToken, options.bootstrapTokenPath, options.jwt, options.jwtPath].filter((v) => v !== undefined).length;
if (given !== 1) {
const where = options.stateDir !== undefined ? ` (no credential to resume in ${options.stateDir})` : "";
- throw new Error(`exactly one of bootstrapToken, bootstrapTokenPath or jwt is required${where}`);
+ throw new Error(`exactly one of bootstrapToken, bootstrapTokenPath, jwt or jwtPath is required${where}`);
}
const role = options.role ?? ROLE_NODE;
let enrollment: Enrollment;
- if (options.jwt !== undefined) {
- enrollment = await controlPlane.register({ identity, jwt: options.jwt, role, ...labelsOf(options) });
+ if (options.jwt !== undefined || options.jwtPath !== undefined) {
+ const jwt = options.jwtPath !== undefined ? (await readFile(options.jwtPath, "utf8")).trim() : (options.jwt as string);
+ enrollment = await controlPlane.register({ identity, jwt, role, ...labelsOf(options) });
} else {
const bootstrapToken = options.bootstrapTokenPath !== undefined ? (await readFile(options.bootstrapTokenPath, "utf8")).trim() : (options.bootstrapToken as string);
enrollment = await controlPlane.enrollBootstrap({
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 7a6288c8..b5f800f9 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -41,10 +41,11 @@ path of an inference or A2A service.
python call.py a2a://greeter /card
python call.py inference://ollama /v1/models
-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-holding the token the mesh operator gave you; the first run spends it and
-keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-there without it.
+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH
+(a workload identity token your platform issues, such as a Kubernetes
+projected service account token), and keeps the identity and credential in
+SAM_STATE_DIR; later runs resume from there without it.
"""
import json
@@ -62,7 +63,10 @@ args = json.loads(argv[2]) if len(argv) > 2 else {"name": "world"}
mesh = AgentMesh.enroll(
os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),
bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),
+ jwt_path=os.environ.get("SAM_JWT_PATH"),
state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/caller"),
+ # A plaintext http:// control plane is otherwise accepted only on loopback.
+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",
)
@@ -100,30 +104,38 @@ beside this program as an inference service. The mesh policy decides which
members may call; the SDK turns the others away before anything reaches this
code or Ollama.
- python serve.py
+ python serve.py # publishes mcp://greeter and a2a://greeter
+ python serve.py greeter-2 # the same under another name
-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-holding the token the mesh operator gave you; the first run spends it and
-keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-there without it.
+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH
+(a workload identity token your platform issues, such as a Kubernetes
+projected service account token), and keeps the identity and credential in
+SAM_STATE_DIR; later runs resume from there without it.
"""
import json
import os
+import sys
import trio
from agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, HTTPService, MCPService, VerifiedBiscuit
from mcp.server.mcpserver import MCPServer
+service_name = sys.argv[1] if len(sys.argv) > 1 else "greeter"
+
mesh = AgentMesh.enroll(
os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),
bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),
- state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/greeter"),
+ jwt_path=os.environ.get("SAM_JWT_PATH"),
+ state_dir=os.environ.get("SAM_STATE_DIR", f"~/.config/sam-mesh/{service_name}"),
+ # A plaintext http:// control plane is otherwise accepted only on loopback.
+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",
)
def create_server() -> MCPServer:
- server = MCPServer("greeter")
+ server = MCPServer(service_name)
@server.tool(description="Greets someone by name")
def greet(name: str) -> str:
@@ -133,14 +145,14 @@ def create_server() -> MCPServer:
async def card(request: HTTPRequest, caller: VerifiedBiscuit) -> HTTPResponse:
- body = json.dumps({"name": "greeter", "path": request.path, "caller": caller.peer_id})
+ body = json.dumps({"name": service_name, "path": request.path, "caller": caller.peer_id})
return HTTPResponse(status=200, headers={"content-type": "application/json"}, body=body.encode())
async def main() -> None:
async with mesh.join() as session:
- await session.serve(MCPService(name="greeter", create_server=create_server))
- await session.serve(HTTPService(type="a2a", name="greeter", target=card))
+ await session.serve(MCPService(name=service_name, create_server=create_server))
+ await session.serve(HTTPService(type="a2a", name=service_name, target=card))
if "OLLAMA_URL" in os.environ:
await session.serve(HTTPService(type="inference", name="ollama", target=os.environ["OLLAMA_URL"]))
diff --git a/sdk/python/examples/call.py b/sdk/python/examples/call.py
index 721838dc..f37c1985 100644
--- a/sdk/python/examples/call.py
+++ b/sdk/python/examples/call.py
@@ -5,10 +5,11 @@ path of an inference or A2A service.
python call.py a2a://greeter /card
python call.py inference://ollama /v1/models
-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-holding the token the mesh operator gave you; the first run spends it and
-keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-there without it.
+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH
+(a workload identity token your platform issues, such as a Kubernetes
+projected service account token), and keeps the identity and credential in
+SAM_STATE_DIR; later runs resume from there without it.
"""
import json
@@ -26,7 +27,10 @@ args = json.loads(argv[2]) if len(argv) > 2 else {"name": "world"}
mesh = AgentMesh.enroll(
os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),
bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),
+ jwt_path=os.environ.get("SAM_JWT_PATH"),
state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/caller"),
+ # A plaintext http:// control plane is otherwise accepted only on loopback.
+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",
)
diff --git a/sdk/python/examples/serve.py b/sdk/python/examples/serve.py
index 7f5e2935..6821732a 100644
--- a/sdk/python/examples/serve.py
+++ b/sdk/python/examples/serve.py
@@ -4,30 +4,38 @@ beside this program as an inference service. The mesh policy decides which
members may call; the SDK turns the others away before anything reaches this
code or Ollama.
- python serve.py
-
-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-holding the token the mesh operator gave you; the first run spends it and
-keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-there without it.
+ python serve.py # publishes mcp://greeter and a2a://greeter
+ python serve.py greeter-2 # the same under another name
+
+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH
+(a workload identity token your platform issues, such as a Kubernetes
+projected service account token), and keeps the identity and credential in
+SAM_STATE_DIR; later runs resume from there without it.
"""
import json
import os
+import sys
import trio
from agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, HTTPService, MCPService, VerifiedBiscuit
from mcp.server.mcpserver import MCPServer
+service_name = sys.argv[1] if len(sys.argv) > 1 else "greeter"
+
mesh = AgentMesh.enroll(
os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),
bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),
- state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/greeter"),
+ jwt_path=os.environ.get("SAM_JWT_PATH"),
+ state_dir=os.environ.get("SAM_STATE_DIR", f"~/.config/sam-mesh/{service_name}"),
+ # A plaintext http:// control plane is otherwise accepted only on loopback.
+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",
)
def create_server() -> MCPServer:
- server = MCPServer("greeter")
+ server = MCPServer(service_name)
@server.tool(description="Greets someone by name")
def greet(name: str) -> str:
@@ -37,14 +45,14 @@ def create_server() -> MCPServer:
async def card(request: HTTPRequest, caller: VerifiedBiscuit) -> HTTPResponse:
- body = json.dumps({"name": "greeter", "path": request.path, "caller": caller.peer_id})
+ body = json.dumps({"name": service_name, "path": request.path, "caller": caller.peer_id})
return HTTPResponse(status=200, headers={"content-type": "application/json"}, body=body.encode())
async def main() -> None:
async with mesh.join() as session:
- await session.serve(MCPService(name="greeter", create_server=create_server))
- await session.serve(HTTPService(type="a2a", name="greeter", target=card))
+ await session.serve(MCPService(name=service_name, create_server=create_server))
+ await session.serve(HTTPService(type="a2a", name=service_name, target=card))
if "OLLAMA_URL" in os.environ:
await session.serve(HTTPService(type="inference", name="ollama", target=os.environ["OLLAMA_URL"]))
diff --git a/sdk/python/src/agent_mesh/mesh.py b/sdk/python/src/agent_mesh/mesh.py
index 748c006e..ce1b642b 100644
--- a/sdk/python/src/agent_mesh/mesh.py
+++ b/sdk/python/src/agent_mesh/mesh.py
@@ -74,6 +74,7 @@ class AgentMesh:
bootstrap_token: Optional[str] = None,
bootstrap_token_path: Optional[str | os.PathLike[str]] = None,
jwt: Optional[str] = None,
+ jwt_path: Optional[str | os.PathLike[str]] = None,
state_dir: Optional[str | os.PathLike[str]] = None,
identity: Optional[Identity] = None,
role: str = ROLE_NODE,
@@ -89,9 +90,11 @@ class AgentMesh:
plane for the saved identity, that member is returned and no token is
needed, so a program can call enroll on every start and read the token
from its environment only on the first. Otherwise exactly one of
- bootstrap_token, bootstrap_token_path or jwt must be given; a token is
- better read from a file than passed as a value. Delete the state
- directory to enroll afresh, for instance with other labels."""
+ bootstrap_token, bootstrap_token_path, jwt or jwt_path must be given; a
+ token is better read from a file than passed as a value, and jwt_path
+ also takes a platform's workload identity token, such as a Kubernetes
+ projected service account token. Delete the state directory to enroll
+ afresh, for instance with other labels."""
state = Path(state_dir).expanduser() if state_dir is not None else None
saved = _load_identity(state)
identity = identity or saved or Identity.generate()
@@ -100,13 +103,16 @@ class AgentMesh:
credential = _load_credential(state)
if credential is not None and credential.control_plane_url.rstrip("/") == control_plane.url.rstrip("/") and credential.time_to_live_seconds() > _REUSE_MIN_TTL_SECONDS:
return cls(identity, control_plane, credential, state)
- given = sum(v is not None for v in (bootstrap_token, bootstrap_token_path, jwt))
+ given = sum(v is not None for v in (bootstrap_token, bootstrap_token_path, jwt, jwt_path))
if given != 1:
where = f" (no credential to resume in {state})" if state is not None else ""
- raise ValueError(f"exactly one of bootstrap_token, bootstrap_token_path or jwt is required{where}")
+ raise ValueError(f"exactly one of bootstrap_token, bootstrap_token_path, jwt or jwt_path is required{where}")
enrollment: Enrollment
- if jwt is not None:
+ if jwt is not None or jwt_path is not None:
+ if jwt_path is not None:
+ jwt = Path(jwt_path).expanduser().read_text().strip()
+ assert jwt is not None
enrollment = control_plane.register(identity, jwt, role=role, labels=labels)
else:
if bootstrap_token_path is not None:
diff --git a/sdk/python/tests/test_mesh.py b/sdk/python/tests/test_mesh.py
index ead4917d..0af392d1 100644
--- a/sdk/python/tests/test_mesh.py
+++ b/sdk/python/tests/test_mesh.py
@@ -55,6 +55,16 @@ class FakeControlPlane:
def transport(self, method, url, headers, body):
path = urllib.parse.urlsplit(url).path
+ if (method, path) == ("POST", "/register"):
+ # The biscuit names the JWT that was presented, so a test can see which.
+ jwt = pb.EnrollRequest.FromString(body).jwt
+ self.issued += 1
+ return 200, pb.EnrollResponse(
+ biscuit_token=f"biscuit-for-{jwt}".encode(),
+ control_plane_public_key=CP_KEY.public_key_raw,
+ router_addresses=["/dns4/router.example/tcp/4001/p2p/12D3KooWP8iKhDf3iCMo2H3butNVfdTUtYwYWYQ75jTGnynXPFMp"],
+ expire_time=_ts_s(int(time.time()) + 3600),
+ ).SerializeToString()
if (method, path) == ("POST", "/enroll"):
self.issued += 1
return 200, pb.BootstrapEnrollResponse(
@@ -149,9 +159,21 @@ def test_enroll_refuses_ambiguous_credentials():
AgentMesh.enroll("http://127.0.0.1:1", transport=cp.transport)
with pytest.raises(ValueError, match="exactly one of"):
AgentMesh.enroll("http://127.0.0.1:1", bootstrap_token="a", jwt="b", transport=cp.transport)
+ with pytest.raises(ValueError, match="exactly one of"):
+ AgentMesh.enroll("http://127.0.0.1:1", jwt="a", jwt_path="/nonexistent", transport=cp.transport)
assert cp.issued == 0
+def test_enroll_reads_a_workload_identity_token_from_jwt_path(tmp_path):
+ cp = FakeControlPlane()
+ token = tmp_path / "token"
+ token.write_text("eyJ.projected.token\n")
+ mesh = AgentMesh.enroll("http://127.0.0.1:1", jwt_path=token, transport=cp.transport)
+ assert mesh.credential.biscuit == b"biscuit-for-eyJ.projected.token"
+ with pytest.raises(FileNotFoundError):
+ AgentMesh.enroll("http://127.0.0.1:1", jwt_path=tmp_path / "missing", transport=cp.transport)
+
+
def test_load_without_identity_says_enroll_first(tmp_path):
with pytest.raises(FileNotFoundError, match="no identity"):
AgentMesh.load(tmp_path)
diff --git a/site/content/docs/guides/native-sdks.md b/site/content/docs/guides/native-sdks.md
index 3be874cc..85e81e52 100644
--- a/site/content/docs/guides/native-sdks.md
+++ b/site/content/docs/guides/native-sdks.md
@@ -76,7 +76,18 @@ export SAM_BOOTSTRAP_TOKEN_PATH=~/sam-one/join-token
A plain `http://` URL is accepted only for a control plane on the same
machine. Anything else needs `https://`, because the control plane is the
trust root of every member and the SDK refuses to fetch it over plaintext
-from a remote address.
+from a remote address. Inside a network you already trust, such as a
+Kubernetes cluster where the control plane is a cluster-local service, set
+`SAM_INSECURE_CONTROL_PLANE=true` (`allowInsecure` in code), the same choice
+as `sam-node --insecure-control-plane`.
+
+On a platform that issues workload identity tokens, a program needs no
+bootstrap token. A mesh whose control plane trusts the platform's issuer
+enrolls the program from that token instead; on Kubernetes that is a
+projected service account token, as [Headless enrollment](../headless-enrollment/)
+shows for `sam-node`. Set `SAM_JWT_PATH` to the token file rather than
+`SAM_BOOTSTRAP_TOKEN_PATH`. That is how the public testnets run these same
+programs as canaries beside the `sam-node` ones.
## 2. Install the SDK
@@ -111,31 +122,38 @@ JavaScript, `serve.js`:
// members may call; the SDK turns the others away before anything reaches
// this code or Ollama.
//
-// node serve.js
+// node serve.js # publishes mcp://greeter and a2a://greeter
+// node serve.js greeter-2 # the same under another name
//
-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-// holding the token the mesh operator gave you; the first run spends it and
-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-// there without it.
+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or
+// SAM_JWT_PATH (a workload identity token your platform issues, such as a
+// Kubernetes projected service account token), and keeps the identity and
+// credential in SAM_STATE_DIR; later runs resume from there without it.
import { homedir } from "node:os";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { AgentMesh } from "@sam-mesh/sdk";
import { z } from "zod";
+const [name = "greeter"] = process.argv.slice(2);
+
const mesh = await AgentMesh.enroll({
controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,
- stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/greeter`,
+ jwtPath: process.env.SAM_JWT_PATH,
+ stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/${name}`,
+ // A plaintext http:// control plane is otherwise accepted only on loopback.
+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",
});
const session = await mesh.join();
await session.serve({
type: "mcp",
- name: "greeter",
+ name,
createServer: () => {
- const server = new McpServer({ name: "greeter", version: "1.0.0" });
- server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name }) => ({
- content: [{ type: "text", text: `hello ${name}` }],
+ const server = new McpServer({ name, version: "1.0.0" });
+ server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name: who }) => ({
+ content: [{ type: "text", text: `hello ${who}` }],
}));
return server;
},
@@ -143,8 +161,8 @@ await session.serve({
await session.serve({
type: "a2a",
- name: "greeter",
- target: (request, caller) => Response.json({ name: "greeter", path: new URL(request.url).pathname, caller: caller.peerId }),
+ name,
+ target: (request, caller) => Response.json({ name, path: new URL(request.url).pathname, caller: caller.peerId }),
});
if (process.env.OLLAMA_URL !== undefined) {
@@ -169,30 +187,38 @@ beside this program as an inference service. The mesh policy decides which
members may call; the SDK turns the others away before anything reaches this
code or Ollama.
- python serve.py
+ python serve.py # publishes mcp://greeter and a2a://greeter
+ python serve.py greeter-2 # the same under another name
-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-holding the token the mesh operator gave you; the first run spends it and
-keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-there without it.
+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH
+(a workload identity token your platform issues, such as a Kubernetes
+projected service account token), and keeps the identity and credential in
+SAM_STATE_DIR; later runs resume from there without it.
"""
import json
import os
+import sys
import trio
from agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, HTTPService, MCPService, VerifiedBiscuit
from mcp.server.mcpserver import MCPServer
+service_name = sys.argv[1] if len(sys.argv) > 1 else "greeter"
+
mesh = AgentMesh.enroll(
os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),
bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),
- state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/greeter"),
+ jwt_path=os.environ.get("SAM_JWT_PATH"),
+ state_dir=os.environ.get("SAM_STATE_DIR", f"~/.config/sam-mesh/{service_name}"),
+ # A plaintext http:// control plane is otherwise accepted only on loopback.
+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",
)
def create_server() -> MCPServer:
- server = MCPServer("greeter")
+ server = MCPServer(service_name)
@server.tool(description="Greets someone by name")
def greet(name: str) -> str:
@@ -202,14 +228,14 @@ def create_server() -> MCPServer:
async def card(request: HTTPRequest, caller: VerifiedBiscuit) -> HTTPResponse:
- body = json.dumps({"name": "greeter", "path": request.path, "caller": caller.peer_id})
+ body = json.dumps({"name": service_name, "path": request.path, "caller": caller.peer_id})
return HTTPResponse(status=200, headers={"content-type": "application/json"}, body=body.encode())
async def main() -> None:
async with mesh.join() as session:
- await session.serve(MCPService(name="greeter", create_server=create_server))
- await session.serve(HTTPService(type="a2a", name="greeter", target=card))
+ await session.serve(MCPService(name=service_name, create_server=create_server))
+ await session.serve(HTTPService(type="a2a", name=service_name, target=card))
if "OLLAMA_URL" in os.environ:
await session.serve(HTTPService(type="inference", name="ollama", target=os.environ["OLLAMA_URL"]))
@@ -257,10 +283,11 @@ JavaScript, `call.js`:
// node call.js a2a://greeter /card
// node call.js inference://ollama /v1/models
//
-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-// holding the token the mesh operator gave you; the first run spends it and
-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-// there without it.
+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or
+// SAM_JWT_PATH (a workload identity token your platform issues, such as a
+// Kubernetes projected service account token), and keeps the identity and
+// credential in SAM_STATE_DIR; later runs resume from there without it.
import { homedir } from "node:os";
import { AgentMesh } from "@sam-mesh/sdk";
@@ -269,7 +296,10 @@ const [service = "mcp://greeter", toolOrPath = "greet", args = '{"name": "world"
const mesh = await AgentMesh.enroll({
controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",
bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,
+ jwtPath: process.env.SAM_JWT_PATH,
stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/caller`,
+ // A plaintext http:// control plane is otherwise accepted only on loopback.
+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",
});
const session = await mesh.join();
console.log(`on the mesh as ${session.peerId}`);
@@ -305,10 +335,11 @@ path of an inference or A2A service.
python call.py a2a://greeter /card
python call.py inference://ollama /v1/models
-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file
-holding the token the mesh operator gave you; the first run spends it and
-keeps the identity and credential in SAM_STATE_DIR, later runs resume from
-there without it.
+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH
+(a workload identity token your platform issues, such as a Kubernetes
+projected service account token), and keeps the identity and credential in
+SAM_STATE_DIR; later runs resume from there without it.
"""
import json
@@ -326,7 +357,10 @@ args = json.loads(argv[2]) if len(argv) > 2 else {"name": "world"}
mesh = AgentMesh.enroll(
os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),
bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),
+ jwt_path=os.environ.get("SAM_JWT_PATH"),
state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/caller"),
+ # A plaintext http:// control plane is otherwise accepted only on loopback.
+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",
)
diff --git a/tests/integration/sdk_examples_test.go b/tests/integration/sdk_examples_test.go
index 202df849..d0b869e5 100644
--- a/tests/integration/sdk_examples_test.go
+++ b/tests/integration/sdk_examples_test.go
@@ -30,6 +30,8 @@ import (
"sync"
"testing"
"time"
+
+ "github.com/google/sam/api"
)
// sdkExampleLauncher starts one of the example programs the SDK READMEs and
@@ -75,22 +77,26 @@ var sdkExampleLaunchers = []sdkExampleLauncher{
// sdkExampleServer is a running serve example.
type sdkExampleServer struct {
- name string
- peerID string
+ name string
+ // service is what it publishes, greeter-<lang>, as the testnet canaries do.
+ service string
+ peerID string
}
var servingLine = regexp.MustCompile(`^serving (.*) as (\S+)$`)
// TestNativeSDKExamples runs the programs the SDK READMEs and the Native
-// SDKs guide embed, unchanged, against a real mesh. Each SDK's serve
-// example publishes mcp://greeter, a2a://greeter and inference://ollama,
-// the last forwarding to a stand-in for Ollama this test runs. Each SDK's
-// call example then reaches the sam-node's mcp://calc and a greeter, which
-// is whichever serve example the DHT lists first when both toolchains are
-// present, naming providers only by what discover returned; the SDK finds
-// the path through the router by itself. The first run spends a bootstrap
-// token, the later runs resume from the state directory without one.
-// Cross-language calls with a fixed pairing are TestNativeSDKsMesh's job.
+// SDKs guide embed, unchanged, against a real mesh, configured as the
+// testnet canaries are (.github/k8s/sam-sdk-canary-template.yaml). Each
+// SDK's serve example enrolls with an OIDC token through SAM_JWT_PATH, the
+// way a Kubernetes workload does, and publishes mcp://greeter-<lang>,
+// a2a://greeter-<lang> and inference://ollama, the last forwarding to a
+// stand-in for Ollama this test runs. Each SDK's call example enrolls with
+// a bootstrap token, reaches the sam-node's mcp://calc and the other
+// language's greeter (its own when the other toolchain is missing), naming
+// providers only by what discover returned; the SDK finds the path through
+// the router by itself. The first run spends the token, the later runs
+// resume from the state directory without one.
func TestNativeSDKExamples(t *testing.T) {
mesh := startSDKMesh(t)
@@ -107,7 +113,7 @@ func TestNativeSDKExamples(t *testing.T) {
var launchers []sdkExampleLauncher
var cmds []*exec.Cmd
for _, l := range sdkExampleLaunchers {
- cmd, skip := l.cmd(context.Background(), mesh.root, "serve")
+ cmd, skip := l.cmd(context.Background(), mesh.root, "serve", "greeter-"+l.name)
if skip != "" {
t.Logf("%s SDK skipped: %s", l.name, skip)
continue
@@ -122,13 +128,14 @@ func TestNativeSDKExamples(t *testing.T) {
errs := make([]error, len(launchers))
var wg sync.WaitGroup
for i := range launchers {
- tokenPath := filepath.Join(t.TempDir(), "join-token")
- if err := os.WriteFile(tokenPath, []byte(mintBootstrapToken(t, mesh.baseURL, mesh.adminToken)+"\n"), 0o600); err != nil {
+ jwtPath := filepath.Join(t.TempDir(), "sam-token")
+ jwt := mesh.mintToken(map[string]interface{}{"sub": "mock-user", "roles": []string{api.RoleNode}})
+ if err := os.WriteFile(jwtPath, []byte(jwt+"\n"), 0o600); err != nil {
t.Fatal(err)
}
cmds[i].Env = append(os.Environ(),
"SAM_CONTROL_PLANE_URL="+mesh.baseURL,
- "SAM_BOOTSTRAP_TOKEN_PATH="+tokenPath,
+ "SAM_JWT_PATH="+jwtPath,
"SAM_STATE_DIR="+filepath.Join(t.TempDir(), "state"),
"OLLAMA_URL="+ollama.URL,
)
@@ -136,7 +143,7 @@ func TestNativeSDKExamples(t *testing.T) {
wg.Add(1)
go func(i int) {
defer wg.Done()
- servers[i], errs[i] = startExampleServer(t, launchers[i].name, cmds[i])
+ servers[i], errs[i] = startExampleServer(t, launchers[i].name, "greeter-"+launchers[i].name, cmds[i])
}(i)
}
wg.Wait()
@@ -149,19 +156,26 @@ func TestNativeSDKExamples(t *testing.T) {
waitForPeerOnRouter(t, mesh.cpPort, mesh.adminToken, s.peerID, 5*time.Second)
}
- servedBy := func(t *testing.T, out, service string) {
- t.Helper()
- got := expectLine(t, out, service+" is served by ")
+ // The greeter a caller of one language targets: the other language's,
+ // as the testnet probes do, or its own when it is the only one present.
+ peerServer := func(name string) *sdkExampleServer {
for _, s := range servers {
- if s.peerID == got {
- return
+ if s.name != name {
+ return s
}
}
- t.Fatalf("%s is served by %s, which is none of the serve examples", service, got)
+ return servers[0]
+ }
+ servedBy := func(t *testing.T, out string, want *sdkExampleServer, serviceType string) {
+ t.Helper()
+ if got := expectLine(t, out, serviceType+"://"+want.service+" is served by "); got != want.peerID {
+ t.Fatalf("%s://%s is served by %s, want the %s serve example %s", serviceType, want.service, got, want.name, want.peerID)
+ }
}
for _, l := range launchers {
l := l
+ target := peerServer(l.name)
t.Run(l.name+"-calls", func(t *testing.T) {
t.Parallel()
stateDir := filepath.Join(t.TempDir(), "state")
@@ -187,11 +201,11 @@ func TestNativeSDKExamples(t *testing.T) {
if err := os.Remove(tokenPath); err != nil {
t.Fatal(err)
}
- out = runExample(t, mesh, l, withoutToken, "a2a://greeter", "/card")
+ out = runExample(t, mesh, l, withoutToken, "a2a://"+target.service, "/card")
if got := expectLine(t, out, "on the mesh as "); got != caller {
t.Fatalf("second run joined as %s, want the identity of the first run %s", got, caller)
}
- servedBy(t, out, "a2a://greeter")
+ servedBy(t, out, target, "a2a")
card := expectLine(t, out, "200 ")
if !strings.Contains(card, `"path": "/card"`) && !strings.Contains(card, `"path":"/card"`) {
t.Fatalf("a2a card %q does not echo the path", card)
@@ -200,7 +214,9 @@ func TestNativeSDKExamples(t *testing.T) {
t.Fatalf("a2a card %q does not name the verified caller %s", card, caller)
}
out = runExample(t, mesh, l, withoutToken, "inference://ollama", "/v1/models")
- servedBy(t, out, "inference://ollama")
+ if got := expectLine(t, out, "inference://ollama is served by "); got != servers[0].peerID && (len(servers) < 2 || got != servers[1].peerID) {
+ t.Fatalf("inference://ollama is served by %s, which is none of the serve examples", got)
+ }
models := expectLine(t, out, "200 ")
if !strings.Contains(models, `"gemma3"`) || !strings.Contains(models, caller) {
t.Fatalf("models %q: want gemma3 owned by the caller %s", models, caller)
@@ -214,7 +230,7 @@ func TestNativeSDKExamples(t *testing.T) {
if other.name == l.name {
continue
}
- out := runExample(t, mesh, other, withoutToken, "mcp://greeter", "greet", `{"name": "sam"}`)
+ out := runExample(t, mesh, other, withoutToken, "mcp://"+target.service, "greet", `{"name": "sam"}`)
if got := expectLine(t, out, "on the mesh as "); got != caller {
t.Fatalf("%s resumed %s's state directory as %s, want %s", other.name, l.name, got, caller)
}
@@ -227,10 +243,16 @@ func TestNativeSDKExamples(t *testing.T) {
importedAPI := importedNode.waitForAPI(t)
waitForPeerOnRouter(t, mesh.cpPort, mesh.adminToken, caller, 10*time.Second)
answer, err := callMCPAllowError(t, importedAPI, "imported-token", "call_remote_tool", map[string]any{
- "peer_id": servers[0].peerID, "tool_name": "mcp://greeter/greet", "arguments": map[string]any{"name": "node"},
+ "peer_id": target.peerID, "tool_name": "mcp://" + target.service + "/greet", "arguments": map[string]any{"name": "node"},
})
if err != nil || !strings.Contains(answer, "hello node") {
- t.Fatalf("sam-node running %s's identity could not call greeter: %v\n%s", l.name, err, answer)
+ t.Fatalf("sam-node running %s's identity could not call %s: %v\n%s", l.name, target.service, err, answer)
+ }
+ // The node's A2A egress path reaches the SDK's handler too, as the
+ // testnet's node probe expects.
+ status, body := egressGet(t, importedAPI, "imported-token", "/sam/"+target.peerID+"/a2a/"+target.service+"/card")
+ if status != 200 || !strings.Contains(body, `"caller"`) || !strings.Contains(body, caller) {
+ t.Fatalf("a2a card through the node: %d %s", status, body)
}
})
}
@@ -264,7 +286,7 @@ func importStateIntoNode(t *testing.T, mesh *sdkMesh, stateDir string) *backgrou
// startExampleServer starts a configured serve example and waits for its
// "serving ... as <peer>" line. Safe to call from several goroutines at
// once, so it reports failures instead of ending the test.
-func startExampleServer(t *testing.T, name string, cmd *exec.Cmd) (*sdkExampleServer, error) {
+func startExampleServer(t *testing.T, name, service string, cmd *exec.Cmd) (*sdkExampleServer, error) {
stderr := &bytes.Buffer{}
cmd.Stderr = stderr
stdout, err := cmd.StdoutPipe()
@@ -306,12 +328,12 @@ func startExampleServer(t *testing.T, name string, cmd *exec.Cmd) (*sdkExampleSe
return nil, fmt.Errorf("%s serve example exited before serving\nstderr:\n%s", name, stderr.String())
}
m := servingLine.FindStringSubmatch(line)
- for _, want := range []string{"mcp://greeter", "a2a://greeter", "inference://ollama"} {
+ for _, want := range []string{"mcp://" + service, "a2a://" + service, "inference://ollama"} {
if !strings.Contains(m[1], want) {
return nil, fmt.Errorf("%s serve example serves %q, want %s among them", name, m[1], want)
}
}
- return &sdkExampleServer{name: name, peerID: m[2]}, nil
+ return &sdkExampleServer{name: name, service: service, peerID: m[2]}, nil
case <-time.After(30 * time.Second):
return nil, fmt.Errorf("%s serve example did not report serving within 30s\nstderr:\n%s", name, stderr.String())
}
diff --git a/tests/integration/sdk_mesh_test.go b/tests/integration/sdk_mesh_test.go
index 60fed942..fec4eb0a 100644
--- a/tests/integration/sdk_mesh_test.go
+++ b/tests/integration/sdk_mesh_test.go
@@ -67,6 +67,9 @@ type sdkMesh struct {
routerPeer string
samNode *backgroundNode
nodeAPI string
+ // mintToken mints an OIDC token the control plane accepts, as a platform's
+ // workload identity token would be.
+ mintToken func(map[string]interface{}) string
}
const sdkMeshAdminToken = "test-admin-token"
@@ -172,6 +175,7 @@ bindings:
routerPeer: extractPeerID(routerAddr),
samNode: samNode,
nodeAPI: samNode.waitForAPI(t),
+ mintToken: mintToken,
}
}