Skip to main content

​
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.

​
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.

​
Permissions and grants

If you want a deployed service to call agents or tools through the Room APIs, its participant token needs the appropriate Room API grants. See API Scopes and Packaging and Deploying Services.

​
CLI and SDK availability

  • CLI: inspect toolkits and invoke tools with meshagent room agent ....
  • Python, JavaScript/TypeScript, Dart, and .NET: helper methods are shown below.

​
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.
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 agent list-toolkits \
  --room myroom

​
Invoke tool

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