Python: [Bug]: get_agent_mode and set_agent_mode treat an empty available_modes sequence as defaults

[boshilin123]

Description

The public get_agent_mode and set_agent_mode helpers document available_modes as defaulting to the built-in modes when it is omitted. However, both helpers currently use tuple(available_modes or DEFAULT_MODE_MAP), which also replaces an explicitly empty sequence with the built-in modes.

Consequently, a caller that configures no available modes silently gets plan / execute instead of receiving a configuration error. This is inconsistent with AgentModeProvider(mode_instructions={}), which raises ValueError: mode_instructions must contain at least one mode.

Steps to reproduce:

1. Create an AgentSession.
2. Call get_agent_mode(session, available_modes=[]).
3. Call set_agent_mode(session, "plan", available_modes=[]).
4. Observe that both calls return plan instead of rejecting the empty mode set.

Expected behavior:

• available_modes is None should continue to mean “use the built-in modes”.
• An explicitly empty sequence should raise a clear ValueError, consistent with AgentModeProvider rejecting an empty mode_instructions mapping.

Actual behavior:

get with []: plan
set with []: plan
provider with empty mapping: ValueError mode_instructions must contain at least one mode.

Code Sample

from agent_framework import AgentSession
from agent_framework import get_agent_mode
from agent_framework import set_agent_mode
from agent_framework._harness._mode import AgentModeProvider

session = AgentSession(session_id="repro")

print("get with []:", get_agent_mode(session, available_modes=[]))
print("set with []:", set_agent_mode(session, "plan", available_modes=[]))

try:
    AgentModeProvider(mode_instructions={})
except ValueError as exc:
    print("provider with empty mapping:", type(exc).__name__, str(exc))

Error Messages / Stack Traces

N/A. The issue is silent fallback rather than an exception or crash.

Package Versions

agent-framework-core: 1.18.0 (editable install from commit 999dda7)

Python Version

Python 3.12 (64-bit)

Additional Context

Both public helpers use the same truthiness fallback in python/packages/core/agent_framework/_harness/_mode.py. The existing 12 tests in python/packages/core/tests/core/test_harness_mode.py pass but do not cover an explicit empty sequence.

Repository issue/PR searches for available_modes empty, get_agent_mode available_modes, and set_agent_mode available_modes found only the original feature PR #5611 and no existing report or fix for this edge case.

Suggested scope:

• Fall back to DEFAULT_MODE_MAP only when available_modes is None.
• Validate that the normalized mapping is non-empty in both helpers or in a shared resolver.
• Add regression tests for both public helpers with available_modes=[].

I would be happy to contribute the focused fix and regression tests if this behavior is confirmed as unintended.

[github-actions]

🤖 Automated triage reproduction notes (agent-authored — trust but verify)

Agent analysis

python/packages/core/agent_framework/_harness/_mode.py::get_agent_mode at line 146 and set_agent_mode at line 194 accept an explicitly empty available_modes sequence and fall back to built-in modes. Minimal repro: create an AgentSession, then call each helper with available_modes=[]; both return plan instead of raising ValueError.

• Failing test: python/packages/core/tests/core/test_harness_mode.py
• Files examined: python/packages/core/agent_framework/_harness/_mode.py, python/packages/core/agent_framework/_harness/_loop.py, python/packages/core/tests/core/test_harness_mode.py, python/packages/core/pyproject.toml
• Tests run: test_harness_mode.py baseline (25 passed), test_get_agent_mode_rejects_empty_available_modes (failed), test_set_agent_mode_rejects_empty_available_modes (failed)
• Reported version: 1.18.0
• Current version: 1.18.0

[ZedingZhang]

Hi westey (@westey-m), I’d like to work on this if no one else is already implementing it.
I plan to make the built-in fallback apply only when available_modes is None, reject explicitly empty sequences with a clear ValueError, and add regression tests for both public helpers. Is this direction looks good?

[westey-m]

Hi ZedingZhang (@ZedingZhang), sure. Feel free to submit a PR, thanks!