Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
sdk: egress destinations are a service type
Antonio Ojeafb399e759541
diff --git a/sdk/README.md b/sdk/README.mdindex b54c8dae..1dd3e22e 100644--- a/sdk/README.md+++ b/sdk/README.md@@ -280,8 +280,11 @@ bytes), with a 64 KiB cap on the first frame.`/<type>/<name>/<upstream>`; the server authorizes `<type>://<name>` withthe same authorizer, then forwards `<upstream>` to the service with thosetwo 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. Bodies are framed by+ are clients of this for `inference://`, `a2a://` and `egress://` services+ (an egress destination is one a `sam-node` serves for a hostname outside+ the mesh, as the control plane assigned it; the SDK reaches it as any+ other service, `/egress/<hostname>/<path>` on that node), and servers of+ it for their own agent, `a2a://<name>`, only. Bodies are framed by`Content-Length` or chunked transfer coding; a response with neither runsto the end of the stream. The JS SDK frames these itself(`http1.ts`), so the same code runs in a browser.@@ -290,7 +293,7 @@ bytes), with a 64 KiB cap on the first frame.A provider announces a service as a DHT provider record for`cidv1(raw, sha256("sam:service:<type>[:<name>]"))`, once for the type and-once for the name (`<type>` is `mcp`, `inference` or `a2a`). A consumer+once for the name (`<type>` is `mcp`, `inference`, `a2a` or `egress`). 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` forinterest-scoped updates; the DHT is the source of truth. The SDKs lookdiff --git a/sdk/js/src/discovery.ts b/sdk/js/src/discovery.tsindex 2f1dde41..5612988b 100644--- a/sdk/js/src/discovery.ts+++ b/sdk/js/src/discovery.ts@@ -22,10 +22,10 @@ import { sha256 } from "multiformats/hashes/sha2";/** The DHT protocol, go-libp2p-kad-dht with dht.ProtocolPrefix("/sam"). */export const DHT_PROTOCOL = "/sam/kad/1.0.0";-export type ServiceType = "mcp" | "inference" | "a2a";+export type ServiceType = "mcp" | "inference" | "a2a" | "egress";export function isServiceType(value: unknown): value is ServiceType {- return value === "mcp" || value === "inference" || value === "a2a";+ return value === "mcp" || value === "inference" || value === "a2a" || value === "egress";}/** The DHT key of a service: by type and name, or by type alone when name is omitted. */@@ -39,7 +39,7 @@ export function parseServiceTarget(target: string): { type: ServiceType | "" ; nif (target === "") {return { type: "", name: "" };}- const m = /^(mcp|inference|a2a):\/\/(.+)$/.exec(target);+ const m = /^(mcp|inference|a2a|egress):\/\/(.+)$/.exec(target);if (!m) {throw new Error(`service target must look like mcp://<name>, got ${JSON.stringify(target)}`);}diff --git a/sdk/js/src/libp2p-http.test.ts b/sdk/js/src/libp2p-http.test.tsindex 424c8548..697e2501 100644--- a/sdk/js/src/libp2p-http.test.ts+++ b/sdk/js/src/libp2p-http.test.ts@@ -359,6 +359,7 @@ test("mesh URLs name a peer and a service", () => {}assert.equal(meshHTTPTarget("a2a://agent"), "/a2a/agent");assert.equal(meshHTTPTarget("a2a://agent", "card"), "/a2a/agent/card");+ assert.equal(meshHTTPTarget("egress://api.github.com", "/repos/acme/x"), "/egress/api.github.com/repos/acme/x");assert.throws(() => meshHTTPTarget("ftp://agent", "/"));assert.throws(() => a2aEndpoint({}), /exactly one/);assert.throws(() => a2aEndpoint({ url: "http://x", handler: () => new Response() }), /exactly one/);diff --git a/sdk/js/src/libp2p-http.ts b/sdk/js/src/libp2p-http.tsindex 6508fcb8..afed2d8c 100644--- a/sdk/js/src/libp2p-http.ts+++ b/sdk/js/src/libp2p-http.ts@@ -175,7 +175,7 @@ export async function admitIngress(req: IngressRequest, endpoint: A2AEndpoint, oreturn { status: 400, text: "Invalid path" };}const [serviceType, serviceName, ...rest] = parts as [string, string, ...string[]];- if (serviceType !== "inference" && serviceType !== "a2a" && serviceType !== "mcp") {+ if (serviceType !== "inference" && serviceType !== "a2a" && serviceType !== "mcp" && serviceType !== "egress") {return { status: 400, text: "Invalid service type" };}const upstreamPath = rest.join("/");@@ -357,7 +357,7 @@ export function httpIngressHandler(endpoint: A2AEndpoint, options: ProviderOptio/** The request target for a service on a peer: /<type>/<name>/<path>. */export function meshHTTPTarget(targetService: string, path = ""): string {- const m = /^(inference|a2a|mcp):\/\/(.+)$/.exec(targetService);+ const m = /^(inference|a2a|mcp|egress):\/\/(.+)$/.exec(targetService);if (m === null) {throw new Error(`service target must look like inference://<name>, got ${JSON.stringify(targetService)}`);}diff --git a/sdk/js/src/mcp.test.ts b/sdk/js/src/mcp.test.tsindex efad91bc..7be179f7 100644--- a/sdk/js/src/mcp.test.ts+++ b/sdk/js/src/mcp.test.ts@@ -129,6 +129,7 @@ test("service keys match internal/node/service.go", async () => {assert.equal(Buffer.from(cid.multihash.bytes).toString("hex"), s.multihash);}assert.deepEqual(parseServiceTarget("mcp://calc"), { type: "mcp", name: "calc" });+ assert.deepEqual(parseServiceTarget("egress://api.github.com"), { type: "egress", name: "api.github.com" });assert.deepEqual(parseServiceTarget(""), { type: "", name: "" });assert.throws(() => parseServiceTarget("calc"), /must look like/);});diff --git a/sdk/js/src/session.ts b/sdk/js/src/session.tsindex 50f57249..748f1586 100644--- a/sdk/js/src/session.ts+++ b/sdk/js/src/session.ts@@ -241,7 +241,7 @@ export class MeshSession {async discover(service: string, name?: string, options: { timeoutMs?: number; limit?: number } = {}): Promise<DiscoveredProvider[]> {const target = service.includes("://") ? parseServiceTarget(service) : { type: service, name };if (!isServiceType(target.type)) {- throw new Error(`service type must be mcp, inference or a2a, got ${JSON.stringify(target.type)}`);+ throw new Error(`service type must be mcp, inference, a2a or egress, got ${JSON.stringify(target.type)}`);}const cid = await serviceCID(target.type, target.name);const signal = AbortSignal.timeout(options.timeoutMs ?? DISCOVERY_TIMEOUT_MS);diff --git a/sdk/python/src/agent_mesh/discovery.py b/sdk/python/src/agent_mesh/discovery.pyindex 9a97292f..238cb928 100644--- a/sdk/python/src/agent_mesh/discovery.py+++ b/sdk/python/src/agent_mesh/discovery.py@@ -41,7 +41,7 @@ logger = logging.getLogger("agent_mesh")# go-libp2p-kad-dht with dht.ProtocolPrefix("/sam").DHT_PROTOCOL = TProtocol("/sam/kad/1.0.0")-ServiceType = Literal["mcp", "inference", "a2a"]+ServiceType = Literal["mcp", "inference", "a2a", "egress"]_QUERY_TIMEOUT = 5.0_MAX_ROUNDS = 3@@ -70,7 +70,7 @@ def parse_service_target(target: str) -> tuple[str, str]:if target == "":return "", ""scheme, sep, name = target.partition("://")- if not sep or scheme not in ("mcp", "inference", "a2a") or not name:+ if not sep or scheme not in ("mcp", "inference", "a2a", "egress") or not name:raise ValueError(f"service target must look like mcp://<name>, got {target!r}")return scheme, namediff --git a/sdk/python/src/agent_mesh/libp2p_http.py b/sdk/python/src/agent_mesh/libp2p_http.pyindex 9d3e2c87..1642fa5a 100644--- a/sdk/python/src/agent_mesh/libp2p_http.py+++ b/sdk/python/src/agent_mesh/libp2p_http.py@@ -211,7 +211,7 @@ async def _handle_ingress(if len(parts) < 2 or not parts[0] or not parts[1]:return plain(400, "Invalid path")service_type, service_name, rest = parts[0], parts[1], parts[2:]- if service_type not in ("inference", "a2a", "mcp"):+ if service_type not in ("inference", "a2a", "mcp", "egress"):return plain(400, "Invalid service type")upstream_path = "/".join(rest)@@ -294,7 +294,7 @@ async def _read_or_eof(stream: INetStream, peer_id: ID) -> bytes:def mesh_http_target(target_service: str, path: str = "") -> str:"""The request target for a service on a peer: /<type>/<name>/<path>."""scheme, sep, name = target_service.partition("://")- if not sep or scheme not in ("inference", "a2a", "mcp") or not name:+ if not sep or scheme not in ("inference", "a2a", "mcp", "egress") or not name:raise ValueError(f"service target must look like inference://<name>, got {target_service!r}")if not path:return f"/{scheme}/{name}"diff --git a/sdk/python/src/agent_mesh/session.py b/sdk/python/src/agent_mesh/session.pyindex 3b36736b..640a7e86 100644--- a/sdk/python/src/agent_mesh/session.py+++ b/sdk/python/src/agent_mesh/session.py@@ -264,8 +264,8 @@ class MeshSession:service of that type, or (type, name). The routers we are connected toseed the walk."""service_type, service_name = parse_service_target(service) if "://" in service else (service, name)- if service_type not in ("mcp", "inference", "a2a"):- raise ValueError(f"service type must be mcp, inference or a2a, got {service_type!r}")+ if service_type not in ("mcp", "inference", "a2a", "egress"):+ raise ValueError(f"service type must be mcp, inference, a2a or egress, got {service_type!r}")seeds = [ID.from_base58(r.peer_id) for r in self.routers]return await find_providers(self.host, service_key(service_type, service_name), seeds, limit)diff --git a/sdk/python/tests/test_libp2p_http.py b/sdk/python/tests/test_libp2p_http.pyindex a7a6adff..df842940 100644--- a/sdk/python/tests/test_libp2p_http.py+++ b/sdk/python/tests/test_libp2p_http.py@@ -254,6 +254,7 @@ def test_mesh_urls_name_a_peer_and_a_service():split_mesh_url(httpx.URL(bad))assert mesh_http_target("a2a://agent") == "/a2a/agent"assert mesh_http_target("a2a://agent", "card") == "/a2a/agent/card"+ assert mesh_http_target("egress://api.github.com", "/repos/acme/x") == "/egress/api.github.com/repos/acme/x"with pytest.raises(ValueError):mesh_http_target("ftp://agent", "/")diff --git a/sdk/python/tests/test_mcp.py b/sdk/python/tests/test_mcp.pyindex c8feb33c..9c9e04dd 100644--- a/sdk/python/tests/test_mcp.py+++ b/sdk/python/tests/test_mcp.py@@ -157,6 +157,7 @@ def test_service_keys_match_internal_node_service():for s in FIXTURE["services"]:assert service_key(s["type"], s["name"] or None).hex() == s["multihash"], f"{s['type']}:{s['name']}"assert parse_service_target("mcp://calc") == ("mcp", "calc")+ assert parse_service_target("egress://api.github.com") == ("egress", "api.github.com")assert parse_service_target("") == ("", "")with pytest.raises(ValueError, match="must look like"):parse_service_target("calc")diff --git a/sdk/testdata/service_keys.json b/sdk/testdata/service_keys.jsonindex 93be7257..1c1ee2af 100644--- a/sdk/testdata/service_keys.json+++ b/sdk/testdata/service_keys.json@@ -4,6 +4,7 @@{ "type": "mcp", "name": "calc", "cid": "bafkreihp6rcivmw3pt27d4d6m73zeblbqueoo5cju6vcqyphqxcnmp563a", "multihash": "1220eff4448ab2db7cf5f1f07e67f79205618508e77449a7aa2861e785c4d63fbed8" },{ "type": "mcp", "name": "", "cid": "bafkreigld2lseddb5lpjmdy7drpmgzf5nle6gam4yjwdbvximrodw4mwre", "multihash": "1220cb1e97220c61eade960f1f1c5ec364bd6ac9e3019cc26c30d6e8645c3b719689" },{ "type": "inference", "name": "gpt", "cid": "bafkreifg2wo7urhcxh6vuv7q2tsvgo4agtjc52fbfxprc53d6ivtmlwkni", "multihash": "1220a6d59dfa44e2b9fd5a57f0d4e5533b8034d22ee8a12ddf117763f22b362eca6a" },- { "type": "a2a", "name": "echo", "cid": "bafkreiheyiafb5vwp6njr6jctvoeji5yavj7st74vfoarsh47u462azeze", "multihash": "1220e4c20050f6b67f9a98f9229d5c44a3b80553f94ffca95c08c8fcfd39ed0324c9" }+ { "type": "a2a", "name": "echo", "cid": "bafkreiheyiafb5vwp6njr6jctvoeji5yavj7st74vfoarsh47u462azeze", "multihash": "1220e4c20050f6b67f9a98f9229d5c44a3b80553f94ffca95c08c8fcfd39ed0324c9" },+ { "type": "egress", "name": "api.github.com", "cid": "bafkreihy5fvpsh6b62yg5qb62qqrcjosc7nn2u2nnlqipvmbqhgxnwcwty", "multihash": "1220f8e96af91fc1f6b06ec03ed4211125d217dadd534d6ae087d58181cd76d8569e" }]}