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.

​
Overview

The AgentsClient is the Room API for calling agents and discovering the toolkits available in a room. Use it when you want to send work to a deployed agent, inspect which built-in or service-provided toolkits are available, or call a tool directly.

​
CLI commands

Start with the CLI help, then use a few common commands:
bash
meshagent room agents --help
meshagent room agents list-toolkits --room myroom
meshagent room agents invoke-tool --room myroom --toolkit my-toolkit --tool my_tool

​
Why use the Agents API?

  • Call a named agent endpoint from the CLI or SDK instead of wiring your own service-to-service protocol.
  • Discover the tools available in the current room before handing work to an agent or rendering a tool picker.
  • Invoke a room toolkit directly when you already know which tool you want.

​
How it works

The Agents API exposes three core concepts:
  • Agent: a named endpoint you call with make_call / call.
  • Toolkit: a named collection of tools available in the room.
  • Tool: an individual operation inside a toolkit.
list_toolkits returns toolkit metadata objects, and each toolkit contains a tools list with the corresponding tool metadata. That metadata is useful when you need to inspect available tools or render dynamic tool UIs, but most users only need the three methods below. If you are looking for how to create or deploy agents, start with meshagent process and the broader Agents overview. This page is about interacting with agents and toolkits that are already available in a room.

​
Permissions and grants

The Agents API is controlled by the agents grant on the participant token. In practice:
  • use call, use_agents, and use_tools when a service needs to call agents or invoke tools
  • use register_agent, register_public_toolkit, and register_private_toolkit when a service needs to publish agents or toolkits into the room
See API Scopes and Service YAML.

​
API reference

Use the methods below to call a named agent endpoint, inspect toolkits in the room, or invoke a tool directly.

​
call(...) / make_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.
await room.agents.make_call(
  name="example-agent",
  url="some-endpoint",
  arguments={"foo": "bar"},
)

​
list_toolkits()

  • Description: Get the toolkits currently available in the room.
  • Parameters:
    • participant_id (optional, Python): Filter toolkits for a given participant.
  • Returns: ToolkitDescription[], where each toolkit includes its metadata and a tools list.
meshagent room agents list-toolkits \
  --room myroom

​
invoke_tool(...)

  • Description: Invoke a tool inside a toolkit directly.
  • Parameters:
    • toolkit: Toolkit name.
    • tool: Tool name.
    • input (Python/Dart): Payload for the tool.
    • arguments (JS/TS/.NET): 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: Tool output (Content / JsonChunk, depending on the SDK).
meshagent room agents invoke-tool \
  --room myroom \
  --toolkit example-toolkit \
  --tool toolA \
  --arguments '{"param1":"value1"}'