dify - 💡(How to fix) Fix Feature Request: Deterministic Agent Iteration Guardrails and Failure Classification [1 participants]

Self Checks

• I have read the Contributing Guide and Language Policy.
• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report, otherwise it will be closed.
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

Related: #5598, which discusses more flexible error handling for LLM nodes.

I would like to propose adding deterministic iteration-level guardrails and structured failure classification to Dify's Agent runtime.

From reading the current Agent runner implementation, both CotAgentRunner and FCAgentRunner appear to rely primarily on max_iteration as the final stopping mechanism for repeated or unproductive Agent loops.

Currently, if an Agent repeats similar thoughts, calls the same tool with nearly identical inputs, receives unusable tool output, or makes no meaningful progress, the runtime may continue consuming tokens until max_iteration is reached.

Dify already persists useful Agent trace data such as thought, tool, tool input, observation, answer, and usage metadata. This makes Dify a good fit for adding lightweight runtime quality checks and structured failure classification.

Proposed Solution

1. Deterministic Agent Iteration Guardrails

Add zero-LLM-cost checks after each Agent iteration to detect common failure patterns before max_iteration is reached.

Examples:

• repeated or near-duplicate thoughts
• repeated tool calls with the same or similar inputs
• malformed or empty intermediate outputs
• tool observations that are unusable or structurally invalid
• no-progress loops across multiple iterations

When a guardrail is triggered, the Agent run could stop early with a clear failure reason instead of continuing to spend tokens.

This would reduce wasted token usage and make Agent failures easier to understand.

2. Structured Failure Classification

Introduce structured failure categories for Agent runtime failures.

For example:

• MAX_ITERATION_REACHED
• REPEATED_THOUGHT_LOOP
• REPEATED_TOOL_CALL
• INVALID_TOOL_OUTPUT
• EMPTY_AGENT_RESPONSE
• TOOL_INVOCATION_FAILED
• MODEL_RATE_LIMITED
• MODEL_CONTEXT_LENGTH_EXCEEDED
• MALFORMED_INTERMEDIATE_STATE
• NO_PROGRESS_DETECTED

These categories could be attached to Agent traces and workflow node results, making failures searchable, measurable, and easier to debug.

Why This Matters

This would improve Dify Agent reliability in several ways:

• stop repeated Agent loops earlier
• reduce unnecessary token consumption
• make Agent failures easier to debug
• provide better observability for production Agent workflows
• allow users to analyze failure patterns across runs
• provide a foundation for future Agent reliability features

I would be happy to help refine the proposal or contribute an initial implementation if the maintainers think this direction fits Dify's Agent runtime roadmap.

2. Additional context or comments

Source References

• CotAgentRunner iteration loop: https://github.com/langgenius/dify/blob/7e6745e105771a87853e1016bc241a2024629639/api/core/agent/cot_agent_runner.py#L77-L178

• FCAgentRunner iteration loop: https://github.com/langgenius/dify/blob/7e6745e105771a87853e1016bc241a2024629639/api/core/agent/fc_agent_runner.py#L52-L85

• AgentMaxIterationError: https://github.com/langgenius/dify/blob/7e6745e105771a87853e1016bc241a2024629639/api/core/agent/errors.py#L1-L10

• Agent trace persistence: https://github.com/langgenius/dify/blob/7e6745e105771a87853e1016bc241a2024629639/api/core/agent/base_agent_runner.py#L333-L420

• Workflow error wrapping: https://github.com/langgenius/dify/blob/7e6745e105771a87853e1016bc241a2024629639/api/core/workflow/workflow_entry.py#L330-L337

Prior Art / Reference Implementation

I have implemented and tested a similar runtime-control approach in an independent Agent Runtime project.

Relevant design decision records:

• Declarative Evaluator Criteria: https://github.com/humingyu234/adaptive-agent-orchestrator/blob/5bd6f3ca84b7368c90287738ad5df193d8d31bc7/docs/decisions/016-declarative-evaluator-criteria.md

• Guardrails and Runtime Safety: https://github.com/humingyu234/adaptive-agent-orchestrator/blob/5bd6f3ca84b7368c90287738ad5df193d8d31bc7/docs/decisions/017-guardrails-v1.md

• Failure Taxonomy and Classification: https://github.com/humingyu234/adaptive-agent-orchestrator/blob/5bd6f3ca84b7368c90287738ad5df193d8d31bc7/docs/decisions/019-failure-taxonomy.md

3. Can you help us with this feature?

• I am interested in contributing to this feature.