Simplify hello world example (#1047)

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: enyst <engel.nyst@gmail.com>

Author: 3 people

.github/workflows/run-examples.yml

@@ -52,6 +52,7 @@ jobs:
               run: |
                   # List of examples to test
                   # Excluded examples:
+                  # - 01_hello_world.py: requires LiteLLM proxy URL (OPENAI_BASE_URL) not set in CI
                   # - 04_confirmation_mode_example.py: requires user input
                   # - 06_interactive_terminal_w_reasoning.py: interactive terminal
                   # - 08_mcp_with_oauth.py: requires OAuth setup
@@ -61,7 +62,6 @@ jobs:
                   # - 04_vscode_with_docker_sandboxed_server.py: requires VSCode setup
                   set -e
                   EXAMPLES=(
-                      "examples/01_standalone_sdk/01_hello_world.py"
                       "examples/01_standalone_sdk/02_custom_tools.py"
                       "examples/01_standalone_sdk/03_activate_skill.py"
                       "examples/01_standalone_sdk/05_use_llm_registry.py"

examples/01_standalone_sdk/01_hello_world.py

@@ -1,33 +1,28 @@
 import os
 
-from pydantic import SecretStr
+from openhands.sdk import LLM, Agent, Conversation, Tool
+from openhands.tools.execute_bash import BashTool
+from openhands.tools.file_editor import FileEditorTool
+from openhands.tools.task_tracker import TaskTrackerTool
 
-from openhands.sdk import LLM, Conversation
-from openhands.tools.preset.default import get_default_agent
 
-
-# Configure LLM and agent
-# You can get an API key from https://app.all-hands.dev/settings/api-keys
-api_key = os.getenv("LLM_API_KEY")
-assert api_key is not None, "LLM_API_KEY environment variable is not set."
-model = os.getenv("LLM_MODEL", "openhands/claude-sonnet-4-5-20250929")
-base_url = os.getenv("LLM_BASE_URL")
 llm = LLM(
-    model=model,
-    api_key=SecretStr(api_key),
-    base_url=base_url,
-    usage_id="agent",
+    model="anthropic/claude-sonnet-4-5-20250929",
+    api_key=os.getenv("LLM_API_KEY"),
+)
+
+agent = Agent(
+    llm=llm,
+    tools=[
+        Tool(name=BashTool.name),
+        Tool(name=FileEditorTool.name),
+        Tool(name=TaskTrackerTool.name),
+    ],
 )
-agent = get_default_agent(llm=llm, cli_mode=True)
 
-# Start a conversation and send some messages
 cwd = os.getcwd()
 conversation = Conversation(agent=agent, workspace=cwd)
 
-# Send a message and let the agent run
 conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
 conversation.run()
-
-# Report cost
-cost = llm.metrics.accumulated_cost
-print(f"EXAMPLE_COST: {cost}")
+print("All done!")

openhands-sdk/openhands/sdk/llm/llm.py

@@ -123,14 +123,14 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     # Config fields
     # =========================================================================
     model: str = Field(default="claude-sonnet-4-20250514", description="Model name.")
-    api_key: SecretStr | None = Field(default=None, description="API key.")
+    api_key: str | SecretStr | None = Field(default=None, description="API key.")
     base_url: str | None = Field(default=None, description="Custom base URL.")
     api_version: str | None = Field(
         default=None, description="API version (e.g., Azure)."
     )
 
-    aws_access_key_id: SecretStr | None = Field(default=None)
-    aws_secret_access_key: SecretStr | None = Field(default=None)
+    aws_access_key_id: str | SecretStr | None = Field(default=None)
+    aws_secret_access_key: str | SecretStr | None = Field(default=None)
     aws_region_name: str | None = Field(default=None)
 
     openrouter_site_url: str = Field(default="https://docs.all-hands.dev/")
@@ -296,7 +296,7 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
     # =========================================================================
     @field_validator("api_key", "aws_access_key_id", "aws_secret_access_key")
     @classmethod
-    def _validate_secrets(cls, v: SecretStr | None, info):
+    def _validate_secrets(cls, v: str | SecretStr | None, info) -> SecretStr | None:
         return validate_secret(v, info)
 
     @model_validator(mode="before")
@@ -342,8 +342,10 @@ def _set_env_side_effects(self):
         if self.openrouter_app_name:
             os.environ["OR_APP_NAME"] = self.openrouter_app_name
         if self.aws_access_key_id:
+            assert isinstance(self.aws_access_key_id, SecretStr)
             os.environ["AWS_ACCESS_KEY_ID"] = self.aws_access_key_id.get_secret_value()
         if self.aws_secret_access_key:
+            assert isinstance(self.aws_secret_access_key, SecretStr)
             os.environ["AWS_SECRET_ACCESS_KEY"] = (
                 self.aws_secret_access_key.get_secret_value()
             )
@@ -633,14 +635,18 @@ def _one_attempt(**retry_kwargs) -> ResponsesAPIResponse:
                     typed_input: ResponseInputParam | str = (
                         cast(ResponseInputParam, input_items) if input_items else ""
                     )
+                    # Extract api_key value with type assertion for type checker
+                    api_key_value: str | None = None
+                    if self.api_key:
+                        assert isinstance(self.api_key, SecretStr)
+                        api_key_value = self.api_key.get_secret_value()
+
                     ret = litellm_responses(
                         model=self.model,
                         input=typed_input,
                         instructions=instructions,
                         tools=resp_tools,
-                        api_key=self.api_key.get_secret_value()
-                        if self.api_key
-                        else None,
+                        api_key=api_key_value,
                         api_base=self.base_url,
                         api_version=self.api_version,
                         timeout=self.timeout,
@@ -708,10 +714,16 @@ def _transport_call(
                     "ignore",
                     category=UserWarning,
                 )
+                # Extract api_key value with type assertion for type checker
+                api_key_value: str | None = None
+                if self.api_key:
+                    assert isinstance(self.api_key, SecretStr)
+                    api_key_value = self.api_key.get_secret_value()
+
                 # Some providers need renames handled in _normalize_call_kwargs.
                 ret = litellm_completion(
                     model=self.model,
-                    api_key=self.api_key.get_secret_value() if self.api_key else None,
+                    api_key=api_key_value,
                     api_base=self.base_url,
                     api_version=self.api_version,
                     timeout=self.timeout,
@@ -755,7 +767,11 @@ def _init_model_info_and_caps(self) -> None:
                 base_url = "http://" + base_url
             try:
                 headers = {}
-                api_key = self.api_key.get_secret_value() if self.api_key else ""
+                # Extract api_key value with type assertion for type checker
+                api_key = ""
+                if self.api_key:
+                    assert isinstance(self.api_key, SecretStr)
+                    api_key = self.api_key.get_secret_value()
                 if api_key:
                     headers["Authorization"] = f"Bearer {api_key}"
 

openhands-sdk/openhands/sdk/utils/pydantic_secrets.py

@@ -28,11 +28,13 @@ def serialize_secret(v: SecretStr | None, info):
     return v
 
 
-def validate_secret(v: SecretStr | None, info):
+def validate_secret(v: str | SecretStr | None, info) -> SecretStr | None:
     """
     Deserialize secret fields, handling encryption and empty values.
 
+    Accepts both str and SecretStr inputs, always returns SecretStr | None.
     - Empty secrets are converted to None
+    - Plain strings are converted to SecretStr
     - If a cipher is provided in context, attempts to decrypt the value
     - If decryption fails, the cipher returns None and a warning is logged
     - This gracefully handles conversations encrypted with different keys or were redacted
@@ -55,4 +57,8 @@ def validate_secret(v: SecretStr | None, info):
         cipher: Cipher = info.context.get("cipher")
         return cipher.decrypt(secret_value)
 
-    return v
+    # Always return SecretStr
+    if isinstance(v, SecretStr):
+        return v
+    else:
+        return SecretStr(secret_value)

tests/cross/test_agent_reconciliation.py

@@ -50,9 +50,11 @@ def test_conversation_restart_with_nested_llms(tmp_path):
     # Verify the conversation was created successfully
     assert conversation1.id == conversation_id
     assert conversation1.agent.llm.api_key is not None
+    assert isinstance(conversation1.agent.llm.api_key, SecretStr)
     assert conversation1.agent.llm.api_key.get_secret_value() == "llm-api-key"
     assert isinstance(conversation1.agent.condenser, LLMSummarizingCondenser)
     assert conversation1.agent.condenser.llm.api_key is not None
+    assert isinstance(conversation1.agent.condenser.llm.api_key, SecretStr)
     assert conversation1.agent.condenser.llm.api_key.get_secret_value() == "llm-api-key"
 
     # Attempt to restart the conversation - this should work without errors
@@ -65,9 +67,11 @@ def test_conversation_restart_with_nested_llms(tmp_path):
     # Make sure the conversation gets initialized properly with no errors
     assert conversation2.id == conversation_id
     assert conversation2.agent.llm.api_key is not None
+    assert isinstance(conversation2.agent.llm.api_key, SecretStr)
     assert conversation2.agent.llm.api_key.get_secret_value() == "llm-api-key"
     assert isinstance(conversation2.agent.condenser, LLMSummarizingCondenser)
     assert conversation2.agent.condenser.llm.api_key is not None
+    assert isinstance(conversation2.agent.condenser.llm.api_key, SecretStr)
     assert conversation2.agent.condenser.llm.api_key.get_secret_value() == "llm-api-key"
 
     # Verify that the agent configuration is properly reconciled

tests/sdk/config/test_llm_config.py

@@ -84,9 +84,9 @@ def test_llm_config_custom_values():
     )
 
     assert config.model == "gpt-4"
-    assert (
-        config.api_key is not None and config.api_key.get_secret_value() == "test-key"
-    )
+    assert config.api_key is not None
+    assert isinstance(config.api_key, SecretStr)
+    assert config.api_key.get_secret_value() == "test-key"
     assert config.base_url == "https://api.example.com"
     assert config.api_version == "v1"
     assert config.num_retries == 3
@@ -122,9 +122,9 @@ def test_llm_config_custom_values():
 def test_llm_config_secret_str():
     """Test that api_key is properly handled as SecretStr."""
     config = LLM(model="gpt-4", api_key=SecretStr("secret-key"), usage_id="test-llm")
-    assert (
-        config.api_key is not None and config.api_key.get_secret_value() == "secret-key"
-    )
+    assert config.api_key is not None
+    assert isinstance(config.api_key, SecretStr)
+    assert config.api_key.get_secret_value() == "secret-key"
     # Ensure the secret is not exposed in string representation
     assert "secret-key" not in str(config)
 
@@ -138,14 +138,12 @@ def test_llm_config_aws_credentials():
         aws_secret_access_key=SecretStr("test-secret-key"),
         aws_region_name="us-east-1",
     )
-    assert (
-        config.aws_access_key_id is not None
-        and config.aws_access_key_id.get_secret_value() == "test-access-key"
-    )
-    assert (
-        config.aws_secret_access_key is not None
-        and config.aws_secret_access_key.get_secret_value() == "test-secret-key"
-    )
+    assert config.aws_access_key_id is not None
+    assert isinstance(config.aws_access_key_id, SecretStr)
+    assert config.aws_access_key_id.get_secret_value() == "test-access-key"
+    assert config.aws_secret_access_key is not None
+    assert isinstance(config.aws_secret_access_key, SecretStr)
+    assert config.aws_secret_access_key.get_secret_value() == "test-secret-key"
     assert config.aws_region_name == "us-east-1"
 
 

tests/sdk/conversation/local/test_state_serialization.py

@@ -540,6 +540,7 @@ def test_conversation_with_agent_different_llm_config():
         )
 
         assert new_conversation._state.agent.llm.api_key is not None
+        assert isinstance(new_conversation._state.agent.llm.api_key, SecretStr)
         assert new_conversation._state.agent.llm.api_key.get_secret_value() == "new-key"
         # Test that the core state structure is preserved (excluding agent differences)
         new_dump = new_conversation._state.model_dump(mode="json", exclude={"agent"})

tests/sdk/llm/test_api_key_validation.py

@@ -27,6 +27,7 @@ def test_valid_api_key_preserved():
     """Test that valid API keys are preserved."""
     llm = LLM(model="gpt-4", api_key=SecretStr("valid-key"), usage_id="test-llm")
     assert llm.api_key is not None
+    assert isinstance(llm.api_key, SecretStr)
     assert llm.api_key.get_secret_value() == "valid-key"
 
 
@@ -43,9 +44,9 @@ def test_none_api_key_preserved():
 def test_empty_string_direct_input():
     """Test that empty string passed directly (not as SecretStr) is converted to None."""  # noqa: E501
     # This tests the case where someone might pass a string directly
-    # Note: This would normally cause a validation error, but we handle it in field validator  # noqa: E501
+    # The field validator now accepts str and converts it to SecretStr
     data = {"model": "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", "api_key": ""}
-    llm = LLM(**data, usage_id="test-llm")  # type: ignore[arg-type]
+    llm = LLM(**data, usage_id="test-llm")  # pyright: ignore[reportArgumentType]
     assert llm.api_key is None
 
 
@@ -55,7 +56,7 @@ def test_whitespace_string_direct_input():
         "model": "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
         "api_key": "   \t\n  ",
     }
-    llm = LLM(**data, usage_id="test-llm")  # type: ignore[arg-type]
+    llm = LLM(**data, usage_id="test-llm")  # pyright: ignore[reportArgumentType]
     assert llm.api_key is None
 
 
@@ -75,6 +76,7 @@ def test_non_bedrock_model_with_valid_key():
     """Test that non-Bedrock models work normally with valid API keys."""
     llm = LLM(model="gpt-4", api_key=SecretStr("valid-openai-key"), usage_id="test-llm")
     assert llm.api_key is not None
+    assert isinstance(llm.api_key, SecretStr)
     assert llm.api_key.get_secret_value() == "valid-openai-key"
 
 
@@ -90,7 +92,37 @@ def test_aws_credentials_handling():
     )
     assert llm.api_key is None
     assert llm.aws_access_key_id is not None
+    assert isinstance(llm.aws_access_key_id, SecretStr)
     assert llm.aws_access_key_id.get_secret_value() == "test-access-key"
     assert llm.aws_secret_access_key is not None
+    assert isinstance(llm.aws_secret_access_key, SecretStr)
     assert llm.aws_secret_access_key.get_secret_value() == "test-secret-key"
     assert llm.aws_region_name == "us-west-2"
+
+
+def test_plain_string_api_key():
+    """Test that plain string API keys are converted to SecretStr."""
+    llm = LLM(model="gpt-4", api_key="my-plain-string-key", usage_id="test-llm")
+    assert llm.api_key is not None
+    assert isinstance(llm.api_key, SecretStr)
+    assert llm.api_key.get_secret_value() == "my-plain-string-key"
+
+
+def test_plain_string_aws_credentials():
+    """Test that plain string AWS credentials are converted to SecretStr."""
+    llm = LLM(
+        usage_id="test-llm",
+        model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
+        api_key=None,
+        aws_access_key_id="plain-access-key",
+        aws_secret_access_key="plain-secret-key",
+        aws_region_name="us-west-2",
+    )
+    assert llm.api_key is None
+    assert llm.aws_access_key_id is not None
+    assert isinstance(llm.aws_access_key_id, SecretStr)
+    assert llm.aws_access_key_id.get_secret_value() == "plain-access-key"
+    assert llm.aws_secret_access_key is not None
+    assert isinstance(llm.aws_secret_access_key, SecretStr)
+    assert llm.aws_secret_access_key.get_secret_value() == "plain-secret-key"
+    assert llm.aws_region_name == "us-west-2"

tests/sdk/llm/test_llm_json_storage.py

@@ -51,6 +51,12 @@ def test_llm_store_and_load_json():
         assert original_llm.api_key is not None
         assert original_llm.aws_access_key_id is not None
         assert original_llm.aws_secret_access_key is not None
+        assert isinstance(loaded_llm.api_key, SecretStr)
+        assert isinstance(original_llm.api_key, SecretStr)
+        assert isinstance(loaded_llm.aws_access_key_id, SecretStr)
+        assert isinstance(original_llm.aws_access_key_id, SecretStr)
+        assert isinstance(loaded_llm.aws_secret_access_key, SecretStr)
+        assert isinstance(original_llm.aws_secret_access_key, SecretStr)
         assert (
             loaded_llm.api_key.get_secret_value()
             == original_llm.api_key.get_secret_value()