Fix quickstarts againn (#224)

* feat: wip on orchestrator state fixing + tracing

Signed-off-by: Samantha Coyle <[email protected]>

* fix: separate ex/in-ternal triggers + wip fix orchestrators

Signed-off-by: Samantha Coyle <[email protected]>

* fix: ensure progress on substeps/steps

Signed-off-by: Samantha Coyle <[email protected]>

* fix: give orchestrators ability to pick up where they left off using same session id

Signed-off-by: Samantha Coyle <[email protected]>

* style: make linter happy

Signed-off-by: Samantha Coyle <[email protected]>

* fix: rm extra edge check since captured elsewhere

Signed-off-by: Samantha Coyle <[email protected]>

* feat: add session context for long term context on durable agents

Signed-off-by: Samantha Coyle <[email protected]>

* fix: updates for all quickstarts for release

Signed-off-by: Samantha Coyle <[email protected]>

* docs: update docs to remind users to fill in api key

Signed-off-by: Samantha Coyle <[email protected]>

---------

Signed-off-by: Samantha Coyle <[email protected]>

Author: sicoyle

dapr_agents/llm/dapr/chat.py

@@ -126,11 +126,42 @@ def translate_response(self, response: dict, model: str) -> dict:
         """
         Convert Dapr Alpha2 response into OpenAI-style ChatCompletion dict.
         """
+        if not isinstance(response, dict):
+            logger.error(f"Invalid response type: {type(response)}")
+            raise ValueError(f"Response must be a dictionary, got {type(response)}")
+
         # Flatten all output choices from Alpha2 envelope
         choices: List[Dict[str, Any]] = []
-        for output in response.get("outputs", []) or []:
-            for choice in output.get("choices", []) or []:
+        outputs = response.get("outputs", []) or []
+        if not isinstance(outputs, list):
+            logger.error(f"Invalid outputs type: {type(outputs)}")
+            raise ValueError(f"Outputs must be a list, got {type(outputs)}")
+
+        for output in outputs:
+            if not isinstance(output, dict):
+                logger.error(f"Invalid output type: {type(output)}")
+                continue
+            output_choices = output.get("choices", []) or []
+            if not isinstance(output_choices, list):
+                logger.error(f"Invalid choices type: {type(output_choices)}")
+                continue
+            for choice in output_choices:
+                if not isinstance(choice, dict):
+                    logger.error(f"Invalid choice type: {type(choice)}")
+                    continue
+                # Ensure message is present and has required fields
+                message = choice.get("message", {})
+                if not isinstance(message, dict):
+                    logger.error(f"Invalid message type: {type(message)}")
+                    continue
+                # Add required fields if missing
+                if "content" not in message:
+                    message["content"] = ""
+                if "role" not in message:
+                    message["role"] = "assistant"
+                choice["message"] = message
                 choices.append(choice)
+
         return {
             "choices": choices,
             "created": int(time.time()),
@@ -336,14 +367,28 @@ def generate(
             if not llm_component:
                 llm_component = _get_llm_component(metadata)
 
+            # Extract and serialize response format parameters
+            api_params = {}
+            if "response_format" in params:
+                try:
+                    import json
+
+                    api_params["response_format"] = json.dumps(
+                        params["response_format"]
+                    )
+                except Exception as e:
+                    logger.warning(f"Failed to serialize response_format: {e}")
+            if "structured_mode" in params:
+                api_params["structured_mode"] = str(params["structured_mode"])
+
             raw = self.client.chat_completion_alpha2(
                 llm=llm_component or self._llm_component,
                 inputs=conv_inputs,
                 scrub_pii=scrubPII,
                 temperature=temperature,
                 tools=params.get("tools"),
                 tool_choice=params.get("tool_choice"),
-                parameters=params.get("parameters"),
+                parameters=api_params or None,
             )
             normalized = self.translate_response(
                 raw, llm_component or self._llm_component

dapr_agents/llm/dapr/utils.py

@@ -51,8 +51,17 @@ def process_dapr_chat_response(response: Dict[str, Any]) -> LLMChatResponse:
             None  # there is no openai "function_call" in dapr only tool calls
         )
 
+        content = msg.get("content")
+        if isinstance(content, dict):
+            try:
+                import json
+
+                content = json.dumps(content)
+            except Exception as e:
+                logger.warning(f"Failed to serialize dictionary content: {e}")
+
         assistant_message = AssistantMessage(
-            content=msg.get("content"),
+            content=content,
             tool_calls=tool_calls,
             function_call=function_call,
         )

dapr_agents/llm/utils/request.py

@@ -128,6 +128,18 @@ def process_params(
 
         if response_format:
             logger.info(f"Structured Mode Activated! Mode={structured_mode}.")
+            # Add system message for JSON formatting
+            # This is necessary for the response formatting of the data to work correctly when a user has a function call response format.
+            inputs = params.get("inputs", [])
+            inputs.insert(
+                0,
+                {
+                    "role": "system",
+                    "content": "You must format your response as a valid JSON object matching the provided schema. Do not include any explanatory text or markdown formatting.",
+                },
+            )
+            params["inputs"] = inputs
+
             params = StructureHandler.generate_request(
                 response_format=response_format,
                 llm_provider=llm_provider,

dapr_agents/llm/utils/structure.py

@@ -259,7 +259,17 @@ def extract_structured_response(
                     if not content:
                         raise StructureError("No content found for JSON mode.")
 
-                    logger.debug(f"Extracted JSON content: {content}")
+                    # Try to parse content as JSON first
+                    try:
+                        if isinstance(content, str):
+                            parsed = json.loads(content)
+                            logger.debug(f"Successfully parsed JSON content: {parsed}")
+                            return parsed
+                    except json.JSONDecodeError:
+                        pass
+
+                    # If parsing fails or content is not a string, return as is
+                    logger.debug(f"Returning raw content: {content}")
                     return content
 
                 else:

dapr_agents/observability/instrumentor.py

@@ -471,9 +471,19 @@ def _apply_workflow_wrappers(self) -> None:
                 wrapper=WorkflowMonitorWrapper(self._tracer),
             )
 
-            # Note: WorkflowRunWrapper removed to prevent double wrapping
-            # run_and_monitor_workflow_async internally calls run_workflow
-            # So wrapping both causes duplicate instances
+            # This is necessary to create the parent workflow span for the 09 quickstart...
+            wrap_function_wrapper(
+                module="dapr_agents.workflow.base",
+                name="WorkflowApp.run_workflow",
+                wrapper=WorkflowRunWrapper(self._tracer),
+            )
+
+            # Instrument workflow registration to add AGENT spans for orchestrator workflows
+            wrap_function_wrapper(
+                module="dapr_agents.workflow.base",
+                name="WorkflowApp._register_workflows",
+                wrapper=WorkflowRegistrationWrapper(self._tracer),
+            )
 
             # Instrument workflow registration to add AGENT spans for orchestrator workflows
             wrap_function_wrapper(

dapr_agents/observability/wrappers/workflow.py

@@ -85,11 +85,23 @@ def __call__(self, wrapped: Any, instance: Any, args: Any, kwargs: Any) -> Any:
         workflow = arguments.get("workflow")
 
         # Extract workflow name
-        workflow_name = (
-            workflow
-            if isinstance(workflow, str)
-            else getattr(instance, "_workflow_name", "unknown_workflow")
-        )
+        if isinstance(workflow, str):
+            workflow_name = workflow
+        else:
+            # Try to get the name from the workflow function/class
+            workflow_name = None
+            # First try the workflow decorator name
+            if hasattr(workflow, "_workflow_name"):
+                workflow_name = workflow._workflow_name
+            # Then try __name__ for function workflows
+            if not workflow_name and hasattr(workflow, "__name__"):
+                workflow_name = workflow.__name__
+            # Finally try the name attribute
+            if not workflow_name and hasattr(workflow, "name"):
+                workflow_name = workflow.name
+            # Fallback
+            if not workflow_name:
+                workflow_name = "AgenticWorkflow"
         logger.debug(f"Extracted workflow_name: {workflow_name}")
 
         # Build span attributes
@@ -316,12 +328,24 @@ def _extract_workflow_name(self, args: Any, kwargs: Any) -> str:
         else:
             workflow = kwargs.get("workflow")
 
-        # Extract workflow name
-        workflow_name = (
-            workflow
-            if isinstance(workflow, str)
-            else getattr(workflow, "__name__", "AgenticWorkflow")
-        )
+        # Extract workflow name with better fallback chain
+        if isinstance(workflow, str):
+            workflow_name = workflow
+        else:
+            # Try to get the name from the workflow function/class
+            workflow_name = None
+            # First try the workflow decorator name
+            if hasattr(workflow, "_workflow_name"):
+                workflow_name = workflow._workflow_name
+            # Then try __name__ for function workflows
+            if not workflow_name and hasattr(workflow, "__name__"):
+                workflow_name = workflow.__name__
+            # Finally try the name attribute
+            if not workflow_name and hasattr(workflow, "name"):
+                workflow_name = workflow.name
+            # Fallback
+            if not workflow_name:
+                workflow_name = "AgenticWorkflow"
         return workflow_name
 
     def _build_workflow_attributes(

dapr_agents/observability/wrappers/workflow_task.py

@@ -591,10 +591,16 @@ async def async_wrapper(instance, *wrapper_args, **wrapper_kwargs):
             logger.warning(
                 f"No parent context available for {span_name}, executing without span"
             )
-            bound_method = wrapped.__get__(instance, type(instance))
-            result = await bound_method(*wrapper_args, **wrapper_kwargs)
-
-            return result
+            try:
+                bound_method = wrapped.__get__(instance, type(instance))
+                result = await bound_method(*wrapper_args, **wrapper_kwargs)
+                return result
+            except Exception as e:
+                logger.error(
+                    f"Error in async workflow task execution (no span): {e}",
+                    exc_info=True,
+                )
+                raise
 
         return async_wrapper(instance, *args, **kwargs)
 

dapr_agents/prompt/utils/chat.py

@@ -80,21 +80,41 @@ def validate_and_create_message(
                 elif isinstance(item, BaseMessage):
                     normalized_messages.append(item)
                 elif isinstance(item, dict):
+                    # For tool messages and assistant messages with tool calls,
+                    # preserve all fields by passing the entire dict as message_data
                     role = item.get("role", "user")
                     content = item.get("content", "")
-                    normalized_messages.append(
-                        validate_and_create_message(role, content, item)
-                    )
+                    if role == "tool" or (
+                        role == "assistant" and item.get("tool_calls")
+                    ):
+                        normalized_messages.append(
+                            validate_and_create_message(role, content, item)
+                        )
+                    else:
+                        # For other messages, create a new message with just role and content
+                        normalized_messages.append(
+                            validate_and_create_message(role, content, {})
+                        )
                 else:
                     raise ValueError(
                         f"Unsupported type in list for variable: {type(item)}"
                     )
         elif isinstance(variable_value, dict):
             role = variable_value.get("role", "user")
             content = variable_value.get("content", "")
-            normalized_messages.append(
-                validate_and_create_message(role, content, variable_value)
-            )
+            if role == "tool" or (
+                role == "assistant" and variable_value.get("tool_calls")
+            ):
+                # For tool messages and assistant messages with tool calls,
+                # preserve all fields by passing the entire dict as message_data
+                normalized_messages.append(
+                    validate_and_create_message(role, content, variable_value)
+                )
+            else:
+                # For other messages, create a new message with just role and content
+                normalized_messages.append(
+                    validate_and_create_message(role, content, {})
+                )
         else:
             raise ValueError(f"Unsupported type for variable: {type(variable_value)}")
 

dapr_agents/utils/signal_mixin.py

@@ -99,10 +99,6 @@ def _handle_shutdown_signal(self, sig: int) -> None:
             except Exception as e:
                 logger.debug(f"Error in graceful shutdown: {e}")
 
-        import sys
-
-        sys.exit(0)
-
     async def graceful_shutdown(self) -> None:
         """
         Perform graceful shutdown operations.

quickstarts/01-hello-world-observability/requirements.txt

@@ -2,5 +2,5 @@ dapr-agents[observability]
 opentelemetry-sdk>=1.35.0,<2.0.0
 opentelemetry-exporter-zipkin-json==1.25.0
 # For local development use local changes by commenting out the dapr-agents line above and uncommenting the line below:
-# -e ../../
+# -e ../../[observability]