#17498·OpenHands

[Feature]: Expose AgentProfile system_message_suffix in Agent settings

Author: fattanehtCreated Sep 17, 2026Updated Sep 17, 2026
Labelsenhancementready-for-dev

Problem or Motivation

Agent Canvas currently does not provide a user-facing way to define persistent custom system-level instructions for an OpenHands agent.

Users may want to configure behavior such as:

  • Always respond in a specific language.
  • Apply stable behavioral instructions across conversations created with a particular Agent Profile.

The backend and Agent Profile model already support this concept through the optional system_message_suffix field. The current frontend, however, does not expose this field in the Agent Profile create/edit UI.

A similar request was previously raised in:

That issue was closed after the introduction of custom microagents in:

However, project microagents/skills are not equivalent to this request. They are file-based, project-scoped extension mechanisms with their own loading and activation semantics. This request is specifically for explicit, persistent, per-Agent-Profile system instructions using the existing system_message_suffix field.

Desired Behavior

In Settings → Agents → Create/Edit Agent, OpenHands Agent Profiles should provide a multiline field such as:

Custom system instructions

The field should:

  • Read and display the profile's existing system_message_suffix.
  • Save the entered text as the profile's system_message_suffix.
  • Use null or an omitted value when the field is empty.
  • Apply the instructions to new conversations started with that Agent Profile.
  • Keep the built-in OpenHands system prompt intact and append the custom instructions as a suffix.
  • Make it clear that changes affect new conversations and do not rewrite the system prompt of already-running conversations.
  • Be available only for Agent Profile types whose backend model supports system_message_suffix.

Example value:

Always respond in English.
Ask for confirmation before making architectural changes.
Use the project's existing design system for UI changes.

Acceptance Criteria

  • The OpenHands Agent Profile create/edit screen provides a multiline Custom instructions field.
  • The field reads from and persists to the existing Agent Profile system_message_suffix.
  • Creating a profile with custom instructions saves them successfully.
  • Editing a profile displays its previously saved custom instructions.
  • Instructions apply to new conversations started with the selected Agent Profile.
  • Existing conversations remain unchanged.
  • Custom instructions are appended to the built-in OpenHands system prompt and do not replace it.
  • Profile instructions compose with AGENTS.md, project skills, and system-generated context without disabling or overwriting them.
  • The same Agent Profile instructions can be applied across different repositories and workspaces.
  • Different Agent Profiles can define different instructions for the same repository.
  • Profiles without custom instructions behave exactly as they do today.
  • Editing unrelated profile settings does not remove or modify the saved suffix.
  • Switching to an agent type that does not support system_message_suffix does not carry over an incompatible value.
  • The field includes localized label, description, placeholder, and validation messages.
  • An appropriate maximum length is enforced consistently with the backend contract.
  • Tests cover creating, loading, updating, clearing, preserving, and applying custom instructions.

Alternatives Considered

No response

Additional Context

A similar request was previously raised in #4924 and closed after custom microagents were introduced in #4983. However, repository instructions, skills, and microagents are project-scoped mechanisms. This request concerns persistent instructions owned by an Agent Profile, which can apply across repositories without modifying or committing workspace files.

The existing architecture already supports the optional system_message_suffix field on OpenHands Agent Profiles. Agent Canvas preserves this field when editing an existing profile, but the current profile editor does not expose it for viewing or modification. Therefore, this appears to be primarily a frontend gap rather than a request for a new prompt mechanism.

This feature should expose the existing suffix capability. It should not expose or replace the complete built-in OpenHands system prompt.