Skip to main content

​
Overview

The AgentsClient defines methods to call agents, ask questions, list available toolkits, list available agents, and invoke specific tools. It uses an underlying RoomClient to send requests.
  • AgentsClient: The main client class for interacting with agents. It handles:
    • Calling agents
    • Asking questions to agents
    • Listing available toolkits
    • Listing available agents
    • Invoking specific tools
  • AgentDescription: Describes an agent, its input/output schemas, requirements, labels, etc.
  • 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" }
)

​
Ask

  • Description:
    Send a prompt to an agent and get a JSON answer. Optionally allow specific toolkits for the request.
  • Parameters:
    • agent: Agent name.
    • arguments: Payload for the agent.
    • requires (optional): List of allowed toolkits/tools.
    • on_behalf_of / onBehalfOf (optional): Act as another participant.
  • Returns: JsonResponse with an answer object.
answer = await room.agents.ask(
  agent="example-agent",
  requires=[RequiredToolkit(name="example-toolkit", tools=["toolA", "toolB"])],
  arguments={
    "prompt": "Explain quantum computing in simple terms."
  }
)
print(answer)  # logs the JSON structure from the agent

​
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]}")

​
List agents

  • Description: List agents available in the room.
  • Parameters: None.
  • Returns: Array of AgentDescription.
agents = await room.agents.list_agents()
for agent in agents:
  print(f"Agent: {agent.name}, Title: {agent.title}")

​
Invoke tool

  • Description:
    Invoke a specific tool inside a toolkit directly (without going through an agent).
  • 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 Agents and Toolkits
    NodeJs
    const agents = await room.agents.listAgents();
const toolkits = await room.agents.listToolkits();
  3. Ask a Question to an Agent
    NodeJs
    const toolkit = new RequiredToolkit({ name: "quantum-toolkit", tools: ["add"] });
const result = await room.agents.ask({
  agent: "my-agent",
  requires: [toolkit],
  arguments: { prompt: "Explain the concept of entanglement." }
});
console.log("Agent Answer:", result);
  4. Invoke a Specific Tool (If needed)
    NodeJs
    const toolResponse = await room.agents.invokeTool({
  toolkit: "example-toolkit",
  tool: "toolA",
  arguments: { foo: "bar" }
});
console.log("Tool Response:", toolResponse);
  5. Call an Agent Directly (If the agent supports such calls)
    NodeJs
    await room.agents.call({
  name: "myAgent",
  url: "run-something",
  arguments: { data: "payload" }
});

​
AgentDescription

Represents an agent’s descriptive information, including schemas for input/output data and any special requirements the agent may have (for instance, a required toolkit or schema).
  • name: The agent name
  • title: The agent title.
  • description: Detailed description of the agent’s behavior or purpose.
  • input_schema: JSON schema describing the input format the agent expects.
  • output_schema (optional): JSON schema describing the agent’s output format.
  • requires (optional): A list of Requirement objects (e.g., RequiredToolkit, RequiredSchema).
  • supports_tools Indicates whether the agent can use external tools.
  • labels (optional): Tags associated with the agent.

​
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 agents and toolkits, invoking tools, or asking questions—and rely on the description classes (AgentDescription, 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.