Skip to content

Agent Mesh

docs: the SDKs are agents; they call services and accept A2A

Antonio Ojea34ef878da18b
diff --git a/sdk/README.md b/sdk/README.md
index e5b5ff33..94069ee1 100644
--- a/sdk/README.md
+++ b/sdk/README.md
@@ -16,8 +16,16 @@ Python package (`sam-mcp-python`) only wrapped the sidecar's HTTP API and was
removed in favour of this work.
Both SDKs speak the mesh protocol directly. There is no SDK-specific
-endpoint anywhere in the mesh; a node built with an SDK is, to every other
-node and to the control plane, a `sam-node`.
+endpoint anywhere in the mesh; a member built with an SDK is, to every other
+member and to the control plane, a peer like a `sam-node`.
+
+An SDK member is an agent, not a service provider. It calls what the mesh
+offers: MCP tools, inference and A2A services that `sam-node`s publish and
+the discovery table names. Inbound, it accepts one thing: A2A requests for
+itself, as `a2a://<name>`, reached by peer ID through a router. It publishes
+no service, writes no provider record and reports no catalog; a tool, a
+model or a named agent that others should find by name runs behind a
+`sam-node`. The reasons are in [Agents, not services](#agents-not-services).
## What exists today
@@ -38,11 +46,10 @@ Milestones 1 to 5 are implemented and tested in both languages:
| Service discovery in the mesh DHT (`/sam/kad/1.0.0`) | yes | yes |
| `/sam/mcp/1.0.0` client: list and call a provider's tools, or its catalog | yes | yes |
| Caller-side label requirements on the provider's credential | yes | yes |
+| `/libp2p-http` client: call inference and A2A services on the mesh; response bodies stream | yes | yes |
+| The mesh as a transport for HTTP clients: `session.fetch()` for fetch-based clients, `MeshTransport` for httpx, so the official A2A SDK's client works unchanged | `fetch` | httpx |
| Provider authorizer: the baseline Datalog and the mesh policy (`GET /policies`), evaluated as `sam-node` does | yes | yes |
-| `/sam/mcp/1.0.0` server: publish MCP services with an in-process MCP server; the member's own catalog | yes | yes |
-| `/libp2p-http` server: publish inference and A2A services, forwarded to a local URL or an in-process handler | yes | yes |
-| `/libp2p-http` client: call inference and A2A services on the mesh | yes | yes |
-| DHT provide with reprovide, `POST /nodes/catalog` self-report | yes | yes |
+| A2A ingress for the agent: `/libp2p-http` for `a2a://<name>`, forwarded to an A2A server beside the process or answered in it; not announced anywhere | yes | yes |
| Control plane pull on `sam-node`'s interval: `/keys` verified against the trusted set, credential refresh after a rotation, `/info` bans and router addresses | yes | yes |
| Gossip events from the control plane (`/sam/mesh/events/v1`, StrictSign): ban enforced at once, key rotation adopted, policy update pulls | yes | yes |
| Banned peers refused: connections dropped and denied, handshakes and requests refused, dials refused | yes | yes |
@@ -50,12 +57,12 @@ Milestones 1 to 5 are implemented and tested in both languages:
A member built this way is on the mesh and uses it in both directions: it
finds a service in the DHT and calls it through the router, verifying the
-provider on every call, and it publishes services of its own that a
-`sam-node` or another SDK member discovers and calls, authorizing every
-caller with the same Datalog the Go node evaluates. It follows the control
-plane while it runs: a ban reaches it as a gossip event within a second and
-again with the next pull, and a key rotation makes it refresh its credential
-under the new key.
+provider on every call, and it answers A2A requests for its own agent from
+a `sam-node` or another SDK member that names it by peer ID, authorizing
+every caller with the same Datalog the Go node evaluates. It follows the
+control plane while it runs: a ban reaches it as a gossip event within a
+second and again with the next pull, and a key rotation makes it refresh
+its credential under the new key.
Facts about the libp2p implementations that the SDKs work around, each
pinned by a test:
@@ -94,7 +101,8 @@ pinned by a test:
every outbound stream and returns it only when sending the SYN fails, so
the 257th `open_stream` on a connection blocks forever with no error. A
member that keeps one connection to its router reaches that in hours (a
- DHT provide every ten minutes, a reservation renewal every hour). `main`
+ reservation renewal every hour, a control plane pull every fifteen
+ minutes). `main`
releases the slot on close (libp2p/py-libp2p#1426); until that is
released, `host.py` replaces `Yamux.open_stream` with one that does the
same, since py-libp2p constructs `Yamux` by name whatever `muxer_opt`
@@ -109,15 +117,21 @@ pinned by a test:
- go-libp2p-kad-dht keys provider records by the multihash, not the CID.
`sdk/testdata/service_keys.json` pins the keys both SDKs derive against
`internal/node/service.go`.
-- go-libp2p-kad-dht stores an ADD_PROVIDER record only when the sender is
- the provider it names and lists at least one address, and it answers
- nothing. The Python SDK sends the record itself to the routers and to the
- closer peers they name (`agent_mesh/discovery.py`); js-libp2p's
- `contentRouting.provide` does the same in client mode.
- go-libp2p-http is plain HTTP/1.1 on a stream, one request per stream,
with `Host` set to the peer ID. The JS SDK bridges the stream to a Node
duplex and runs Node's HTTP server and client on it; the Python SDK
- drives `h11` over the stream.
+ drives `h11` over the stream. Both read the response body as it arrives,
+ which an A2A `message/stream` (server-sent events) needs.
+- URL parsers lowercase the host (WHATWG `URL`, httpx), and a base58 peer
+ ID is case-sensitive. The URL an HTTP client uses for a peer's service
+ therefore carries the peer ID in the path,
+ `http://mesh/sam/<peer-id>/<type>/<name>/<path>`, the shape of `sam-node`'s
+ egress proxy and of an agent card it rewrote; the host is ignored.
+- A member that publishes nothing has announced no address, so nothing in
+ the DHT or a router's peerstore names one. `sam-node` dials
+ `/p2p/<router>/p2p-circuit` for every router it authenticated with when
+ it knows nothing else about a peer, as both SDKs do for a peer named by
+ ID (`internal/node/mcp.go`, `preparePeerAddrs`).
- Every Go component runs GossipSub with `StrictSign`. `@libp2p/gossipsub`
(the libp2p-maintained package; `@chainsafe/libp2p-gossipsub` stops at
libp2p 2) and py-libp2p's `GossipSub` with `strict_signing=True` both
@@ -180,7 +194,7 @@ messages in `api/sam.proto`. Bodies are capped at 1 MiB on both sides.
| `POST /refresh` | `TokenRefreshRequest`, header `Authorization: Bearer <base64 biscuit>` | `TokenRefreshResponse` | sign `sam:refresh:<peer_id>:<ts>` |
| `GET /keys` | — | `KeysResponse` | none; see below |
| `GET /policies` | header `Authorization: Bearer <base64 biscuit>` | `PolicyConfigGetResponse{datalog_rules}` | none; the biscuit must belong to an admitted node |
-| `POST /nodes/catalog` | `NodeCatalogReport`, header `Authorization: Bearer <base64 biscuit>` | `204` | none; the reporting peer is read from the biscuit |
+| `POST /nodes/catalog` | `NodeCatalogReport`, header `Authorization: Bearer <base64 biscuit>` | `204` | none; the reporting peer is read from the biscuit. `sam-node` reports what it publishes; an SDK member publishes nothing and does not call it |
- `<ts>` is the request's `challenge_unix_ms`, unix milliseconds, and must
be within 5 minutes of the control plane's clock (`challengeMaxAge`).
@@ -226,9 +240,9 @@ messages in `api/sam.proto`. Bodies are capped at 1 MiB on both sides.
### Streams
-Two protocols, both starting with a length-prefixed protobuf frame. Framing
-is the go-msgio varint style (unsigned varint byte length, then the bytes),
-with a 64 KiB cap on the first frame.
+Three protocols. The first two start with a length-prefixed protobuf frame;
+framing is the go-msgio varint style (unsigned varint byte length, then the
+bytes), with a 64 KiB cap on the first frame.
- `/sam/auth/1.0.0` (`HandleAuthHandshake`, and the router's equivalent).
Client sends `AuthFrame{biscuit}`; server verifies the biscuit against the
@@ -237,13 +251,24 @@ with a 64 KiB cap on the first frame.
credential. The client verifies that credential the same way and, for a
router, requires the router role. This is how a member joins: connect to a
router, run this handshake, and the router admits it to the relay and
- gossip.
+ gossip. Both SDKs answer it too, so a `sam-node` can verify them before
+ calling.
- `/sam/mcp/1.0.0` (`WithBiscuitAuth` then `HandleMCPStream`). Client sends
`AuthFrame{biscuit, target_service: "mcp://<service>", agent}`; server
authorizes the request with the Biscuit authorizer described below and
answers `AuthResponse`. The stream then carries MCP JSON-RPC messages, each
one varint-length-prefixed (`StreamTransport` in `internal/node/gate.go`).
- An empty `target_service` selects the node's own catalog tools.
+ An empty `target_service` selects the node's own catalog tools. The SDKs
+ are clients of this protocol only; they serve no MCP.
+- `/libp2p-http` (go-libp2p-http; `StartIngressServer` and the egress proxy
+ in `internal/node`). Plain HTTP/1.1 on a stream, one request per stream,
+ `Host` set to the peer ID, the caller's biscuit in `X-Sam-Biscuit` and the
+ agent it speaks for in `X-Sam-Agent`. The path is
+ `/<type>/<name>/<upstream>`; the server authorizes `<type>://<name>` with
+ the same authorizer, then forwards `<upstream>` to the service with those
+ two headers stripped and `X-Peer-Id` set to the verified caller. The SDKs
+ are clients of this for `inference://` and `a2a://` services, and servers
+ of it for their own agent, `a2a://<name>`, only.
### Discovery (`internal/node/service.go`)
@@ -252,7 +277,15 @@ A provider announces a service as a DHT provider record for
once for the name (`<type>` is `mcp`, `inference` or `a2a`). A consumer
looks up providers for the same CID, dials one and opens `/sam/mcp/1.0.0`.
Gossip topics under `/sam/discovery/v1/...` carry `ServiceAnnounce` for
-interest-scoped updates; the DHT is the source of truth.
+interest-scoped updates; the DHT is the source of truth. The SDKs look
+records up and announce none.
+
+A peer that announced nothing is still reachable by peer ID: every router
+relays for the peers it admitted, so a caller dials
+`<router>/p2p-circuit/p2p/<peer>` through each router that admitted it.
+Both SDKs do this for a bare peer ID, and `sam-node` does it when it knows
+no other address for a peer (`preparePeerAddrs` in `internal/node/mcp.go`).
+This is how an SDK agent is reached.
### Authorization on the provider side (`internal/node/middleware.go`)
@@ -284,6 +317,47 @@ of it is derived in the SDK:
accepts as a rule (`role("dev") <- true` for a
`sam:system:authenticated` binding).
+## Agents, not services
+
+An SDK member calls services and accepts A2A requests for its own agent.
+It does not publish services: no MCP server, no named inference or A2A
+service, no DHT record, no catalog entry. The reasons:
+
+- **The agent is the principal; a service is infrastructure.** A harness
+ (LangChain, Claude Code, a browser agent) is an MCP client. The tools it
+ should see through the mesh are the ones `sam-node`s publish. Something
+ that must be reachable by name, a tool, a model, a named agent, is a
+ deployment concern, and the sidecar model exists for it: the `sam-node`
+ beside it publishes the service and enforces the policy once, in Go.
+- **Publishing is the expensive part.** Being a provider needs a DHT
+ provide loop, a catalog report and provider records that go stale on
+ every rollout. Accepting requests for the agent itself needs the relay
+ reservation, the auth handshake and the authorizer, all of which a member
+ needs anyway to be verified by a `sam-node` before it is called.
+- **One inbound protocol.** A2A is the protocol for talking to an agent,
+ and the A2A SDKs serve one agent card each. One ingress means one
+ authorizer path to audit in three languages instead of two ingress
+ protocols times a registry of services.
+- **The browser.** A browser cannot listen. An agent in a browser is
+ reachable through a router's relay and nothing else, which is what
+ `accept_a2a` is.
+
+What an SDK agent is on the wire: a peer with a relay reservation on a
+router, answering `/sam/auth/1.0.0` and `/libp2p-http` for `a2a://<name>`,
+with no DHT record and no catalog entry. To a `sam-node` it is a peer whose
+address nobody announced, reached through the router that admitted both,
+and whose credential it verifies before forwarding
+`/sam/<peer>/a2a/<name>/...`. Routers, the control plane and the Datalog
+need no special case.
+
+Two agents that both wrote nothing down still meet: A learns B's peer ID
+(an invite, an agent card, a coordinator), dials it through a router, both
+present their credentials, and A opens the A2A conversation on that
+connection; libp2p's TLS is end to end, so the router carries ciphertext.
+An agent that must be *found* by name runs behind a `sam-node`. Two agents
+that both can only call out (two browsers) meet at a third agent behind a
+`sam-node` that both call.
+
## Plan
Each milestone lands in both languages with its tests before the next one
@@ -365,7 +439,7 @@ holds against the control plane's records.
service the node does not have. The runners took `discover`, `tools` and
`call` commands for it.
-### Milestone 4 — serve tools (done)
+### Milestone 4 — be an agent (done)
- Datalog as the contract, Go side: the baseline moved into a generated
artifact both SDKs embed, the control plane renders the mesh policy as
@@ -373,39 +447,41 @@ holds against the control plane's records.
See the authorization section above.
- Provider authorizer in each SDK (`authorizer.ts`, `authorizer.py`), built
from the artifact and `datalog_rules`, evaluated on every inbound
- `AuthFrame` and every `/libp2p-http` request in the order
- `internal/node/middleware.go` uses.
-- `/sam/mcp/1.0.0` server: read the `AuthFrame`, authorize, answer with the
- member's credential, then hand the stream to the service's MCP server
- (`@modelcontextprotocol/sdk` `McpServer`; `mcp.server.mcpserver.MCPServer`
- run over pumped streams). A denied caller gets `AuthResponse{success:
- false}` with the reason; a granted service the member does not publish
- closes the stream after the answer, as `sam-node` does. The empty target is
- the member's catalog (`list_local_services`).
-- `/libp2p-http` server for inference and A2A: the path is
+ `/libp2p-http` request in the order `internal/node/middleware.go` uses.
+- `/libp2p-http` server for the agent: the path is
`/<type>/<name>/<upstream>`, the biscuit is `X-Sam-Biscuit`; after
- authorization the request goes to a local URL or an in-process handler
- with the biscuit and agent headers stripped and `X-Peer-Id` set to the
- verified caller. `session.request(addr, "inference://<name>", path)` is
- the client side.
-- `session.serve(spec)` registers the service, fetches the mesh policy on
- the first call and re-reads it on `sam-node`'s sync interval, announces
- the service in the DHT (type and name, reprovided periodically) and
- reports it to `POST /nodes/catalog`.
-- Tests. Unit: each SDK's handlers behind an in-process host, called with
- its own clients: an MCP tool, the catalog, a proxied backend that sees
- `X-Peer-Id` and never the biscuit, an in-process handler, and refusals for
- a role that grants nothing, an ungranted service, a missing service, a
+ authorization for `<type>://<name>`, a request for the agent's own
+ `a2a://<name>` goes to an A2A server beside the process or a handler in
+ it, with the biscuit and agent headers stripped and `X-Peer-Id` set to the
+ verified caller; anything else is 404, after authorization, so an
+ unauthorized caller learns nothing. JS also takes a Node request
+ listener, which is what an Express app with the A2A SDK's handlers is,
+ and runs it on the ingress's own `http.Server`.
+- `session.accept_a2a(target, name=)` / `session.acceptA2A(spec)` fetches
+ the mesh policy, re-reads it on `sam-node`'s sync interval and starts
+ answering. It announces nothing. One agent per session.
+- `/libp2p-http` client for callers built on HTTP libraries:
+ `open_http_request` / `fetchOverStream` return once the headers are in
+ and stream the body; `MeshTransport` (httpx) and `session.fetch()`
+ (fetch) carry a client's requests to the peer a mesh URL names. The A2A
+ SDK's client takes either without changes.
+- `sam-node`: a peer it knows no address for is dialed through every
+ router it authenticated with, so its egress proxy reaches an agent by
+ peer ID (`preparePeerAddrs`).
+- Tests. Unit: each SDK's ingress behind an in-process host, called with
+ its own clients: a forwarded A2A server that sees `X-Peer-Id` and never
+ the biscuit, an SSE body read event by event, an in-process handler (and
+ a Node listener), an httpx client on `MeshTransport`, and refusals for a
+ role that grants nothing, an ungranted type, another agent name (404), a
missing biscuit and a dotted path; plus the authorizer alone against the
- decisions `internal/node/middleware_test.go` pins. Integration: in the
- mesh of `sdk_mesh_test.go` each SDK member publishes `mcp://echo-<sdk>`
- and `inference://llm-<sdk>`; the `sam-node` calls the tool with
- `call_remote_tool` and the inference endpoint through its egress proxy,
- the other SDK member discovers both in the DHT and calls them through the
- router, and a Go peer the control plane vouches for but whose role the
- policy grants nothing is refused at the `AuthResponse` and with 403 on
- the HTTP path, then served once it presents a node-role token. About 9
- seconds for the whole mesh.
+ decisions `internal/node/middleware_test.go` pins, and `sam-node`'s
+ router fallback. Integration: in the mesh of `sdk_mesh_test.go` each SDK
+ member accepts `a2a://agent`; the `sam-node` reaches it by peer ID
+ through its egress proxy, the other SDK member does the same with no
+ lookup, a lookup for `a2a://agent` finds nothing, the member refuses a
+ `/sam/mcp/1.0.0` stream, and a Go peer whose role the policy grants
+ nothing gets 403 and is answered once it presents a node-role token.
+ About 9 seconds for the whole mesh.
### Milestone 5 — parity and release (done)
@@ -416,7 +492,8 @@ holds against the control plane's records.
was unknown when the credential was issued (`issuedUnderKeys` in the
credential file); `/info` for router addresses and the ban set,
reconciled with the rule that a ban recorded after the request went out
- survives an answer that omits it; the mesh policy when serving. Runs
+ survives an answer that omits it; the mesh policy while accepting
+ callers. Runs
once shortly after join, then on `sam-node`'s interval with the same
jitter, and whenever an event triggers it.
- Gossip events on `/sam/mesh/events/v1`: the topic validator rejects
@@ -424,9 +501,9 @@ holds against the control plane's records.
events; `BANNED` evicts the peer at once, `KEY_ROTATION` adopts the key
and triggers a pull, `POLICY_UPDATE` triggers a pull. Bans are not
persisted; a restarted member reads them from `/info`.
-- Ban enforcement: the auth handshake, the MCP handshake and HTTP ingress
- refuse a banned peer before looking at its token; `connect()` refuses to
- dial one; its connections are dropped when the ban lands.
+- Ban enforcement: the auth handshake and the A2A ingress refuse a banned
+ peer before looking at its token; `connect()` refuses to dial one; its
+ connections are dropped when the ban lands.
- Publishing: `.github/workflows/release.yml` stamps the release tag's
version on both packages (`hack/sdk-version.sh`) and publishes
`@sam-mesh/sdk` to npm and `sam-mesh` to PyPI through trusted
@@ -462,18 +539,23 @@ holds against the control plane's records.
### 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.
+`sam-node` ones (`.github/k8s/sam-sdk-canary-template.yaml`): two pairs, an
+agent written with one SDK and a caller written with the other in one pod,
+enrolled with the pod's projected service account token through
+`SAM_JWT_PATH`. The agent accepts `a2a://agent`; the caller reads its peer
+ID from the line it prints, through a volume the pod shares, calls it every
+five minutes and is Ready while the last call succeeded, so the
+Deployment's availability says whether an agent is still reachable after
+hours on the mesh. Two CronJobs cross every implementation boundary every
+15 minutes and once per rollout: the `sam-node` cold-path probe
+(`sam-probe-cronjob-template.yaml`) runs an agent per SDK as sidecars and
+reaches each by peer ID through the egress proxy (node → SDK), and the SDK
+cold-path probe (`sam-sdk-probe-cronjob-template.yaml`) runs each SDK's
+`call` against the everything canary by name (SDK → node) and the other
+SDK's agent by peer ID (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
@@ -486,6 +568,9 @@ the Go components they talk to.
### Non-goals
- Rewriting the control plane, router or sandbox components; they stay Go.
+- Publishing services from an SDK: an MCP server, a named inference or A2A
+ service, a DHT record or a catalog entry. That is `sam-node`'s job; see
+ [Agents, not services](#agents-not-services).
- A browser build. Node.js only until the transport story for browsers
(WebTransport or WebRTC to routers) is designed.
- Any SDK-only wire protocol. If an SDK needs something the Go node does not
@@ -517,7 +602,7 @@ both so nothing skips there. The SDK members in the mesh test are the
runners `sdk/js/src/conformance-join.ts` and
`sdk/python/src/agent_mesh/conformance_join.py`: each joins, prints what it
holds, then takes JSON commands on stdin (`auth`, `discover`, `tools`,
-`call`, `serve`, `http`, `peers`, `sync`, `banned`, `quit`) so the Go test
+`call`, `accept`, `http`, `peers`, `sync`, `banned`, `quit`) so the Go test
can drive both languages through the same script.
The programs the package READMEs and the Native SDKs guide show are
@@ -550,18 +635,19 @@ one follows is named so a change on one side can be carried to the others.
| JavaScript (`sdk/js/src/`) | Python (`sdk/python/src/agent_mesh/`) | Mirrors |
| --- | --- | --- |
| `identity.ts` | `identity.py` | ed25519 key pair, libp2p key encodings, peer ID |
-| `controlplane.ts` | `controlplane.py` | `/info`, `/keys`, `/enroll`, `/enroll/status`, `/register`, `/refresh`, `/policies`, `/nodes/catalog`, with the challenges of `api/network.go` |
+| `controlplane.ts` | `controlplane.py` | `/info`, `/keys`, `/enroll`, `/enroll/status`, `/register`, `/refresh`, `/policies`, with the challenges of `api/network.go` |
| `credential.ts` | `credential.py` | what a member holds, `AuthFrame` encoding, `issuedUnderKeys` |
| `mesh.ts` | `mesh.py` | `AgentMesh`: enroll (resumes an unexpired credential in the state directory before spending a token), load, refresh, `syncControlPlane` as `SyncControlPlane` in `internal/node/controlplane_sync.go`; state directory (`identity.key`, `credential.json`, the same layout in both languages) |
| `biscuit.ts` | `biscuit.py` | verification of a peer's credential, as `internal/identity.verifyBiscuit` |
| `host.ts` | `host.py` | the libp2p host as `internal/node/node.go` configures it, plus gossipsub and the connection gater |
| `auth.ts` | `auth.py` | `/sam/auth/1.0.0` on both sides, as `HandleAuthHandshake` |
| — | `relay.py` | circuit relay v2 client (py-libp2p's cannot talk to go-libp2p) |
-| `session.ts` | `session.py` | `MeshSession`: join, relay reservation, refresh loop, control plane sync loop, gossip events, `serve()` |
-| `discovery.ts` | `discovery.py` | service keys and DHT lookups as `internal/node/service.go`; Python also provides, py-libp2p's client cannot |
+| `session.ts` | `session.py` | `MeshSession`: join, relay reservation, refresh loop, control plane sync loop, gossip events, `acceptA2A()` / `accept_a2a()`, `fetch()` |
+| `discovery.ts` | `discovery.py` | service keys and DHT lookups as `internal/node/service.go`; lookups only, no records |
| `mcp.ts` | `mcp_client.py` | MCP over `/sam/mcp/1.0.0`, the client side of `internal/node/gate.go` |
| `authorizer.ts` | `authorizer.py` | the provider authorizer, as `internal/node.(*SamNode).Authorize`, over the generated baseline and `datalog_rules` |
-| `serve.ts` | `serve.py` | `/sam/mcp/1.0.0` server, `/libp2p-http` server and client, service registry, as `WithBiscuitAuth` and `StartIngressServer` |
+| `libp2p-http.ts` | `libp2p_http.py` | `/libp2p-http` client (streaming) and the A2A ingress for the agent, as go-libp2p-http and `StartIngressServer`; mesh URLs |
+| — | `httpx_transport.py` | `MeshTransport`, the mesh as an `httpx.AsyncBaseTransport` (JS has `session.fetch()` instead) |
| `sync.ts` | `sync.py` | ban set and mesh event verification, as `reconcileBannedPeers` and `verifyEvent` |
| `conformance.ts`, `conformance-join.ts` | `conformance.py`, `conformance_join.py` | the runners the integration tests drive |
| `../examples/` | `../../examples/` | the programs the docs embed and `TestNativeSDKExamples` runs |
diff --git a/sdk/js/README.md b/sdk/js/README.md
index 857f1197..424ae3ce 100644
--- a/sdk/js/README.md
+++ b/sdk/js/README.md
@@ -3,8 +3,10 @@
Native JavaScript SDK for joining a SAM agent mesh from inside the agent
process. It replaces the `sam-node` sidecar for agents written for Node.js:
the agent enrolls with the control plane, joins the mesh through a router,
-finds services and calls them, publishes services of its own, and follows
-the control plane's keys, bans and policy while it runs.
+finds services and calls them, answers A2A requests for the agent itself,
+and follows the control plane's keys, bans and policy while it runs. It
+publishes no service; a tool or a model others should find by name runs
+behind a `sam-node`.
Guide: [sam-mesh.dev/docs/guides/native-sdks](https://sam-mesh.dev/docs/guides/native-sdks/),
from an empty machine to two programs on a mesh.
@@ -31,12 +33,13 @@ Find a service and call it:
<!-- embed: sdk/js/examples/call.ts -->
```ts
-// Finds a service on the mesh and calls it: a tool of an MCP service, or a
-// path of an inference or A2A service.
+// Calls something on the mesh: a tool of an MCP service or a path of an
+// inference or A2A service someone published, found by name, or an agent that
+// published nothing, reached by its peer ID.
//
-// node call.js mcp://greeter greet '{"name": "Ada"}'
-// node call.js a2a://greeter /card
+// node call.js mcp://everything echo '{"message": "hi"}'
// node call.js inference://ollama /v1/models
+// node call.js 12D3KooW... a2a://agent /card
//
// 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
@@ -46,7 +49,13 @@ Find a service and call it:
import { homedir } from "node:os";
import { AgentMesh, type DiscoveredProvider } from "@sam-mesh/sdk";
-const [service = "mcp://greeter", toolOrPath = "greet", args = '{"name": "world"}'] = process.argv.slice(2);
+let argv = process.argv.slice(2);
+// A first argument that is not a service target is the peer ID of an agent.
+let peerId: string | undefined;
+if (argv[0] !== undefined && !argv[0].includes("://")) {
+ [peerId, ...argv] = argv as [string, ...string[]];
+}
+const [service = peerId !== undefined ? "a2a://agent" : "mcp://everything", toolOrPath = peerId !== undefined ? "/card" : "echo", args = '{"message": "hi"}'] = argv;
const mesh = await AgentMesh.enroll({
controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",
@@ -59,23 +68,32 @@ const mesh = await AgentMesh.enroll({
const session = await mesh.join();
console.log(`on the mesh as ${session.peerId}`);
-const providers = await session.discover(service);
-if (providers.length === 0) {
- throw new Error(`no member of the mesh serves ${service}`);
-}
-// A provider record can outlive its member; the first that answers is used.
-let provider: DiscoveredProvider | undefined;
-for (const candidate of providers) {
- try {
- await session.connect(candidate);
- provider = candidate;
- break;
- } catch (err) {
- console.error(`${candidate.peerId}: ${(err as Error).message}`);
+// The peer to call: an agent named by ID, or a provider of a published service.
+let provider: DiscoveredProvider = { peerId: peerId ?? "", addrs: [] };
+if (peerId !== undefined) {
+ // An agent is not in the discovery table; the SDK finds the path to its
+ // peer ID through the routers.
+ await session.connect(peerId);
+} else {
+ const providers = await session.discover(service);
+ if (providers.length === 0) {
+ throw new Error(`no member of the mesh serves ${service}`);
+ }
+ // A provider record can outlive its member; the first that answers is used.
+ let reached = false;
+ for (const candidate of providers) {
+ try {
+ await session.connect(candidate);
+ provider = candidate;
+ reached = true;
+ break;
+ } catch (err) {
+ console.error(`${candidate.peerId}: ${(err as Error).message}`);
+ }
+ }
+ if (!reached) {
+ throw new Error(`no provider of ${service} is reachable`);
}
-}
-if (provider === undefined) {
- throw new Error(`no provider of ${service} is reachable`);
}
console.log(`${service} is served by ${provider.peerId}`);
@@ -93,64 +111,49 @@ await session.close();
```
<!-- /embed -->
-Publish services of your own:
+Be an agent others can call. Nothing is published; a caller reaches the
+agent by its peer ID, the one it prints, through a router:
-<!-- embed: sdk/js/examples/serve.ts -->
+<!-- embed: sdk/js/examples/agent.ts -->
```ts
-// Publishes services on the mesh and answers callers until stopped: an MCP
-// tool, an A2A endpoint and, when OLLAMA_URL is set, the Ollama server running
-// 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.
+// An agent on the mesh: joins, then answers A2A requests from other members
+// until stopped. It publishes nothing. There is no service name to look up; a
+// caller reaches the agent by its peer ID, through a router, as a2a://agent.
+// The mesh policy decides which members may call; the SDK turns the others
+// away before anything reaches this code.
//
-// node serve.js # publishes mcp://greeter and a2a://greeter
-// node serve.js greeter-2 # the same under another name
+// node agent.js # answered by the handler below
+// node agent.js http://127.0.0.1:9999 # forwarded to an A2A server beside 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.
+// credential in SAM_STATE_DIR; later runs resume from there, as the same
+// peer, 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 [backendURL] = 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,
jwtPath: process.env.SAM_JWT_PATH,
- stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/${name}`,
+ stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/agent`,
// 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,
- createServer: () => {
- 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;
- },
-});
-
-await session.serve({
- type: "a2a",
- name,
- target: (request, caller) => Response.json({ name, path: new URL(request.url).pathname, caller: caller.peerId }),
-});
-
-if (process.env.OLLAMA_URL !== undefined) {
- await session.serve({ type: "inference", name: "ollama", target: process.env.OLLAMA_URL });
-}
-
-console.log(`serving ${session.servedServices.map((s) => `${s.type}://${s.name}`).join(", ")} as ${session.peerId}`);
+// Answers every path with who was asked and who asked; a real agent runs an
+// A2A server here, or beside this process at backendURL.
+const target = await session.acceptA2A(
+ backendURL !== undefined
+ ? { url: backendURL }
+ : { handler: (request, caller) => Response.json({ name: "agent", path: new URL(request.url).pathname, caller: caller.peerId }) },
+);
+console.log(`accepting ${target} as ${session.peerId}`);
const stop = () => void session.close().then(() => process.exit(0));
process.on("SIGINT", stop);
diff --git a/sdk/js/examples/call.ts b/sdk/js/examples/call.ts
index 28ba1522..b3249fa6 100644
--- a/sdk/js/examples/call.ts
+++ b/sdk/js/examples/call.ts
@@ -2,7 +2,7 @@
// inference or A2A service someone published, found by name, or an agent that
// published nothing, reached by its peer ID.
//
-// node call.js mcp://greeter greet '{"name": "Ada"}'
+// node call.js mcp://everything echo '{"message": "hi"}'
// node call.js inference://ollama /v1/models
// node call.js 12D3KooW... a2a://agent /card
//
@@ -12,7 +12,7 @@
// 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, type Peer } from "@sam-mesh/sdk";
+import { AgentMesh, type DiscoveredProvider } from "@sam-mesh/sdk";
let argv = process.argv.slice(2);
// A first argument that is not a service target is the peer ID of an agent.
@@ -20,7 +20,7 @@ let peerId: string | undefined;
if (argv[0] !== undefined && !argv[0].includes("://")) {
[peerId, ...argv] = argv as [string, ...string[]];
}
-const [service = peerId !== undefined ? "a2a://agent" : "mcp://greeter", toolOrPath = peerId !== undefined ? "/card" : "greet", args = '{"name": "world"}'] = argv;
+const [service = peerId !== undefined ? "a2a://agent" : "mcp://everything", toolOrPath = peerId !== undefined ? "/card" : "echo", args = '{"message": "hi"}'] = argv;
const mesh = await AgentMesh.enroll({
controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",
@@ -33,32 +33,34 @@ const mesh = await AgentMesh.enroll({
const session = await mesh.join();
console.log(`on the mesh as ${session.peerId}`);
-let provider: Peer | undefined;
+// The peer to call: an agent named by ID, or a provider of a published service.
+let provider: DiscoveredProvider = { peerId: peerId ?? "", addrs: [] };
if (peerId !== undefined) {
// An agent is not in the discovery table; the SDK finds the path to its
// peer ID through the routers.
await session.connect(peerId);
- provider = peerId;
} else {
const providers = await session.discover(service);
if (providers.length === 0) {
throw new Error(`no member of the mesh serves ${service}`);
}
// A provider record can outlive its member; the first that answers is used.
+ let reached = false;
for (const candidate of providers) {
try {
await session.connect(candidate);
provider = candidate;
+ reached = true;
break;
} catch (err) {
console.error(`${candidate.peerId}: ${(err as Error).message}`);
}
}
- if (provider === undefined) {
+ if (!reached) {
throw new Error(`no provider of ${service} is reachable`);
}
}
-console.log(`${service} is served by ${typeof provider === "string" ? provider : (provider as { peerId: string }).peerId}`);
+console.log(`${service} is served by ${provider.peerId}`);
if (service.startsWith("mcp://")) {
const tools = await session.listTools(provider, service);
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 6d72c3ac..ee8165e5 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -3,8 +3,10 @@
Native Python SDK for joining a SAM agent mesh from inside the agent
process. It replaces the `sam-node` sidecar for agents written in Python:
the agent enrolls with the control plane, joins the mesh through a router,
-finds services and calls them, publishes services of its own, and follows
-the control plane's keys, bans and policy while it runs. Import it as
+finds services and calls them, answers A2A requests for the agent itself,
+and follows the control plane's keys, bans and policy while it runs. It
+publishes no service; a tool or a model others should find by name runs
+behind a `sam-node`. Import it as
`agent_mesh`.
Guide: [sam-mesh.dev/docs/guides/native-sdks](https://sam-mesh.dev/docs/guides/native-sdks/),
@@ -34,12 +36,13 @@ Find a service and call it:
<!-- embed: sdk/python/examples/call.py -->
```python
-"""Finds a service on the mesh and calls it: a tool of an MCP service, or a
-path of an inference or A2A service.
+"""Calls something on the mesh: a tool of an MCP service or a path of an
+inference or A2A service someone published, found by name, or an agent that
+published nothing, reached by its peer ID.
- python call.py mcp://greeter greet '{"name": "Ada"}'
- python call.py a2a://greeter /card
+ python call.py mcp://everything echo '{"message": "hi"}'
python call.py inference://ollama /v1/models
+ python call.py 12D3KooW... a2a://agent /card
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
@@ -56,9 +59,13 @@ import trio
from agent_mesh import AgentMesh
argv = sys.argv[1:]
-service = argv[0] if len(argv) > 0 else "mcp://greeter"
-tool_or_path = argv[1] if len(argv) > 1 else "greet"
-args = json.loads(argv[2]) if len(argv) > 2 else {"name": "world"}
+# A first argument that is not a service target is the peer ID of an agent.
+peer_id = None
+if argv and "://" not in argv[0]:
+ peer_id, argv = argv[0], argv[1:]
+service = argv[0] if len(argv) > 0 else ("a2a://agent" if peer_id else "mcp://everything")
+tool_or_path = argv[1] if len(argv) > 1 else ("/card" if peer_id else "echo")
+args = json.loads(argv[2]) if len(argv) > 2 else {"message": "hi"}
mesh = AgentMesh.enroll(
os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),
@@ -74,19 +81,25 @@ async def main() -> None:
async with mesh.join() as session:
print(f"on the mesh as {session.peer_id}")
- providers = await session.discover(service)
- if not providers:
- raise SystemExit(f"no member of the mesh serves {service}")
- # A provider record can outlive its member; the first that answers is used.
- for provider in providers:
- try:
- await session.connect(provider)
- break
- except (ConnectionError, PermissionError) as err:
- print(f"{provider.peer_id}: {err}", file=sys.stderr)
+ if peer_id:
+ # An agent is not in the discovery table; the SDK finds the path
+ # to its peer ID through the routers.
+ await session.connect(peer_id)
+ provider = peer_id
else:
- raise SystemExit(f"no provider of {service} is reachable")
- print(f"{service} is served by {provider.peer_id}")
+ providers = await session.discover(service)
+ if not providers:
+ raise SystemExit(f"no member of the mesh serves {service}")
+ # A provider record can outlive its member; the first that answers is used.
+ for provider in providers:
+ try:
+ await session.connect(provider)
+ break
+ except (ConnectionError, PermissionError) as err:
+ print(f"{provider.peer_id}: {err}", file=sys.stderr)
+ else:
+ raise SystemExit(f"no provider of {service} is reachable")
+ print(f"{service} is served by {peer_id or provider.peer_id}")
if service.startswith("mcp://"):
tools = await session.list_tools(provider, service)
@@ -102,24 +115,25 @@ trio.run(main)
```
<!-- /embed -->
-Publish services of your own:
+Be an agent others can call. Nothing is published; a caller reaches the
+agent by its peer ID, the one it prints, through a router:
-<!-- embed: sdk/python/examples/serve.py -->
+<!-- embed: sdk/python/examples/agent.py -->
```python
-"""Publishes services on the mesh and answers callers until stopped: an MCP
-tool, an A2A endpoint and, when OLLAMA_URL is set, the Ollama server running
-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.
+"""An agent on the mesh: joins, then answers A2A requests from other members
+until stopped. It publishes nothing. There is no service name to look up; a
+caller reaches the agent by its peer ID, through a router, as `a2a://agent`.
+The mesh policy decides which members may call; the SDK turns the others away
+before anything reaches this code.
- python serve.py # publishes mcp://greeter and a2a://greeter
- python serve.py greeter-2 # the same under another name
+ python agent.py # answered by the handler below
+ python agent.py http://127.0.0.1:9999 # forwarded to an A2A server beside 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.
+SAM_STATE_DIR; later runs resume from there, as the same peer, without it.
"""
import json
@@ -127,45 +141,31 @@ import os
import sys
import trio
-from agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, HTTPService, MCPService, VerifiedBiscuit
-from mcp.server.mcpserver import MCPServer
+from agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, VerifiedBiscuit
-service_name = sys.argv[1] if len(sys.argv) > 1 else "greeter"
+backend_url = sys.argv[1] if len(sys.argv) > 1 else None
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", f"~/.config/sam-mesh/{service_name}"),
+ state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/agent"),
# 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(service_name)
-
- @server.tool(description="Greets someone by name")
- def greet(name: str) -> str:
- return f"hello {name}"
-
- return server
-
-
async def card(request: HTTPRequest, caller: VerifiedBiscuit) -> HTTPResponse:
- body = json.dumps({"name": service_name, "path": request.path, "caller": caller.peer_id})
+ """Answers every path with who was asked and who asked; a real agent runs
+ an A2A server here, or beside this process at backend_url."""
+ body = json.dumps({"name": "agent", "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=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"]))
-
- served = ", ".join(f"{t}://{n}" for t, n, _ in session.services.list())
- print(f"serving {served} as {session.peer_id}", flush=True)
+ target = await session.accept_a2a(backend_url or card)
+ print(f"accepting {target} as {session.peer_id}", flush=True)
await trio.sleep_forever()
diff --git a/sdk/python/examples/call.py b/sdk/python/examples/call.py
index 43a2ef05..415132b5 100644
--- a/sdk/python/examples/call.py
+++ b/sdk/python/examples/call.py
@@ -2,7 +2,7 @@
inference or A2A service someone published, found by name, or an agent that
published nothing, reached by its peer ID.
- python call.py mcp://greeter greet '{"name": "Ada"}'
+ python call.py mcp://everything echo '{"message": "hi"}'
python call.py inference://ollama /v1/models
python call.py 12D3KooW... a2a://agent /card
@@ -25,9 +25,9 @@ argv = sys.argv[1:]
peer_id = None
if argv and "://" not in argv[0]:
peer_id, argv = argv[0], argv[1:]
-service = argv[0] if len(argv) > 0 else ("a2a://agent" if peer_id else "mcp://greeter")
-tool_or_path = argv[1] if len(argv) > 1 else ("/card" if peer_id else "greet")
-args = json.loads(argv[2]) if len(argv) > 2 else {"name": "world"}
+service = argv[0] if len(argv) > 0 else ("a2a://agent" if peer_id else "mcp://everything")
+tool_or_path = argv[1] if len(argv) > 1 else ("/card" if peer_id else "echo")
+args = json.loads(argv[2]) if len(argv) > 2 else {"message": "hi"}
mesh = AgentMesh.enroll(
os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),
diff --git a/site/content/docs/guides/native-sdks.md b/site/content/docs/guides/native-sdks.md
index eedb11d9..89649ba6 100644
--- a/site/content/docs/guides/native-sdks.md
+++ b/site/content/docs/guides/native-sdks.md
@@ -7,18 +7,26 @@ weight: 6
An agent written in JavaScript or Python can be a member of the mesh itself,
with no `sam-node` beside it. The SDK enrolls with the control plane, joins
through a router, finds services, calls MCP tools and inference or A2A
-endpoints, and publishes services of its own. Every caller of those services
-is checked against the mesh policy before anything reaches your code.
+endpoints, and answers A2A requests for the agent itself. Every caller of
+the agent is checked against the mesh policy before anything reaches your
+code.
-This guide takes you from nothing to two programs on a mesh: one that
-publishes a tool and an agent card, and one that finds them and calls them.
-Both programs are in the repository under
+This guide takes you from nothing to two programs on a mesh: an agent that
+other members can call, and a caller that reaches a service by name and the
+agent by its peer ID. Both programs are in the repository under
[`sdk/js/examples`](https://github.com/google/sam/tree/main/sdk/js/examples)
and
[`sdk/python/examples`](https://github.com/google/sam/tree/main/sdk/python/examples),
and the repository's tests run them against a real mesh, so what you read
here is what runs.
+An SDK member calls what the mesh offers and accepts A2A requests for its
+own agent. It does not publish services. A tool, a model or an agent that
+others should find by name runs behind a `sam-node`, which publishes it and
+enforces the policy; see [Your own mesh](../../getting-started/your-own-mesh/).
+The reasons are in the
+[SDK README](https://github.com/google/sam/blob/main/sdk/README.md#agents-not-services).
+
## 1. Get a mesh
A program needs the URL of a control plane and a token that lets it enroll.
@@ -92,84 +100,67 @@ programs as canaries beside the `sam-node` ones.
## 2. Install the SDK
```bash
-npm install @sam-mesh/sdk @modelcontextprotocol/sdk zod # Node.js 22 or later
+npm install @sam-mesh/sdk # Node.js 22 or later
```
```bash
-pip install sam-mesh # Python 3.11 or later
+pip install sam-mesh # Python 3.11 or later
```
-The JavaScript package depends on the MCP SDK and zod; the install line
-names them so your project can import them directly. The Python package is
-imported as `agent_mesh`. It runs on trio, because py-libp2p does; under
-asyncio, use it through `anyio` with the trio backend.
+The Python package is imported as `agent_mesh`. It runs on trio, because
+py-libp2p does; under asyncio, use it through `anyio` with the trio backend.
-## 3. Publish a service
+## 3. Be an agent
-This program publishes an MCP tool named `greet` under the service
-`mcp://greeter` and an A2A endpoint under `a2a://greeter`, and stays on the
-mesh answering callers until you stop it. With `OLLAMA_URL` set, it also
-publishes the Ollama server running beside it as `inference://ollama`, so a
-model on your laptop becomes a model on the mesh.
+This program joins the mesh and answers A2A requests for `a2a://agent`
+until you stop it. It publishes nothing: there is no name to look up. A
+caller reaches it by the peer ID it prints, through a router. Without an
+argument the handler in the program answers; with the URL of an A2A server
+running beside it, requests are forwarded there, which is how an agent
+written with an A2A SDK joins the mesh.
-JavaScript, `serve.js`:
+JavaScript, `agent.js`:
-<!-- embed: sdk/js/examples/serve.ts -->
+<!-- embed: sdk/js/examples/agent.ts -->
```ts
-// Publishes services on the mesh and answers callers until stopped: an MCP
-// tool, an A2A endpoint and, when OLLAMA_URL is set, the Ollama server running
-// 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.
+// An agent on the mesh: joins, then answers A2A requests from other members
+// until stopped. It publishes nothing. There is no service name to look up; a
+// caller reaches the agent by its peer ID, through a router, as a2a://agent.
+// The mesh policy decides which members may call; the SDK turns the others
+// away before anything reaches this code.
//
-// node serve.js # publishes mcp://greeter and a2a://greeter
-// node serve.js greeter-2 # the same under another name
+// node agent.js # answered by the handler below
+// node agent.js http://127.0.0.1:9999 # forwarded to an A2A server beside 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.
+// credential in SAM_STATE_DIR; later runs resume from there, as the same
+// peer, 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 [backendURL] = 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,
jwtPath: process.env.SAM_JWT_PATH,
- stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/${name}`,
+ stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/agent`,
// 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,
- createServer: () => {
- 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;
- },
-});
-
-await session.serve({
- type: "a2a",
- name,
- target: (request, caller) => Response.json({ name, path: new URL(request.url).pathname, caller: caller.peerId }),
-});
-
-if (process.env.OLLAMA_URL !== undefined) {
- await session.serve({ type: "inference", name: "ollama", target: process.env.OLLAMA_URL });
-}
-
-console.log(`serving ${session.servedServices.map((s) => `${s.type}://${s.name}`).join(", ")} as ${session.peerId}`);
+// Answers every path with who was asked and who asked; a real agent runs an
+// A2A server here, or beside this process at backendURL.
+const target = await session.acceptA2A(
+ backendURL !== undefined
+ ? { url: backendURL }
+ : { handler: (request, caller) => Response.json({ name: "agent", path: new URL(request.url).pathname, caller: caller.peerId }) },
+);
+console.log(`accepting ${target} as ${session.peerId}`);
const stop = () => void session.close().then(() => process.exit(0));
process.on("SIGINT", stop);
@@ -177,24 +168,24 @@ process.on("SIGTERM", stop);
```
<!-- /embed -->
-Python, `serve.py`:
+Python, `agent.py`:
-<!-- embed: sdk/python/examples/serve.py -->
+<!-- embed: sdk/python/examples/agent.py -->
```python
-"""Publishes services on the mesh and answers callers until stopped: an MCP
-tool, an A2A endpoint and, when OLLAMA_URL is set, the Ollama server running
-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.
+"""An agent on the mesh: joins, then answers A2A requests from other members
+until stopped. It publishes nothing. There is no service name to look up; a
+caller reaches the agent by its peer ID, through a router, as `a2a://agent`.
+The mesh policy decides which members may call; the SDK turns the others away
+before anything reaches this code.
- python serve.py # publishes mcp://greeter and a2a://greeter
- python serve.py greeter-2 # the same under another name
+ python agent.py # answered by the handler below
+ python agent.py http://127.0.0.1:9999 # forwarded to an A2A server beside 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.
+SAM_STATE_DIR; later runs resume from there, as the same peer, without it.
"""
import json
@@ -202,45 +193,31 @@ import os
import sys
import trio
-from agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, HTTPService, MCPService, VerifiedBiscuit
-from mcp.server.mcpserver import MCPServer
+from agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, VerifiedBiscuit
-service_name = sys.argv[1] if len(sys.argv) > 1 else "greeter"
+backend_url = sys.argv[1] if len(sys.argv) > 1 else None
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", f"~/.config/sam-mesh/{service_name}"),
+ state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/agent"),
# 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(service_name)
-
- @server.tool(description="Greets someone by name")
- def greet(name: str) -> str:
- return f"hello {name}"
-
- return server
-
-
async def card(request: HTTPRequest, caller: VerifiedBiscuit) -> HTTPResponse:
- body = json.dumps({"name": service_name, "path": request.path, "caller": caller.peer_id})
+ """Answers every path with who was asked and who asked; a real agent runs
+ an A2A server here, or beside this process at backend_url."""
+ body = json.dumps({"name": "agent", "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=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"]))
-
- served = ", ".join(f"{t}://{n}" for t, n, _ in session.services.list())
- print(f"serving {served} as {session.peer_id}", flush=True)
+ target = await session.accept_a2a(backend_url or card)
+ print(f"accepting {target} as {session.peer_id}", flush=True)
await trio.sleep_forever()
@@ -251,37 +228,39 @@ trio.run(main)
Run one of them:
```bash
-node serve.js
+node agent.js
# or
-python serve.py
+python agent.py
```
```text
-serving mcp://greeter, a2a://greeter as 12D3KooWQmB5…
+accepting a2a://agent as 12D3KooWQmB5…
```
The program spent the token, saved its identity and credential under
-`~/.config/sam-mesh/greeter`, joined through the router and announced its
-services. Run it again and it resumes from that directory; the token is no
-longer needed. The service is reachable from every member of the mesh:
+`~/.config/sam-mesh/agent`, joined through the router and started answering.
+Run it again and it resumes from that directory, as the same peer; the token
+is no longer needed. Keep the peer ID: it is how the agent is reached, from
another program written with an SDK, a `sam-node` on any machine, or a
phone.
## 4. Call it
-This program finds a service by name and calls it: a tool of an MCP service,
-or a path of an inference or A2A service.
+This program calls something on the mesh: a tool or a path of a service
+someone published, found by name, or an agent that published nothing,
+reached by its peer ID.
JavaScript, `call.js`:
<!-- embed: sdk/js/examples/call.ts -->
```ts
-// Finds a service on the mesh and calls it: a tool of an MCP service, or a
-// path of an inference or A2A service.
+// Calls something on the mesh: a tool of an MCP service or a path of an
+// inference or A2A service someone published, found by name, or an agent that
+// published nothing, reached by its peer ID.
//
-// node call.js mcp://greeter greet '{"name": "Ada"}'
-// node call.js a2a://greeter /card
+// node call.js mcp://everything echo '{"message": "hi"}'
// node call.js inference://ollama /v1/models
+// node call.js 12D3KooW... a2a://agent /card
//
// 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
@@ -291,7 +270,13 @@ JavaScript, `call.js`:
import { homedir } from "node:os";
import { AgentMesh, type DiscoveredProvider } from "@sam-mesh/sdk";
-const [service = "mcp://greeter", toolOrPath = "greet", args = '{"name": "world"}'] = process.argv.slice(2);
+let argv = process.argv.slice(2);
+// A first argument that is not a service target is the peer ID of an agent.
+let peerId: string | undefined;
+if (argv[0] !== undefined && !argv[0].includes("://")) {
+ [peerId, ...argv] = argv as [string, ...string[]];
+}
+const [service = peerId !== undefined ? "a2a://agent" : "mcp://everything", toolOrPath = peerId !== undefined ? "/card" : "echo", args = '{"message": "hi"}'] = argv;
const mesh = await AgentMesh.enroll({
controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",
@@ -304,23 +289,32 @@ const mesh = await AgentMesh.enroll({
const session = await mesh.join();
console.log(`on the mesh as ${session.peerId}`);
-const providers = await session.discover(service);
-if (providers.length === 0) {
- throw new Error(`no member of the mesh serves ${service}`);
-}
-// A provider record can outlive its member; the first that answers is used.
-let provider: DiscoveredProvider | undefined;
-for (const candidate of providers) {
- try {
- await session.connect(candidate);
- provider = candidate;
- break;
- } catch (err) {
- console.error(`${candidate.peerId}: ${(err as Error).message}`);
+// The peer to call: an agent named by ID, or a provider of a published service.
+let provider: DiscoveredProvider = { peerId: peerId ?? "", addrs: [] };
+if (peerId !== undefined) {
+ // An agent is not in the discovery table; the SDK finds the path to its
+ // peer ID through the routers.
+ await session.connect(peerId);
+} else {
+ const providers = await session.discover(service);
+ if (providers.length === 0) {
+ throw new Error(`no member of the mesh serves ${service}`);
+ }
+ // A provider record can outlive its member; the first that answers is used.
+ let reached = false;
+ for (const candidate of providers) {
+ try {
+ await session.connect(candidate);
+ provider = candidate;
+ reached = true;
+ break;
+ } catch (err) {
+ console.error(`${candidate.peerId}: ${(err as Error).message}`);
+ }
+ }
+ if (!reached) {
+ throw new Error(`no provider of ${service} is reachable`);
}
-}
-if (provider === undefined) {
- throw new Error(`no provider of ${service} is reachable`);
}
console.log(`${service} is served by ${provider.peerId}`);
@@ -342,12 +336,13 @@ Python, `call.py`:
<!-- embed: sdk/python/examples/call.py -->
```python
-"""Finds a service on the mesh and calls it: a tool of an MCP service, or a
-path of an inference or A2A service.
+"""Calls something on the mesh: a tool of an MCP service or a path of an
+inference or A2A service someone published, found by name, or an agent that
+published nothing, reached by its peer ID.
- python call.py mcp://greeter greet '{"name": "Ada"}'
- python call.py a2a://greeter /card
+ python call.py mcp://everything echo '{"message": "hi"}'
python call.py inference://ollama /v1/models
+ python call.py 12D3KooW... a2a://agent /card
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
@@ -364,9 +359,13 @@ import trio
from agent_mesh import AgentMesh
argv = sys.argv[1:]
-service = argv[0] if len(argv) > 0 else "mcp://greeter"
-tool_or_path = argv[1] if len(argv) > 1 else "greet"
-args = json.loads(argv[2]) if len(argv) > 2 else {"name": "world"}
+# A first argument that is not a service target is the peer ID of an agent.
+peer_id = None
+if argv and "://" not in argv[0]:
+ peer_id, argv = argv[0], argv[1:]
+service = argv[0] if len(argv) > 0 else ("a2a://agent" if peer_id else "mcp://everything")
+tool_or_path = argv[1] if len(argv) > 1 else ("/card" if peer_id else "echo")
+args = json.loads(argv[2]) if len(argv) > 2 else {"message": "hi"}
mesh = AgentMesh.enroll(
os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),
@@ -382,19 +381,25 @@ async def main() -> None:
async with mesh.join() as session:
print(f"on the mesh as {session.peer_id}")
- providers = await session.discover(service)
- if not providers:
- raise SystemExit(f"no member of the mesh serves {service}")
- # A provider record can outlive its member; the first that answers is used.
- for provider in providers:
- try:
- await session.connect(provider)
- break
- except (ConnectionError, PermissionError) as err:
- print(f"{provider.peer_id}: {err}", file=sys.stderr)
+ if peer_id:
+ # An agent is not in the discovery table; the SDK finds the path
+ # to its peer ID through the routers.
+ await session.connect(peer_id)
+ provider = peer_id
else:
- raise SystemExit(f"no provider of {service} is reachable")
- print(f"{service} is served by {provider.peer_id}")
+ providers = await session.discover(service)
+ if not providers:
+ raise SystemExit(f"no member of the mesh serves {service}")
+ # A provider record can outlive its member; the first that answers is used.
+ for provider in providers:
+ try:
+ await session.connect(provider)
+ break
+ except (ConnectionError, PermissionError) as err:
+ print(f"{provider.peer_id}: {err}", file=sys.stderr)
+ else:
+ raise SystemExit(f"no provider of {service} is reachable")
+ print(f"{service} is served by {peer_id or provider.peer_id}")
if service.startswith("mcp://"):
tools = await session.list_tools(provider, service)
@@ -411,39 +416,36 @@ trio.run(main)
<!-- /embed -->
In a second terminal, with the same two environment variables set, call the
-tool and the agent card. Either language finds a service published from the
-other:
+agent by the peer ID it printed. Either language reaches an agent written
+with the other:
```bash
-node call.js mcp://greeter greet '{"name": "Ada"}'
+python call.py 12D3KooWQmB5… a2a://agent /card
```
```text
on the mesh as 12D3KooWHZ2M…
-mcp://greeter is served by 12D3KooWQmB5…
-tools: greet
-hello Ada
+a2a://agent is served by 12D3KooWQmB5…
+200 {"name": "agent", "path": "/card", "caller": "12D3KooWHZ2M…"}
```
+A service a `sam-node` publishes is found by name instead. On a mesh with
+the `everything` canary of the public testnets, or your own `sam-node` with
+an MCP server behind it:
+
```bash
-python call.py a2a://greeter /card
+node call.js mcp://everything echo '{"message": "hi"}'
```
```text
on the mesh as 12D3KooWHZ2M…
-a2a://greeter is served by 12D3KooWQmB5…
-200 {"name": "greeter", "path": "/card", "caller": "12D3KooWHZ2M…"}
-```
-
-If you started the server with `OLLAMA_URL=http://127.0.0.1:11434`, ask it
-for its models:
-
-```bash
-node call.js inference://ollama /v1/models
+mcp://everything is served by 12D3KooWAb3d…
+tools: echo, add, …
+Echo: hi
```
-The caller and the server are two identities on the mesh with their own
-state directories, `caller` and `greeter`. Each spent a token on its first
+The caller and the agent are two identities on the mesh with their own
+state directories, `caller` and `agent`. Each spent a token on its first
run; the standing join token of `sam-one` admits any number of members.
## What happened
@@ -466,29 +468,30 @@ the SDK follows the control plane: keys, bans and router addresses on
`sam-node`'s schedule, and sooner when the control plane announces a change
over the mesh.
-`discover` looked the service up by name in a table the routers host. Every
-call then dials the addresses the provider advertised and the path through
-the router, and verifies the provider's credential before sending anything.
-`requiredLabels` (`required_labels` in Python) refuses a provider whose
-control-plane-attested labels do not carry the values you ask for.
-
-`serve` fetched the mesh policy and started answering. Every caller must
-present a credential signed by a trusted control plane key, bound to the
-connection's peer and unexpired, and its role must be granted the service
-by the policy. The check runs on the same Datalog text a `sam-node`
-evaluates. A caller the policy does not admit is turned away before the
-request reaches your handler or your backend. Your handler sees the verified
-caller as `caller.peerId` (`caller.peer_id`) and, for a forwarded backend
-such as Ollama, as the `X-Peer-Id` header; the caller's credential is never
-forwarded.
+`discover` looked a service up by name in a table the routers host. An
+agent is not in that table; given its peer ID, `connect` dials the path
+through every router that admitted the caller, and the router opens a
+circuit because it admitted the agent too. Either way the SDK verifies the
+peer's credential before sending anything, and `requiredLabels`
+(`required_labels` in Python) refuses a peer whose control-plane-attested
+labels do not carry the values you ask for.
+
+`acceptA2A` (`accept_a2a`) fetched the mesh policy and started answering.
+Every caller must present a credential signed by a trusted control plane
+key, bound to the connection's peer and unexpired, and its role must be
+granted `a2a://agent` by the policy. The check runs on the same Datalog
+text a `sam-node` evaluates. A caller the policy does not admit is turned
+away before the request reaches your handler or your A2A server. Your
+handler sees the verified caller as `caller.peerId` (`caller.peer_id`) and
+a forwarded server as the `X-Peer-Id` header; the caller's credential is
+never forwarded. The connection is encrypted end to end between the two
+peers; the router forwards ciphertext.
Under the open development policy of `sam-one`, every member holds the
`node` role and that role may call any service. On a shared mesh the policy
-grants a role the services it may call (`allowed_services: ["mcp://greeter"]`
+grants a role the services it may call (`allowed_services: ["a2a://agent"]`
or a pattern) and the members it may reach; see
-[Mesh policy](../../reference/policy/). A refused MCP caller receives
-`AuthResponse{success: false}` on the stream; a refused HTTP caller receives
-`403`.
+[Mesh policy](../../reference/policy/). A refused caller receives `403`.
## Beyond the examples
@@ -496,19 +499,30 @@ or a pattern) and the members it may reach; see
`connect` accept a provider from `discover`, a peer id, or a multiaddr.
With a peer id alone the SDK goes through the routers.
- **Every service of a type.** `discover("mcp")` lists every MCP provider
- on the mesh; `discover("mcp://greeter")` those of one service.
-- **A member's own catalog.** `listTools(peer, "")` returns the provider's
- `list_local_services` tool, the same one a `sam-node` offers.
-- **Forwarding to a local server.** `serve({ type: "inference", name,
- target: "http://127.0.0.1:8000" })` and
- `HTTPService(type="inference", name=..., target="http://...")` forward
- authorized requests to a URL; a function instead of a URL handles them in
- the process.
+ on the mesh; `discover("mcp://everything")` those of one service.
+- **A member's own catalog.** `listTools(peer, "")` returns a `sam-node`'s
+ `list_local_services` tool.
+- **An agent written with an A2A SDK.** Run its server on a local port and
+ pass the URL: `acceptA2A({ url: "http://127.0.0.1:9999" })`,
+ `accept_a2a("http://127.0.0.1:9999")`. In JavaScript an Express app with
+ the A2A SDK's handlers can also run in the process:
+ `acceptA2A({ listener: app })`. The agent's name defaults to `agent`;
+ `name` picks another, and callers use `a2a://<name>`.
+- **Calling an agent with an A2A SDK client.** The mesh is a transport for
+ HTTP clients. A peer's service has the URL
+ `http://mesh/sam/<peer-id>/a2a/agent` (`MeshSession.meshURL`,
+ `MeshSession.mesh_url`); the A2A JavaScript client takes
+ `fetchImpl: session.fetch()`, the Python one an
+ `httpx.AsyncClient(transport=MeshTransport(session))`. Response bodies
+ stream, so `message/stream` works.
- **Reading the policy.** `session.policyRules` (`session.policy_rules`)
holds the Datalog the session enforces, for logging or tests.
## What the SDKs do not do
+- They do not publish services. An MCP server, a model or an agent that
+ others should find by name runs behind a `sam-node`, which publishes it
+ to the discovery table and reports it to the console.
- They do not run a sidecar API or a sandbox. An agent that needs the egress
policy enforcement of `sam-box` runs beside a `sam-node`.
- They do not serve the discovery table. A member is a client of it; the