Agent Settings

Configure, serialize, and recreate agents from structured settings.

A ready-to-run example is available here!

OpenHandsAgentSettings gives you a structured, serializable way to define an agent’s model, tools, and optional subsystems like the condenser. Use it when you want to store agent configuration in JSON, send it over an API, or rebuild agents from validated settings later.

Why Use Agent Settings

• Keep agent configuration as data instead of wiring everything together imperatively.
• Validate settings with Pydantic before creating an agent.
• Serialize and deserialize settings for storage, transport, or UI-driven configuration.
• Create different agent variants by changing only the settings payload.

Build Settings

Create an OpenHandsAgentSettings object with the same ingredients you would normally pass to an Agent.

from pydantic import SecretStr

from openhands.sdk import LLM, Tool
from openhands.sdk.settings import CondenserSettings, OpenHandsAgentSettings
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.terminal import TerminalTool

settings = OpenHandsAgentSettings(
    llm=LLM(
        model="anthropic/claude-sonnet-4-5-20250929",
        api_key=SecretStr("your-api-key"),
    ),
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
    ],
    condenser=CondenserSettings(enabled=True, max_size=50),
)

Serialize and Restore Settings

Because OpenHandsAgentSettings is a Pydantic model, you can dump it to JSON-compatible data and restore it later.

payload = settings.model_dump(mode="json")
restored = OpenHandsAgentSettings.model_validate(payload)

This is useful when:

• Saving agent configuration in a database
• Sending settings through an API
• Letting users edit agent configuration in a form-based UI
• Rehydrating the same agent setup in another process

Create an Agent from Settings

Once validated, create a working agent directly from the settings object.

agent = settings.create_agent()

You can then pass that agent into a Conversation, or derive another agent by changing the settings payload. For example, the full example below also shows how removing FileEditorTool and disabling the condenser produces a different agent configuration without rewriting the rest of the setup.

Ready-to-run Example

This example is available on GitHub: examples/01_standalone_sdk/46_agent_settings.py

examples/01_standalone_sdk/46_agent_settings.py

"""Create, serialize, and deserialize OpenHandsAgentSettings, then build an agent.

Demonstrates:
1. Configuring an agent entirely through OpenHandsAgentSettings (LLM, tools, condenser).
2. Serializing settings to JSON and restoring them.
3. Building an Agent from settings via ``create_agent()``.
4. Running a short conversation to prove the settings take effect.
5. Changing the tool list and showing the agent's capabilities change.
"""

import json
import os

from pydantic import SecretStr

from openhands.sdk import LLM, Conversation, OpenHandsAgentSettings, Tool
from openhands.sdk.settings import CondenserSettings
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.terminal import TerminalTool


# ── 1. Build settings ────────────────────────────────────────────────────
api_key = os.getenv("LLM_API_KEY")
assert api_key is not None, "LLM_API_KEY environment variable is not set."

settings = OpenHandsAgentSettings(
    llm=LLM(
        model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
        api_key=SecretStr(api_key),
        base_url=os.getenv("LLM_BASE_URL"),
    ),
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
    ],
    condenser=CondenserSettings(enabled=True, max_size=50),
)

# ── 2. Serialize → JSON → deserialize ────────────────────────────────────
payload = settings.model_dump(mode="json")
print("Serialized settings (JSON):")
print(json.dumps(payload, indent=2, default=str)[:800], "…")
print()

restored = OpenHandsAgentSettings.model_validate(payload)
assert restored.condenser.enabled is True
assert restored.condenser.max_size == 50
assert len(restored.tools) == 2
print("✓ Roundtrip deserialization successful — all fields preserved")
print()

# ── 3. Create agent from settings and run a task ─────────────────────────
agent = settings.create_agent()
print(f"Agent created: llm.model={agent.llm.model}")
print(f"  tools={[t.name for t in agent.tools]}")
print(f"  condenser={type(agent.condenser).__name__}")
print()

cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)
conversation.send_message(
    "Create a file called hello_settings.txt containing "
    "'Agent settings work!' then confirm the file exists with ls."
)
conversation.run()

# Verify the agent actually wrote the file
assert os.path.exists(os.path.join(cwd, "hello_settings.txt")), (
    "Agent should have created hello_settings.txt"
)
print("✓ Agent created hello_settings.txt — settings drove real behavior")
print()

# ── 4. Different settings → different behavior ───────────────────────────
# Now create settings with ONLY the terminal tool and condenser disabled.
terminal_only_settings = OpenHandsAgentSettings(
    llm=settings.llm,
    tools=[Tool(name=TerminalTool.name)],
    condenser=CondenserSettings(enabled=False),
)

terminal_agent = terminal_only_settings.create_agent()
print(f"Terminal-only agent tools: {[t.name for t in terminal_agent.tools]}")
assert len(terminal_agent.tools) == 1
assert terminal_agent.condenser is None  # condenser disabled in these settings
print("✓ Different settings produce different agent configuration")
print()

# ── Cleanup ──────────────────────────────────────────────────────────────
os.remove(os.path.join(cwd, "hello_settings.txt"))

# Report cost
cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost
print(f"\nEXAMPLE_COST: {cost}")

You can run the example code as-is.

The model name should follow the LiteLLM convention: 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.

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 for details.

Next Steps

• Getting Started - Start from a minimal agent and conversation setup
• Context Condenser - Control conversation compaction behavior
• TaskToolSet - Compose specialized sub-agents for larger tasks