Skip to main content
MeshAgent tools can be run by both agent and human participants. Tools are centrally managed like agents meaning they can be deployed as a MeshAgent service and used by people or agents that have access to your Room. A Toolkit allows you to group related Tools together so that they can be used seamlessly by any person or agent in the Room. In this quickstart we’ll walk through how to:
  • Write custom tools
  • Create a toolkit to group your related tools
  • Call a toolkit into a MeshAgent 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 we’ll write the logic for the Add and Subtract tools. Next, we’ll bundle them into a RemoteToolkit that the ServiceHost can register for room calls. When we call the tools into the room either with meshagent call tool or meshagent service run, the ser 
import asyncio
from meshagent.api.services import ServiceHost
from meshagent.tools import Tool, ToolContext, RemoteToolkit
from meshagent.otel import otel_config

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


class Add(Tool):
    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(Tool):
    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(RemoteToolkit):
    def __init__(self):
        super().__init__(
            name="math-toolkit",
            title="math-toolkit",
            description="a toolkit for adding and subtracting numbers",
            tools=[Add(), Subtract()],
        )


print(f"running on port {service.port}")
asyncio.run(service.run())

​
Step 2: Calling custom tools into a MeshAgent Room

From the terminal inside our activated virtual environment we’ll use the MeshAgent CLI to call the toolkit into the room. 
meshagent setup # authenticate to MeshAgent
meshagent service run "main.py" --room=toolsroom
This command will start the toolkit on an available port at the path /math. If you are running multiple agents or tools, you can use the same ServiceHost and set different paths for each of the agents and toolkits. The service run command automatically detects the different paths and identities (this is the recommended way to test your agents and tools). As an alternative to the service run command you can also run the service locally by running python main.py in one tab in your terminal, then from another tab you can call individual toolkits into the room using the meshagent call tool command. If you do this, be sure you’ve also stored a MESHAGENT_API_KEY in your environment. You can create and activate a key from the MeshAgent CLI by running mehsagent api-key create <your-key-name> activate then export the result. For example: 
meshagent setup # authenticate to MeshAgent
# meshagent api-key create my-api-key activate # create and activate key if you don't already have one
# export MESHAGENT_API_KEY="xxxxxxx"
meshagent call tool --room=toolsroom --participant-name=math-toolkit --url=http://localhost:8081/math
In either case, the toolkit will be available in the room at the /math path with the name math-toolkit. Once the toolkit joins the room, you can invoke it directly from the MeshAgent Studio UI, the MeshAgent CLI, or through code.

​
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 you can either invoke the tool directly through Toolkits or add it to a TaskRunner through Run Task
    • Using the Toolkit directly: Click Toolkits…, find the tool you want to run then click Invoke. This will collect the parameters needed from you (if any) and display a dialogue for you to enter any required values. Once finished click Ok. The tool will execute and display the result in the Studio UI.
    • Using A TaskRunner: Click Run Task…, then select the Generic Task Runner as the agent, next click the “Add Tools” button. Now you’ll see our math-toolkit with both the “add” and “subtract” tools. On both of the tools you will see an info button, an invoke button, and an add button. The info button will display the JSON schema we created to define the tool, the invoke button will invoke the tool directly, and the add button will add the tool(s) to the TaskRunner. Select either the “Invoke” or “Add Tool” option for either the “add” or “subtract” tool and an agent will collect the required values and execute the tool.
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. Note: Remember if you leave the Room and go back into it later you will need to call the tool back into the Room unless the tool is deployed as a MeshAgent service (meaning you will need to rerun the CLI command to call in the tool to the Room).

​
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 agents invoke-tool --room=toolsroom --tool=add --toolkit=math-toolkit --arguments='{"a": 5, "b":7}'

​
Invoking tools from code

You can also call the tool directly from code. Assuming your service is still running, we can also invoke the tool using the MeshAgent RoomClient. This code will create a ParticipantToken will the required permissions to invoke the tools, connect to the room with the token, then invoke both the add and subtract tools. 
import os
import asyncio
import logging
from meshagent.api import (
    RoomClient,
    WebSocketClientProtocol,
    ParticipantToken,
    ApiScope,
    ParticipantGrant,
)
from meshagent.api.helpers import websocket_room_url
from meshagent.otel import otel_config

otel_config()
log = logging.getLogger(__name__)

api_key = os.getenv("MESHAGENT_API_KEY")
if not api_key:
    raise RuntimeError("Set MESHAGENT_API_KEY before running this script.")


async def main():
    room_name = "toolsroom"

    token = ParticipantToken(
        name="sample-participant",
        grants=[
            ParticipantGrant(name="room", scope=room_name),
            ParticipantGrant(name="role", scope="agent"),
            ParticipantGrant(name="api", scope=ApiScope.agent_default()),
        ],
    ).to_jwt(api_key=api_key)

    protocol = WebSocketClientProtocol(
        url=websocket_room_url(room_name=room_name), token=token
    )
    try:
        async with RoomClient(protocol=protocol) as room:
            log.info(f"Connected to room: {room.room_name}")

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

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


asyncio.run(main())
Invoking the tools using the RoomClient will give you the following result: 
The result from adding the numbers is: JsonResponse: json={"result": 3} usage=None
The result from subtracting the numbers is: JsonResponse: 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 agents list-toolkits --room=toolsroom

​
Discovering tools from code

Running this snippet will show any tool available as a MeshAgent service as well as tools that are currently connected to the Room. Again we construct the ParticipantToken with the appropriate permissions, connect to the room with the RoomClient, then list the available toolkits. 
import os
import asyncio
import logging
from meshagent.api import (
    RoomClient,
    WebSocketClientProtocol,
    ParticipantToken,
    ApiScope,
    ParticipantGrant,
)
from meshagent.api.helpers import websocket_room_url
from meshagent.otel import otel_config

otel_config()
log = logging.getLogger(__name__)

api_key = os.getenv("MESHAGENT_API_KEY")
if not api_key:
    raise RuntimeError("Set MESHAGENT_API_KEY before running this script.")


async def main():
    room_name = "toolsroom"

    token = ParticipantToken(
        name="sample-participant",
        grants=[
            ParticipantGrant(name="room", scope=room_name),
            ParticipantGrant(name="role", scope="agent"),
            ParticipantGrant(name="api", scope=ApiScope.agent_default()),
        ],
    ).to_jwt(api_key=api_key)

    protocol = WebSocketClientProtocol(
        url=websocket_room_url(room_name=room_name), token=token
    )
    try:
        async with RoomClient(protocol=protocol) 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}")

            agents = await room.agents.list_agents()
            print("The agents in the room are:")
            for agent in agents:
                print(f"Agent: {agent.name}")
    except Exception as e:
        log.error(f"Error listing available toolkits:{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 your tools to be available in all the Rooms inside your Project you will need to deploy the tool as a MeshAgent service. You can also define a tool while you define an agent and just deploy your agent as a MeshAgent service. This will make the agent available in all of the MeshAgent Rooms in your Project, but your tool won’t be directly invokable by anyone other than the agent you defined the tool with.