[Swarm] ContextExpression and OnContextCondition

[marklysze]

Update

1. This PR now provides a ContextExpression class that takes an expression based on context variables and evaluates it to True or False.

Notes:

• Variable references use ${var_name} syntax: ${logged_in}, ${attempts}
• String literals can use normal quotes: 'hello', "world"
• Supported operators:
  • Logical: not/!, and/&, or/|
  • Comparison: >, <, >=, <=, ==, !=
• Parentheses can be used for grouping
• Examples:
  • "not ${logged_in} and ${is_admin} or ${guest_checkout}"
  • "!${logged_in} & ${is_admin} | ${guest_checkout}"
  • "${attempts} > 3 | ${is_admin} == True"

This will provide a very powerful way to use context variables without the need to create functions in a lot of cases.

Reasoning for the syntax:

• ${} follows similar conventions for bash/terminal, curly brackets for variables is also common
• Operators are common Python syntax, plus support added for common operator characters: !, &, |

E.g.

OnCondition(
    target=some_agent,
    condition="Some condition",
    available=ContextExpression("not(${is_logged_in}) or ${customer_level} == 'premium' or ${attempts} >= 3")
)

2. This PR incorporates a new OnCondition, called OnContextCondition, that will use context variables and a ContextExpression to determine hand-offs.

This is not LLM based, and these conditions will be run before the OnCondition and AfterWork hand offs. If any of these evaluate to True the hand-off will be made.

E.g.

OnContextCondition(
    target=some_agent,
    condition=ContextExpression("!${on_probation} or ${tier} == 'Gold'"),
    available="is_logged_in")

Related issue number

Closes #1220
Closes #1203

Checks

• I've included any doc changes needed for https://docs.ag2.ai/. See https://docs.ag2.ai/docs/contributor-guide/documentation to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

[marklysze]

Support a logical expression, like available="!('this_var' & 'this_other_var') | ('something_else_var')"

[codecov]

Codecov Report

Attention: Patch coverage is 77.77778% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
autogen/agentchat/utils.py	82.43%	10 Missing and 3 partials ⚠️
autogen/agentchat/agent.py	16.66%	4 Missing and 1 partial ⚠️

❗ There is a different number of reports uploaded between BASE (fb0000b) and HEAD (c49cb43). Click for more details.

HEAD has 1264 uploads less than BASE

Flag	BASE (fb0000b)	HEAD (c49cb43)
3.9	82	0
ubuntu-latest	145	1
optional-deps	141	0
commsagent-telegram	9	0
3.10	96	0
commsagent-slack	9	0
commsagent-discord	9	0
3.13	85	0
core-without-llm	14	1
browser-use	7	0
macos-latest	104	0
3.11	64	1
3.12	36	0
windows-latest	114	0
jupyter-executor	9	0
retrievechat-qdrant	14	0
retrievechat-mongodb	10	0
retrievechat	15	0
websockets	9	0
interop	13	0
interop-pydantic-ai	9	0
retrievechat-pgvector	10	0
twilio	9	0
interop-langchain	9	0
graph-rag-falkor-db	6	0
docs	6	0
crawl4ai	13	0
interop-crewai	9	0
lmm	4	0
teachable	4	0
cerebras	15	0
agent-eval	1	0
gpt-assistant-agent	3	0
llama-index-agent	3	0
together	14	0
swarm	14	0
cohere	15	0
ollama	15	0
retrievechat-couchbase	3	0
mistral	14	0
anthropic	16	0
bedrock	15	0
gemini	14	0
websurfer	15	0
long-context	3	0
groq	14	0
core-llm	8	0
integration	12	0
falkordb	2	0
gemini-realtime	1	0
autobuild	1	0
deepseek	1	0
openai-realtime	1	0
neo4j	2	0
openai	1	0

Files with missing lines	Coverage Δ
autogen/__init__.py	100.00% <ø> (ø)
autogen/agentchat/__init__.py	100.00% <100.00%> (ø)
autogen/agentchat/agent.py	71.87% <16.66%> (-13.32%)	⬇️
autogen/agentchat/utils.py	84.17% <82.43%> (-8.38%)	⬇️

... and 69 files with indirect coverage changes