Skip to content

Agent Mesh

sdk: egress destinations are a service type

Antonio Ojeafb399e759541
diff --git a/sdk/README.md b/sdk/README.md
index 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>` 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. 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 runs
to 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 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. The SDKs look
diff --git a/sdk/js/src/discovery.ts b/sdk/js/src/discovery.ts
index 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 | "" ; n
if (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.ts
index 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.ts
index 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, o
return { 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.ts
index 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.ts
index 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.py
index 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, name
diff --git a/sdk/python/src/agent_mesh/libp2p_http.py b/sdk/python/src/agent_mesh/libp2p_http.py
index 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.py
index 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 to
seed 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.py
index 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.py
index 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.json
index 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" }
]
}