feat(sdk): add ask_oracle tool

.github/agent-server-openapi-weak-schema-allowlist.json

@@ -77,6 +77,12 @@
     "reason": "Agent settings retain a backward-compatible extension surface while known security-sensitive fields remain typed.",
     "owner": "OpenHands OSS"
   },
+  {
+    "pointer": "/components/schemas/AskOracleTool/properties/meta/anyOf/0/additionalProperties",
+    "kind": "unrestricted-additional-properties",
+    "reason": "Tool metadata is intentionally extensible across tool providers.",
+    "owner": "OpenHands"
+  },
   {
     "pointer": "/components/schemas/BrowserClickTool/properties/meta/anyOf/0/additionalProperties",
     "kind": "unrestricted-additional-properties",

examples/01_standalone_sdk/58_ask_oracle_tool/main.py

@@ -0,0 +1,78 @@
+"""Consult the Oracle end-to-end with the ask_oracle tool.
+
+The Oracle is a saved LLM profile resolved by convention under the name
+``oracle``. This example wires two profiles — the agent's primary model and a
+separate ``oracle`` model — adds ``Tool(name="ask_oracle")`` to the agent, then
+drives a normal conversation: the agent decides to call ``ask_oracle``, the tool
+consults the ``oracle`` profile, and the agent uses the Oracle's answer to reply.
+
+Usage:
+    LLM_API_KEY=... LLM_BASE_URL=https://llm-proxy.app.all-hands.dev \
+        uv run python examples/01_standalone_sdk/58_ask_oracle_tool/main.py
+
+Note:
+    The example saves the ``oracle`` profile in a temporary directory so it
+    does not modify the user's default profile store.
+"""
+
+import os
+import tempfile
+
+from pydantic import SecretStr
+
+from openhands.sdk import LLM, Agent, LocalConversation, Tool
+from openhands.sdk.llm.llm_profile_store import LLMProfileStore
+from openhands.tools.ask_oracle import ORACLE_PROFILE_NAME
+
+
+DEFAULT_BASE_URL = "https://llm-proxy.app.all-hands.dev"
+# The agent's primary model (follows the standard LLM_MODEL env like other
+# examples). The Oracle defaults to the same model; override ASK_ORACLE_MODEL to
+# point the "oracle" profile at a different/stronger model.
+PRIMARY_MODEL = os.getenv("ASK_ORACLE_PRIMARY_MODEL") or os.getenv(
+    "LLM_MODEL", "openai/gpt-5.5"
+)
+ORACLE_MODEL = os.getenv("ASK_ORACLE_MODEL", PRIMARY_MODEL)
+
+api_key = os.getenv("LLM_API_KEY")
+assert api_key is not None, "LLM_API_KEY environment variable is not set."
+base_url = os.getenv("LLM_BASE_URL", DEFAULT_BASE_URL)
+
+with tempfile.TemporaryDirectory() as profile_store_dir:
+    store = LLMProfileStore(profile_store_dir)
+    # The Oracle model is saved under the conventional profile name "oracle".
+    store.save(
+        ORACLE_PROFILE_NAME,
+        LLM(
+            model=ORACLE_MODEL,
+            api_key=SecretStr(api_key),
+            base_url=base_url,
+            usage_id="oracle",
+        ),
+        include_secrets=True,
+    )
+
+    primary_llm = LLM(
+        model=PRIMARY_MODEL,
+        api_key=SecretStr(api_key),
+        base_url=base_url,
+        usage_id="primary",
+    )
+    agent = Agent(llm=primary_llm, tools=[Tool(name="ask_oracle")])
+    conversation = LocalConversation(
+        agent=agent,
+        workspace=os.getcwd(),
+        profile_store_dir=profile_store_dir,
+    )
+
+    print(f"Primary model: {conversation.agent.llm.model}")
+    print(f"Oracle model:  {ORACLE_MODEL}")
+    conversation.send_message(
+        "Call the oracle to ask it for its opinion on the weather today, "
+        "then just tell me in two words how it's like."
+    )
+    conversation.run()
+
+    combined = conversation.state.stats.get_combined_metrics()
+    print(f"Total cost: ${combined.accumulated_cost:.6f}")
+    print(f"EXAMPLE_COST: {combined.accumulated_cost}")

openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py

@@ -237,6 +237,7 @@ def __init__(
         prompt_cache_key: str | None = None,
         file_store: FileStore | None = None,
         mcp_tool_provider: MCPToolProvider | None = None,
+        profile_store_dir: str | Path | None = None,
         **_: object,
     ):
         """Initialize the conversation.
@@ -295,6 +296,8 @@ def __init__(
             file_store: Optional FileStore to use for conversation state and EventLog
                 persistence. If provided, this takes precedence over persistence_dir
                 for state and EventLog storage.
+            profile_store_dir: Optional directory containing saved LLM profiles.
+                Defaults to ``~/.openhands/profiles``.
         """
         super().__init__()  # Initialize with span tracking
         # Mark cleanup as initiated as early as possible to avoid races or partially
@@ -482,7 +485,7 @@ def _default_callback(e):
         # Agent initialization is deferred to _ensure_agent_ready() for lazy loading
         # This ensures plugins are loaded before agent initialization
         self.llm_registry = LLMRegistry()
-        self._profile_store = LLMProfileStore()
+        self._profile_store = LLMProfileStore(profile_store_dir)
         self._cipher = cipher
 
         # Seed agent_context.secrets into the registry for every agent (regular

openhands-sdk/openhands/sdk/tool/builtins/__init__.py

@@ -1,8 +1,9 @@
-"""Implementing essential tools that doesn't interact with the environment.
+"""SDK-resident tools that do not interact with the environment.
 
-These are built in and are *required* for the agent to work.
+`BUILT_IN_TOOLS` contains tools attached to every agent. `BUILT_IN_TOOL_CLASSES`
+also includes optional SDK tools that are resolved by name from agent setup.
 
-For tools that require interacting with the environment, add them to `openhands-tools`.
+Tools that require interacting with the environment belong in `openhands-tools`.
 """
 
 from openhands.sdk.tool.builtins.finish import (

openhands-tools/openhands/tools/__init__.py

@@ -18,6 +18,7 @@
 
 from importlib.metadata import PackageNotFoundError, version
 
+from openhands.tools.ask_oracle import AskOracleTool
 from openhands.tools.delegate import DelegationVisualizer
 from openhands.tools.file_editor import FileEditorTool
 from openhands.tools.preset.default import (
@@ -40,6 +41,7 @@
 
 __all__ = [
     "__version__",
+    "AskOracleTool",
     "DelegationVisualizer",
     "FileEditorTool",
     "TaskToolSet",

openhands-tools/openhands/tools/ask_oracle/__init__.py

@@ -0,0 +1,36 @@
+"""Ask-Oracle tool package.
+
+Provides a read-only ``ask_oracle`` tool: a one-shot, tool-less sub-agent that
+consults a stronger/more-capable LLM for a second opinion. The Oracle model is a
+saved LLM profile, resolved by convention under the name ``oracle`` (see
+``ORACLE_PROFILE_NAME``).
+
+Usage:
+    from openhands.tools.ask_oracle import AskOracleTool
+
+    agent = Agent(
+        llm=llm,
+        tools=[Tool(name=AskOracleTool.name)],
+    )
+
+The agent's active conversation LLM is never switched. The Oracle call sends only
+the Oracle system prompt plus the agent's question and optional context, without
+forwarding conversation history or tools.
+"""
+
+from openhands.tools.ask_oracle.definition import (
+    ORACLE_PROFILE_NAME,
+    AskOracleAction,
+    AskOracleObservation,
+    AskOracleTool,
+)
+from openhands.tools.ask_oracle.impl import AskOracleExecutor
+
+
+__all__ = [
+    "ORACLE_PROFILE_NAME",
+    "AskOracleAction",
+    "AskOracleObservation",
+    "AskOracleExecutor",
+    "AskOracleTool",
+]

openhands-tools/openhands/tools/ask_oracle/definition.py

@@ -0,0 +1,114 @@
+"""Action, observation, and tool definitions for the ask_oracle tool."""
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final, Self
+
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.tool.registry import register_tool
+from openhands.sdk.tool.tool import (
+    Action,
+    Observation,
+    ToolAnnotations,
+    ToolDefinition,
+)
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.state import ConversationState
+
+
+# The Oracle model is a saved LLM profile resolved by convention under this
+# name. Save a profile named "oracle" (e.g. via LLMProfileStore.save("oracle",
+# llm)) and the tool will consult it. No agent setting or wiring is required.
+ORACLE_PROFILE_NAME: Final[str] = "oracle"
+
+
+class AskOracleAction(Action):
+    """Action for asking the Oracle for advice."""
+
+    question: str = Field(
+        description=(
+            "The specific question or dilemma to ask the Oracle about. Use this "
+            "when you are stuck, uncertain, or need a second opinion."
+        )
+    )
+    context: str | None = Field(
+        default=None,
+        description=(
+            "Optional extra context, such as approaches already tried, constraints, "
+            "or the recommendation you are considering."
+        ),
+    )
+
+    @property
+    def visualize(self) -> Text:
+        content = Text()
+        content.append("Ask Oracle: ", style="bold cyan")
+        content.append(self.question)
+        if self.context:
+            content.append("\nContext: ", style="bold")
+            content.append(self.context)
+        return content
+
+
+class AskOracleObservation(Observation):
+    """Observation returned by the Oracle consultation."""
+
+    @property
+    def visualize(self) -> Text:
+        content = Text()
+        if self.is_error:
+            content.append("Oracle consultation failed", style="bold red")
+        else:
+            content.append("Oracle recommendation", style="bold green")
+        if self.text:
+            content.append("\n")
+            content.append(self.text)
+        return content
+
+
+_DESCRIPTION = (
+    "Ask the Oracle for a second opinion. The Oracle is a smart model intended "
+    "to help with difficult reasoning.\n\n"
+    "Use this when you are stuck, uncertain, comparing approaches, or need a "
+    "higher-quality recommendation before proceeding.\n\n"
+    "Treat the Oracle's response as strong guidance and follow its recommendation "
+    "unless you have a clear reason not to."
+)
+
+
+class AskOracleTool(ToolDefinition[AskOracleAction, AskOracleObservation]):
+    """Tool for consulting the Oracle (a saved LLM profile named "oracle")."""
+
+    @classmethod
+    def create(
+        cls,
+        conv_state: "ConversationState | None" = None,  # noqa: ARG003
+        **params,
+    ) -> Sequence[Self]:
+        if params:
+            raise ValueError("AskOracleTool does not accept parameters")
+
+        # Import here to keep module import light and avoid any import cycles.
+        from openhands.tools.ask_oracle.impl import AskOracleExecutor
+
+        return [
+            cls(
+                description=_DESCRIPTION,
+                action_type=AskOracleAction,
+                observation_type=AskOracleObservation,
+                executor=AskOracleExecutor(),
+                annotations=ToolAnnotations(
+                    readOnlyHint=True,
+                    destructiveHint=False,
+                    idempotentHint=False,
+                    openWorldHint=True,
+                ),
+            )
+        ]
+
+
+# Automatically register when this module is imported.
+register_tool(AskOracleTool.name, AskOracleTool)