docs(examples): align Ask Oracle conventions

[enyst]

HUMAN:
This PR tweaks a bit the Ask Oracle tool example, to be consistent with the patterns in other examples in the codebase.

---

AGENT:

Why

Keep the checked-in Ask Oracle example aligned with established SDK usage patterns and the synchronized documentation.

Summary

• Reference the registered tool through AskOracleTool.name.
• Use the public conversation_stats metrics accessor.
• Remove a redundant comment.

Issue Number

Follow-up to SDK PR #3673. Documentation: OpenHands/docs PR #566.

How to Test

LLM_API_KEY=... \
LLM_BASE_URL=https://llm-proxy.eval.all-hands.dev \
LLM_MODEL=openai/gpt-5.1 \
ASK_ORACLE_PRIMARY_MODEL=openai/gpt-5.1 \
ASK_ORACLE_MODEL=openai/gpt-5-mini \
OPENHANDS_SUPPRESS_BANNER=1 \
uv run pytest tests/examples/test_examples.py --run-examples -k 58_ask_oracle_tool

Result: 1 passed, 69 deselected.

Also ran:

uv run pre-commit run --files examples/01_standalone_sdk/58_ask_oracle_tool/main.py

All hooks passed.

Video/Screenshots

Not applicable; this is a small example-code consistency change.

Design Doc

Not applicable.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

This PR was created by an AI agent (OpenAI Codex) on behalf of the user.

---

🐳 Agent Server images for this PR — GHCR package, pull/run commands, and all pushed tags (click to expand)

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.13-nodejs22-slim	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:41bb901-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-41bb901-python \
  ghcr.io/openhands/agent-server:41bb901-python

All tags pushed for this build

ghcr.io/openhands/agent-server:41bb901-golang-amd64
ghcr.io/openhands/agent-server:41bb901cab640f85d1c4b7e216bbfc96eb163ab0-golang-amd64
ghcr.io/openhands/agent-server:gpt-ask-oracle-example-conventions-golang-amd64
ghcr.io/openhands/agent-server:41bb901-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:41bb901-golang-arm64
ghcr.io/openhands/agent-server:41bb901cab640f85d1c4b7e216bbfc96eb163ab0-golang-arm64
ghcr.io/openhands/agent-server:gpt-ask-oracle-example-conventions-golang-arm64
ghcr.io/openhands/agent-server:41bb901-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:41bb901-java-amd64
ghcr.io/openhands/agent-server:41bb901cab640f85d1c4b7e216bbfc96eb163ab0-java-amd64
ghcr.io/openhands/agent-server:gpt-ask-oracle-example-conventions-java-amd64
ghcr.io/openhands/agent-server:41bb901-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:41bb901-java-arm64
ghcr.io/openhands/agent-server:41bb901cab640f85d1c4b7e216bbfc96eb163ab0-java-arm64
ghcr.io/openhands/agent-server:gpt-ask-oracle-example-conventions-java-arm64
ghcr.io/openhands/agent-server:41bb901-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:41bb901-python-amd64
ghcr.io/openhands/agent-server:41bb901cab640f85d1c4b7e216bbfc96eb163ab0-python-amd64
ghcr.io/openhands/agent-server:gpt-ask-oracle-example-conventions-python-amd64
ghcr.io/openhands/agent-server:41bb901-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:41bb901-python-arm64
ghcr.io/openhands/agent-server:41bb901cab640f85d1c4b7e216bbfc96eb163ab0-python-arm64
ghcr.io/openhands/agent-server:gpt-ask-oracle-example-conventions-python-arm64
ghcr.io/openhands/agent-server:41bb901-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:41bb901-golang
ghcr.io/openhands/agent-server:41bb901cab640f85d1c4b7e216bbfc96eb163ab0-golang
ghcr.io/openhands/agent-server:gpt-ask-oracle-example-conventions-golang
ghcr.io/openhands/agent-server:41bb901-golang_tag_1.21-bookworm
ghcr.io/openhands/agent-server:41bb901-java
ghcr.io/openhands/agent-server:41bb901cab640f85d1c4b7e216bbfc96eb163ab0-java
ghcr.io/openhands/agent-server:gpt-ask-oracle-example-conventions-java
ghcr.io/openhands/agent-server:41bb901-eclipse-temurin_tag_17-jdk
ghcr.io/openhands/agent-server:41bb901-python
ghcr.io/openhands/agent-server:41bb901cab640f85d1c4b7e216bbfc96eb163ab0-python
ghcr.io/openhands/agent-server:gpt-ask-oracle-example-conventions-python
ghcr.io/openhands/agent-server:41bb901-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim

About Multi-Architecture Support

• Each variant tag (e.g., 41bb901-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 41bb901-python-amd64) are also available if needed

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

Both changes here align the Ask Oracle example with the conventions already used everywhere else in examples/01_standalone_sdk/:

• Tool(name=AskOracleTool.name) is what the docs, the ask_oracle test suite, and every other example that wires a built-in tool use, instead of a duplicated string literal.
• conversation.conversation_stats is the public accessor used in every SDK example that prints metrics (see 27_observability_laminar.py, 13_get_llm_metrics.py, 36_event_json_to_openai_messages.py, etc.); conversation.state.stats works but bypasses the supported API. Renaming combined to cost is a small but nice readability win — the name now matches what the value actually holds.
• Dropping the redundant inline comment over ORACLE_PROFILE_NAME is also correct — the constant name and the module docstring already explain it.

No behavior change, no API surface change, no dependency change. Tests live in tests/tools/ask_oracle/ and exercise the tool itself, not this example script — so there is no test gap to address from a doc-only edit like this.

✅ Approving.

---

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW
  Single-file doc-only change to an example script; semantics are unchanged because AskOracleTool.name resolves to the same string "ask_oracle" and conversation.conversation_stats is the supported accessor for self._state.stats.

VERDICT:
✅ Worth merging: Conventions are now consistent with the rest of examples/01_standalone_sdk/.

KEY INSIGHT:
Using class-level .name constants for tool registration and conversation.conversation_stats for metrics is the convention across this repo — once you spot it, every example that drifts from it becomes visible.

---

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation