Add native responses

examples/26_responses_reasoning.py

@@ -0,0 +1,77 @@
+"""
+Example: Responses API path via LiteLLM in a Real Agent Conversation
+
+- Runs a real Agent/Conversation to verify /responses path works
+- Demonstrates rendering of Responses reasoning within normal conversation events
+"""
+
+from __future__ import annotations
+
+import os
+
+from pydantic import SecretStr
+
+from openhands.sdk import (
+    Conversation,
+    Event,
+    LLMConvertibleEvent,
+    get_logger,
+)
+from openhands.sdk.llm import LLM
+from openhands.tools.preset.default import get_default_agent
+
+
+logger = get_logger(__name__)
+
+
+api_key = os.getenv("LITELLM_API_KEY") or os.getenv("OPENAI_API_KEY")
+assert api_key, "Set LITELLM_API_KEY or OPENAI_API_KEY in your environment."
+
+model = os.getenv("OPENAI_RESPONSES_MODEL", "openai/gpt-5-mini")
+base_url = os.getenv("LITELLM_BASE_URL", "https://llm-proxy.eval.all-hands.dev")
+
+llm = LLM(
+    model=model,
+    api_key=SecretStr(api_key),
+    base_url=base_url,
+    # Responses-path options
+    enable_encrypted_reasoning=True,  # request encrypted reasoning passthrough
+    reasoning_effort="high",
+    # Logging / behavior tweaks
+    log_completions=False,
+    drop_params=True,
+    service_id="agent",
+)
+
+print("\n=== Agent Conversation using /responses path ===")
+agent = get_default_agent(
+    llm=llm,
+    cli_mode=True,  # disable browser tools for env simplicity
+)
+
+llm_messages = []  # collect raw LLM-convertible messages for inspection
+
+
+def conversation_callback(event: Event):
+    if isinstance(event, LLMConvertibleEvent):
+        llm_messages.append(event.to_llm_message())
+
+
+conversation = Conversation(
+    agent=agent,
+    callbacks=[conversation_callback],
+    workspace=os.getcwd(),
+)
+
+# Keep the tasks short for demo purposes
+conversation.send_message("Read the repo and write one fact into FACTS.txt.")
+conversation.run()
+
+conversation.send_message("Now delete FACTS.txt.")
+conversation.run()
+
+print("=" * 100)
+print("Conversation finished. Got the following LLM messages:")
+for i, message in enumerate(llm_messages):
+    ms = str(message)
+    print(f"Message {i}: {ms[:200]}{'...' if len(ms) > 200 else ''}")

openhands/sdk/agent/agent.py

@@ -19,6 +19,7 @@
 from openhands.sdk.llm import (
     Message,
     MessageToolCall,
+    ReasoningItemModel,
     RedactedThinkingBlock,
     TextContent,
     ThinkingBlock,
@@ -169,16 +170,26 @@ def step(
         _messages = LLMConvertibleEvent.events_to_messages(llm_convertible_events)
         logger.debug(
             "Sending messages to LLM: "
-            f"{json.dumps([m.model_dump() for m in _messages], indent=2)}"
+            f"{json.dumps([m.model_dump() for m in _messages[1:]], indent=2)}"
         )
 
         try:
-            llm_response = self.llm.completion(
-                messages=_messages,
-                tools=list(self.tools_map.values()),
-                extra_body={"metadata": self.llm.metadata},
-                add_security_risk_prediction=self._add_security_risk_prediction,
-            )
+            if self.llm.uses_responses_api():
+                llm_response = self.llm.responses(
+                    messages=_messages,
+                    tools=list(self.tools_map.values()),
+                    include=None,
+                    store=False,
+                    add_security_risk_prediction=self._add_security_risk_prediction,
+                    metadata=self.llm.metadata,
+                )
+            else:
+                llm_response = self.llm.completion(
+                    messages=_messages,
+                    tools=list(self.tools_map.values()),
+                    extra_body={"metadata": self.llm.metadata},
+                    add_security_risk_prediction=self._add_security_risk_prediction,
+                )
         except Exception as e:
             # If there is a condenser registered and the exception is a context window
             # exceeded, we can recover by triggering a condensation request.
@@ -223,6 +234,9 @@ def step(
                     reasoning_content=message.reasoning_content if i == 0 else None,
                     # Only first gets thinking blocks
                     thinking_blocks=list(message.thinking_blocks) if i == 0 else [],
+                    responses_reasoning_item=message.responses_reasoning_item
+                    if i == 0
+                    else None,
                 )
                 if action_event is None:
                     continue
@@ -292,6 +306,7 @@ def _get_action_event(
         thought: list[TextContent] = [],
         reasoning_content: str | None = None,
         thinking_blocks: list[ThinkingBlock | RedactedThinkingBlock] = [],
+        responses_reasoning_item: ReasoningItemModel | None = None,
     ) -> ActionEvent | None:
         """Converts a tool call into an ActionEvent, validating arguments.
 
@@ -304,13 +319,13 @@ def _get_action_event(
             available = list(self.tools_map.keys())
             err = f"Tool '{tool_name}' not found. Available: {available}"
             logger.error(err)
-            # Persist assistant function_calls so next turn
-            # has matching call_id for tool output
+            # Persist assistant function_call so next turn has matching call_id
             tc_event = ActionEvent(
                 source="agent",
                 thought=thought,
                 reasoning_content=reasoning_content,
                 thinking_blocks=thinking_blocks,
+                responses_reasoning_item=responses_reasoning_item,
                 tool_call=tool_call,
                 tool_name=tool_call.name,
                 tool_call_id=tool_call.id,
@@ -354,13 +369,13 @@ def _get_action_event(
                 f"Error validating args {tool_call.arguments} for tool "
                 f"'{tool.name}': {e}"
             )
-            # Persist assistant function_calls so next turn
-            # has matching call_id for tool output
+            # Persist assistant function_call so next turn has matching call_id
             tc_event = ActionEvent(
                 source="agent",
                 thought=thought,
                 reasoning_content=reasoning_content,
                 thinking_blocks=thinking_blocks,
+                responses_reasoning_item=responses_reasoning_item,
                 tool_call=tool_call,
                 tool_name=tool_call.name,
                 tool_call_id=tool_call.id,
@@ -381,6 +396,7 @@ def _get_action_event(
             thought=thought,
             reasoning_content=reasoning_content,
             thinking_blocks=thinking_blocks,
+            responses_reasoning_item=responses_reasoning_item,
             tool_name=tool.name,
             tool_call_id=tool_call.id,
             tool_call=tool_call,

openhands/sdk/event/llm_convertible/action.py

@@ -8,6 +8,7 @@
 from openhands.sdk.llm import (
     Message,
     MessageToolCall,
+    ReasoningItemModel,
     RedactedThinkingBlock,
     TextContent,
     ThinkingBlock,
@@ -29,6 +30,9 @@ class ActionEvent(LLMConvertibleEvent):
         default_factory=list,
         description="Anthropic thinking blocks from the LLM response",
     )
+    responses_reasoning_item: ReasoningItemModel | None = Field(
+        default=None, description="OpenAI Responses reasoning item from model output"
+    )
     action: Action | None = Field(
         default=None,
         description="Single tool call returned by LLM (None when non-executable)",
@@ -82,6 +86,17 @@ def visualize(self) -> Text:
             content.append(thought_text)
             content.append("\n\n")
 
+        # Responses API reasoning (plaintext only; never render encrypted_content)
+        reasoning_item = self.responses_reasoning_item
+        if reasoning_item is not None:
+            content.append("Reasoning:\n", style="bold")
+            if reasoning_item.summary:
+                for s in reasoning_item.summary:
+                    content.append(f"- {s}\n")
+            if reasoning_item.content:
+                for b in reasoning_item.content:
+                    content.append(f"{b}\n")
+
         # Display action information using action's visualize method
         if self.action:
             content.append(self.action.visualize)
@@ -100,6 +115,7 @@ def to_llm_message(self) -> Message:
             tool_calls=[self.tool_call],
             reasoning_content=self.reasoning_content,
             thinking_blocks=self.thinking_blocks,
+            responses_reasoning_item=self.responses_reasoning_item,
         )
 
     def __str__(self) -> str:

openhands/sdk/event/llm_convertible/message.py

@@ -50,17 +50,29 @@ def visualize(self) -> Text:
         """Return Rich Text representation of this message event."""
         content = Text()
 
+        # Message text content
         text_parts = content_to_str(self.llm_message.content)
         if text_parts:
             full_content = "".join(text_parts)
             content.append(full_content)
         else:
             content.append("[no text content]")
 
+        # Responses API reasoning (plaintext only; never render encrypted_content)
+        reasoning_item = self.llm_message.responses_reasoning_item
+        if reasoning_item is not None:
+            content.append("\n\nReasoning:\n", style="bold")
+            if reasoning_item.summary:
+                for s in reasoning_item.summary:
+                    content.append(f"- {s}\n")
+            if reasoning_item.content:
+                for b in reasoning_item.content:
+                    content.append(f"{b}\n")
+
         # Add microagent information if present
         if self.activated_microagents:
             content.append(
-                f"\nActivated Microagents: {', '.join(self.activated_microagents)}",
+                f"\n\nActivated Microagents: {', '.join(self.activated_microagents)}",
             )
 
         # Add extended content if available
@@ -69,7 +81,9 @@ def visualize(self) -> Text:
                 isinstance(c, ImageContent) for c in self.extended_content
             ), "Extended content should not contain images"
             text_parts = content_to_str(self.extended_content)
-            content.append("\nPrompt Extension based on Agent Context:\n")
+            content.append(
+                "\n\nPrompt Extension based on Agent Context:\n", style="bold"
+            )
             content.append(" ".join(text_parts))
 
         return content

openhands/sdk/event/llm_convertible/observation.py

@@ -121,6 +121,8 @@ def visualize(self) -> Text:
         return content
 
     def to_llm_message(self) -> Message:
+        # Provide plain string error content; serializers handle Chat vs Responses.
+        # For Responses API, output is a string; JSON is not required.
         return Message(
             role="tool",
             content=[TextContent(text=self.error)],

openhands/sdk/llm/__init__.py

@@ -5,6 +5,7 @@
     ImageContent,
     Message,
     MessageToolCall,
+    ReasoningItemModel,
     RedactedThinkingBlock,
     TextContent,
     ThinkingBlock,
@@ -31,6 +32,7 @@
     "ImageContent",
     "ThinkingBlock",
     "RedactedThinkingBlock",
+    "ReasoningItemModel",
     "content_to_str",
     "Metrics",
     "MetricsSnapshot",