fix(agent): finalize react loop on max iterations

[BreezyB1n]

PR Title

fix(agent): finalize react loop on max iterations

AgentScope Version

2.0.1

Description

Refs #1805

This PR changes how a ReAct agent behaves when it reaches max_iters.

Previously, the agent stopped the loop and returned a fixed message saying the reasoning-acting loop had reached its maximum iterations. That could end the reply abruptly even when the agent had already completed useful tool work.

Now, when the loop reaches max_iters, the agent:

• emits ExceedMaxItersEvent, so the condition remains observable;
• appends a HintBlock to the agent context with instructions to stop using tools and summarize progress;
• runs one final reasoning step with ToolChoice(mode="none");
• returns the model-generated final text as the completed reply.

The AGUI protocol mapping now treats ExceedMaxItersEvent as a CUSTOM event named exceed_max_iters instead of a RUN_ERROR, since the run can still finish normally after the final text-only reasoning step.

Tests cover the final model turn, event stream behavior, persisted hint context, and AGUI protocol conversion.

Compatibility note

ExceedMaxItersEvent is still emitted. In the AGUI protocol mapping, consumers should now handle it as a CUSTOM event named exceed_max_iters instead of RUN_ERROR.

Documentation

No documentation PR is included. This change does not add a public API. It changes the runtime behavior after ReActConfig.max_iters is reached and is covered by tests.

Validation

pre-commit run --all-files
uv run --with '.[dev]' pytest tests/agent_basic_test.py tests/agui_protocol_test.py -q
uv run --with '.[dev]' pytest tests/hitl_user_confirmation_test.py tests/hitl_external_execution_test.py -q
uv run --with '.[dev]' python -m compileall -q src/agentscope/agent/_agent.py tests/agent_basic_test.py tests/agui_protocol_test.py
git diff --check

Manual validation

Ran a local smoke test with DashScope qwen-plus and ReActConfig(max_iters=1) using a tool that encourages the first model turn to call a tool.

Observed behavior:

• The first model turn called continue_work once.
• The agent emitted EXCEED_MAX_ITERS after the first tool result.
• The agent made one final model call that streamed only text blocks.
• No tool calls were emitted after EXCEED_MAX_ITERS.
• The reply ended normally with REPLY_END.
• The finalization hint remained in context as source="max_iters".

Summary output:

total_tool_calls: 1
saw_exceed_max_iters: True
saw_reply_end: True
tool_calls_after_exceed: 0
captured_finalization_text: True
context_hint_sources: ['max_iters']

PASS: max_iters triggered text-only finalization and completed normally.

Screenshot:

Checklist

• An issue has been created for this PR
• I have read the [CONTRIBUTING.md](https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md)
• Docstrings are in Google style
• Related documentation has been updated (e.g. links, examples, etc.) in [documentation repository](https://github.com/agentscope-ai/docs)
• Code is ready for review

[BreezyB1n]

@DavdGao Could you please take a look at this pull request (PR) when you have a moment? Thanks a lot.