Skip to content

docs(sdk): document ask_oracle tool #566

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
enyst wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(sdk): document ask_oracle tool #566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
689f391
docs(sdk): document ask oracle tool
enyst Jun 11, 2026
f380da2
docs(sdk): clarify oracle prompt context
openhands-agent Jun 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,6 +278,7 @@
"sdk/guides/agent-custom",
"sdk/guides/agent-file-based",
"sdk/guides/agent-stuck-detector",
"sdk/guides/agent-ask-oracle",
"sdk/guides/agent-tom-agent",
"sdk/guides/critic"
]
Expand Down
40 changes: 40 additions & 0 deletions sdk/guides/agent-ask-oracle.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
title: Ask Oracle
description: Let an agent consult a saved Oracle LLM profile for stateless second-opinion advice.
---

import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx";

> A ready-to-run example is available [here](#ready-to-run-example)!

Use `ask_oracle` when the active agent should ask a stronger or more specialized saved LLM profile for a second opinion without switching its own active profile.

## When to Use It

`ask_oracle` is useful when an agent is stuck, comparing approaches, or wants another model to review a risky decision. The Oracle call is stateless from the Oracle's point of view: it receives a dedicated Oracle system prompt plus the agent's question and optional context, returns a text recommendation, and does not take over the conversation.

## Configure the Oracle Profile

First save the LLM you want to use as the Oracle with `LLMProfileStore`. Then set `oracle_llm_profile` on `OpenHandsAgentSettings` to the saved profile name.

```python icon="python" focus={10} wrap
from openhands.sdk import LLM, OpenHandsAgentSettings

settings = OpenHandsAgentSettings(
llm=LLM(model="openai/gpt-5-nano"),
oracle_llm_profile="oracle",
)
agent = settings.create_agent()
```

When `oracle_llm_profile` is unset, the tool is not added. When it is set, the agent receives an `ask_oracle` tool and can consult that saved profile while keeping its regular LLM unchanged.

## Ready-to-run Example

<Note>
This example is available on GitHub: [examples/01_standalone_sdk/54_ask_oracle_tool/main.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/54_ask_oracle_tool/main.py)
</Note>

```python icon="python" expandable examples/01_standalone_sdk/54_ask_oracle_tool/main.py
# content is auto-synced
```
Loading