Register remote tools

Use remote tools when execution needs browser or client-owned capabilities. Keep database, secret-bearing API, and backend work in server-side tools.

1. Declare schemas in 10xgraph.json

{
  "agent": "graph.agent:app",
  "remote_tools": [
    {
      "node": "tools",
      "name": "get_location",
      "description": "Read the browser's current location.",
      "parameters": {
        "type": "object",
        "properties": {
          "high_accuracy": {"type": "boolean"}
        },
        "required": []
      }
    }
  ]
}

Restart the API after changing schemas. Startup fails for unknown fields, duplicate names, malformed parameters, or a node that is not a ToolNode. Run 10xgraph audit first to validate the schema format and duplicate names.

2. Register matching handlers

client.registerToolHandler("get_location", async ({ high_accuracy = false }) => {
  const position = await new Promise<GeolocationPosition>((resolve, reject) => {
    navigator.geolocation.getCurrentPosition(resolve, reject, {
      enableHighAccuracy: high_accuracy,
    });
  });

  return {
    latitude: position.coords.latitude,
    longitude: position.coords.longitude,
  };
});

3. Invoke normally

const result = await client.invoke([
  Message.text_message("Where am I?", "user"),
]);

The SDK detects remote calls, runs handlers, returns tool results, and continues the graph automatically. There is no setup() method or dynamic setup endpoint.

registerToolHandler(name, handler)

Register handlers before invoke(), stream(), or wsStream(). Schemas are trusted server configuration: the client stores and executes only handlers and cannot add or replace schemas.

registerTool({ name, handler, ...metadata }) remains available for existing clients. Schema metadata supplied there stays local and is not sent to the server. New code should use registerToolHandler().

Execution behavior

When a response contains a RemoteToolCallBlock, the SDK:

1. Finds the handler by tool name.
2. Calls it with the model-generated arguments.
3. Wraps the result in a ToolResultBlock.
4. Continues execution until no remote calls remain or the recursion limit (recursion_limit, default 25) is reached.

Missing handlers and thrown errors become failed tool results rather than transport failures.

Troubleshooting