Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: serve a model in "Your own mesh", cover the three service types
Antonio Ojeac13f63ae9288
diff --git a/site/content/docs/getting-started/quickstart.md b/site/content/docs/getting-started/quickstart.mdindex ccc02b94..0ad91d33 100644--- a/site/content/docs/getting-started/quickstart.md+++ b/site/content/docs/getting-started/quickstart.md@@ -119,6 +119,19 @@ The call left your machine over an authenticated peer-to-peer connection.The node that hosts the service checked the mesh policy, ran the tool, andreturned the result the same way. Any MCP client can make the same calls.+MCP is one of three service types. The testnet also publishes `inference`+services, and the same node offers their models on an OpenAI-compatible+endpoint. The Unix socket needs no token:++```bash+curl -s --unix-socket ~/.config/sam-mesh/sam.sock http://localhost/v1/models+```++A completion request to `/v1/chat/completions` for one of those models is+routed to the node that serves it. The third type, `a2a`, is an agent that+speaks the A2A protocol; [Your own mesh](../your-own-mesh/) publishes a+model from your laptop and shows where each type fits.+## 5. Give your agent the skillThe MCP tools tell an agent what it can do. The SAM skill tells it when anddiff --git a/site/content/docs/getting-started/your-own-mesh.md b/site/content/docs/getting-started/your-own-mesh.mdindex 8a68629e..4beb004d 100644--- a/site/content/docs/getting-started/your-own-mesh.md+++ b/site/content/docs/getting-started/your-own-mesh.md@@ -8,11 +8,14 @@ aliases:The quick start joined a mesh that someone else runs. This page runs one foryou: a control plane, a router and a web console on your laptop, in one-process, with two nodes talking through it. `sam-one` runs the same code as a+process, with two nodes talking through it. One node publishes a model that+runs on your machine, the other calls it. `sam-one` runs the same code as aKubernetes deployment, so what you learn here applies there too.-You need the `sam-one`, `sam-node` and `mcp-client` binaries. The-[install script](../quickstart/#1-install) provides all three.+You need the `sam-one` and `sam-node` binaries. The+[install script](../quickstart/#1-install) provides both. The model is served+by [Ollama](https://ollama.com); any OpenAI-compatible server works in its+place.## 1. Start the control plane@@ -50,22 +53,31 @@ about it: any enrolled node may register any service and call any service.This is a reasonable default for a laptop and a bad one for anything shared.The last section explains how to replace it.-## 2. Publish a service from one node+## 2. Publish a model from one node-Any HTTP backend can be a mesh service. Start a simple one and declare it in-a node configuration file:+A node publishes backends that speak one of three protocols, and the+service `type` says which: `inference` for an OpenAI-compatible API, `mcp`+for an MCP server, `a2a` for an A2A agent. The type is a contract, not a+label. The node speaks that protocol to the backend and to nobody else: an+`inference` backend is offered for the models it lists on `/v1/models`, an+`mcp` server is advertised once the node has completed an MCP session with+it, an `a2a` agent once it has served its agent card. A plain web server+declared under any of these types is never advertised. The mesh is not a+generic HTTP tunnel.++Pull a small model and declare Ollama as an `inference` service. The+`target_url` is the backend's root, without `/v1`; the node adds the prefix:```bash-mkdir -p /tmp/www && echo "hello from node a" > /tmp/www/hello.txt-python3 -m http.server 9000 --bind 127.0.0.1 --directory /tmp/www &+ollama pull gemma3:1bcat > ~/node-a.yaml <<'EOF'version: "v1alpha1"services:- - type: mcp- name: hello- description: "a static file, served over the mesh"- target_url: "http://127.0.0.1:9000"+ - type: inference+ name: laptop-llm+ description: "Ollama on my laptop"+ target_url: "http://127.0.0.1:11434"EOF```@@ -81,10 +93,10 @@ sam-node run --control-plane $URL \```Three of these flags are only needed because both nodes run on one machine.-`--bind-addr=` (an empty value) keeps the node's local API on its Unix socket,-so the two nodes do not compete for port 8080. `--allow-loopback` lets the-nodes advertise and dial `127.0.0.1`. `--listen .../tcp/0` picks a free-peer-to-peer port. On separate machines you would not pass any of them.+`--bind-addr=` (an empty value) keeps the node's local API on its Unix+socket, so the two nodes do not compete for port 8080. `--allow-loopback`+lets the nodes advertise and dial `127.0.0.1`. `--listen .../tcp/0` picks a+free peer-to-peer port. On separate machines you would not pass any of them.The node enrolls with the join token, connects to the router and prints itspeer ID:@@ -94,7 +106,9 @@ SAM Node Online.PeerID: 12D3KooWSCnbUoZ8Jv3EKGv17LqEWtnTMfZ3XYJUg2WTm5Gz2hUK```-Keep that value.+Ollama is never exposed on the network. It listens on loopback, and the only+way to it from another machine is through this node, which checks the+caller's credential and the mesh policy on every request.## 3. Call it from another node@@ -108,26 +122,37 @@ sam-node run --control-plane $URL \--data-dir ~/node-b --bind-addr= --allow-loopback --listen /ip4/127.0.0.1/tcp/0```-Every node's local API includes a proxy at `/sam/<peer-id>/<type>/<name>/`-that forwards to a service on another node. Ask node B for node A's file:+Every node's local API includes an OpenAI-compatible endpoint. `/v1/models`+lists the models that every reachable `inference` provider serves, and a+completion request is routed to a provider of the model it names. Ask node+B:```bash-PEER_A=12D3KooWSCnbUoZ8Jv3EKGv17LqEWtnTMfZ3XYJUg2WTm5Gz2hUK+SOCK=~/node-b/sam.sock-curl --unix-socket ~/node-b/sam.sock "http://localhost/sam/$PEER_A/mcp/hello/hello.txt"-# hello from node a+curl -s --unix-socket $SOCK http://localhost/v1/models++curl -s --unix-socket $SOCK http://localhost/v1/chat/completions \+ -H 'Content-Type: application/json' \+ -d '{"model":"gemma3:1b","messages":[{"role":"user","content":"Say hello in five words."}]}'```+The model list shows `gemma3:1b` with node A's peer ID as `owned_by`. Allow+a few seconds after A starts for B to learn about it. Nodes announce their+services in a discovery table that the router hosts, and the announcement+takes a moment to arrive.+The request went from B's socket to B, then over an authenticated connection-to A, through A's policy check, to the Python server, and back. If A and B-cannot reach each other directly, the connection is relayed through the-router inside `sam-one`. Allow a few seconds after A starts for B to learn-about it. Nodes announce their services in a discovery table that the router-hosts, and the announcement takes a moment to arrive.+to A, through A's policy check, to Ollama, and back. Both nodes verified the+other's credential before any data moved. If A and B cannot reach each other+directly, the connection is relayed through the router inside `sam-one`,+which carries ciphertext and learns only that the two are talking.-An MCP backend works the same way. The difference is that the node-understands the protocol: the service appears in `discover_remote_services`-and its tools in `find_remote_tools`, as on the testnet.+The socket needs no token: only your user can open it. To point an OpenAI+SDK at the mesh instead, give node B a TCP port with+`--bind-addr 127.0.0.1:8081` and a token as in the+[quick start](../quickstart/#3-run-the-node), then use+`http://127.0.0.1:8081/v1` as `base_url` and the token as `api_key`.## 4. Look at it in the console@@ -148,6 +173,35 @@ sam-one token revoke <token-id> --server $URL --data-dir ~/sam-onesam-one admin ban <peer-id> --server $URL --data-dir ~/sam-one```+## MCP servers and A2A agents++The other two service types are declared the same way and reached through+the same node. An MCP server gives agents tools; the quick start+[calls one](../quickstart/#4-call-a-tool-on-the-mesh) on the testnet through+the node's MCP endpoint. A stdio server is declared with `command` and the+node runs it; a Streamable HTTP server with `target_url`:++```yaml+ - type: mcp+ name: filesystem+ command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"]+```++An A2A agent is another agent, spoken to with the A2A protocol. It is+reached at `/sam/<peer-id>/a2a/<name>/` on the caller's node, which+regenerates the agent card so that a stock A2A client works unchanged:++```yaml+ - type: a2a+ name: triage+ target_url: "http://127.0.0.1:9999"+```++[Exposing services](../../guides/exposing-services/) covers all three types+and what the policy must grant. The [A2A chat](../../use-cases/chat-a2a/)+and [Gemini Buddy](../../use-cases/gemini-buddy/) use cases run a complete+agent behind each of the other two types.+## Reaching it from other machinesEverything above used `http://127.0.0.1`. `sam-node` accepts a plain `http`diff --git a/site/content/docs/preview/sandboxed-agents.md b/site/content/docs/preview/sandboxed-agents.mdindex 8a68c037..f3a71ab2 100644--- a/site/content/docs/preview/sandboxed-agents.md+++ b/site/content/docs/preview/sandboxed-agents.md@@ -63,7 +63,7 @@ classifies the name and decides:| Name | Decision ||---|---|| `mesh.sam.alt` | The mesh surface: `/v1/models`, `/v1/chat/completions`, `/v1/completions`, `/mcp`. Any other path is `403`. |-| `<service>.mcp.sam.alt` | One specific mesh service. Discovery chooses the provider. |+| `<service>.<type>.sam.alt` | One specific mesh service, `<type>` being `mcp`, `inference` or `a2a`: `code-reviewer.mcp.sam.alt`, `openrouter.inference.sam.alt`. Discovery chooses the provider. || anything else | Matched against the agent's egress allowance. A name that is not in the allowance is refused. |A refusal fails the `CONNECT` with `403` and a `Boundary-Reason` header. Thediff --git a/site/content/docs/reference/node-api.md b/site/content/docs/reference/node-api.mdindex 6d596226..77a235c6 100644--- a/site/content/docs/reference/node-api.md+++ b/site/content/docs/reference/node-api.md@@ -171,6 +171,17 @@ curl -s --unix-socket $SOCK $URL \Over TCP, add `-H "X-Sam-Authentication: Bearer $TOKEN"` and use`http://127.0.0.1:8080` as the base URL.+### Talking A2A through the proxy++An A2A client starts from the agent card. Fetched through the proxy path,+the card comes back regenerated: its interface URL is the proxy path+itself, so a stock client sends `message/send` there without changes:++```bash+curl -s --unix-socket $SOCK \+ http://localhost/sam/<peer-id>/a2a/triage/.well-known/agent-card.json+```+## Inference`/v1/models` collects the model list of every reachable `inference` provider@@ -180,10 +191,19 @@ node picks a provider that serves it. It prefers a local provider, and ranksremote providers by the labels the caller required, the operator's floor,and load. A model that no provider lists answers `404`.+```bash+curl -s --unix-socket $SOCK http://localhost/v1/models++curl -s --unix-socket $SOCK http://localhost/v1/chat/completions \+ -H 'Content-Type: application/json' \+ -d '{"model":"<model-id>","messages":[{"role":"user","content":"hi"}]}'+```+Any OpenAI SDK works with `base_url` set to `http://127.0.0.1:8080/v1` andthe API token as `api_key`. The node accepts the token in `Authorization`here because nothing on this path forwards that header. Streaming responses-are passed through.+are passed through. One provider can also be addressed directly, at+`/sam/<peer-id>/inference/<name>/v1/chat/completions`.## Identity evidencediff --git a/tests/e2e/fixtures/fake_openai.py b/tests/e2e/fixtures/fake_openai.pynew file mode 100644index 00000000..dd3ffa54--- /dev/null+++ b/tests/e2e/fixtures/fake_openai.py@@ -0,0 +1,48 @@+#!/usr/bin/env python3+# A minimal OpenAI-compatible backend for e2e tests: one model, one canned+# completion. Standard library only, so it runs wherever python3 does.+import json+from http.server import BaseHTTPRequestHandler, HTTPServer++MODEL = "e2e-model"+++class Handler(BaseHTTPRequestHandler):+ def _json(self, status, body):+ data = json.dumps(body).encode()+ self.send_response(status)+ self.send_header("Content-Type", "application/json")+ self.send_header("Content-Length", str(len(data)))+ self.end_headers()+ self.wfile.write(data)++ def do_GET(self):+ if self.path == "/v1/models":+ self._json(200, {"object": "list", "data": [{"id": MODEL, "object": "model", "owned_by": "e2e"}]})+ return+ self._json(404, {"error": {"message": "not found"}})++ def do_POST(self):+ length = int(self.headers.get("Content-Length") or 0)+ try:+ req = json.loads(self.rfile.read(length) or b"{}")+ except ValueError:+ req = {}+ if self.path == "/v1/chat/completions" and req.get("model") == MODEL:+ self._json(200, {+ "id": "cmpl-e2e", "object": "chat.completion", "model": MODEL,+ "choices": [{"index": 0, "finish_reason": "stop",+ "message": {"role": "assistant", "content": "hello from the mesh"}}],+ "usage": {"prompt_tokens": 1, "completion_tokens": 4, "total_tokens": 5},+ })+ return+ self._json(404, {"error": {"message": "unknown model", "code": "model_not_found"}})++ def log_message(self, *args):+ pass+++if __name__ == "__main__":+ server = HTTPServer(("127.0.0.1", 0), Handler)+ print(f"listening on port {server.server_address[1]}", flush=True)+ server.serve_forever()diff --git a/tests/e2e/standalone.bats b/tests/e2e/standalone.batsindex ebfd4964..22440142 100644--- a/tests/e2e/standalone.bats+++ b/tests/e2e/standalone.bats@@ -2,8 +2,9 @@# Black-box CUJ for the sam-one all-in-one binary: boot on a random port# published in the banner, join real sam-nodes through it, drive the admin CLI-# against the live server, and push a request across the dataplane from node B-# to a smoke HTTP service declared in node A's configuration (egress proxy -> router -> A).+# against the live server, and serve a model across the dataplane from an+# inference service declared in node A's configuration to node B's /v1+# endpoint (B -> router -> A). Mirrors docs/getting-started/your-own-mesh.# In-process coverage lives in tests/integration/standalone_test.go; this file# only exercises what needs the real binaries.@@ -90,24 +91,27 @@ start_node() {JOIN_TOKEN="$(cat "$SAM_ONE_DATA/join-token")"[[ "$JOIN_TOKEN" == sam_tok_* ]]- # Smoke HTTP backend on node A's host, declared as a URL-backed service in- # node A's configuration: services only exist by declaration at startup,- # there is no runtime registration endpoint.- # -u: unbuffered, or the "Serving HTTP" banner never flushes to the log.- mkdir -p "$TEST_TMPDIR/www"- echo "sam-one dataplane ok" > "$TEST_TMPDIR/www/hello.txt"- python3 -u -m http.server 0 --bind 127.0.0.1 --directory "$TEST_TMPDIR/www" \+ # An OpenAI-compatible backend on node A's host, declared as an inference+ # service in node A's configuration, as in docs/getting-started/your-own-mesh.+ # Services only exist by declaration at startup, there is no runtime+ # registration endpoint. The same server is also declared as `mcp`: the+ # type is a contract the node verifies, so that one must never be advertised.+ python3 -u "$BATS_TEST_DIRNAME/fixtures/fake_openai.py" \> "$TEST_TMPDIR/backend.log" 2>&1 &BACKEND_PID=$!- wait_for_log "$TEST_TMPDIR/backend.log" "Serving HTTP"+ wait_for_log "$TEST_TMPDIR/backend.log" "listening on port"backend_port="$(grep -oE 'port [0-9]+' "$TEST_TMPDIR/backend.log" | grep -oE '[0-9]+')"cat > "$TEST_TMPDIR/node-a-services.yaml" <<EOFversion: "v1alpha1"services:- - type: "mcp"- name: "smoke"- description: "e2e smoke backend"+ - type: inference+ name: laptop-llm+ description: "e2e inference backend"+ target_url: "http://127.0.0.1:${backend_port}"+ - type: mcp+ name: not-an-mcp-server+ description: "a plain HTTP server mislabelled as mcp"target_url: "http://127.0.0.1:${backend_port}"EOF@@ -122,15 +126,33 @@ EOFsock_b="$TEST_TMPDIR/node-b/sam.sock"[[ -S "$sock_a" && -S "$sock_b" ]]- # Node B reaches the service on node A through its egress proxy: the request- # crosses B -> router -> A over the mesh, exercising the full dataplane.- body=""+ # The mislabelled service is registered but withheld from discovery.+ wait_for_log "$TEST_TMPDIR/node-a.log" "not-an-mcp-server but not advertising it"++ # Node B's OpenAI-compatible endpoint lists the model with A as its owner:+ # the announcement crosses A -> router -> B over the mesh.+ models=""for _ in $(seq 1 30); do- body="$(curl -sf --unix-socket "$sock_b" "http://localhost/sam/${peer_a}/mcp/smoke/hello.txt" || true)"- [[ "$body" == *"sam-one dataplane ok"* ]] && break+ models="$(curl -sf --unix-socket "$sock_b" "http://localhost/v1/models" || true)"+ [[ "$models" == *'"e2e-model"'* ]] && breaksleep 1done- [[ "$body" == *"sam-one dataplane ok"* ]]+ [[ "$models" == *'"e2e-model"'* ]]+ [[ "$models" == *"$peer_a"* ]]++ # A completion is routed B -> router -> A -> backend, exercising the full+ # dataplane, and comes back as the OpenAI response the backend produced.+ run curl -sf --unix-socket "$sock_b" "http://localhost/v1/chat/completions" \+ -H 'Content-Type: application/json' \+ -d '{"model":"e2e-model","messages":[{"role":"user","content":"hi"}]}'+ [[ "$status" -eq 0 ]]+ [[ "$output" == *"hello from the mesh"* ]]++ # The plain HTTP server never shows up as an MCP provider.+ run curl -sf --unix-socket "$sock_b" \+ "http://localhost/sam/service/discover?type=mcp&name=not-an-mcp-server&timeout=3s"+ [[ "$status" -eq 0 ]]+ [[ "$output" != *"$peer_a"* ]]# The admin CLI works against the live server using the persisted admin token.run "$SAM_ONE_BINARY" token create --server "$SAM_ONE_URL" \