fix(examples): allow all examples to run with same LLM_API_KEY #1065

jpshackelford · 2025-11-06T18:02:51Z

Problem

The hello world example uses a hardcoded Anthropic model name instead of reading from environment variables like other examples. This creates an inconsistent experience:

Users must change LLM_API_KEY depending on which example they want to run
Demo workflows are disrupted when you want to run hello world first, then move to other examples
First-time users encounter confusing stack traces instead of clear error messages when API keys don't match making first impression that SDK or examples are buggy.

Solution

This change makes hello world consistent with other examples by:

Using LLM_MODEL environment variable with default openhands/claude-sonnet-4-5-20250929
Adding a comment with instructions on where to get API keys and how to switch to other models

Now users can set up their environment once and run all examples with the same configuration, making the SDK more approachable for first-time users and smoother for demos.

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:7c9df63-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

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

Allow hello world example to use the same LLM_API_KEY and LLM_BASE_URL environment variables as other examples, enabling consistent configuration across all examples. Changes: - Use os.getenv() for model with default 'openhands/claude-sonnet-4-5-20250929' - Add base_url parameter from LLM_BASE_URL environment variable - Add usage_id for better tracking - Add comments about API key configuration

examples/01_standalone_sdk/01_hello_world.py

rbren

will give feedback in a min :)

- Update all example files to use anthropic/claude-sonnet-4-5-20250929 as the default model - Remove comments about obtaining credits from hello world example - Model and API key can be overridden via LLM_MODEL and LLM_API_KEY environment variables

jpshackelford · 2025-11-07T02:46:32Z

Based on feedback via slack, added a commit that:

Removes comment from 01_hello_world.py
Updates all examples from openhands/claude-sonnet-4-5-20250929 to anthropic/claude-sonnet-4-5-20250929
Allows LLM_MODEL and LLM_API_KEY environment variables to override settings in 01_hello_world.py as elsewhere

This commit DOES NOT address with the few cases where a model besides openhands/claude-sonnet-4-5-20250929 is hardcoded.

examples/01_standalone_sdk/19_llm_routing.py

…LM routing example Ensures both primary and secondary LLMs use the same provider/key by default. Co-authored-by: openhands <openhands@all-hands.dev>

…M_MODEL Restores in-line env read for API key with model still read from env with fallback. Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2025-11-09T05:02:12Z

🔄 Running Examples with `openhands/claude-haiku-4-5-20251001`

Last updated: 2025-11-09 05:21:47 UTC

Example	Status	Duration	Cost
01_standalone_sdk/02_custom_tools.py	✅ PASS	26s	$0.03
01_standalone_sdk/03_activate_skill.py	✅ PASS	11s	$0.01
01_standalone_sdk/05_use_llm_registry.py	✅ PASS	8s	$0.01
01_standalone_sdk/07_mcp_integration.py	✅ PASS	43s	$0.02
01_standalone_sdk/09_pause_example.py	✅ PASS	13s	$0.01
01_standalone_sdk/10_persistence.py	✅ PASS	37s	$0.03
01_standalone_sdk/11_async.py	✅ PASS	32s	$0.03
01_standalone_sdk/12_custom_secrets.py	✅ PASS	14s	$0.01
01_standalone_sdk/13_get_llm_metrics.py	✅ PASS	31s	$0.02
01_standalone_sdk/14_context_condenser.py	✅ PASS	198s	$0.40
01_standalone_sdk/17_image_input.py	✅ PASS	19s	$0.02
01_standalone_sdk/18_send_message_while_processing.py	✅ PASS	20s	$0.01
01_standalone_sdk/19_llm_routing.py	✅ PASS	16s	$0.01
01_standalone_sdk/20_stuck_detector.py	✅ PASS	16s	$0.01
01_standalone_sdk/21_generate_extraneous_conversation_costs.py	❌ FAIL (exit: 1)	10s	$0.00
01_standalone_sdk/22_anthropic_thinking.py	✅ PASS	14s	$0.01
01_standalone_sdk/23_responses_reasoning.py	✅ PASS	36s	$0.01
01_standalone_sdk/24_planning_agent_workflow.py	✅ PASS	312s	$0.42
01_standalone_sdk/25_agent_delegation.py	❌ FAIL (exit: 1)	45s	$0.00
01_standalone_sdk/26_custom_visualizer.py	✅ PASS	19s	$0.00N/A
02_remote_agent_server/01_convo_with_local_agent_server.py	✅ PASS	55s	$0.04
02_remote_agent_server/02_convo_with_docker_sandboxed_server.py	✅ PASS	116s	$0.04
02_remote_agent_server/03_browser_use_with_docker_sandboxed_server.py	✅ PASS	63s	$0.04
02_remote_agent_server/04_convo_with_api_sandboxed_server.py	❌ FAIL (exit: 1)	3s	$0.00

❌ Some tests failed

Total: 24 | Passed: 21 | Failed: 3

View full workflow run

…osts example Ensures CI uses the same provider/key by reading model from LLM_MODEL for both LLMs. Co-authored-by: openhands <openhands@all-hands.dev>

xingyaoww

LGTM

done

jpshackelford force-pushed the jps/same-settings-for-all-examples branch from dfa6594 to 7f3ad3c Compare November 6, 2025 18:09

jpshackelford requested review from rbren November 6, 2025 18:12

jpshackelford changed the title ~~fix(examples): use environment variables for LLM config in hello world~~ fix(examples): allow all examples to run with same LLM_API_KEY Nov 6, 2025

enyst reviewed Nov 6, 2025

View reviewed changes

examples/01_standalone_sdk/01_hello_world.py Outdated Show resolved Hide resolved

enyst reviewed Nov 6, 2025

View reviewed changes

examples/01_standalone_sdk/01_hello_world.py Outdated Show resolved Hide resolved

rbren previously requested changes Nov 6, 2025

View reviewed changes

enyst reviewed Nov 7, 2025

View reviewed changes

examples/01_standalone_sdk/19_llm_routing.py Show resolved Hide resolved

enyst and others added 2 commits November 9, 2025 04:49

fix(examples): use openhands/ provider for default primary model in L…

d9feffd

…LM routing example Ensures both primary and secondary LLMs use the same provider/key by default. Co-authored-by: openhands <openhands@all-hands.dev>

chore(examples): simplify hello world by inlining LLM_API_KEY like LL…

d6b8ffc

…M_MODEL Restores in-line env read for API key with model still read from env with fallback. Co-authored-by: openhands <openhands@all-hands.dev>

enyst approved these changes Nov 9, 2025

View reviewed changes

enyst added the test-examples Run all applicable "examples/" files. Expensive operation. label Nov 9, 2025

fix(examples): use env-driven model for secondary LLM in extraneous c…

b65dd11

…osts example Ensures CI uses the same provider/key by reading model from LLM_MODEL for both LLMs. Co-authored-by: openhands <openhands@all-hands.dev>

OpenHands deleted a comment from openhands-ai bot Nov 9, 2025

Merge branch 'main' into jps/same-settings-for-all-examples

e9715ca

xingyaoww approved these changes Nov 11, 2025

View reviewed changes

enyst merged commit 907ead5 into main Nov 11, 2025
21 checks passed

enyst deleted the jps/same-settings-for-all-examples branch November 11, 2025 18:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(examples): allow all examples to run with same LLM_API_KEY #1065

fix(examples): allow all examples to run with same LLM_API_KEY #1065

Uh oh!

jpshackelford commented Nov 6, 2025 •

edited by github-actions bot

Loading

Uh oh!

Uh oh!

Uh oh!

rbren left a comment

Uh oh!

jpshackelford commented Nov 7, 2025

Uh oh!

Uh oh!

github-actions bot commented Nov 9, 2025 •

edited

Loading

Uh oh!

xingyaoww left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

fix(examples): allow all examples to run with same LLM_API_KEY #1065

fix(examples): allow all examples to run with same LLM_API_KEY #1065

Uh oh!

Conversation

jpshackelford commented Nov 6, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Uh oh!

Uh oh!

Uh oh!

rbren left a comment

Choose a reason for hiding this comment

Uh oh!

jpshackelford commented Nov 7, 2025

Uh oh!

Uh oh!

github-actions bot commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔄 Running Examples with openhands/claude-haiku-4-5-20251001

❌ Some tests failed

Uh oh!

xingyaoww left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jpshackelford commented Nov 6, 2025 •

edited by github-actions bot

Loading

github-actions bot commented Nov 9, 2025 •

edited

Loading

🔄 Running Examples with `openhands/claude-haiku-4-5-20251001`