Heuristic:Microsoft Agent framework Silent Workflow Failures
| Knowledge Sources | |
|---|---|
| Domains | Debugging, AI_Agents |
| Last Updated | 2026-02-11 16:45 GMT |
Overview
Many declarative workflow action failures (missing properties, invalid state, malformed JSON) log warnings but do not raise exceptions, causing workflows to silently skip steps instead of failing visibly.
Description
The declarative workflow engine uses a forgiving error handling pattern: when control-flow actions (`forEach`, `if`, `switch`) encounter missing required properties, they log a `logger.warning()` and return early instead of raising an exception. Similarly, AG-UI predictive state, SSE parsing, and durable state deserialization use the same pattern. This design choice prioritizes workflow continuity over strict validation, but makes debugging significantly harder because the workflow appears to succeed even when steps are silently skipped.
Usage
Apply this heuristic when debugging declarative workflows that produce unexpected results. If a workflow step seems to be skipped or a condition never evaluates, check the logs for WARNING messages. The most common silent failures are:
- `forEach` missing `source` property
- `if` missing `condition` property
- `switch` missing `value` property
- Durable state schema version missing (causes full state reset)
- Predictive state with malformed JSON in tool arguments
The Insight (Rule of Thumb)
- Action: Always monitor WARNING-level logs when running declarative workflows. Enable logging at WARNING level minimum.
- Value: Set up structured logging to capture and alert on framework warnings in production.
- Trade-off: Silent failures keep workflows running but can mask YAML configuration errors for extended periods.
Reasoning
ForEach missing source from `python/packages/declarative/agent_framework_declarative/_workflows/_actions_control_flow.py:45-47`:
if not source_expr:
logger.warning("Foreach action missing 'source' property")
return
If missing condition from the same file at lines 103-105:
if condition_expr is None:
logger.warning("If action missing 'condition' property")
return
Switch missing value at lines 147-149:
if not value_expr:
logger.warning("Switch action missing 'value' property")
return
Durable state schema reset from `python/packages/durabletask/agent_framework_durabletask/_durable_agent_state.py:426-429`:
if schema_version is None:
logger.warning("Resetting state as it is incompatible with the current schema, all history will be lost")
return cls()
AG-UI predictive state from `python/packages/ag-ui/agent_framework_ag_ui/_run.py:1008-1012`:
# Ignore malformed JSON in tool arguments for predictive state;
# predictive updates are best-effort and should not break the flow.
logger.warning(
"Failed to decode JSON arguments for predictive tool '%s'.",
tool_name,
)