[Bug]: ReactAgent workflow crashes with context in formatter

[Florian-BACHO]

Bug Description

Hi,

I noticed that the llama_index.core.agent.workflow.ReActAgent workflow crashes when setting a ReActChatFormatter formatter with a context.

Using ReActChatFormatter.from_defaults() works fine but using ReActChatFormatter.from_defaults(context="This is some context") produces a KeyError.

Version

0.12.43

Steps to Reproduce

import asyncio

from llama_index.core.agent import ReActChatFormatter
from llama_index.core.agent.workflow import ReActAgent
from llama_index.core.base.llms.types import ChatMessage
from llama_index.llms.openai import OpenAI


async def main() -> None:
    llm = OpenAI(model="gpt-4o")

    formatter = ReActChatFormatter.from_defaults(context="This is some context")

    agent = ReActAgent(
        tools=[], llm=llm, formatter=formatter
    )

    usr_msg = ChatMessage(role="user", content="hello")

    await agent.run(user_msg=usr_msg)


if __name__ == "__main__":
    asyncio.run(main())

Relevant Logs/Tracbacks

Traceback (most recent call last):
  File "/home/root/test/.venv/lib/python3.12/site-packages/workflows/context/context.py", line 628, in _step_worker
    new_ev = await instrumented_step(**kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/root/test/.venv/lib/python3.12/site-packages/llama_index_instrumentation/dispatcher.py", line 365, in async_wrapper
    result = await func(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/root/test/.venv/lib/python3.12/site-packages/llama_index/core/agent/workflow/base_agent.py", line 346, in run_agent_step
    agent_output = await self.take_step(
                   ^^^^^^^^^^^^^^^^^^^^^
  File "/home/root/test/.venv/lib/python3.12/site-packages/llama_index/core/agent/workflow/react_agent.py", line 86, in take_step
    input_chat = react_chat_formatter.format(
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/root/test/.venv/lib/python3.12/site-packages/llama_index/core/agent/react/formatter.py", line 81, in format
    fmt_sys_header = self.system_header.format(**format_args)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
KeyError: 'context'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/root/.local/share/uv/python/cpython-3.12.10-linux-x86_64-gnu/lib/python3.12/asyncio/events.py", line 88, in _run
    self._context.run(self._callback, *self._args)
  File "/home/root/test/.venv/lib/python3.12/site-packages/llama_index_instrumentation/dispatcher.py", line 290, in handle_future_result
    raise exception
  File "/home/root/test/.venv/lib/python3.12/site-packages/workflows/workflow.py", line 416, in _run_workflow
    raise exception_raised
  File "/home/root/test/.venv/lib/python3.12/site-packages/workflows/context/context.py", line 637, in _step_worker
    raise WorkflowRuntimeError(
workflows.errors.WorkflowRuntimeError: Error in step 'run_agent_step': 'context'
Traceback (most recent call last):
  File "/home/root/test/.venv/lib/python3.12/site-packages/workflows/context/context.py", line 628, in _step_worker
    new_ev = await instrumented_step(**kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/root/test/.venv/lib/python3.12/site-packages/llama_index_instrumentation/dispatcher.py", line 365, in async_wrapper
    result = await func(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/root/test/.venv/lib/python3.12/site-packages/llama_index/core/agent/workflow/base_agent.py", line 346, in run_agent_step
    agent_output = await self.take_step(
                   ^^^^^^^^^^^^^^^^^^^^^
  File "/home/root/test/.venv/lib/python3.12/site-packages/llama_index/core/agent/workflow/react_agent.py", line 86, in take_step
    input_chat = react_chat_formatter.format(
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/root/test/.venv/lib/python3.12/site-packages/llama_index/core/agent/react/formatter.py", line 81, in format
    fmt_sys_header = self.system_header.format(**format_args)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
KeyError: 'context'

[dosubot]

This KeyError happens because when you create a ReActChatFormatter with a context, it sets up a system_header template that expects a {context} variable. If, at any point, the context attribute is missing or empty when format() is called, the formatter tries to fill in the template without the required context key, which triggers the KeyError. This is a mismatch between the template and the arguments provided to it during formatting. You can see this logic in the formatter's implementation: if self.context is set, it adds "context" to format_args; otherwise, it doesn't, but the template may still expect it, leading to the error if context is missing or empty at runtime formatter.py source.

To work around this, make sure that the context attribute is always set (not None or empty) whenever you use a formatter that expects a context in its system_header template. If you need to dynamically update the context, ensure that the new value is not empty before calling format(). Alternatively, you could modify the formatter to use a safer formatting approach or always include a default context value when the template expects it.

There are no existing issues or recent changes in the repo that address this specific bug. If you want a more robust fix, consider updating the formatter logic to always provide a context key (even if it's an empty string) when the template expects it, or use a template that doesn't require context when none is provided.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[Florian-BACHO]

@dosu the formatter and its context remain unchanged after being set in my steps to reproduce code.

[dosubot]

The KeyError happens because, even though you set the context when creating the formatter, the ReActAgent workflow overwrites the formatter's context with the system prompt from the LLM input during execution. If the system prompt is missing or empty at that point, the context becomes empty, but the formatter's template still expects a {context} key—causing the crash. This is a side effect of how the agent workflow manages context, not a bug in your usage or in the formatter itself. You can see this logic in the agent's take_step method, where it sets the formatter's context to the system prompt before formatting the input chat messages (source).

A workaround is to ensure the system prompt is always set when running the agent, or to modify the agent/formatter logic to provide a default context if none is present. This architectural quirk is not currently addressed by any recent changes or issues in the repo.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[Florian-BACHO]

Alright. I could make it work by doing the following:

agent = ReActAgent(
    tools=tool_list, llm=llm, system_prompt="this is some context",
    formatter=ReActChatFormatter.from_defaults(system_header=CONTEXT_REACT_CHAT_SYSTEM_HEADER)
)

It seems to be necessary to set the formatter with CONTEXT_REACT_CHAT_SYSTEM_HEADER. It would be nice to create a system that choses the right system header according to whether system_prompt is set or not. Or at least write this somewhere in the doc.

Thanks @dosu

[logan-markewich]

@Florian-BACHO this is actually a bug. But also, I really recommend just setting the system_prompt in the agent (which ends up getting injected as context in the react header)

If you use both, it starts to get a little confusing 😅 But I can make a PR to fix

[Florian-BACHO]

@logan-markewich setting the system prompt is not enough to inject it. It seems that we have to explicitly set formatter=ReActChatFormatter.from_defaults(system_header=CONTEXT_REACT_CHAT_SYSTEM_HEADER) too (but without context). The default react header does not include the context

[logan-markewich]

Fix #19158