Announce a Capability#

A capability is a typed unit of work a node can do. An announcement places its descriptor and provider properties into the distributed fold. Callers with the required discovery authority can then find it. Invocation is a separate decision.

Two things you can announce#

Tags describe what a node is — gpu, region:eu-west, a model it hosts, an accelerator it has. Nothing is callable; you are populating a placement index so somebody can find a machine that fits.

Tools describe what a node can do — a named, schema'd operation an agent can invoke. A tool is the thing an LLM's tool-call resolves to.

Most agent code wants tools. Most placement code wants tags. They travel in the same capability set and are announced by the same call.

Serving a tool and announcing a tool are different acts#

Most bindings expose these as separate operations:

1. Serving registers a handler on an RPC surface, so that a call addressed to that tool name reaches your function.
2. Announcing puts the tool's descriptor into your capability set, so that peers folding your announcement learn the tool exists.

Do the first without the second and you have a working tool nobody can find: discover returns nothing, invoke fails to route, and neither error mentions announcing. In Rust the two are fused — registering a tool inserts it into the node's tool registry and the next announce carries it. In TypeScript, Python and Go they are not, and each fragment below shows the explicit merge step its binding needs.

The RPC handle#

The tool API does not hang off the node. It hangs off a typed RPC surface constructed over the node — serve, call, list and watch are all operations on that surface.

Rust is the exception, and it is the reason this is worth spelling out: in Rust the mesh node is that surface, so the tool methods are node methods. Documentation written from Rust first tends to project that shape onto the other three, where it is wrong. Take the constructor from your own fragment.

Announcement mechanics#

Announcements expire. The default TTL is five minutes. Re-announce before it elapses or peers garbage-collect your entry and you quietly stop being discoverable.

Re-announcing is cheap. The mesh diffs against your last announced set, so a steady-state re-announce costs tens of bytes rather than a full rebroadcast. There is no reason to hand-roll change detection.

Announcements travel multi-hop, bounded by a hop count, so a peer several hops away can fold your capability without ever having connected to you directly.

Announcing to nobody succeeds. If the node has no connected, started peers, the announce call returns cleanly and reaches no one. If discovery remains empty, confirm the node has joined a peer before changing the capability filter. See the handshake.

Discovery and invocation have separate authority#

Announcing does not make a capability visible to every participant or open to invocation.

Visibility and invocability are separate decisions. Organization-scoped discovery can hide or encrypt a descriptor for callers outside its audience. The provider then makes the final admission decision when a caller invokes it. See Invoke and Errors.

The full tag and axis model — hardware, software, model, tool, resource-limit projections — is in Capabilities and Capability Schema.

Announce it — Python#

Capabilities are on the wrapper; tools are one layer down#

net_sdk.MeshNode now carries the capability lifecycle directly — announce_capabilities, find_nodes / find_nodes_scoped, and find_best_node / find_best_node_scoped:

from net_sdk import MeshNode
 
node = MeshNode(bind_addr="127.0.0.1:9001", psk="42" * 32)
node.announce_capabilities({"tags": ["gpu"], "hardware": {"memory_gb": 64}})

The tool surface still lives on the native handle, and so does nRPC:

from net.mesh_rpc import TypedMeshRpc
 
native = node._native                       # tools/nRPC only
rpc = TypedMeshRpc.from_mesh(native)

Reaching a private attribute is not a recommendation, it is the current state of the binding for those surfaces. It is called out here rather than hidden because the alternative is a reader concluding Python cannot serve tools — it can, one layer down.

Serve a tool#

from net_sdk import serve_tool, descriptor_for, add_tool_capabilities_to_announce
 
def web_search(req):
    return {"results": [f"first hit for '{req['query']}'"]}
 
handle = serve_tool(
    rpc,
    {"name": "web_search", "description": "Search the web.", "tags": ["web", "research"]},
    web_search,
)

serve_tool(rpc, options_or_descriptor, handler) — the first argument is the TypedMeshRpc. The options argument accepts a ToolDescriptor, a dict of descriptor_for keyword arguments (must include name), or a bare name string with the rest passed as keywords.

serve_tool_async is the asyncio variant; serve_tool_streaming serves a tool that emits multiple chunks.

Announce the tool — the step serve_tool does not do#

caps = add_tool_capabilities_to_announce(
    {"tags": []},
    [descriptor_for("web_search", description="Search the web.",
                    tags=["web", "research"])],
)
native.announce_capabilities(caps)

add_tool_capabilities_to_announce adds an ai-tool:<tool_id> tag and a tools[] entry to a capability-set dict, and returns the same dict for chaining. Without it the handler is served and invisible. The binding's own docstring calls this a v1 convenience that becomes optional once pyo3 exposes tool_registry() — until then it is required, not optional.

Tags without a tool#

native.announce_capabilities({"tags": ["gpu", "inference", "region:eu-west"]})

The capability set is a plain dict in Python — no builder, no typed class.

Verify it worked#

From a peer that folded the announcement:

import time
from net_sdk import list_tools
 
agent_native = agent._native
 
deadline = time.monotonic() + 3.0
while time.monotonic() < deadline and not list_tools(agent_native):
    time.sleep(0.02)
 
assert list_tools(agent_native), "the announcement did not fold"

list_tools also takes the native handle. Passing the MeshNode raises AttributeError: 'MeshNode' object has no attribute 'list_tools' — which reads like a missing feature and is a wrong argument.

Next: Discover a capability.