Agent Server: Persist settings to disk and expose CRUD endpoints

[xingyaoww]

Summary

The SDK already has well-structured settings models (OpenHandsAgentSettings, ACPAgentSettings, ConversationSettings) with schema versioning, migration support (from_persisted()), and form-schema export (export_schema()). However, the agent-server never actually persists or loads these settings. The settings_router.py only serves schema metadata (GET /settings/agent-schema, GET /settings/conversation-schema) — it tells the frontend what fields exist but never reads or writes actual values.

This means:

• There is no settings file on disk
• The frontend cannot save or retrieve user preferences
• Every StartConversationRequest must provide the full Agent configuration inline — there are no "use my saved settings" defaults

What's Needed

1. A settings file path in the agent-server Config

Add a configurable settings_path: Path (defaulting to e.g. workspace/settings/ or ~/.openhands/settings/) to the agent-server Config model so the server knows where to read/write settings files.

2. GET /settings/agent — Load persisted agent settings

Return the currently persisted AgentSettings values from disk. If no file exists, return the defaults from default_agent_settings(). Use AgentSettings.from_persisted(data) to handle any schema migrations on load.

3. PUT /settings/agent — Save agent settings to disk

Accept an AgentSettingsConfig payload (the discriminated union of OpenHandsAgentSettings | ACPAgentSettings), validate it via validate_agent_settings(), and persist it to disk using model_dump() with the current schema_version.

4. GET /settings/conversation — Load persisted conversation settings

Return the currently persisted ConversationSettings values from disk. If no file exists, return defaults. Use ConversationSettings.from_persisted(data) for migration support.

5. PUT /settings/conversation — Save conversation settings to disk

Accept a ConversationSettings payload, validate, and persist to disk.

6. Default settings injection into conversation creation

When StartConversationRequest is received without an explicit agent (or with partial config), the agent-server should load the persisted settings and use ConversationSettings.create_request() to fill in defaults. This closes the loop: settings saved via the UI automatically apply to new conversations.

Context

The SDK plumbing is ready:

• ConversationSettings has schema_version, from_persisted(), create_request(), and model_dump()
• AgentSettings (discriminated union) has from_persisted(), schema_version, migrations via _apply_persisted_migrations
• OpenHandsAgentSettings.create_agent() and ACPAgentSettings.create_agent() build fully configured agent objects from settings
• The migration framework (_AGENT_SETTINGS_MIGRATIONS, _CONVERSATION_SETTINGS_MIGRATIONS) supports forward-compatible schema evolution

This is a key requirement for the agent-server: "Settings are persisted to disk".

[neubig]

I checked this against #3026 and the Q2 transition plan. To avoid duplicate tracking, I think this issue should remain the canonical SDK issue for the core settings-persistence work rather than opening another SDK PR1 issue.

Suggested scope split after #3026:

• feat(agent-server): Add file-based settings and secrets persistence #3026 substantially covers the disk-backed settings/secrets persistence portion here, but should still be checked for: first-class config path, migration via from_persisted(), route compatibility, and safe secret-redaction semantics.
• The main remaining part of this issue is item 6: conversation creation should be able to use persisted settings server-side, so clients do not need to fetch/redeliver a full runnable Agent payload or raw LLM credentials.

Concrete acceptance criteria for the remaining conversation-creation work:

1. A client can start a conversation without sending an explicit agent object, by opting into stored settings or using a new settings-backed request model.
2. The server loads persisted AgentSettingsConfig and ConversationSettings, applies request-level overrides, and constructs the StartConversationRequest server-side.
3. The request can still provide runtime-only values such as workspace, initial message, plugins, hooks, tool module qualnames, and agent definitions.
4. Persisted secrets are resolved server-side; frontend/browser clients never need GET /api/settings?expose_secrets=true to start a normal conversation.
5. Existing full-agent POST /api/conversations payloads remain backward compatible.
6. Tests cover default settings, persisted settings, per-request overrides, secret redaction, ACP settings, and legacy full-agent payload compatibility.

This comment was created by an AI agent (OpenHands) on behalf of the user.

[malhotra5]

RE: Default settings injection into conversation creation

I think we should avoid this. Primarily because when inspecting the API docs for this endpoint, it's ambiguous when the agent field is optional. The start request should be authoritative specification for the conversation, with no hidden side effects from server-side state.

RE: Put API endpoints

PATCH seems better to allow for partial updates (or full updates depending on the diff)

RE: separate routes for conversation and agent settings

In PR #3026, we combine these routes into one. The reason is because then we have exactly one file which manages persistence. As new setting types are made available, we can continue to add them as part of the route specification while keeping the number of files for persistence the same.

[malhotra5]

RE: Default settings injection into conversation creation

Actually we maybe opt for this because the a simple FE client will need to receive plain text secrets and forward it in the start conversation request (which is insecure). Alternatively, the FE can request encrypted plain text secrets and forward it via start conversation request, but either way the API contract will require some modification

[malhotra5]

Resolved via #3060