Add new tool calling capability

README.md

@@ -120,6 +120,8 @@ tox -e type
 
 8. Run examples
 
+The tests in examples are using Mechanical Markdown (MM) from https://github.com/dapr/mechanical-markdown.
+
 ```bash
 tox -e examples
 ```

dapr/aio/clients/grpc/client.py

@@ -42,6 +42,7 @@
 
 from dapr.aio.clients.grpc.subscription import Subscription
 from dapr.clients.exceptions import DaprInternalError, DaprGrpcError
+from dapr.clients.grpc._conversation_helpers import _generate_unique_tool_call_id
 from dapr.clients.grpc._crypto import EncryptOptions, DecryptOptions
 from dapr.clients.grpc._state import StateOptions, StateItem
 from dapr.clients.grpc._helpers import getWorkflowRuntimeStatus
@@ -63,6 +64,8 @@
     to_bytes,
     validateNotNone,
     validateNotBlankString,
+    convert_dict_to_grpc_dict_of_any,
+    convert_value_to_struct,
 )
 from dapr.aio.clients.grpc._request import (
     EncryptRequestIterator,
@@ -76,13 +79,18 @@
     InvokeMethodRequest,
     BindingRequest,
     TransactionalStateOperation,
-    ConversationInput,
 )
+from dapr.clients.grpc import conversation
+
 from dapr.clients.grpc._jobs import Job
 from dapr.clients.grpc._response import (
     BindingResponse,
     ConversationResponse,
     ConversationResult,
+    ConversationResponseAlpha2,
+    ConversationResultAlpha2,
+    ConversationResultAlpha2Choices,
+    ConversationResultAlpha2Message,
     DaprResponse,
     GetSecretResponse,
     GetBulkSecretResponse,
@@ -1722,7 +1730,7 @@ async def purge_workflow(self, instance_id: str, workflow_component: str) -> Dap
     async def converse_alpha1(
         self,
         name: str,
-        inputs: List[ConversationInput],
+        inputs: List[conversation.ConversationInput],
         *,
         context_id: Optional[str] = None,
         parameters: Optional[Dict[str, GrpcAny]] = None,
@@ -1736,7 +1744,7 @@ async def converse_alpha1(
             name: Name of the LLM component to invoke
             inputs: List of conversation inputs
             context_id: Optional ID for continuing an existing chat
-            parameters: Optional custom parameters for the request
+            parameters: Optional custom parameters for the request (raw Python values or GrpcAny objects)
             metadata: Optional metadata for the component
             scrub_pii: Optional flag to scrub PII from inputs and outputs
             temperature: Optional temperature setting for the LLM to optimize for creativity or predictability
@@ -1752,11 +1760,14 @@ async def converse_alpha1(
             for inp in inputs
         ]
 
+        # Convert raw Python parameters to GrpcAny objects
+        converted_parameters = convert_dict_to_grpc_dict_of_any(parameters)
+
         request = api_v1.ConversationRequest(
             name=name,
             inputs=inputs_pb,
             contextID=context_id,
-            parameters=parameters or {},
+            parameters=converted_parameters,
             metadata=metadata or {},
             scrubPII=scrub_pii,
             temperature=temperature,
@@ -1775,6 +1786,114 @@ async def converse_alpha1(
         except grpc.aio.AioRpcError as err:
             raise DaprGrpcError(err) from err
 
+    async def converse_alpha2(
+        self,
+        name: str,
+        inputs: List[conversation.ConversationInputAlpha2],
+        *,
+        context_id: Optional[str] = None,
+        parameters: Optional[Dict[str, GrpcAny]] = None,
+        metadata: Optional[Dict[str, str]] = None,
+        scrub_pii: Optional[bool] = None,
+        temperature: Optional[float] = None,
+        tools: Optional[List[conversation.ConversationTools]] = None,
+        tool_choice: Optional[str] = None,
+    ) -> ConversationResponseAlpha2:
+        """Invoke an LLM using the conversation API (Alpha2) with tool calling support.
+
+        Args:
+            name: Name of the LLM component to invoke
+            inputs: List of Alpha2 conversation inputs with sophisticated message types
+            context_id: Optional ID for continuing an existing chat
+            parameters: Optional custom parameters for the request (raw Python values or GrpcAny objects)
+            metadata: Optional metadata for the component
+            scrub_pii: Optional flag to scrub PII from inputs and outputs
+            temperature: Optional temperature setting for the LLM to optimize for creativity or predictability
+            tools: Optional list of tools available for the LLM to call
+            tool_choice: Optional control over which tools can be called ('none', 'auto', 'required', or specific tool name)
+
+        Returns:
+            ConversationResponseAlpha2 containing the conversation results with choices and tool calls
+
+        Raises:
+            DaprGrpcError: If the Dapr runtime returns an error
+        """
+
+        # Convert inputs to proto format
+        inputs_pb = []
+        for inp in inputs:
+            proto_input = api_v1.ConversationInputAlpha2()
+            if inp.scrub_pii is not None:
+                proto_input.scrub_pii = inp.scrub_pii
+
+            for message in inp.messages:
+                proto_input.messages.append(message.to_proto())
+
+            inputs_pb.append(proto_input)
+
+        # Convert tools to proto format
+        tools_pb = []
+        if tools:
+            for tool in tools:
+                proto_tool = api_v1.ConversationTools()
+                if tool.function:
+                    proto_tool.function.name = tool.function.name
+                    if tool.function.description:
+                        proto_tool.function.description = tool.function.description
+                    if tool.function.parameters:
+                        proto_tool.function.parameters.CopyFrom(
+                            convert_value_to_struct(tool.function.parameters)
+                        )
+                tools_pb.append(proto_tool)
+
+        # Convert raw Python parameters to GrpcAny objects
+        converted_parameters = convert_dict_to_grpc_dict_of_any(parameters)
+
+        # Build the request
+        request = api_v1.ConversationRequestAlpha2(
+            name=name,
+            inputs=inputs_pb,
+            parameters=converted_parameters,
+            metadata=metadata or {},
+            tools=tools_pb,
+        )
+
+        if context_id is not None:
+            request.context_id = context_id
+        if scrub_pii is not None:
+            request.scrub_pii = scrub_pii
+        if temperature is not None:
+            request.temperature = temperature
+        if tool_choice is not None:
+            request.tool_choice = tool_choice
+
+        try:
+            response = await self._stub.ConverseAlpha2(request)
+
+            outputs = []
+            for output in response.outputs:
+                choices = []
+                for choice in output.choices:
+                    # workaround for some issues with missing tool ID in some providers (ie: Gemini)
+                    for i, tool_call in enumerate(choice.message.tool_calls):
+                        if not tool_call.id:
+                            choice.message.tool_calls[i].id = _generate_unique_tool_call_id()
+                    choices.append(
+                        ConversationResultAlpha2Choices(
+                            finish_reason=choice.finish_reason,
+                            index=choice.index,
+                            message=ConversationResultAlpha2Message(
+                                content=choice.message.content, tool_calls=choice.message.tool_calls
+                            ),
+                        )
+                    )
+                outputs.append(ConversationResultAlpha2(choices=choices))
+
+            return ConversationResponseAlpha2(context_id=response.context_id, outputs=outputs)
+
+        except grpc.aio.AioRpcError as err:
+            raise DaprGrpcError(err) from err
+
     async def wait(self, timeout_s: float):
         """Waits for sidecar to be available within the timeout.
 

dapr/clients/_constants.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+
+"""
+Copyright 2025 The Dapr Authors
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+"""
+Internal constants for the Dapr clients package.
+
+This module contains shared constants that can be imported by various
+client modules without creating circular dependencies.
+"""
+
+# Encoding and content type constants
+DEFAULT_ENCODING = 'utf-8'
+DEFAULT_JSON_CONTENT_TYPE = f'application/json; charset={DEFAULT_ENCODING}'

dapr/clients/base.py

@@ -17,10 +17,6 @@
 from typing import Optional
 
 
-DEFAULT_ENCODING = 'utf-8'
-DEFAULT_JSON_CONTENT_TYPE = f'application/json; charset={DEFAULT_ENCODING}'
-
-
 class DaprActorClientBase(ABC):
     """A base class that represents Dapr Actor Client."""