> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-extend-api-reference-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LLM Profile Store

> Save, load, and manage reusable LLM configurations so you never repeat setup code again.

export const path_to_script_1 = "examples/01_standalone_sdk/44_model_switching_in_convo.py"

export const path_to_script_0 = "examples/01_standalone_sdk/37_llm_profile_store.py"

> A ready-to-run example is available [here](#ready-to-run-example)!

The `LLMProfileStore` class provides a centralized mechanism for managing `LLM` configurations.
Define a profile once, reuse it everywhere — across scripts, sessions, and even machines.

## Benefits

* **Persistence:** Saves model parameters (API keys, temperature, max tokens, ...) to a stable disk format.
* **Reusability:** Import a defined profile into any script or session with a single identifier.
* **Portability:** Simplifies the synchronization of model configurations across different machines or deployment environments.

## How It Works

<Steps>
  <Step>
    ### Create a Store

    The store manages a directory of JSON profile files. By default it uses `~/.openhands/profiles`,
    but you can point it anywhere.

    ```python icon="python" focus={3, 4, 6, 7} theme={null}
    from openhands.sdk import LLMProfileStore

    # Default location: ~/.openhands/profiles
    store = LLMProfileStore()

    # Or bring your own directory
    store = LLMProfileStore(base_dir="./my-profiles")
    ```
  </Step>

  <Step>
    ### Save a Profile

    Got an LLM configured just right? Save it for later.

    ```python icon="python" focus={11, 12} theme={null}
    from pydantic import SecretStr
    from openhands.sdk import LLM, LLMProfileStore

    fast_llm = LLM(
        usage_id="fast",
        model="anthropic/claude-sonnet-4-5-20250929",
        api_key=SecretStr("sk-..."),
        temperature=0.0,
    )

    store = LLMProfileStore()
    store.save("fast", fast_llm)
    ```

    <Info>
      API keys are **excluded** by default for security. Pass `include_secrets=True` to the save method if you wish to
      persist them; otherwise, they will be read from the environment at load time.
    </Info>
  </Step>

  <Step>
    ### Load a Profile

    Next time you need that LLM, just load it:

    ```python icon="python" theme={null}
    # Same model, ready to go.
    llm = store.load("fast")
    ```
  </Step>

  <Step>
    ### List and Clean Up

    See what you've got, delete what you don't need:

    ```python icon="python" focus={1, 3, 4} theme={null}
    print(store.list())   # ['fast.json', 'creative.json']

    store.delete("creative")
    print(store.list())   # ['fast.json']
    ```
  </Step>
</Steps>

## Good to Know

Profile names must be simple filenames (no slashes, no dots at the start).

## Ready-to-run Example

<Note>
  This example is available on GitHub: [examples/01\_standalone\_sdk/37\_llm\_profile\_store.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/37_llm_profile_store.py)
</Note>

```python icon="python" expandable examples/01_standalone_sdk/37_llm_profile_store.py theme={null}
"""Example: Using LLMProfileStore to save and reuse LLM configurations.

LLMProfileStore persists LLM configurations as JSON files, so you can define
a profile once and reload it across sessions without repeating setup code.
"""

import os
import tempfile

from pydantic import SecretStr

from openhands.sdk import LLM, LLMProfileStore


# Use a temporary directory so this example doesn't pollute your home folder.
# In real usage you can omit base_dir to use the default (~/.openhands/profiles).
store = LLMProfileStore(base_dir=tempfile.mkdtemp())


# 1. Create two LLM profiles with different usage

api_key = os.getenv("LLM_API_KEY")
assert api_key is not None, "LLM_API_KEY environment variable is not set."
base_url = os.getenv("LLM_BASE_URL")
model = os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929")

fast_llm = LLM(
    usage_id="fast",
    model=model,
    api_key=SecretStr(api_key),
    base_url=base_url,
    temperature=0.0,
)

creative_llm = LLM(
    usage_id="creative",
    model=model,
    api_key=SecretStr(api_key),
    base_url=base_url,
    temperature=0.9,
)

# 2. Save profiles

# Note that secrets are excluded by default for safety.
store.save("fast", fast_llm)
store.save("creative", creative_llm)

# To persist the API key as well, pass `include_secrets=True`:
# store.save("fast", fast_llm, include_secrets=True)

# 3. List available persisted profiles

print(f"Stored profiles: {store.list()}")

# 4. Load a profile

loaded = store.load("fast")
assert isinstance(loaded, LLM)
print(
    "Loaded profile. "
    f"usage:{loaded.usage_id}, "
    f"model: {loaded.model}, "
    f"temperature: {loaded.temperature}."
)

# 5. Delete a profile

store.delete("creative")
print(f"After deletion: {store.list()}")

print("EXAMPLE_COST: 0")
```

You can run the example code as-is.

<Note>
  The model name should follow the [LiteLLM convention](https://models.litellm.ai/): `provider/model_name` (e.g., `anthropic/claude-sonnet-4-5-20250929`, `openai/gpt-4o`).
  The `LLM_API_KEY` should be the API key for your chosen provider.
</Note>

<CodeGroup>
  <CodeBlock language="bash" filename="Bring-your-own provider key" icon="terminal" wrap>
    {`export LLM_API_KEY="your-api-key"\nexport LLM_MODEL="anthropic/claude-sonnet-4-5-20250929"  # or openai/gpt-4o, etc.\ncd software-agent-sdk\nuv run python ${path_to_script_0}`}
  </CodeBlock>

  <CodeBlock language="bash" filename="OpenHands Cloud" icon="terminal" wrap>
    {`# https://app.all-hands.dev/settings/api-keys\nexport LLM_API_KEY="your-openhands-api-key"\nexport LLM_MODEL="openhands/claude-sonnet-4-5-20250929"\ncd software-agent-sdk\nuv run python ${path_to_script_0}`}
  </CodeBlock>
</CodeGroup>

<Tip>
  **ChatGPT Plus/Pro subscribers**: You can use `LLM.subscription_login()` to authenticate with your ChatGPT account and access Codex models without consuming API credits. See the [LLM Subscriptions guide](/sdk/guides/llm-subscriptions) for details.
</Tip>

## Mid-Conversation Model Switching

You can use a saved profile to switch the active model on a running conversation between turns. This is useful when you want to start with one model, then switch to another for later user messages while keeping the same conversation history and combined usage metrics.

<Note>
  This example is available on GitHub: [examples/01\_standalone\_sdk/44\_model\_switching\_in\_convo.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/44_model_switching_in_convo.py)
</Note>

```python icon="python" expandable examples/01_standalone_sdk/44_model_switching_in_convo.py theme={null}
"""Mid-conversation model switching.

Usage:
    uv run examples/01_standalone_sdk/44_model_switching_in_convo.py
"""

import os

from openhands.sdk import LLM, Agent, LocalConversation, Tool
from openhands.sdk.llm.llm_profile_store import LLMProfileStore
from openhands.tools.terminal import TerminalTool


LLM_API_KEY = os.getenv("LLM_API_KEY")
store = LLMProfileStore()

store.save(
    "gpt",
    LLM(model="openhands/gpt-5.2", api_key=LLM_API_KEY),
    include_secrets=True,
)

agent = Agent(
    llm=LLM(
        model=os.getenv("LLM_MODEL", "openhands/claude-sonnet-4-5-20250929"),
        api_key=LLM_API_KEY,
    ),
    tools=[Tool(name=TerminalTool.name)],
)
conversation = LocalConversation(agent=agent, workspace=os.getcwd())

# Send a message with the default model
conversation.send_message("Say hello in one sentence.")
conversation.run()

# Switch to a different model and send another message
conversation.switch_profile("gpt")
print(f"Switched to: {conversation.agent.llm.model}")

conversation.send_message("Say goodbye in one sentence.")
conversation.run()

# Print metrics per model
for usage_id, metrics in conversation.state.stats.usage_to_metrics.items():
    print(f"  [{usage_id}] cost=${metrics.accumulated_cost:.6f}")

combined = conversation.state.stats.get_combined_metrics()
print(f"Total cost: ${combined.accumulated_cost:.6f}")
print(f"EXAMPLE_COST: {combined.accumulated_cost}")

store.delete("gpt")
```

You can run the example code as-is.

<Note>
  The model name should follow the [LiteLLM convention](https://models.litellm.ai/): `provider/model_name` (e.g., `anthropic/claude-sonnet-4-5-20250929`, `openai/gpt-4o`).
  The `LLM_API_KEY` should be the API key for your chosen provider.
</Note>

<CodeGroup>
  <CodeBlock language="bash" filename="Bring-your-own provider key" icon="terminal" wrap>
    {`export LLM_API_KEY="your-api-key"\nexport LLM_MODEL="anthropic/claude-sonnet-4-5-20250929"  # or openai/gpt-4o, etc.\ncd software-agent-sdk\nuv run python ${path_to_script_1}`}
  </CodeBlock>

  <CodeBlock language="bash" filename="OpenHands Cloud" icon="terminal" wrap>
    {`# https://app.all-hands.dev/settings/api-keys\nexport LLM_API_KEY="your-openhands-api-key"\nexport LLM_MODEL="openhands/claude-sonnet-4-5-20250929"\ncd software-agent-sdk\nuv run python ${path_to_script_1}`}
  </CodeBlock>
</CodeGroup>

<Tip>
  **ChatGPT Plus/Pro subscribers**: You can use `LLM.subscription_login()` to authenticate with your ChatGPT account and access Codex models without consuming API credits. See the [LLM Subscriptions guide](/sdk/guides/llm-subscriptions) for details.
</Tip>

## Next Steps

* **[LLM Registry](/sdk/guides/llm-registry)** - Manage multiple LLMs in memory at runtime
* **[LLM Routing](/sdk/guides/llm-routing)** - Automatically route to different models
* **[Exception Handling](/sdk/guides/llm-error-handling)** - Handle LLM errors gracefully


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.