Building AI agents, atomically
fix: prevent silent drop of mid-conversation system messages on Gemini (#221)
KennyVaneetvelde3c6f43e7ed3e
diff --git a/atomic-agents/atomic_agents/agents/atomic_agent.py b/atomic-agents/atomic_agents/agents/atomic_agent.pyindex 3147d3f..101b1f0 100644--- a/atomic-agents/atomic_agents/agents/atomic_agent.py+++ b/atomic-agents/atomic_agents/agents/atomic_agent.py@@ -76,6 +76,14 @@ class AgentConfig(BaseModel):default="assistant",description="The role of the assistant in the conversation. Use 'model' for Gemini, 'assistant' for OpenAI/Anthropic.",)+ tool_result_role: Optional[str] = Field(+ default=None,+ description=(+ "The role to use for mid-conversation tool results and context injections. "+ "Defaults to 'user' when assistant_role is 'model' (Gemini), otherwise 'system'. "+ "Set explicitly to override auto-detection."+ ),+ )model_config = {"arbitrary_types_allowed": True}mode: Mode = Field(default=Mode.TOOLS, description="The Instructor mode used for structured outputs (TOOLS, JSON, etc.).")model_api_parameters: Optional[dict] = Field(None, description="Additional parameters passed to the API provider.")@@ -170,6 +178,12 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:self.system_prompt_generator = config.system_prompt_generator or SystemPromptGenerator()self.system_role = config.system_roleself.assistant_role = config.assistant_role+ if config.tool_result_role is not None:+ self.tool_result_role = config.tool_result_role+ else:+ # Auto-detect: Gemini drops mid-conversation "system" messages,+ # so default to "user" for Gemini backends (identified by assistant_role="model")+ self.tool_result_role = "user" if config.assistant_role == "model" else "system"self.initial_history = self.history.copy()self.current_user_input = Noneself.mode = config.mode@@ -185,6 +199,21 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:"""self.history = self.initial_history.copy()+ def add_tool_result(self, content: BaseIOSchema) -> None:+ """+ Adds a tool result or context injection to the chat history using the+ backend-appropriate role.++ This method should be used instead of ``history.add_message("system", ...)``+ when injecting tool execution results, resource contents, or other mid-conversation+ context into the agent's history. It automatically uses the correct role for the+ configured backend (e.g. ``"user"`` for Gemini, ``"system"`` for OpenAI/Anthropic).++ Args:+ content (BaseIOSchema): The tool result or context to inject.+ """+ self.history.add_message(self.tool_result_role, content)+@propertydef input_schema(self) -> Type[BaseIOSchema]:"""@@ -247,7 +276,21 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:def _prepare_messages(self):self.messages = self._build_system_messages()- self.messages += self.history.get_history()+ history = self.history.get_history()+ # Remap "system" role messages in history when the backend doesn't support+ # mid-conversation system messages (e.g. Gemini). The initial system prompt+ # is built separately via _build_system_messages() and is unaffected.+ if self.tool_result_role != "system":+ logger = logging.getLogger(__name__)+ for msg in history:+ if msg["role"] == "system":+ logger.debug(+ "Remapping mid-conversation 'system' message to '%s' "+ "(backend does not support mid-conversation system messages).",+ self.tool_result_role,+ )+ msg["role"] = self.tool_result_role+ self.messages += historydef _get_completion_kwargs(self) -> Dict[str, Any]:"""diff --git a/atomic-agents/tests/agents/test_atomic_agent.py b/atomic-agents/tests/agents/test_atomic_agent.pyindex 0cf5cf6..7260e48 100644--- a/atomic-agents/tests/agents/test_atomic_agent.py+++ b/atomic-agents/tests/agents/test_atomic_agent.py@@ -1087,3 +1087,115 @@ def test_get_context_token_count_multimodal_content(mock_get_token_counter, mockimage_entry = next(item for item in content if item.get("type") == "image_url")assert "image_url" in image_entryassert image_entry["image_url"]["url"] == "https://example.com/test.png"+++# --- Tests for tool_result_role and Gemini system message remapping (issue #221) ---+++def test_tool_result_role_defaults_to_system_for_openai(mock_instructor, mock_system_prompt_generator):+ config = AgentConfig(+ client=mock_instructor,+ model="gpt-5-mini",+ system_prompt_generator=mock_system_prompt_generator,+ assistant_role="assistant",+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)+ assert agent.tool_result_role == "system"+++def test_tool_result_role_defaults_to_user_for_gemini(mock_instructor, mock_system_prompt_generator):+ config = AgentConfig(+ client=mock_instructor,+ model="gemini-2.0-flash",+ system_prompt_generator=mock_system_prompt_generator,+ assistant_role="model",+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)+ assert agent.tool_result_role == "user"+++def test_tool_result_role_explicit_override(mock_instructor, mock_system_prompt_generator):+ config = AgentConfig(+ client=mock_instructor,+ model="gemini-2.0-flash",+ system_prompt_generator=mock_system_prompt_generator,+ assistant_role="model",+ tool_result_role="system",+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)+ assert agent.tool_result_role == "system"+++def test_add_tool_result_uses_correct_role(mock_instructor, mock_system_prompt_generator):+ history = ChatHistory()+ config = AgentConfig(+ client=mock_instructor,+ model="gemini-2.0-flash",+ system_prompt_generator=mock_system_prompt_generator,+ assistant_role="model",+ history=history,+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)+ content = BasicChatInputSchema(chat_message="Tool result data")+ agent.add_tool_result(content)++ messages = history.get_history()+ assert len(messages) == 1+ assert messages[0]["role"] == "user"+++def test_add_tool_result_uses_system_for_openai(mock_instructor, mock_system_prompt_generator):+ history = ChatHistory()+ config = AgentConfig(+ client=mock_instructor,+ model="gpt-5-mini",+ system_prompt_generator=mock_system_prompt_generator,+ history=history,+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)+ content = BasicChatInputSchema(chat_message="Tool result data")+ agent.add_tool_result(content)++ messages = history.get_history()+ assert len(messages) == 1+ assert messages[0]["role"] == "system"+++def test_prepare_messages_remaps_system_to_user_for_gemini(mock_instructor, mock_system_prompt_generator):+ history = ChatHistory()+ config = AgentConfig(+ client=mock_instructor,+ model="gemini-2.0-flash",+ system_prompt_generator=mock_system_prompt_generator,+ assistant_role="model",+ history=history,+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)++ # Simulate legacy pattern: add_message("system", ...) directly on history+ history.add_message("system", BasicChatInputSchema(chat_message="Tool output"))+ agent._prepare_messages()++ # The system prompt message (first) should keep its role,+ # but mid-conversation "system" messages in history should be remapped to "user"+ history_messages = [m for m in agent.messages if m.get("content") != mock_system_prompt_generator.generate_prompt()]+ assert len(history_messages) == 1+ assert history_messages[0]["role"] == "user"+++def test_prepare_messages_keeps_system_for_openai(mock_instructor, mock_system_prompt_generator):+ history = ChatHistory()+ config = AgentConfig(+ client=mock_instructor,+ model="gpt-5-mini",+ system_prompt_generator=mock_system_prompt_generator,+ history=history,+ )+ agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](config)++ history.add_message("system", BasicChatInputSchema(chat_message="Tool output"))+ agent._prepare_messages()++ history_messages = [m for m in agent.messages if m.get("content") != mock_system_prompt_generator.generate_prompt()]+ assert len(history_messages) == 1+ assert history_messages[0]["role"] == "system"diff --git a/atomic-examples/mcp-agent/example-client/example_client/main_http.py b/atomic-examples/mcp-agent/example-client/example_client/main_http.pyindex 66e7f2a..b676bd7 100644--- a/atomic-examples/mcp-agent/example-client/example_client/main_http.py+++ b/atomic-examples/mcp-agent/example-client/example_client/main_http.py@@ -210,7 +210,7 @@ def main():result_message = MCPOrchestratorInputSchema(query=(f"Tool {tool_name} executed with result: " f"{tool_output.result}"))- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)ResourceClass = resource_schema_to_class_map.get(schema_type)if ResourceClass:@@ -227,7 +227,7 @@ def main():result_message = MCPOrchestratorInputSchema(query=(f"Resource {resource_name} read with content: {resource_output.content}"))- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)PromptClass = prompt_schema_to_class_map.get(schema_type)if PromptClass:@@ -244,7 +244,7 @@ def main():result_message = MCPOrchestratorInputSchema(query=(f"Prompt {prompt_name} generated content: {prompt_output.content}"))- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)if not schema_type_valid:console.print(f"[red]Error: Unknown schema type {schema_type.__name__}[/red]")diff --git a/atomic-examples/mcp-agent/example-client/example_client/main_sse.py b/atomic-examples/mcp-agent/example-client/example_client/main_sse.pyindex 8789b3e..630848a 100644--- a/atomic-examples/mcp-agent/example-client/example_client/main_sse.py+++ b/atomic-examples/mcp-agent/example-client/example_client/main_sse.py@@ -424,7 +424,7 @@ def main():result_message = MCPOrchestratorInputSchema(query=f"Tool {tool_name} executed with result: {tool_output.result}")- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)ResourceClass = resource_schema_to_class_map.get(schema_type)if ResourceClass:@@ -441,7 +441,7 @@ def main():result_message = MCPOrchestratorInputSchema(query=f"Resource {resource_name} used to fetch content: {resource_output.content}")- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)PromptClass = prompt_schema_to_class_map.get(schema_type)if PromptClass:@@ -458,7 +458,7 @@ def main():result_message = MCPOrchestratorInputSchema(query=f"Prompt {prompt_name} created: {prompt_output.content}")- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)if not schema_type_valid:console.print(f"[red]Unknown schema type '{schema_type.__name__}' returned by orchestrator[/red]")diff --git a/atomic-examples/mcp-agent/example-client/example_client/main_stdio.py b/atomic-examples/mcp-agent/example-client/example_client/main_stdio.pyindex e2dfc12..5e78fa1 100644--- a/atomic-examples/mcp-agent/example-client/example_client/main_stdio.py+++ b/atomic-examples/mcp-agent/example-client/example_client/main_stdio.py@@ -249,7 +249,7 @@ def main():result_message = MCPOrchestratorInputSchema(query=(f"Tool {tool_name} executed with result: " f"{tool_output.result}"))- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)ResourceClass = resource_schema_to_class_map.get(schema_type)if ResourceClass:@@ -266,7 +266,7 @@ def main():result_message = MCPOrchestratorInputSchema(query=(f"Resource {resource_name} read with content: {resource_output.content}"))- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)PromptClass = prompt_schema_to_class_map.get(schema_type)if PromptClass:@@ -283,7 +283,7 @@ def main():result_message = MCPOrchestratorInputSchema(query=(f'Prompt {prompt_name} generated successfully. Content: "{prompt_output.content}"'))- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)if not schema_type_valid:raise ValueError(f"Unknown schema type '" f"{schema_type.__name__}" f"' returned by orchestrator")diff --git a/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.py b/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.pyindex f06e00b..9ad37b0 100644--- a/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.py+++ b/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.py@@ -255,7 +255,7 @@ async def main():result_message = MCPOrchestratorInputSchema(query=(f"Tool {tool_name} executed with result: " f"{tool_output.result}"))- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)ResourceClass = resource_schema_to_class_map.get(schema_type)if ResourceClass:@@ -272,7 +272,7 @@ async def main():result_message = MCPOrchestratorInputSchema(query=(f"Resource {resource_name} read with content: {resource_output.content}"))- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)PromptClass = prompt_schema_to_class_map.get(schema_type)if PromptClass:@@ -289,7 +289,7 @@ async def main():result_message = MCPOrchestratorInputSchema(query=(f"Prompt {prompt_name} generated content: {prompt_output.content}"))- orchestrator_agent.history.add_message("system", result_message)+ orchestrator_agent.add_tool_result(result_message)if not schema_type_valid:raise ValueError(f"Unknown schema type '" f"{schema_type.__name__}" f"' returned by orchestrator")diff --git a/atomic-examples/orchestration-agent/orchestration_agent/orchestrator.py b/atomic-examples/orchestration-agent/orchestration_agent/orchestrator.pyindex 043232b..37b7862 100644--- a/atomic-examples/orchestration-agent/orchestration_agent/orchestrator.py+++ b/atomic-examples/orchestration-agent/orchestration_agent/orchestrator.py@@ -174,7 +174,7 @@ if __name__ == "__main__":history = orchestrator_agent.historyorchestrator_agent = orchestrator_agent_finalorchestrator_agent.history = history- orchestrator_agent.history.add_message("system", response)+ orchestrator_agent.add_tool_result(response)final_answer = orchestrator_agent.run(input_schema)console.print(f"\n[bold blue]Final Answer:[/bold blue] {final_answer.final_answer}")# Reset the agent to the originaldiff --git a/atomic-examples/progressive-disclosure/progressive_disclosure/agents/orchestrator_agent.py b/atomic-examples/progressive-disclosure/progressive_disclosure/agents/orchestrator_agent.pyindex e6857aa..f2de618 100644--- a/atomic-examples/progressive-disclosure/progressive_disclosure/agents/orchestrator_agent.py+++ b/atomic-examples/progressive-disclosure/progressive_disclosure/agents/orchestrator_agent.py@@ -363,7 +363,7 @@ def execute_orchestrator_loop(# Add result to historyresult_message = OrchestratorInputSchema(query=f"Tool '{tool_name}' executed. Result: {tool_output.result}")- orchestrator.history.add_message("system", result_message)+ orchestrator.add_tool_result(result_message)# Continue the loopoutput = orchestrator.run()@@ -453,7 +453,7 @@ def execute_orchestrator_loop_parallel(prompt_msg = OrchestratorInputSchema(query="All tool results are now available. Please provide your final answer using FinalResponseSchema.")- orchestrator.history.add_message("system", prompt_msg)+ orchestrator.add_tool_result(prompt_msg)output = orchestrator.run()actions = output.actionscontinue # Re-check for FinalResponseSchema@@ -520,7 +520,7 @@ def execute_orchestrator_loop_parallel(# Add results to historyresult_message = OrchestratorInputSchema(query=result_text)- orchestrator.history.add_message("system", result_message)+ orchestrator.add_tool_result(result_message)# Continue the loopoutput = orchestrator.run()