Skip to main content
Version: Next

cli_communication_protocol

File: plugins/communication_protocols/cli/src/utcp_cli/cli_communication_protocol.py

class CliCommunicationProtocol (CommunicationProtocol)​

Documentation

Communication protocol for interacting with CLI-based tool providers.

This class implements the CommunicationProtocol interface to handle communication with command-line tools. It discovers tools by executing a command specified in a CliCallTemplate and parsing the output for a UTCP manual. It also executes tool calls by running the corresponding command with the provided arguments.

Methods:​

async register_manual(self, caller, manual_call_template: CallTemplate) -> RegisterManualResult

Registers a CLI-based manual and discovers its tools.

This method executes the command specified in the CliCallTemplate's command_name field. It then attempts to parse the command's output (stdout) as a UTCP manual in JSON format.

Args

  • caller: The UTCP client instance that is calling this method.
  • manual_call_template: The CliCallTemplate containing the details for tool discovery, such as the command to run.

Returns

A RegisterManualResult object indicating whether the registration was successful and containing the discovered tools.

Raises

  • ValueError: If the manual_call_template is not an instance of CliCallTemplate or if command_name is not set.
async deregister_manual(self, caller, manual_call_template: CallTemplate) -> None

Deregisters a CLI manual.

For the CLI protocol, this is a no-op as there are no persistent connections to terminate.

Args

  • caller: The UTCP client instance that is calling this method.
  • manual_call_template: The call template of the manual to deregister.
async call_tool(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate) -> Any

Calls a CLI tool by executing its command.

This method constructs and executes the command specified in the CliCallTemplate. It formats the provided tool_args as command-line arguments and runs the command in a subprocess.

Args

  • caller: The UTCP client instance that is calling this method.
  • tool_name: The name of the tool to call.
  • tool_args: A dictionary of arguments for the tool call.
  • tool_call_template: The CliCallTemplate for the tool.

Returns

The result of the command execution. If the command exits with a code of 0, it returns the content of stdout. If the exit code is non-zero, it returns the content of stderr.

Raises

  • ValueError: If tool_call_template is not an instance of CliCallTemplate or if command_name is not set.
async call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate) -> AsyncGenerator[Any, None]

Execute a tool call through the CLI transport streamingly.

The CLI protocol does not natively support streaming, so the command is executed to completion and the full result is yielded as a single chunk.

Args

  • caller: The UTCP client that is calling this method.
  • tool_name: Name of the tool to call.
  • tool_args: Dictionary of arguments to pass to the tool.
  • tool_call_template: Call template of the tool to call.

Yields

The complete tool result as a single item.