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

# Agents

## 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 bash theme={null}
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`](../agents/process/overview) and the broader [Agents overview](../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](../rest_api/api_scopes) and [Service YAML](../services/deployment/deploy_services).

## 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.
  * `api` *(optional, Python)*: Room API scope to include with the call.
* **Returns**: `None`.

<CodeGroup>
  ```python Python theme={null}
  await room.agents.make_call(
    name="example-agent",
    url="some-endpoint",
    arguments={"foo": "bar"},
  )

  ```

  ```javascript NodeJs theme={null}
  await room.agents.call({
    name: "example-agent",
    url: "some-endpoint",
    arguments: { foo: "bar" },
  });

  ```

  ```typescript TypeScript theme={null}
  await room.agents.call({
    name: "example-agent",
    url: "some-endpoint",
    arguments: { foo: "bar" },
  });

  ```

  ```dart Dart theme={null}
  await room.agents.call(
    name: "example-agent",
    url: "some-endpoint",
    arguments: {"foo": "bar"},
  );

  ```

  ```dotnet C# theme={null}
  await room.Agents.MakeCall(
    "example-agent",
    "some-endpoint",
    new Dictionary<string, object?>
    {
      ["foo"] = "bar"
    }
  );

  ```
</CodeGroup>

### `list_toolkits()`

* **Description**: Get the toolkits currently available in the room.
* **Parameters**:
  * `participant_id` *(optional, Python)*: Filter toolkits for a given participant.
  * `participant_name` *(optional, Python)*: Filter toolkits for a participant by name.
  * `timeout` *(optional, Python)*: Discovery timeout in seconds.
* **Returns**: `ToolkitDescription[]`, where each toolkit includes its metadata and a `tools` list.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room agents list-toolkits \
    --room myroom

  ```

  ```python Python theme={null}
  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]}")

  ```

  ```javascript NodeJs theme={null}
  const allToolkits = await room.agents.listToolkits();

  allToolkits.forEach((toolkit) => {
    console.log(`Toolkit: ${toolkit.name}, Tools: ${toolkit.tools.map((t) => t.name)}`);
  });

  ```

  ```typescript TypeScript theme={null}
  const allToolkits = await room.agents.listToolkits();

  allToolkits.forEach((toolkit) => {
    console.log(`Toolkit: ${toolkit.name}, Tools: ${toolkit.tools.map((t) => t.name)}`);
  });

  ```

  ```dart Dart theme={null}
  final allToolkits = await room.agents.listToolkits();

  for (final toolkit in allToolkits) {
    print('Toolkit: ${toolkit.name}, Tools: ${toolkit.tools.map((t) => t.name).join(", ")}');
  }

  ```

  ```dotnet C# theme={null}
  var toolkits = await room.Agents.ListToolkits();

  foreach (var toolkit in toolkits)
  {
    Console.WriteLine($"{toolkit.Name}: {toolkit.Title}");
    foreach (var tool in toolkit.Tools)
    {
      Console.WriteLine($"  {tool.Name}: {tool.Title}");
    }
  }

  ```
</CodeGroup>

### `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` *(optional, Python)*: Target a specific participant-hosted toolkit.
  * `on_behalf_of_id` *(optional, Python)*: Invoke on behalf of another participant when the token allows it.
* **Returns**: Tool output (`Content` / `JsonChunk`, depending on the SDK).

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room agents invoke-tool \
    --room myroom \
    --toolkit example-toolkit \
    --tool toolA \
    --arguments '{"param1":"value1"}'

  ```

  ```python Python theme={null}
  response = await room.agents.invoke_tool(
    toolkit="example-toolkit",
    tool="toolA",
    input={"param1": "value1"},
  )

  ```

  ```javascript NodeJs theme={null}
  const response = await room.agents.invokeTool({
    toolkit: "example-toolkit",
    tool: "toolA",
    arguments: { param1: "value1" },
  });

  ```

  ```typescript TypeScript theme={null}
  const response = await room.agents.invokeTool({
    toolkit: "example-toolkit",
    tool: "toolA",
    arguments: { param1: "value1" },
  });

  ```

  ```dart Dart theme={null}
  final response = await room.agents.invokeTool(
    toolkit: "example-toolkit",
    tool: "toolA",
    input: ToolContentInput(
      JsonContent(json: {"param1": "value1"}),
    ),
  );

  ```

  ```dotnet C# theme={null}
  var toolArgs = new Dictionary<string, object?>
  {
    ["param1"] = "value1"
  };
  var toolResult = await room.Agents.InvokeTool("example-toolkit", "toolA", toolArgs);

  ```
</CodeGroup>

## Related guides

* [Room API Overview](./overview)
* [Service YAML](../services/deployment/deploy_services)
* [Agents Overview](../agents/overview)