Skip to main content
MeshAgent tools are room-connected capabilities that humans and agents can discover, call, and share. Use this page to understand the core model: what a tool is, what a toolkit is, how shared tool registration works, and how MeshAgent handles always-on versus per-turn tool access.

​
Mental model

  • Tool = one discrete action an agent or human participant can take.
  • ToolContext = the execution context available when a tool runs.
  • LocalRoomTool = a mixin for tools that need a bound RoomClient; room-aware tools use self.room.
  • Toolkit = a named bundle of related tools plus optional rules and descriptions.
  • Hosted toolkit = a Toolkit that a service or room participant registers with a room so other participants can discover and call it.

​
Tools

​
Tool

A Tool defines one action that an agent or person can perform. The tool declares what it expects in input_schema and what work to perform in execute(). Constructor parameters Method
Python

​
Tool return types

Tools commonly return subclasses of Content declared in meshagent.api.messaging.

​
ToolContext

ToolContext carries the runtime information a tool needs. If a tool needs room access, use RoomToolContext or a room-bound toolkit. If a tool needs room access, inherit LocalRoomTool and use self.room inside execute(...). Toolkits and hosting helpers bind the active RoomClient before the tool runs.

​
Toolkits

​
Toolkit vs hosted toolkit

A Toolkit is the definition of a group of tools plus the metadata and validation rules that go with them. Use a plain Toolkit when the tools only need to exist inside one process, such as a single agent runtime. Use a hosted toolkit when the tools should be registered in a room so other participants can discover and call them.

​
Toolkit

A Toolkit bundles related tools under a single name so callers can discover, invoke, and permission them together. Constructor parameters Methods
  • get_tool(name): returns the named tool or raises a RoomException if it is not present.
  • execute(context, name, input): validates the input content, invokes the tool, and returns a response.
Toolkits emit OpenTelemetry spans out of the box, so MeshAgent can track who called a tool, how long it took, and what room it ran in.

​
Hosted toolkit lifecycle

Hosted toolkits are plain Toolkit instances across the SDKs.
  • In Python, expose local toolkits from a room-connected SingleRoomAgent by overriding get_exposed_toolkits() and running the agent with SingleRoomAgent.run(). If your application already owns a RoomClient, use MeshAgent’s lower-level room-hosting helpers to register the toolkit and keep it available for room calls.
  • In TypeScript and Dart, startHostedToolkit(...) registers the toolkit and returns a HostedToolkit handle. Higher-level helpers like React’s useClientToolkits(...) and Flutter’s ClientToolkits widget use that same hosting API internally.
Toolkit itself does not expose start() / stop(). Those lifecycle operations live on the room-hosting helper or the returned hosted-toolkit handle. Hosted handle methods
  • stop():
    • stops listening for room tool calls,
    • unregisters the toolkit from the room.

​
Toolkit patterns

MeshAgent supports two complementary ways to make tools available during an agent turn.

​
Static toolkits

Static toolkits stay attached to the agent for its full lifetime.
  • Construct the toolkit up front and pass it in the agent’s toolkits list.
  • The toolkit is instantiated once and participates in every LLM turn.
  • Use this when the agent should always have a capability available.
On the CLI, built-in capabilities now use one canonical flag per capability, such as --web-search, --web-fetch, --storage, --shell, --advanced-shell, --document-authoring, and --discovery. --require-toolkit remains the flag for attaching an external toolkit by name. If you need a capability available for every turn, add the corresponding toolkit directly in code or start the agent with the relevant CLI flag. If the capability should be discoverable by other participants, host the toolkit in a room and let callers invoke it over MeshAgent’s room-tool protocol.

​
Tool access and availability

​
RequiredToolkit

Agents can declare toolkit dependencies explicitly:
Python
When the agent connects, the room server verifies the required toolkit is available. If not, the agent gets an error instead of starting with missing capabilities.

​
Tool access and permissions

Tool access is controlled by the participant token’s ApiScope.agents grant:
  • register_public_toolkit / register_private_toolkit: allow registering public or private toolkits.
  • use_tools: required to list or inspect toolkits.
  • call: required to invoke tools.
Public toolkits are visible to any participant with use_tools. Private toolkits are only listed for the participant that registered them. Use API scope grants to decide which services or users can register, inspect, and call tools.