add more information on execute registered tools, also added more tests for them to validate

Signed-off-by: Filinto Duran <[email protected]>

Author: filintod

README.md

@@ -126,11 +126,10 @@ tox -e examples
 
 [Dapr Mechanical Markdown](https://github.com/dapr/mechanical-markdown) is used to test the examples.
 
-If you need to run the examples against a development version of the runtime, you can use the following command:
+If you need to run the examples against a pre-released version of the runtime, you can use the following command:
 - Get your daprd runtime binary from [here](https://github.com/dapr/dapr/releases) for your platform.
-- Copy the binary to a folder, for example `examples/.dapr/bin/` directory.
-- In your example README, change the `dapr run` command and add a line `--runtime-path ./examples \`.
-- Copy a dapr config file `config.yaml` file to the `examples/.dapr` directory.  This file is usually in your $(HOME)/.dapr directory if you had installed dapr cli before.
+- Copy the binary to your dapr home folder at $HOME/.dapr/bin/daprd.
+Or using dapr cli directly: `dapr init --runtime-version <release version>`
 - Now you can run the example with `tox -e examples`.
 
 

dapr/clients/grpc/_conversation_helpers.py

@@ -859,7 +859,7 @@ def _coerce_and_validate(value: Any, expected_type: Any) -> Any:
     args = get_args(expected_type)
 
     if expected_type is Any:
-        raise TypeError(f'We cannot handle parameters with type Any')
+        raise TypeError('We cannot handle parameters with type Any')
 
     # Optional[T] -> Union[T, None]
     if origin is Union:

dapr/clients/grpc/conversation.py

@@ -452,6 +452,14 @@ def tool(
 ):
     """
     Decorate a callable as a conversation tool.
+
+    Security note:
+    - Register only trusted functions. Tool calls may be triggered from LLM outputs and receive
+      untrusted parameters.
+    - Use precise type annotations and docstrings for your function; we derive a JSON schema used by
+      the binder to coerce types and reject unexpected/invalid arguments.
+    - Add your own guardrails if the tool can perform side effects (filesystem, network, subprocess).
+    - You can set register=False and call register_tool later to control registration explicitly.
     """
 
     def _decorate(f: Callable):
@@ -481,19 +489,35 @@ def _decorate(f: Callable):
 
 @dataclass
 class ConversationTools:
-    """Tools available for conversation."""
+    """Tools available for conversation.
+
+    Notes on safety and validation:
+    - Tools execute arbitrary Python callables. Register only trusted functions and be mindful of
+      side effects (filesystem, network, subprocesses).
+    - Parameters provided by an LLM are untrusted. The invocation path uses bind_params_to_func to
+      coerce types based on your function annotations and to reject unexpected/invalid arguments.
+    - Consider adding your own validation/guardrails in your tool implementation.
+    """
 
     # currently only function is supported
     function: ConversationToolsFunction
     backend: Optional[ToolBackend] = None
 
     def invoke(self, params: Params = None) -> Any:
-        """execute the tool with params"""
+        """Execute the tool with params (synchronous).
+
+        params may be:
+        - Mapping[str, Any]: passed as keyword arguments
+        - Sequence[Any]: passed as positional arguments
+        - None: no arguments
+        Detailed validation and coercion are performed by the backend via bind_params_to_func.
+        """
         if not self.backend:
             raise conv_helpers.ToolExecutionError('Tool backend not set')
         return self.backend.invoke(self.function, params)
 
     async def ainvoke(self, params: Params = None, *, timeout: Union[float, None] = None) -> Any:
+        """Execute the tool asynchronously. See invoke() for parameter shape and safety notes."""
         if not self.backend:
             raise conv_helpers.ToolExecutionError('Tool backend not set')
         return await self.backend.ainvoke(self.function, params, timeout=timeout)
@@ -528,18 +552,43 @@ def _get_tool(name: str) -> ConversationTools:
 
 
 def execute_registered_tool(name: str, params: Union[Params, str] = None) -> Any:
-    """Execute a registered tool."""
+    """Execute a registered tool.
+
+    Security considerations:
+    - A registered tool typically executes user-defined code (or code imported from libraries). Only
+      register and execute tools you trust. Treat model-provided params as untrusted input.
+    - Prefer defining a JSON schema for your tool function parameters (ConversationToolsFunction
+      is created from your function’s signature and annotations). The internal binder performs
+      type coercion and rejects unexpected/invalid arguments.
+    - Add your own guardrails if the tool can perform side effects (filesystem, network, subprocess, etc.).
+    """
     if isinstance(params, str):
         params = json.loads(params)
+    # Minimal upfront shape check; detailed validation happens in bind_params_to_func
+    if params is not None and not isinstance(params, (Mapping, Sequence)):
+        raise conv_helpers.ToolArgumentError(
+            'params must be a mapping (kwargs), a sequence (args), or None'
+        )
     return _get_tool(name).invoke(params)
 
 
 async def execute_registered_tool_async(
     name: str, params: Union[Params, str] = None, *, timeout: Union[float, None] = None
 ) -> Any:
-    """Execute a registered tool asynchronously."""
+    """Execute a registered tool asynchronously.
+
+    Security considerations:
+    - Only execute trusted tools; treat model-provided params as untrusted input.
+    - Prefer well-typed function signatures and schemas for parameter validation. The binder will
+      coerce and validate, rejecting unexpected arguments.
+    - For async tools, consider timeouts and guardrails to limit side effects.
+    """
     if isinstance(params, str):
         params = json.loads(params)
+    if params is not None and not isinstance(params, (Mapping, Sequence)):
+        raise conv_helpers.ToolArgumentError(
+            'params must be a mapping (kwargs), a sequence (args), or None'
+        )
     return await _get_tool(name).ainvoke(params, timeout=timeout)
 
 

tests/clients/test_conversation.py

@@ -15,6 +15,7 @@
 
 
 import asyncio
+import json
 import unittest
 import uuid
 
@@ -27,6 +28,7 @@
 from dapr.clients.grpc._conversation_helpers import (
     ToolArgumentError,
     ToolExecutionError,
+    ToolNotFoundError,
 )
 from dapr.clients.grpc.conversation import (
     ConversationInput,
@@ -50,6 +52,7 @@
     ConversationMessageOfAssistant,
     ConversationToolCalls,
     ConversationToolCallsOfFunction,
+    execute_registered_tool,
 )
 from dapr.clients.grpc.conversation import (
     tool as tool_decorator,
@@ -1105,5 +1108,120 @@ def test_empty_and_none_outputs(self):
         self.assertEqual(response_none.to_assistant_messages(), [])
 
 
+class ExecuteRegisteredToolSyncTests(unittest.TestCase):
+    def tearDown(self):
+        # Cleanup all tools we may have registered by name prefix
+        # (names are randomized per test to avoid collisions)
+        pass  # Names are unique per test; we explicitly unregister in tests
+
+    def test_sync_success_with_kwargs_and_sequence_and_json(self):
+        name = f'test_add_{uuid.uuid4().hex[:8]}'
+
+        @tool_decorator(name=name)
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        try:
+            # kwargs mapping
+            out = execute_registered_tool(name, {'a': 2, 'b': 3})
+            self.assertEqual(out, 5)
+
+            # sequence args
+            out2 = execute_registered_tool(name, [10, 5])
+            self.assertEqual(out2, 15)
+
+            # JSON string params
+            out3 = execute_registered_tool(name, json.dumps({'a': '7', 'b': '8'}))
+            self.assertEqual(out3, 15)
+        finally:
+            unregister_tool(name)
+
+    def test_sync_invalid_params_type_raises(self):
+        name = f'test_echo_{uuid.uuid4().hex[:8]}'
+
+        @tool_decorator(name=name)
+        def echo(x: str) -> str:
+            return x
+
+        try:
+            with self.assertRaises(ToolArgumentError):
+                execute_registered_tool(name, 123)  # not Mapping/Sequence/None
+        finally:
+            unregister_tool(name)
+
+    def test_sync_unregistered_tool_raises(self):
+        name = f'does_not_exist_{uuid.uuid4().hex[:8]}'
+        with self.assertRaises(ToolNotFoundError):
+            execute_registered_tool(name, {'a': 1})
+
+    def test_sync_tool_exception_wrapped(self):
+        name = f'test_fail_{uuid.uuid4().hex[:8]}'
+
+        @tool_decorator(name=name)
+        def fail() -> None:
+            raise ValueError('boom')
+
+        try:
+            with self.assertRaises(ToolExecutionError):
+                execute_registered_tool(name)
+        finally:
+            unregister_tool(name)
+
+
+class ExecuteRegisteredToolAsyncTests(unittest.IsolatedAsyncioTestCase):
+    async def asyncTearDown(self):
+        # Nothing persistent; individual tests unregister.
+        pass
+
+    async def test_async_success_and_json_params(self):
+        name = f'test_async_echo_{uuid.uuid4().hex[:8]}'
+
+        @tool_decorator(name=name)
+        async def echo(value: str) -> str:
+            await asyncio.sleep(0)
+            return value
+
+        try:
+            out = await execute_registered_tool_async(name, {'value': 'hi'})
+            self.assertEqual(out, 'hi')
+
+            out2 = await execute_registered_tool_async(name, json.dumps({'value': 'ok'}))
+            self.assertEqual(out2, 'ok')
+        finally:
+            unregister_tool(name)
+
+    async def test_async_invalid_params_type_raises(self):
+        name = f'test_async_inv_{uuid.uuid4().hex[:8]}'
+
+        @tool_decorator(name=name)
+        async def one(x: int) -> int:
+            return x
+
+        try:
+            with self.assertRaises(ToolArgumentError):
+                await execute_registered_tool_async(name, 3.14)  # invalid type
+        finally:
+            unregister_tool(name)
+
+    async def test_async_unregistered_tool_raises(self):
+        name = f'does_not_exist_{uuid.uuid4().hex[:8]}'
+        with self.assertRaises(ToolNotFoundError):
+            await execute_registered_tool_async(name, None)
+
+    async def test_async_tool_exception_wrapped(self):
+        name = f'test_async_fail_{uuid.uuid4().hex[:8]}'
+
+        @tool_decorator(name=name)
+        async def fail_async() -> None:
+            await asyncio.sleep(0)
+            raise RuntimeError('nope')
+
+        try:
+            with self.assertRaises(ToolExecutionError):
+                await execute_registered_tool_async(name)
+        finally:
+            unregister_tool(name)
+
+
 if __name__ == '__main__':
     unittest.main()