Skip to content

Agent Mesh

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.md
index 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, and
returned 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 skill
The MCP tools tell an agent what it can do. The SAM skill tells it when and
diff --git a/site/content/docs/getting-started/your-own-mesh.md b/site/content/docs/getting-started/your-own-mesh.md
index 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 for
you: 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 a
Kubernetes 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:1b
cat > ~/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 its
peer 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-one
sam-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 machines
Everything 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.md
index 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. The
diff --git a/site/content/docs/reference/node-api.md b/site/content/docs/reference/node-api.md
index 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 ranks
remote 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` and
the 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 evidence
diff --git a/tests/e2e/fixtures/fake_openai.py b/tests/e2e/fixtures/fake_openai.py
new file mode 100644
index 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.bats
index 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" <<EOF
version: "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 @@ EOF
sock_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"'* ]] && break
sleep 1
done
- [[ "$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" \