Skip to main content

​
Overview

The AgentsClient defines methods to call agents, list available toolkits, and invoke specific tools. It uses an underlying RoomClient to send requests.
  • AgentsClient: The main client class for interacting with agents and tools. It handles:
    • Calling agents
    • Listing available toolkits
    • Invoking specific tools
  • ToolDescription: Describes an individual tool, including metadata and input schemas.
  • ToolkitDescription: Groups multiple tools under one toolkit name, allowing retrieval of individual tools by name.
  • ToolkitConfiguration: Describes which tools in a toolkit you want to enable or use.

​
API Methods

​
Call

  • Description:
    Send a request to an agent to perform an action. (Python uses make_call; other SDKs use call.)
  • Parameters:
    • name: The agent name.
    • url: The route on the agent to call.
    • arguments: Payload to send.
  • Returns: None (request is fire-and-forget; handle results in your agent).
await room.agents.make_call(
  name="example-agent",
  url="some-endpoint",
  arguments={ "foo": "bar" }
)

​
List toolkits

  • Description: Get all available toolkits and their tools.
  • Parameters:
    • participant_id (optional, Python): Filter toolkits for a given participant.
  • Returns: Array of ToolkitDescription.
all_toolkits = await room.agents.list_toolkits()

for toolkit in all_toolkits:
  print(f"Toolkit: {toolkit.name}, Tools: {[tool.name for tool in toolkit.tools]}")

​
Invoke tool

  • Description:
    Invoke a specific tool inside a toolkit directly (without going through an agent). TaskRunners are exposed as toolkits, so invoke their run_<agent_name>_task tool to run them.
  • Parameters:
    • toolkit: Toolkit name.
    • tool: Tool name.
    • arguments: Payload for the tool.
    • participant_id / on_behalf_of_id (optional, Python): Act as another participant.
    • caller_context (optional, Python): Additional context metadata for the call.
  • Returns: Response (JsonResponse in most SDKs) with tool output.
response = await room.agents.invoke_tool(
  toolkit="example-toolkit",
  tool="toolA",
  arguments={"param1": "value1"}
)
# 'response' may contain JSON data or a message detailing the tool's output.

​
Invoke tool (with request body)

  • Description:
    Send a Request object (with optional binary payload) directly to a tool.
  • Availability: Python SDK (invoke_request_tool); other SDKs can send raw arguments via invokeTool.
  • Parameters:
    • toolkit: Toolkit name.
    • tool: Tool name.
    • request: A Request object carrying headers/args and optional bytes via get_data().
    • participant_id / on_behalf_of_id (optional, Python): Act as another participant.
    • caller_context (optional, Python): Extra context metadata.
  • Returns: Response (JsonResponse or stream) from the tool.
from meshagent.api.messaging import Request

req = Request(arguments={"param1": "value1"}, data=b"raw-bytes-if-needed")
response = await room.agents.invoke_request_tool(
    toolkit="example-toolkit",
    tool="toolA",
    request=req,
)

​
Typical Workflow

  1. Instantiate RoomClient
    NodeJs
    const room = new RoomClient({protocol});
  2. List Available Toolkits
    NodeJs
    const toolkits = await room.agents.listToolkits();
  3. Invoke a TaskRunner Tool
    NodeJs
    const result = await room.agents.invokeTool({
  toolkit: "mytaskrunner",
  tool: "run_mytaskrunner_task",
  arguments: { prompt: "Explain the concept of entanglement." }
});
console.log("Tool Result:", result);
  4. Call an Agent Directly (If the agent supports such calls)
    NodeJs
    await room.agents.call({
  name: "myAgent",
  url: "run-something",
  arguments: { data: "payload" }
});

​
ToolDescription

Represents metadata and input requirements for an individual tool. Tools can exist independently or be grouped in a ToolkitDescription.
  • name The tool’s name.
  • title: The tool’s title.
  • description: The tool’s description.
  • input_schema: JSON Schema describing the payload expected when invoking the tool.
  • thumbnail_url (optional): URL for an icon or thumbnail.
  • defs (optional): Additional JSON Schema definitions referenced by inputSchema.
  • pricing (optional): Pricing metadata, if the tool carries usage costs.
  • supports_context (optional; defaults to False): Indicates whether the tool can consume conversational context automatically.

​
ToolkitDescription

Groups multiple tools under a single toolkit. Allows easy retrieval of tools by name and provides a common structure for describing a set of tools.
  • name: The toolkit’s name.
  • title: Display title for the toolkit.
  • description: The toolkit’s description.
  • tools: A list of ToolDescription.
  • thumbnail_url (optional): Thumbnail image URL when provided.

​
ToolkitConfiguration

Specifies how a particular toolkit should be used. It can indicate whether to use all tools or only specific ones within the toolkit.

​
Conclusion

The AgentsClient module provides a flexible, high-level API for managing and interacting with agents and toolkits in a distributed or plugin-based environment. Use AgentsClient for routine operations—listing toolkits, invoking tools, or calling agents—and rely on the description classes (ToolDescription and ToolkitDescription) to manage the metadata and validation for those resources. For more details on the underlying request/response flow, refer to your implementation of RoomClient, Response, and JsonResponse.