[Feat]: add context msg to new conversation endpoint (OpenHands#8586)

Co-authored-by: openhands <[email protected]>
Co-authored-by: Engel Nyst <[email protected]>

Author: 3 people

docs/static/openapi.json

@@ -876,6 +876,11 @@
                     "type": "string",
                     "nullable": true
                   },
+                  "conversation_instructions": {
+                    "type": "string",
+                    "nullable": true,
+                    "description": "Optional instructions the agent must follow throughout the conversation while addressing the user's initial task"
+                  },
                   "image_urls": {
                     "type": "array",
                     "items": {

openhands/agenthub/codeact_agent/prompts/additional_info.j2

@@ -36,4 +36,9 @@ You are have access to the following environment variables
 Today's date is {{ runtime_info.date }} (UTC).
 {% endif %}
 </RUNTIME_INFORMATION>
+{% if conversation_instructions and conversation_instructions.content -%}
+<CONVERSATION_INSTRUCTIONS>
+{{ conversation_instructions.content }}
+</CONVERSATION_INSTRUCTIONS>
+{% endif %}
 {% endif %}

openhands/cli/main.py

@@ -105,6 +105,7 @@ async def run_session(
     settings_store: FileSettingsStore,
     current_dir: str,
     task_content: str | None = None,
+    conversation_instructions: str | None = None,
     session_name: str | None = None,
 ) -> bool:
     reload_microagents = False
@@ -248,6 +249,7 @@ def on_event(event: Event) -> None:
         sid=sid,
         selected_repository=config.sandbox.selected_repo,
         repo_directory=repo_directory,
+        conversation_instructions=conversation_instructions,
     )
 
     # Add MCP tools to the agent

openhands/core/main.py

@@ -55,6 +55,7 @@ async def run_controller(
     fake_user_response_fn: FakeUserResponseFunc | None = None,
     headless_mode: bool = True,
     memory: Memory | None = None,
+    conversation_instructions: str | None = None,
 ) -> State | None:
     """Main coroutine to run the agent controller with task input flexibility.
 
@@ -126,6 +127,7 @@ async def run_controller(
             sid=sid,
             selected_repository=config.sandbox.selected_repo,
             repo_directory=repo_directory,
+            conversation_instructions=conversation_instructions,
         )
 
     # Add MCP tools to the agent

openhands/core/setup.py

@@ -135,6 +135,7 @@ def create_memory(
     selected_repository: str | None = None,
     repo_directory: str | None = None,
     status_callback: Callable | None = None,
+    conversation_instructions: str | None = None,
 ) -> Memory:
     """Create a memory for the agent to use.
 
@@ -145,13 +146,16 @@ def create_memory(
         selected_repository: The repository to clone and start with, if any.
         repo_directory: The repository directory, if any.
         status_callback: Optional callback function to handle status updates.
+        conversation_instructions: Optional instructions that are passed to the agent
     """
     memory = Memory(
         event_stream=event_stream,
         sid=sid,
         status_callback=status_callback,
     )
 
+    memory.set_conversation_instructions(conversation_instructions)
+
     if runtime:
         # sets available hosts
         memory.set_runtime_info(runtime, {})

openhands/events/observation/agent.py

@@ -75,6 +75,7 @@ class RecallObservation(Observation):
     additional_agent_instructions: str = ''
     date: str = ''
     custom_secrets_descriptions: dict[str, str] = field(default_factory=dict)
+    conversation_instructions: str = ''
 
     # knowledge
     microagent_knowledge: list[MicroagentKnowledge] = field(default_factory=list)
@@ -117,6 +118,7 @@ def __str__(self) -> str:
                     f'additional_agent_instructions={self.additional_agent_instructions[:20]}...',
                     f'date={self.date}'
                     f'custom_secrets_descriptions={self.custom_secrets_descriptions}',
+                    f'conversation_instructions={self.conversation_instructions[0:20]}...'
                 ]
             )
         else:

openhands/memory/conversation_memory.py

@@ -41,7 +41,12 @@
 from openhands.events.observation.mcp import MCPObservation
 from openhands.events.observation.observation import Observation
 from openhands.events.serialization.event import truncate_content
-from openhands.utils.prompt import PromptManager, RepositoryInfo, RuntimeInfo
+from openhands.utils.prompt import (
+    ConversationInstructions,
+    PromptManager,
+    RepositoryInfo,
+    RuntimeInfo,
+)
 
 
 class ConversationMemory:
@@ -467,6 +472,13 @@ def _process_observation(
                         custom_secrets_descriptions=obs.custom_secrets_descriptions,
                     )
 
+                conversation_instructions = None
+
+                if obs.conversation_instructions:
+                    conversation_instructions = ConversationInstructions(
+                        content=obs.conversation_instructions
+                    )
+
                 repo_instructions = (
                     obs.repo_instructions if obs.repo_instructions else ''
                 )
@@ -476,10 +488,10 @@ def _process_observation(
                     repo_info.repo_name or repo_info.repo_directory
                 )
                 has_runtime_info = runtime_info is not None and (
-                    runtime_info.available_hosts
-                    or runtime_info.additional_agent_instructions
+                    runtime_info.date or runtime_info.custom_secrets_descriptions
                 )
                 has_repo_instructions = bool(repo_instructions.strip())
+                has_conversation_instructions = conversation_instructions is not None
 
                 # Filter and process microagent knowledge
                 filtered_agents = []
@@ -497,11 +509,17 @@ def _process_observation(
                 message_content = []
 
                 # Build the workspace context information
-                if has_repo_info or has_runtime_info or has_repo_instructions:
+                if (
+                    has_repo_info
+                    or has_runtime_info
+                    or has_repo_instructions
+                    or has_conversation_instructions
+                ):
                     formatted_workspace_text = (
                         self.prompt_manager.build_workspace_context(
                             repository_info=repo_info,
                             runtime_info=runtime_info,
+                            conversation_instructions=conversation_instructions,
                             repo_instructions=repo_instructions,
                         )
                     )

openhands/memory/memory.py

@@ -22,7 +22,11 @@
     load_microagents_from_dir,
 )
 from openhands.runtime.base import Runtime
-from openhands.utils.prompt import RepositoryInfo, RuntimeInfo
+from openhands.utils.prompt import (
+    ConversationInstructions,
+    RepositoryInfo,
+    RuntimeInfo,
+)
 
 GLOBAL_MICROAGENTS_DIR = os.path.join(
     os.path.dirname(os.path.dirname(openhands.__file__)),
@@ -65,6 +69,7 @@ def __init__(
         # Store repository / runtime info to send them to the templating later
         self.repository_info: RepositoryInfo | None = None
         self.runtime_info: RuntimeInfo | None = None
+        self.conversation_instructions: ConversationInstructions | None = None
 
         # Load global microagents (Knowledge + Repo)
         # from typically OpenHands/microagents (i.e., the PUBLIC microagents)
@@ -156,6 +161,7 @@ def _on_workspace_context_recall(
             or self.runtime_info
             or repo_instructions
             or microagent_knowledge
+            or self.conversation_instructions
         ):
             obs = RecallObservation(
                 recall_type=RecallType.WORKSPACE_CONTEXT,
@@ -180,6 +186,9 @@ def _on_workspace_context_recall(
                 custom_secrets_descriptions=self.runtime_info.custom_secrets_descriptions
                 if self.runtime_info is not None
                 else {},
+                conversation_instructions=self.conversation_instructions.content
+                if self.conversation_instructions is not None
+                else '',
             )
             return obs
         return None
@@ -290,7 +299,9 @@ def set_repository_info(self, repo_name: str, repo_directory: str) -> None:
             self.repository_info = None
 
     def set_runtime_info(
-        self, runtime: Runtime, custom_secrets_descriptions: dict[str, str]
+        self,
+        runtime: Runtime,
+        custom_secrets_descriptions: dict[str, str],
     ) -> None:
         """Store runtime info (web hosts, ports, etc.)."""
         # e.g. { '127.0.0.1': 8080 }
@@ -306,9 +317,21 @@ def set_runtime_info(
             )
         else:
             self.runtime_info = RuntimeInfo(
-                date=date, custom_secrets_descriptions=custom_secrets_descriptions
+                date=date,
+                custom_secrets_descriptions=custom_secrets_descriptions,
             )
 
+    def set_conversation_instructions(
+        self, conversation_instructions: str | None
+    ) -> None:
+        """
+        Set contextual information for conversation
+        This is information the agent may require
+        """
+        self.conversation_instructions = ConversationInstructions(
+            content=conversation_instructions or ''
+        )
+
     def send_error_message(self, message_id: str, message: str):
         """Sends an error message if the callback function was provided."""
         if self.status_callback:

openhands/server/routes/manage_conversations.py

@@ -61,6 +61,7 @@ class InitSessionRequest(BaseModel):
     image_urls: list[str] | None = None
     replay_json: str | None = None
     suggested_task: SuggestedTask | None = None
+    conversation_instructions: str | None = None
 
     model_config = {'extra': 'forbid'}
 
@@ -82,6 +83,7 @@ async def _create_new_conversation(
     initial_user_msg: str | None,
     image_urls: list[str] | None,
     replay_json: str | None,
+    conversation_instructions: str | None = None,
     conversation_trigger: ConversationTrigger = ConversationTrigger.GUI,
     attach_convo_id: bool = False,
 ) -> AgentLoopInfo:
@@ -120,6 +122,7 @@ async def _create_new_conversation(
     session_init_args['selected_repository'] = selected_repository
     session_init_args['custom_secrets'] = custom_secrets
     session_init_args['selected_branch'] = selected_branch
+    session_init_args['conversation_instructions'] = conversation_instructions
     conversation_init_data = ConversationInitData(**session_init_args)
     logger.info('Loading conversation store')
     conversation_store = await ConversationStoreImpl.get_instance(config, user_id)
@@ -195,6 +198,7 @@ async def new_conversation(
     replay_json = data.replay_json
     suggested_task = data.suggested_task
     git_provider = data.git_provider
+    conversation_instructions = data.conversation_instructions
 
     conversation_trigger = ConversationTrigger.GUI
 
@@ -222,6 +226,7 @@ async def new_conversation(
             image_urls=image_urls,
             replay_json=replay_json,
             conversation_trigger=conversation_trigger,
+            conversation_instructions=conversation_instructions
         )
 
         return InitSessionResponse(

openhands/server/session/agent_session.py

@@ -90,6 +90,7 @@ async def start(
         selected_repository: str | None = None,
         selected_branch: str | None = None,
         initial_message: MessageAction | None = None,
+        conversation_instructions: str | None = None,
         replay_json: str | None = None,
     ) -> None:
         """Starts the Agent session
@@ -144,6 +145,7 @@ async def start(
             self.memory = await self._create_memory(
                 selected_repository=selected_repository,
                 repo_directory=repo_directory,
+                conversation_instructions=conversation_instructions,
                 custom_secrets_descriptions=custom_secrets_handler.get_custom_secrets_descriptions()
             )
 
@@ -415,7 +417,11 @@ def _create_controller(
         return controller
 
     async def _create_memory(
-        self, selected_repository: str | None, repo_directory: str | None, custom_secrets_descriptions: dict[str, str]
+        self, 
+        selected_repository: str | None, 
+        repo_directory: str | None, 
+        conversation_instructions: str | None,
+        custom_secrets_descriptions: dict[str, str]
     ) -> Memory:
         memory = Memory(
             event_stream=self.event_stream,
@@ -426,6 +432,7 @@ async def _create_memory(
         if self.runtime:
             # sets available hosts and other runtime info
             memory.set_runtime_info(self.runtime, custom_secrets_descriptions)
+            memory.set_conversation_instructions(conversation_instructions)
 
             # loads microagents from repo/.openhands/microagents
             microagents: list[BaseMicroagent] = await call_sync_from_async(
@@ -435,7 +442,10 @@ async def _create_memory(
             memory.load_user_workspace_microagents(microagents)
 
             if selected_repository and repo_directory:
-                memory.set_repository_info(selected_repository, repo_directory)
+                memory.set_repository_info(
+                    selected_repository, 
+                    repo_directory
+                )
         return memory
 
     def _maybe_restore_state(self) -> State | None: