Universal Tool Calling Protocol (UTCP) Python Client

The UTCP CLI plugin allows you to define a sequence of commands that execute within a single subprocess. This ensures that state, such as directory changes (cd) and environment variables, persists across the entire command chain.

Key features include:

• State Preservation: Changes to the working directory or environment persist between commands in the sequence.
• Argument Substitution: Use the UTCP_ARG_argname_UTCP_END placeholder to inject tool arguments into commands.
• Output Referencing: Access the output of any previous command in the sequence using $CMD_N_OUTPUT (where N is the zero-based index of the command).
• Output Control: Use append_to_final_output: false on specific commands to prevent their output from being included in the final tool result returned to the client.
• Cross-Platform Support: Automatically generates appropriate scripts (PowerShell for Windows, Bash for Unix/Linux/macOS).

from utcp.utcp_client import UtcpClient

# Example of a multi-step tool definition
client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "file_analysis",
        "call_template_type": "cli",
        "commands": [
            {
                "command": "cd UTCP_ARG_target_dir_UTCP_END",
                "append_to_final_output": false
            },
            {
                "command": "find . -type f -name '*.py' | wc -l"
            }
        ]
    }]
})

result = await client.call_tool("file_analysis.count_python_files", {"target_dir": "/project"})

The WebSocket plugin uses a flexible templating system to allow communication with any existing WebSocket endpoint. You can define how arguments are mapped to the outgoing message using UTCP_ARG_arg_name_UTCP_ARG placeholders.

There are three primary modes:

1. No Template (Default): If the message field is omitted, the plugin sends the tool arguments directly as a JSON object. This is ideal for endpoints that already accept standard JSON.
2. Dict Template: Use a dictionary to create structured messages (e.g., JSON-RPC or custom nested JSON). Templates work recursively in dicts and lists.
3. String Template: Use a string for text-based or delimited protocols (e.g., IoT commands or custom text formats).

Example of a Dict Template: If you define a template with "action": "UTCP_ARG_action_UTCP_ARG" and call the tool with {"action": "search"}, the plugin will inject search into the placeholder.

{
    "message": {
        "type": "request",
        "action": "UTCP_ARG_action_UTCP_ARG",
        "params": {
            "user_id": "UTCP_ARG_user_id_UTCP_ARG"
        }
    }
}

UTCP uses the allowed_communication_protocols field to implement fine-grained security control. This prevents a manual from accidentally or maliciously escalating to unauthorized protocols (e.g., an HTTP manual attempting to execute CLI tools).

Default Behavior

If allowed_communication_protocols is not set or is empty, a manual is restricted to tools that use the same protocol type as the manual itself.

Explicitly Allowing Multiple Protocols

To allow a manual to interact with tools from different protocols, you must explicitly list them in the allowed_communication_protocols array.

Security Enforcement

1. Registration Filtering: During register_manual(), tools with unauthorized protocols are filtered out and a WARNING is issued.
2. Call-Time Validation: If an unauthorized tool is called, the client will raise a ValueError.

Configuration Summary

from utcp_http.http_call_template import HttpCallTemplate

# This manual can ONLY register/call HTTP tools (default restriction)
http_manual = HttpCallTemplate(
    name="my_api",
    call_template_type="http",
    url="https://api.example.com/utcp"
    # allowed_communication_protocols not set → defaults to ["http"]
)

# This manual can register/call both HTTP and CLI tools
multi_protocol_manual = HttpCallTemplate(
    name="flexible_manual",
    call_template_type="http",
    url="https://api.example.com/utcp",
    allowed_communication_protocols=["http", "cli"]  # Explicitly allow both
)

To define a CLI tool, add a template to the manual_call_templates list in your UtcpClient configuration.

Set call_template_type to "cli". The template object supports:

• name: The unique identifier for the tool.
• commands: An array of command objects. Each object contains:
  • command: The actual shell command string.
  • append_to_final_output: (Optional) Boolean indicating if this command's output should be part of the final result.
• working_dir: (Optional) The directory where the commands should start.
• env_vars: (Optional) A dictionary of environment variables to pass to the subprocess.

{
  "name": "python_pipeline",
  "call_template_type": "cli",
  "commands": [
    {
      "command": "python setup.py install",
      "append_to_final_output": false
    },
    {
      "command": "python script.py --input UTCP_ARG_input_file_UTCP_END --result \"$CMD_0_OUTPUT\"",
      "append_to_final_output": true
    }
  ],
  "env_vars": {
    "PYTHONPATH": "/custom/path",
    "API_KEY": "${API_KEY}"
  }
}