fix(llm-agent): surface React provider errors

Author: milliondreams

llm-agent/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "rusticai-llm-agent"
-version = "1.4.0"
+version = "1.4.1"
 description = "A complete set of LLM agents"
 authors = [{name = "Dragonscale Industries Inc.", email = "dev@dragonscale.ai"}]
 license = "Apache-2.0"

llm-agent/src/rustic_ai/llm_agent/react/react_agent.py

@@ -5,6 +5,7 @@
 from typing import List, Literal, Optional, Union
 import uuid
 
+import openai
 from pydantic import (
     BaseModel,
     ConfigDict,
@@ -346,6 +347,30 @@ def handle_chat_completion_request(self, ctx: ProcessContext[ChatCompletionReque
             # Send the final ChatCompletionResponse
             ctx.send(result)
 
+        except openai.APIConnectionError as e:
+            logger.error("Provider connection error in ReAct loop: %s", e, exc_info=True)
+            error = ChatCompletionError(
+                status_code=(
+                    ResponseCodes.API_TIMEOUT_ERROR
+                    if isinstance(e, openai.APITimeoutError)
+                    else ResponseCodes.API_CONNECTION_ERROR
+                ),
+                message=str(e),
+                model=str(self.config.model) if self.config.model else self.name,
+                request_messages=list(request.messages),
+            )
+            ctx.send_error(error)
+        except openai.APIStatusError as e:
+            logger.error("Provider error in ReAct loop: %s", e, exc_info=True)
+            error = ChatCompletionError(
+                status_code=ResponseCodes(e.status_code),
+                message=e.message,
+                response=e.response.text if e.response else None,
+                model=str(self.config.model) if self.config.model else self.name,
+                request_messages=list(request.messages),
+                body=e.body if hasattr(e, "body") else None,
+            )
+            ctx.send_error(error)
         except Exception as e:
             logger.error(f"Error in ReAct loop: {e}", exc_info=True)
             ctx.send_error(
@@ -461,8 +486,6 @@ def _run_react_iterations(
             iteration_request = self._build_react_iteration_request(state)
             iteration_request = self._preprocess_iteration_if_needed(ctx, llm, iteration_request, iteration)
             response = self._call_llm_direct(llm, iteration_request)
-            if isinstance(response, str):
-                return response
             if response.usage:
                 state.total_usage = CompletionUsage(
                     prompt_tokens=state.total_usage.prompt_tokens + response.usage.prompt_tokens,
@@ -1163,7 +1186,7 @@ def _call_llm(
         llm: LLM,
         messages: List[DiscriminatedLLMMessage],
         tools: Optional[list] = None,
-    ) -> Union[ChatCompletionResponse, str]:
+    ) -> ChatCompletionResponse:
         """
         Call the LLM with the given messages and tools.
 
@@ -1173,7 +1196,7 @@ def _call_llm(
             tools: Optional tools list (uses toolset if not provided).
 
         Returns:
-            ChatCompletionResponse on success, error string on failure.
+            ChatCompletionResponse on success.
         """
         if tools is None:
             tools = self.config.toolset.chat_tools if self.config.toolset.tool_count > 0 else None
@@ -1191,7 +1214,7 @@ def _call_llm_direct(
         self,
         llm: LLM,
         request: ChatCompletionRequest,
-    ) -> Union[ChatCompletionResponse, str]:
+    ) -> ChatCompletionResponse:
         """
         Call the LLM with a pre-built request.
 
@@ -1200,14 +1223,9 @@ def _call_llm_direct(
             request: The chat completion request.
 
         Returns:
-            ChatCompletionResponse on success, error string on failure.
+            ChatCompletionResponse on success.
         """
-        try:
-            response = llm.completion(request, self.config.model)
-            return response
-        except Exception as e:
-            logger.error(f"LLM call failed: {e}", exc_info=True)
-            return f"LLM call failed: {e}"
+        return llm.completion(request, self.config.model)
 
     @staticmethod
     def _structured_tool_error(code: str, message: str) -> str:

llm-agent/tests/react/test_react_agent.py

@@ -2,19 +2,23 @@
 from typing import Any, ClassVar, List, Optional
 from unittest.mock import patch
 
+import httpx
+import openai
 from pydantic import BaseModel, ConfigDict, ValidationError
 import pytest
 
 from rustic_ai.core.guild.agent_ext.depends.dependency_resolver import DependencySpec
 from rustic_ai.core.guild.agent_ext.depends.llm.models import (
     AssistantMessage,
+    ChatCompletionError,
     ChatCompletionMessageToolCall,
     ChatCompletionRequest,
     ChatCompletionResponse,
     Choice,
     CompletionUsage,
     FinishReason,
     FunctionCall,
+    ResponseCodes,
     SystemMessage,
     ToolType,
     UserMessage,
@@ -570,6 +574,154 @@ def test_agent_simple_response(self, generator, build_message_from_payload):
         assert "react_trace" in provider_fields
         assert len(provider_fields["react_trace"]) == 0  # No tool calls
 
+    def test_provider_error_is_emitted_as_typed_error(self, generator, build_message_from_payload):
+        agent_spec: AgentSpec = (
+            AgentBuilder(ReActAgent)
+            .set_id("react_agent")
+            .set_name("ReAct Agent")
+            .set_description("A ReAct agent for testing")
+            .set_properties(
+                ReActAgentConfig(
+                    model="test-model",
+                    toolset=CalculatorToolset(),
+                )
+            )
+            .build_spec()
+        )
+        agent, results = wrap_agent_for_testing(
+            agent_spec,
+            dependency_map={
+                "llm": DependencySpec(
+                    class_name="rustic_ai.litellm.agent_ext.llm.LiteLLMResolver",
+                    properties={"model": "test-model"},
+                )
+            },
+        )
+        provider_error = openai.RateLimitError(
+            "You have no credits remaining. PRIVATE_PROVIDER_DETAIL",
+            response=httpx.Response(
+                429,
+                request=httpx.Request("POST", "https://provider.invalid/chat"),
+                json={"error": {"code": "insufficient_quota"}},
+            ),
+            body={"error": {"code": "insufficient_quota"}},
+        )
+
+        with patch.object(agent, "_call_llm_direct", side_effect=provider_error):
+            agent._on_message(
+                build_message_from_payload(
+                    generator,
+                    ChatCompletionRequest(messages=[UserMessage(content="PRIVATE_USER_PROMPT")]),
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].format.endswith(".ChatCompletionError")
+        error = ChatCompletionError.model_validate(results[0].payload)
+        assert error.status_code == ResponseCodes.RATE_LIMIT_ERROR
+        assert error.body == {"error": {"code": "insufficient_quota"}}
+        assert error.request_messages[0].content == "PRIVATE_USER_PROMPT"
+
+    @pytest.mark.parametrize(
+        ("provider_error", "expected_status"),
+        [
+            (
+                openai.APIConnectionError(
+                    message="PRIVATE_CONNECTION_DETAIL",
+                    request=httpx.Request("POST", "https://provider.invalid/chat"),
+                ),
+                ResponseCodes.API_CONNECTION_ERROR,
+            ),
+            (
+                openai.APITimeoutError(
+                    request=httpx.Request("POST", "https://provider.invalid/chat")
+                ),
+                ResponseCodes.API_TIMEOUT_ERROR,
+            ),
+        ],
+    )
+    def test_provider_transport_error_is_emitted_as_typed_error(
+        self,
+        generator,
+        build_message_from_payload,
+        provider_error,
+        expected_status,
+    ):
+        agent_spec: AgentSpec = (
+            AgentBuilder(ReActAgent)
+            .set_id("react_agent")
+            .set_name("ReAct Agent")
+            .set_description("A ReAct agent for testing")
+            .set_properties(
+                ReActAgentConfig(
+                    model="test-model",
+                    toolset=CalculatorToolset(),
+                )
+            )
+            .build_spec()
+        )
+        agent, results = wrap_agent_for_testing(
+            agent_spec,
+            dependency_map={
+                "llm": DependencySpec(
+                    class_name="rustic_ai.litellm.agent_ext.llm.LiteLLMResolver",
+                    properties={"model": "test-model"},
+                )
+            },
+        )
+
+        with patch.object(agent, "_call_llm_direct", side_effect=provider_error):
+            agent._on_message(
+                build_message_from_payload(
+                    generator,
+                    ChatCompletionRequest(messages=[UserMessage(content="PRIVATE_USER_PROMPT")]),
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].format.endswith(".ChatCompletionError")
+        error = ChatCompletionError.model_validate(results[0].payload)
+        assert error.status_code == expected_status
+        assert error.request_messages[0].content == "PRIVATE_USER_PROMPT"
+
+    def test_unexpected_error_is_emitted_once_as_internal_error(self, generator, build_message_from_payload):
+        agent_spec: AgentSpec = (
+            AgentBuilder(ReActAgent)
+            .set_id("react_agent")
+            .set_name("ReAct Agent")
+            .set_description("A ReAct agent for testing")
+            .set_properties(
+                ReActAgentConfig(
+                    model="test-model",
+                    toolset=CalculatorToolset(),
+                )
+            )
+            .build_spec()
+        )
+        agent, results = wrap_agent_for_testing(
+            agent_spec,
+            dependency_map={
+                "llm": DependencySpec(
+                    class_name="rustic_ai.litellm.agent_ext.llm.LiteLLMResolver",
+                    properties={"model": "test-model"},
+                )
+            },
+        )
+
+        with patch.object(agent, "_call_llm_direct", side_effect=RuntimeError("PRIVATE_INTERNAL_DETAIL")):
+            agent._on_message(
+                build_message_from_payload(
+                    generator,
+                    ChatCompletionRequest(messages=[UserMessage(content="PRIVATE_USER_PROMPT")]),
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].format.endswith(".ChatCompletionError")
+        error = ChatCompletionError.model_validate(results[0].payload)
+        assert error.status_code == ResponseCodes.INTERNAL_SERVER_ERROR
+        assert error.message == "Error in ReAct loop: PRIVATE_INTERNAL_DETAIL"
+
     def test_agent_with_tool_call(self, generator, build_message_from_payload):
         """Test agent with tool calls."""
         agent_spec: AgentSpec = (