Add example for reconstructing OpenAI messages from events

[enyst]

HUMAN: The bot reviewer doesn’t know that .pr/ are temporary and will be cleaned up automatically.

This PR proposes an example of how to convert back events to LLM-ready messages, for RL or debugging or whatever purpose. Since the SDK is developer focused, maybe it makes sense? So we can also point easily to it if we get this question again.

Slack reference

—-

Summary

• add persistence section header and use .conversations root
• trim verbose persistence logging in the example
• add a short module docstring

Testing

• make build
• uv run pre-commit run --files examples/01_standalone_sdk/36_event_json_to_openai_messages.py

Docs PR: OpenHands/docs#303

---

Agent Server images for this PR

• 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.12-nodejs22	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:15eda6e-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:15eda6e-golang-amd64
ghcr.io/openhands/agent-server:15eda6e-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:15eda6e-golang-arm64
ghcr.io/openhands/agent-server:15eda6e-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:15eda6e-java-amd64
ghcr.io/openhands/agent-server:15eda6e-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:15eda6e-java-arm64
ghcr.io/openhands/agent-server:15eda6e-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:15eda6e-python-amd64
ghcr.io/openhands/agent-server:15eda6e-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:15eda6e-python-arm64
ghcr.io/openhands/agent-server:15eda6e-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:15eda6e-golang
ghcr.io/openhands/agent-server:15eda6e-java
ghcr.io/openhands/agent-server:15eda6e-python

About Multi-Architecture Support

• Each variant tag (e.g., 15eda6e-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., 15eda6e-python-amd64) are also available if needed

[github-actions]

✅ PR Artifacts Cleaned Up

The .pr/ directory has been automatically removed.

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • [Optional] Docs example

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #1916 at branch `example/event-json-openai-messages`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[all-hands-bot]

Code Review Summary

This PR adds a useful example for reconstructing OpenAI messages from persisted events. However, there are critical issues that need to be addressed:

🔴 Critical Issues

1. Runtime artifacts committed to repository

The entire .pr/event-json-to-openai-messages/ directory should NOT be committed. It contains:

• Generated event logs and state files
• API usage metadata
• Lock files

These files:

• Will bloat the repository over time
• Contain runtime-specific data that's not portable
• Are regenerated automatically when the example runs
• May contain sensitive information

Action required: Delete the .pr/event-json-to-openai-messages/ directory and add both .pr/ and .conversations/ to .gitignore

🟠 Important Issues

2. Path inconsistency (line 12)

The code sets persistence_root = Path(".conversations") but the committed artifacts are in .pr/event-json-to-openai-messages/. This suggests the example was run with different settings than what's in the code.

Recommendation: Ensure the code matches how the example should actually be run.

🟡 Suggestions

3. Missing error handling (line 88)

The event loading code Event.model_validate_json(path.read_text()) will raise an unhandled exception if any JSON file is malformed. Consider adding try/except for robustness.

4. Add .gitignore entries

Add these patterns to .gitignore:

.pr/
.conversations/

🟢 Nits

5. Comment clarity (line 21)

Consider adding a comment explaining why imports come after environment setup:

# Import after setting env vars because these modules read them at import time
from openhands.sdk import (  # noqa: E402

---

Overall: The Python code example itself is well-structured and demonstrates the concept clearly. Once the runtime artifacts are removed and the path inconsistency is resolved, this will be a valuable addition to the examples.

[xingyaoww]

LGTM! Shall we add it to our OpenHands/docs site as well?

[enyst]

LGTM! Shall we add it to our OpenHands/docs site as well?

Yes!

• docs PR: Document serialized events example docs#303
• how it looks like: https://allhandsai-example-event-json-openai-messages.mintlify.app/sdk/guides/convo-persistence#reading-serialized-events

[xingyaoww]

Thanks @enyst!