Skip to content

Add separator banners to TOOL USE, AGENT START, and ERROR events with unified color scheme #25

Description

@galuszkm

Problem Statement

The AnsiRenderer only shows separator banners for REASONING and RESPONDING mode transitions. Three important event types lack separators:

  • TOOL USE — renders as a plain ⚙ [main] -> 'tool_name' line with no visual break from the surrounding text stream, making tool calls hard to spot.
  • AGENT START — renders as [writer] starting…, which easily gets lost in dense multi-agent output, making it hard to tell where one agent ends and another begins.
  • ERROR — renders as ✗ [agent] ERROR: msg, which looks like just another status line and can be missed when scanning long outputs.

Additionally, the existing color scheme has no consistent rationale across event types.

Proposed Solution

Add separator banners to _handle_tool_start, _handle_agent_start, and _handle_error in src/strands_compose/renderers/ansi.py, using a unified three-group color scheme:

Separator Color Code Semantic group
REASONING Yellow \033[33m Thinking (unchanged)
RESPONDING Cyan \033[36m Output (unchanged)
TOOL USE Bright magenta \033[95m Transition/action
AGENT START Bright magenta \033[95m Transition/action
ERROR Red \033[31m Danger

Changes required:

  1. src/strands_compose/renderers/ansi.py__init__: add self._magenta = "\033[95m" if is_tty else ""
  2. src/strands_compose/renderers/ansi.py_handle_tool_start: reset _active_agent = None, add self._separator(agent, "TOOL USE", color=self._magenta) before the gear-icon line
  3. src/strands_compose/renderers/ansi.py_handle_agent_start: add self._separator(agent, "AGENT START", color=self._magenta) before the [agent] starting… line
  4. src/strands_compose/renderers/ansi.py_handle_error: add self._separator(agent, "ERROR", color=self._red) before the error detail line
  5. tests/unit/renderers/test_ansi.py: verify "TOOL USE", "AGENT START", and the "ERROR" separator text appear in rendered output for the respective events

Use Case

In multi-agent orchestrations (delegation, swarm, graph), output from multiple agents interleaves. Clear visual separators at agent boundaries, tool calls, and errors make it easy to scan output and immediately identify:

  • Which agent is active (magenta AGENT START / TOOL USE)
  • What the agent is doing (yellow REASONING / cyan RESPONDING)
  • Where things went wrong (red ERROR)

This is especially valuable during development and debugging of multi-agent pipelines.

Alternatives Considered

  • Using a unique color per separator type — rejected because too many colors reduces scannability. Three semantic groups (thinking / output / transition+error) are easier to internalize.
  • Adding separators to COMPLETE, NODE_START/STOP, MULTIAGENT_START/COMPLETE — rejected because these are either low-information, already visually distinct (arrows), or rare enough not to warrant extra chrome.
  • Using light blue (\033[94m) instead of magenta — rejected because magenta has higher contrast against both yellow and cyan, making transition events more distinct.

Additional Context

N/A

Metadata

Metadata

Labels

enhancementNew feature or request

Fields

No fields configured for Feature.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions