Skip to main content
Configure openhands.sdk.llm.LLM instances with the parameters described in this section. These fields apply identically whether you launch agents through your own code or via the OpenHands interfaces built on the SDK.

​
Environment variable layout

The SDK expects environment variables prefixed with LLM_. They are lowercased and mapped onto field names when you call LLM.load_from_env(). 
export LLM_MODEL="anthropic/claude-sonnet-4.1"
export LLM_API_KEY="sk-ant-123"
export LLM_SERVICE_ID="primary"
export LLM_TIMEOUT="120"
export LLM_NUM_RETRIES="5"
Then, in Python: 
from openhands.sdk import LLM

llm = LLM.load_from_env()
The loader automatically casts values into integers, floats, booleans, JSON, or SecretStr where appropriate.

​
JSON configuration

For declarative deployments you can persist the SDK model schema to JSON: 
from pydantic import SecretStr

llm = LLM(
    model="openai/gpt-4o",
    api_key=SecretStr("sk-openai"),
    temperature=0.1,
)
with open("config/llm.json", "w") as fp:
    fp.write(llm.model_dump_json(exclude_none=True, indent=2))

reloaded = LLM.load_from_json("config/llm.json")
Serialized structures redact secrets (API keys, AWS credentials). Combine the JSON file with environment variables for secrets when your runtime requires human review of committed configuration.

​
Commonly tuned parameters

  • Latency & retry controls: timeout, num_retries, retry_min_wait, retry_max_wait, and retry_multiplier govern the SDK’s LLM retry behavior across providers.
  • Prompt shaping: temperature, top_p, top_k, reasoning_effort, and extended_thinking_budget adjust sampling characteristics and Anthropic reasoning budgets.
  • Cost reporting: input_cost_per_token and output_cost_per_token flow into SDK telemetry so downstream interfaces can display usage estimates.
Refer to the docstring within openhands.sdk.llm.LLM for the full schema. All fields can be set programmatically or via environment variables using the naming rule field -> LLM_FIELD.
⌘I