Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: the SDKs are agents; they call services and accept A2A
Antonio Ojea34ef878da18b
diff --git a/sdk/README.md b/sdk/README.mdindex 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 wasremoved 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: itfinds 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, eachpinned by a test:@@ -94,7 +101,8 @@ pinned by a test:every outbound stream and returns it only when sending the SYN fails, sothe 257th `open_stream` on a connection blocks forever with no error. Amember 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 isreleased, `host.py` replaces `Yamux.open_stream` with one that does thesame, 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 Nodeduplex 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 atlibp2p 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 mustbe 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 arouter, requires the router role. This is how a member joins: connect to arouter, 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}`; serverauthorizes the request with the Biscuit authorizer described below andanswers `AuthResponse`. The stream then carries MCP JSON-RPC messages, eachone 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 foronce for the name (`<type>` is `mcp`, `inference` or `a2a`). A consumerlooks 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.+## PlanEach 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 generatedartifact 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`), builtfrom 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), amissing 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 thecredential 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. Runsonce shortly after join, then on `sam-node`'s interval with the samejitter, 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 keyand triggers a pull, `POLICY_UPDATE` triggers a pull. Bans are notpersisted; 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'sversion 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 testnetsBoth 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 therunners `sdk/js/src/conformance-join.ts` and`sdk/python/src/agent_mesh/conformance_join.py`: each joins, prints what itholds, 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 testcan 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.mdindex 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 agentprocess. 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.tsindex 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.mdindex 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 agentprocess. 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 /cardSAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the fileSAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH@@ -56,9 +59,13 @@ import triofrom agent_mesh import AgentMeshargv = 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_idelse:- 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 itSAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the fileSAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH(a workload identity token your platform issues, such as a Kubernetesprojected 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 osimport sysimport 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 Nonemesh = 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.pyindex 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 thatpublished 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/modelspython call.py 12D3KooW... a2a://agent /card@@ -25,9 +25,9 @@ argv = sys.argv[1:]peer_id = Noneif 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.mdindex eedb11d9..89649ba6 100644--- a/site/content/docs/guides/native-sdks.md+++ b/site/content/docs/guides/native-sdks.md@@ -7,18 +7,26 @@ weight: 6An 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, joinsthrough 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 readhere 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 meshA 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 itSAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the fileSAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH(a workload identity token your platform issues, such as a Kubernetesprojected 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 osimport sysimport 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 Nonemesh = 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, fromanother program written with an SDK, a `sam-node` on any machine, or aphone.## 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 /cardSAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the fileSAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH@@ -364,9 +359,13 @@ import triofrom agent_mesh import AgentMeshargv = 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_idelse:- 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``````texton 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"}'``````texton 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 firstrun; 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 changeover 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 egresspolicy enforcement of `sam-box` runs beside a `sam-node`.- They do not serve the discovery table. A member is a client of it; the