eemario opened a new pull request, #1397: URL: https://github.com/apache/flink-agents/pull/1397
<!-- * Thank you very much for contributing to Flink Agents. * Please add the relevant components in the PR title. E.g., [api], [runtime], [java], [python], [hotfix], etc. --> <!-- Please link the PR to the relevant issue(s). Hotfix doesn't need this. --> Linked issue: #xxx ### Purpose of change Allow users to limit turns, elapsed time, and token usage for each ReAct loop, preventing unbounded execution and resource consumption. #### Runtime flow Resolve the request budget or job-level defaults, initialize loop state, and check limits before starting each turn. Model responses update token usage. Exhaustion either starts a tool-free closing turn or returns a failed response. #### Key decisions Check at turn boundaries rather than interrupting in-flight calls. Routing, retries, fallback, and structured-output conversion belong to the same turn. Keep subagent budgets independent. ### Behavioral Semantics #### Interaction decisions | Condition | Behavior | |---|---| | No request budget | Use job-level defaults; unlimited if unset | | Explicit request budget | Replace all job-level budget defaults | | Multiple limits configured | Any exhausted limit triggers the configured mode | | Exhausted + SOFT (default) | Allow one additional tool-free turn, including normal retries and structured-output conversion | | Exhausted + HARD | Return a failed `ChatResponseEvent` without starting another turn | | Subagent invocation | Child tracks its own budget; parent excludes child turns/tokens but includes elapsed waiting time | #### Behavioral contracts - A turn calls the model and executes its requested tools. Retries, routing, fallback, and structured-output conversion do not consume additional turns. - Time measures elapsed wall-clock time, including recovery downtime. Limits do not interrupt an admitted turn or guarantee a strict spending ceiling. - Tokens accumulate from reported input/output usage, including LLM-judge calls. Missing usage logs a warning and may undercount consumption. - Recovery restores saved budget state and the persisted loop start time. Replayed results reconstruct usage; re-execution may incur additional external consumption. #### Failure behavior Invalid budgets are rejected. Model and parsing failures retain the existing retry/fallback behavior. HARD exhaustion, unsuccessful SOFT finalization, or tool calls returned by SOFT finalization produce a failed `ChatResponseEvent`. Runtime persistence failures continue to propagate through the existing failure path. ### Tests | Contract | Coverage | |---|---| | Budget validation and serialization | `ReActLoopBudgetTest`, `test_react_loop_budget.py` | | Request budget replaces defaults | `requestBudgetReplacesAllConfiguredDefaults`, `test_request_budget_replaces_global_limits` | | Turn-boundary checks and SOFT/HARD behavior | `ChatModelActionRetryTest`, `test_chat_model_action_retry.py` | | Routing/retries/fallback share budget accounting | `ChatModelActionRoutingTest`, `test_model_routing.py` | | Invalid SOFT output fails before fallback events | `test_soft_fallback_tool_calls_fail_before_routing_event` | | Recovery preserves timing and reconstructs usage | `ReActLoopBudgetRecoveryTest` | | Chat memory and subagent budget isolation | `ChatMemoryIsolationTest`, `ChatCallTest`, `ReActAgentSubagentTest` | | Cross-language model calls and serialization | Model bridge, event/AgentPlan snapshot, and cross-language runtime tests | ### API Adds Java/Python `ReActLoopBudget`, request-level budget configuration through `ChatRequestEvent`, budget support in `ReActAgent` and Python `ctx.chat`, and `react-loop.budget.*` job-level defaults. Java `ctx.chat` accepts the budget through its request event. Existing callers remain unlimited unless budget defaults are configured. Existing constructors remain available; agent YAML gains no new budget field. ### Documentation <!-- Do not remove this section. Check the proper box only. --> - [ ] `doc-needed` <!-- Your PR changes impact docs --> - [ ] `doc-not-needed` <!-- Your PR changes do not impact docs --> - [x] `doc-included` <!-- Your PR already contains the necessary documentation updates --> ### Was this patch authored or co-authored using generative AI tooling? <!-- Do not remove this section. Check the proper box only. --> - [x] Yes - [ ] No Generated-by: Codex (GPT-6) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
