Skip to content

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.py
index 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_role
self.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 = None
self.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)
+
@property
def 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 += history
def _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.py
index 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, mock
image_entry = next(item for item in content if item.get("type") == "image_url")
assert "image_url" in image_entry
assert 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.history
orchestrator_agent = orchestrator_agent_final
orchestrator_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 original
diff --git a/atomic-examples/progressive-disclosure/progressive_disclosure/agents/orchestrator_agent.py b/atomic-examples/progressive-disclosure/progressive_disclosure/agents/orchestrator_agent.py
index 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 history
result_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 loop
output = 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.actions
continue # Re-check for FinalResponseSchema
@@ -520,7 +520,7 @@ def execute_orchestrator_loop_parallel(
# Add results to history
result_message = OrchestratorInputSchema(query=result_text)
- orchestrator.history.add_message("system", result_message)
+ orchestrator.add_tool_result(result_message)
# Continue the loop
output = orchestrator.run()