Document workflow termination guarantees for cycle detection warning

[Copilot]

Agent Framework validation detects cycles in the workflow graph due to bidirectional edges in the coordinator-centric star topology. The warning is safe to acknowledge—termination is guaranteed through multiple mechanisms, but this wasn't documented.

Changes

Code Documentation

• workflow/core.py: Added "Termination Conditions" section explaining three termination mechanisms (max_iterations, structured output routing, coordinator control)
• workflow/executors.py: Documented termination logic in EventPlanningCoordinator, on_specialist_response(), and _synthesize_plan()
• Added inline comments explaining why cycles are safe and necessary for the coordinator pattern

Project Documentation

• AGENTS.md: Added "Termination Guarantees" section under architecture patterns
• docs/WORKFLOW_CYCLES.md: Comprehensive guide explaining cycle detection, why bidirectional edges are safe, and best practices
• README.md: Added references to cycle safety documentation

Tests

• test_workflow.py: Added test_workflow_has_termination_guarantees() and test_workflow_termination_documentation() to verify termination mechanisms

Termination Mechanisms

# 1. Framework-enforced iteration limit
WorkflowBuilder(max_iterations=30)  # Hard limit

# 2. Structured output signals completion
class SpecialistOutput(BaseModel):
    next_agent: str | None  # None = workflow complete
    user_input_needed: bool

# 3. Explicit termination via output
async def _synthesize_plan(self, ctx, conversation):
    await ctx.yield_output(final_plan)  # Terminates workflow

Bidirectional edges enable dynamic routing (e.g., budget → venue for cheaper option), but cycles cannot be infinite due to these three layers of protection.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• astral.sh
  • Triggering command: curl -LsSf REDACTED (dns block)
• https://api.github.com/repos/microsoft/agent-framework/commits/main
  • Triggering command: /home/REDACTED/.local/bin/uv sync --dev (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Workflow validation warning: Cycle detected in workflow graph – ensure termination/iteration limits exist</issue_title>
<issue_description>### Bug Summary
A warning appears in the console related to workflow validation cycles:

[2025-11-01 15:05:04 - /Users/govindk/code/work/ip/ignite-build/spec-to-agents/.venv/lib/python3.13/site-packages/agent_framework/_workflows/_validation.py:482 - WARNING] Cycle detected in the workflow graph involving: logistics -> catering -> budget -> venue -> event_coordinator -> logistics. Ensure termination or iteration limits exist.

Details

• The warning is triggered by the workflow validation code in the agent_framework package (see below).
• The validation logic uses a cycle detection algorithm in WorkflowGraphValidator._validate_cycles() and warns if cycles are detected among workflow executors.
• The cycle in my workflow involves: logistics -> catering -> budget -> venue -> event_coordinator -> logistics.

Source code (validation logic)

# (see full source in agent_framework/_workflows/_validation.py)
# ...
class WorkflowGraphValidator:
    ...
    def _validate_cycles(self) -> None:
        ...
        logger.warning(
            "Cycle detected in the workflow graph involving: %s. Ensure termination or iteration limits exist.",
            formatted_cycles,
        )

Expected Behavior

Workflow cycles should either be handled with clear termination conditions or have explicit iteration limits to prevent infinite loops.

Steps to Reproduce

1. Construct a workflow graph with the following nodes: logistics, catering, budget, venue, event_coordinator, logistics (cycle).
2. Run validation (or initialize the workflow).
3. Observe warning in the console.

Additional Notes

• Need to review workflow logic and ensure all cycles have proper termination or iteration limits.
• See WorkflowGraphValidator._validate_cycles for the logic that triggers this warning.

If you need more information or a reproduction case, let me know!</issue_description>

Comments on the Issue (you are @copilot in this section)

Note

Custom agent used: agent-workflows
Expert in Microsoft Agent Framework Workflows for Python - specializes in multi-agent orchestration, coordinator patterns, structured routing, human-in-the-loop, and workflow debugging

• Fixes Workflow validation warning: Cycle detected in workflow graph – ensure termination/iteration limits exist #83

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.