Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt

Use this file to discover all available pages before exploring further.

Custom tools let you add capabilities beyond the built-in MeshAgent toolkits. A Toolkit groups related Tools together so they can be registered in a room and used by people or agents. In this guide you’ll:
  • Write custom tools
  • Create a toolkit to group your related tools
  • Register a toolkit in a room
  • Invoke tools using the MeshAgent Studio UI, MeshAgent CLI, and code
  • Discover available tools in a Room

​
Creating a custom toolkit

​
Step 1: Writing custom tools

Let’s create a simple toolkit with two tools, one that can add two numbers, and one that can subtract two numbers. First write the logic for the add and subtract tools. Then bundle them into a Toolkit that the ServiceHost can register for room calls. Save this example as tools-adder.py: 
import asyncio
from meshagent.api.services import ServiceHost
from meshagent.tools import FunctionTool, ToolContext, Toolkit
from meshagent.otel import otel_config

otel_config(service_name="math_tools")
service = ServiceHost()


class Add(FunctionTool):
    def __init__(self):
        super().__init__(
            name="add",
            title="adding tool",
            description="a tool that adds two numbers",
            input_schema={
                "type": "object",
                "additionalProperties": False,
                "required": ["a", "b"],
                "properties": {
                    "a": {"type": "integer"},
                    "b": {"type": "integer"},
                },
            },
        )

    async def execute(self, context: ToolContext, *, a: int, b: int):
        result = {"result": a + b}
        print(result)
        return result


class Subtract(FunctionTool):
    def __init__(self):
        super().__init__(
            name="subtract",
            title="subtracting tool",
            description="a tool that subtracts two numbers",
            input_schema={
                "type": "object",
                "additionalProperties": False,
                "required": ["a", "b"],
                "properties": {
                    "a": {"type": "integer"},
                    "b": {"type": "integer"},
                },
            },
        )

    async def execute(self, context: ToolContext, *, a: int, b: int):
        result = {"result": a - b}
        print(result)
        return result


@service.path(path="/math", identity="math-toolkit")
class MathToolkit(Toolkit):
    def __init__(self):
        super().__init__(
            name="math-toolkit",
            title="math-toolkit",
            description="a toolkit for adding and subtracting numbers",
            tools=[Add(), Subtract()],
        )


if __name__ == "__main__":
    print(f"running on port {service.port}")
    asyncio.run(service.run())

​
Step 2: Register the toolkit in a room

Create the room and start the toolkit locally: 
meshagent setup # authenticate to MeshAgent
meshagent rooms create --name toolsroom --if-not-exists
meshagent service run tools-adder.py --room toolsroom
This command runs the local Python service and registers the toolkit into toolsroom as a temporary room service. In this example, the toolkit is exposed at the /math path with the name math-toolkit. If you are running several local agents or tools, meshagent service run is the simplest way to test them in a room without packaging and deploying a full service first.

​
Step 3: Invoking a MeshAgent Tool

​
Invoking tools in MeshAgent Studio

  1. Go to studio.meshagent.com and login
  2. From the Sessions tab enter the toolsroom
  3. From the menu in the upper left, click Toolkits
  4. Find the tool you want to run and click Invoke
  5. Enter any required values and click Ok
The tool will execute and display the result in the Studio UI. From the “Developer Console” on the bottom half of the screen you’ll be able to see logs, traces, and metrics from tool calls as they happen in the room. Because this example is running locally through meshagent service run, the toolkit is only available while that terminal session is still running.

​
Invoking tools from the MeshAgent CLI

While the service is running, from a new tab in your terminal invoke the tool. The result will print to the terminal.
bash
meshagent room agents invoke-tool --room=toolsroom --toolkit=math-toolkit --tool=add --arguments='{"a": 5, "b":7}'

​
Invoking tools from code

You can also call the tool directly from code. Run the Python or .NET example through meshagent room connect --room=toolsroom --identity=sample-participant -- <command> so MeshAgent injects the room connection environment automatically. For example: meshagent room connect --room=toolsroom --identity=sample-participant -- python3 tools-calling.py. 
import asyncio
import logging
from meshagent.api import RoomClient
from meshagent.otel import otel_config

otel_config()
log = logging.getLogger(__name__)


async def main():
    # Run with:
    # meshagent room connect --room=toolsroom --identity=sample-participant -- python3 tools-calling.py
    try:
        async with RoomClient() as room:
            log.info("Connected to room: %s", room.room_name)

            add_result = await room.agents.invoke_tool(
                toolkit="math-toolkit", tool="add", input={"a": 1, "b": 2}
            )
            log.info("The result from adding the numbers is: %s", add_result)

            subtract_result = await room.agents.invoke_tool(
                toolkit="math-toolkit", tool="subtract", input={"a": 1, "b": 2}
            )
            log.info("The result from subtracting the numbers is: %s", subtract_result)
    except Exception as e:
        log.error("Error invoking tool: %s", e)
        raise


asyncio.run(main())
Invoking the tools using the RoomClient will give you the following result: 
The result from adding the numbers is: JsonChunk: json={"result": 3} usage=None
The result from subtracting the numbers is: JsonChunk: json={"result": -1} usage=None

​
Discovering tools

At any time, you can use the MeshAgent CLI or connect to the room with a RoomClient to discover what tools are connected to a given room. This can be useful if you want to allow your users to grant additional capabilities to your agents at runtime or verify a tool is present in the room.

​
Discovering tools from the CLI

meshagent room agents list-toolkits --room=toolsroom

​
Discovering tools from code

Running this snippet lists the toolkits that are currently available in the room. Use the same meshagent room connect --room=toolsroom --identity=sample-participant -- <command> pattern when you run it locally. 
import asyncio
import logging
from meshagent.api import RoomClient
from meshagent.otel import otel_config

otel_config()
log = logging.getLogger(__name__)


async def main():
    # Run with:
    # meshagent room connect --room=toolsroom --identity=sample-participant -- python3 tools-discovery.py
    try:
        async with RoomClient() as room:
            toolkits = await room.agents.list_toolkits()

            print("The tools connected to our room are:")
            for toolkit in toolkits:
                print(
                    f"\n Toolkit: {toolkit.name}: {toolkit.title} - {toolkit.description}"
                )
                for tool in toolkit.tools:
                    print(f" Tool: {tool.name}: {tool.title} - {tool.description}")

    except Exception as e:
        log.error("Error listing available toolkits: %s", e)
        raise


asyncio.run(main())
You should see that the math toolkit with both the add and subtract tools are available in the room. 
Toolkit: math-toolkit: math-toolkit - a toolkit for adding and subtracting numbers
 Tool: add: adding tool - a tool that adds two numbers
 Tool: subtract: subtracting tool - a tool that subtracts two numbers

​
Next Steps

If you want the toolkit to stay available after your local terminal session ends, package and deploy it as a MeshAgent service.