fix(agentic): honor iterations_limit in builds

[Cristhianzl]

Summary

QA reopened the iterations-budget work (follow-up to #14038): iterations_limit
was validated at the API and worked in isolation, but had no effect on real
builds — iterations_limit=1 still ran 6 model calls and completed.

Summary by CodeRabbit

• New Features

  • Added support for setting the assistant’s per-session step limit with /iterations N.
  • Values are limited to 1–200 and saved for future sessions.
  • Use /iterations off to restore the default limit of 30 steps.
  • Step-limit settings now apply consistently across supported assistant flow types.

• Documentation

  • Clarified step-budget behavior, cost considerations, limits, persistence, and override handling.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ecf9cdd2-5f6f-4466-853c-e6ba69cb11ba

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

The assistant iteration budget now uses a shared default, supports bounded per-request overrides, and propagates Python-flow overrides through graph loading into Agent max_iterations. Tests cover defaults, overrides, forwarding, and clamping; documentation describes both JSON and Python paths.

Changes

Assistant iteration budget

Layer / File(s)	Summary
Shared budget and graph construction src/backend/base/langflow/agentic/flows/flow_builder_assistant.py, src/backend/base/langflow/agentic/services/flow_preparation.py, src/backend/tests/unit/agentic/flows/test_assistant_agent_iteration_budget.py	The assistant uses DEFAULT_ASSISTANT_ITERATIONS, accepts iterations_limit, clamps it to the supported range, and applies the result to the Agent graph.
Python loader forwarding and documented override paths src/backend/base/langflow/agentic/services/helpers/flow_loader.py, src/backend/tests/unit/agentic/services/test_iterations_budget.py, docs/features/langflow-assistant.md	Python graph loading forwards ITERATIONS_LIMIT to compatible builders, with tests covering defaults, forwarding, and clamping; documentation describes JSON and Python propagation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant load_graph_for_execution
  participant _load_graph_from_python
  participant get_graph
  participant AgentComponent
  Client->>load_graph_for_execution: provide ITERATIONS_LIMIT
  load_graph_for_execution->>_load_graph_from_python: pass provider_vars
  _load_graph_from_python->>get_graph: pass iterations_limit
  get_graph->>AgentComponent: set bounded max_iterations

Loading

Possibly related PRs

• langflow-ai/langflow#14038: Extends iteration-limit propagation through the assistant request and streaming execution path.

Suggested labels: documentation

🚥 Pre-merge checks | ✅ 8 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (8 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: making iterations_limit take effect during agentic builds.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Coverage For New Implementations	✅ Passed	PASS: The PR adds backend unit tests in test_*.py that cover JSON pinning, get_graph(iterations_limit), loader forwarding, clamping, and default budget behavior.
Test Quality And Coverage	✅ Passed	PASS: Tests cover JSON injection, Python builder, and loader forwarding/clamping with real assertions; async tests fit pytest asyncio auto mode.
Test File Naming And Structure	✅ Passed	Backend tests are named test_*.py in unit dirs, use valid pytest/async structure, have descriptive names, and include positive/negative coverage; no integration/frontend mismatch.
Excessive Mock Usage Warning	✅ Passed	Touched tests use real flow JSON, real builder/load paths, and simple assertions; no mock objects or patching are present in the changed files.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cz/honor-iterations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Test Coverage Advisor

No source changes detected without accompanying tests. Thanks for keeping coverage up! 🎉

Advisory check only — never blocks merge.

[erichare]

Hey @Cristhianzl , could you take a look at these findings?

Code Review Summary

Found 2 critical issues that need to be fixed:

🔴 Critical (Must Fix)

1. [P1] Nested component generation bypasses the iteration budget

FilePath: src/backend/base/langflow/agentic/services/helpers/flow_loader.py line 176
Related: src/lfx/src/lfx/mcp/flow_builder_tools/run_tools.py line 424

global_variables={"FLOW_ID": flow_id}

Explanation

/iterations 1 limits the outer Python builder, but GenerateComponent launches a nested JSON assistant without ITERATIONS_LIMIT. That Agent therefore retains the default budget of 30 calls per attempt, defeating the cost cap for component_then_flow requests.

Suggested Fix

Carry the budget through task-local context and include it in the nested subflow’s globals. Add a regression test covering iteration-limited custom-component builds.

---

2. [P1] The existing loader test suite now fails

FilePath: src/backend/base/langflow/agentic/services/helpers/flow_loader.py line 237

return await _load_graph_from_python(flow_path, provider, model_name, api_key_var, provider_vars)

Explanation

The loader now always supplies a fifth argument, including None, but assertions in test_flow_loader.py lines 372 and 425 still expect four arguments.

Reproduced on the current head: 2 failed, 26 passed. GitHub’s unit-test shards were still running when reviewed.

Suggested Fix

Update both mock expectations to include provider_vars=None, and add explicit non-None forwarding coverage.

---

Found 1 suggestion for improvement:

🟡 Suggestions (Should Consider)

1. [P2] Non-streaming endpoints silently ignore iterations_limit

FilePath: src/backend/base/langflow/agentic/api/router.py line 292

Explanation

AssistantRequest accepts iterations_limit, but only /assist/stream forwards it. /assist and /execute/{flow_name} accept the same schema yet silently execute with the default budget.

Suggested Fix

Seed ITERATIONS_LIMIT centrally in the resolved global variables, or explicitly forward it from every endpoint using AssistantRequest. Add route-level regression tests.

✅ What's Good

• Reviewed current head 97d7ef4 against base 4f86736.
• The primary streaming Python-builder path correctly applies the budget.
• All 13 PR-added iteration tests passed.
• Ruff and git diff --check passed.
• Generated component-index and starter-project checks passed.

[github-actions]

Frontend Unit Test Coverage Report

Coverage Summary

Lines	Statements	Branches	Functions
	46.92% (66202/141080)	70.11% (9220/13149)	44.91% (1514/3371)

Unit Test Results

Tests	Skipped	Failures	Errors	Time
5391	0 💤	0 ❌	0 🔥	15m 38s ⏱️

[codecov]

Codecov Report

❌ Patch coverage is 70.73171% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.87%. Comparing base (4a880f2) to head (2216ded).
⚠️ Report is 3 commits behind head on release-1.11.0.

Files with missing lines	Patch %	Lines
...rc/lfx/src/lfx/mcp/flow_builder_tools/run_tools.py	0.00%	7 Missing ⚠️
...ase/langflow/agentic/services/assistant_service.py	71.42%	4 Missing ⚠️
src/backend/base/langflow/agentic/api/router.py	50.00%	1 Missing ⚠️

Additional details and impacted files

@@                Coverage Diff                 @@
##           release-1.11.0   #14094      +/-   ##
==================================================
- Coverage           60.87%   60.87%   -0.01%     
==================================================
  Files                2375     2426      +51     
  Lines              234025   236737    +2712     
  Branches            32939    37019    +4080     
==================================================
+ Hits               142472   144114    +1642     
- Misses              89842    90914    +1072     
+ Partials             1711     1709       -2     

Flag	Coverage Δ
backend	65.64% <85.29%> (-2.15%)	⬇️
frontend	60.04% <ø> (+0.58%)	⬆️
lfx	59.24% <0.00%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...e/langflow/agentic/flows/flow_builder_assistant.py	100.00% <100.00%> (ø)
...ase/langflow/agentic/services/agent_run_context.py	100.00% <100.00%> (ø)
...base/langflow/agentic/services/flow_preparation.py	91.42% <100.00%> (-2.10%)	⬇️
...e/langflow/agentic/services/helpers/flow_loader.py	91.52% <100.00%> (-0.58%)	⬇️
src/backend/base/langflow/agentic/api/router.py	71.53% <50.00%> (+17.63%)	⬆️
...ase/langflow/agentic/services/assistant_service.py	85.11% <71.42%> (-1.85%)	⬇️
...rc/lfx/src/lfx/mcp/flow_builder_tools/run_tools.py	45.10% <0.00%> (-1.53%)	⬇️

... and 430 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[erichare]

LGTM @Cristhianzl !

[github-actions]

Build successful! ✅
Deploying docs draft.
Deploy successful! View draft