A programming framework for agentic AI
Make termination condition config declarative (#4984)
Victor Dibiad883e3dfb0a0
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/base/__init__.py b/python/packages/autogen-agentchat/src/autogen_agentchat/base/__init__.pyindex 5815adc35..dcb0a24c3 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/base/__init__.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/base/__init__.py@@ -2,7 +2,7 @@ from ._chat_agent import ChatAgent, Responsefrom ._handoff import Handofffrom ._task import TaskResult, TaskRunnerfrom ._team import Team-from ._termination import TerminatedException, TerminationCondition+from ._termination import AndTerminationCondition, OrTerminationCondition, TerminatedException, TerminationCondition__all__ = ["ChatAgent",@@ -10,6 +10,8 @@ __all__ = ["Team","TerminatedException","TerminationCondition",+ "AndTerminationCondition",+ "OrTerminationCondition","TaskResult","TaskRunner","Handoff",diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/base/_termination.py b/python/packages/autogen-agentchat/src/autogen_agentchat/base/_termination.pyindex 8975c75aa..dcefa5a04 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/base/_termination.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/base/_termination.py@@ -2,13 +2,17 @@ import asynciofrom abc import ABC, abstractmethodfrom typing import List, Sequence+from autogen_core import Component, ComponentBase, ComponentModel+from pydantic import BaseModel+from typing_extensions import Self+from ..messages import AgentEvent, ChatMessage, StopMessageclass TerminatedException(BaseException): ...-class TerminationCondition(ABC):+class TerminationCondition(ABC, ComponentBase[BaseModel]):"""A stateful condition that determines when a conversation should be terminated.A termination condition is a callable that takes a sequence of ChatMessage objects@@ -43,6 +47,9 @@ class TerminationCondition(ABC):asyncio.run(main())"""+ component_type = "termination"+ # component_config_schema = BaseModel # type: ignore+@property@abstractmethoddef terminated(self) -> bool:@@ -72,14 +79,22 @@ class TerminationCondition(ABC):def __and__(self, other: "TerminationCondition") -> "TerminationCondition":"""Combine two termination conditions with an AND operation."""- return _AndTerminationCondition(self, other)+ return AndTerminationCondition(self, other)def __or__(self, other: "TerminationCondition") -> "TerminationCondition":"""Combine two termination conditions with an OR operation."""- return _OrTerminationCondition(self, other)+ return OrTerminationCondition(self, other)++class AndTerminationConditionConfig(BaseModel):+ conditions: List[ComponentModel]+++class AndTerminationCondition(TerminationCondition, Component[AndTerminationConditionConfig]):+ component_config_schema = AndTerminationConditionConfig+ component_type = "termination"+ component_provider_override = "autogen_agentchat.base.AndTerminationCondition"-class _AndTerminationCondition(TerminationCondition):def __init__(self, *conditions: TerminationCondition) -> None:self._conditions = conditionsself._stop_messages: List[StopMessage] = []@@ -111,8 +126,27 @@ class _AndTerminationCondition(TerminationCondition):await condition.reset()self._stop_messages.clear()+ def _to_config(self) -> AndTerminationConditionConfig:+ """Convert the AND termination condition to a config."""+ return AndTerminationConditionConfig(conditions=[condition.dump_component() for condition in self._conditions])++ @classmethod+ def _from_config(cls, config: AndTerminationConditionConfig) -> Self:+ """Create an AND termination condition from a config."""+ conditions = [TerminationCondition.load_component(condition_model) for condition_model in config.conditions]+ return cls(*conditions)+++class OrTerminationConditionConfig(BaseModel):+ conditions: List[ComponentModel]+ """List of termination conditions where any one being satisfied is sufficient."""+++class OrTerminationCondition(TerminationCondition, Component[OrTerminationConditionConfig]):+ component_config_schema = OrTerminationConditionConfig+ component_type = "termination"+ component_provider_override = "autogen_agentchat.base.OrTerminationCondition"-class _OrTerminationCondition(TerminationCondition):def __init__(self, *conditions: TerminationCondition) -> None:self._conditions = conditions@@ -133,3 +167,13 @@ class _OrTerminationCondition(TerminationCondition):async def reset(self) -> None:for condition in self._conditions:await condition.reset()++ def _to_config(self) -> OrTerminationConditionConfig:+ """Convert the OR termination condition to a config."""+ return OrTerminationConditionConfig(conditions=[condition.dump_component() for condition in self._conditions])++ @classmethod+ def _from_config(cls, config: OrTerminationConditionConfig) -> Self:+ """Create an OR termination condition from a config."""+ conditions = [TerminationCondition.load_component(condition_model) for condition_model in config.conditions]+ return cls(*conditions)diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/conditions/_terminations.py b/python/packages/autogen-agentchat/src/autogen_agentchat/conditions/_terminations.pyindex c472d7e32..d824815ae 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/conditions/_terminations.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/conditions/_terminations.py@@ -1,13 +1,25 @@import timefrom typing import List, Sequence+from autogen_core import Component+from pydantic import BaseModel+from typing_extensions import Self+from ..base import TerminatedException, TerminationConditionfrom ..messages import AgentEvent, ChatMessage, HandoffMessage, MultiModalMessage, StopMessage-class StopMessageTermination(TerminationCondition):+class StopMessageTerminationConfig(BaseModel):+ pass+++class StopMessageTermination(TerminationCondition, Component[StopMessageTerminationConfig]):"""Terminate the conversation if a StopMessage is received."""+ component_type = "termination"+ component_config_schema = StopMessageTerminationConfig+ component_provider_override = "autogen_agentchat.conditions.StopMessageTermination"+def __init__(self) -> None:self._terminated = False@@ -27,14 +39,29 @@ class StopMessageTermination(TerminationCondition):async def reset(self) -> None:self._terminated = False+ def _to_config(self) -> StopMessageTerminationConfig:+ return StopMessageTerminationConfig()++ @classmethod+ def _from_config(cls, config: StopMessageTerminationConfig) -> Self:+ return cls()+-class MaxMessageTermination(TerminationCondition):+class MaxMessageTerminationConfig(BaseModel):+ max_messages: int+++class MaxMessageTermination(TerminationCondition, Component[MaxMessageTerminationConfig]):"""Terminate the conversation after a maximum number of messages have been exchanged.Args:max_messages: The maximum number of messages allowed in the conversation."""+ component_type = "termination"+ component_config_schema = MaxMessageTerminationConfig+ component_provider_override = "autogen_agentchat.conditions.MaxMessageTermination"+def __init__(self, max_messages: int) -> None:self._max_messages = max_messagesself._message_count = 0@@ -57,14 +84,30 @@ class MaxMessageTermination(TerminationCondition):async def reset(self) -> None:self._message_count = 0+ def _to_config(self) -> MaxMessageTerminationConfig:+ return MaxMessageTerminationConfig(max_messages=self._max_messages)++ @classmethod+ def _from_config(cls, config: MaxMessageTerminationConfig) -> Self:+ return cls(max_messages=config.max_messages)+-class TextMentionTermination(TerminationCondition):+class TextMentionTerminationConfig(BaseModel):+ text: str+++class TextMentionTermination(TerminationCondition, Component[TextMentionTerminationConfig]):"""Terminate the conversation if a specific text is mentioned.+Args:text: The text to look for in the messages."""+ component_type = "termination"+ component_config_schema = TextMentionTerminationConfig+ component_provider_override = "autogen_agentchat.conditions.TextMentionTermination"+def __init__(self, text: str) -> None:self._text = textself._terminated = False@@ -90,8 +133,21 @@ class TextMentionTermination(TerminationCondition):async def reset(self) -> None:self._terminated = False+ def _to_config(self) -> TextMentionTerminationConfig:+ return TextMentionTerminationConfig(text=self._text)++ @classmethod+ def _from_config(cls, config: TextMentionTerminationConfig) -> Self:+ return cls(text=config.text)+-class TokenUsageTermination(TerminationCondition):+class TokenUsageTerminationConfig(BaseModel):+ max_total_token: int | None+ max_prompt_token: int | None+ max_completion_token: int | None+++class TokenUsageTermination(TerminationCondition, Component[TokenUsageTerminationConfig]):"""Terminate the conversation if a token usage limit is reached.Args:@@ -103,6 +159,10 @@ class TokenUsageTermination(TerminationCondition):ValueError: If none of max_total_token, max_prompt_token, or max_completion_token is provided."""+ component_type = "termination"+ component_config_schema = TokenUsageTerminationConfig+ component_provider_override = "autogen_agentchat.conditions.TokenUsageTermination"+def __init__(self,max_total_token: int | None = None,@@ -146,8 +206,27 @@ class TokenUsageTermination(TerminationCondition):self._prompt_token_count = 0self._completion_token_count = 0+ def _to_config(self) -> TokenUsageTerminationConfig:+ return TokenUsageTerminationConfig(+ max_total_token=self._max_total_token,+ max_prompt_token=self._max_prompt_token,+ max_completion_token=self._max_completion_token,+ )++ @classmethod+ def _from_config(cls, config: TokenUsageTerminationConfig) -> Self:+ return cls(+ max_total_token=config.max_total_token,+ max_prompt_token=config.max_prompt_token,+ max_completion_token=config.max_completion_token,+ )+++class HandoffTerminationConfig(BaseModel):+ target: str-class HandoffTermination(TerminationCondition):++class HandoffTermination(TerminationCondition, Component[HandoffTerminationConfig]):"""Terminate the conversation if a :class:`~autogen_agentchat.messages.HandoffMessage`with the given target is received.@@ -155,6 +234,10 @@ class HandoffTermination(TerminationCondition):target (str): The target of the handoff message."""+ component_type = "termination"+ component_config_schema = HandoffTerminationConfig+ component_provider_override = "autogen_agentchat.conditions.HandoffTermination"+def __init__(self, target: str) -> None:self._terminated = Falseself._target = target@@ -177,14 +260,29 @@ class HandoffTermination(TerminationCondition):async def reset(self) -> None:self._terminated = False+ def _to_config(self) -> HandoffTerminationConfig:+ return HandoffTerminationConfig(target=self._target)++ @classmethod+ def _from_config(cls, config: HandoffTerminationConfig) -> Self:+ return cls(target=config.target)-class TimeoutTermination(TerminationCondition):++class TimeoutTerminationConfig(BaseModel):+ timeout_seconds: float+++class TimeoutTermination(TerminationCondition, Component[TimeoutTerminationConfig]):"""Terminate the conversation after a specified duration has passed.Args:timeout_seconds: The maximum duration in seconds before terminating the conversation."""+ component_type = "termination"+ component_config_schema = TimeoutTerminationConfig+ component_provider_override = "autogen_agentchat.conditions.TimeoutTermination"+def __init__(self, timeout_seconds: float) -> None:self._timeout_seconds = timeout_secondsself._start_time = time.monotonic()@@ -209,8 +307,19 @@ class TimeoutTermination(TerminationCondition):self._start_time = time.monotonic()self._terminated = False+ def _to_config(self) -> TimeoutTerminationConfig:+ return TimeoutTerminationConfig(timeout_seconds=self._timeout_seconds)++ @classmethod+ def _from_config(cls, config: TimeoutTerminationConfig) -> Self:+ return cls(timeout_seconds=config.timeout_seconds)-class ExternalTermination(TerminationCondition):++class ExternalTerminationConfig(BaseModel):+ pass+++class ExternalTermination(TerminationCondition, Component[ExternalTerminationConfig]):"""A termination condition that is externally controlledby calling the :meth:`set` method.@@ -230,6 +339,10 @@ class ExternalTermination(TerminationCondition):"""+ component_type = "termination"+ component_config_schema = ExternalTerminationConfig+ component_provider_override = "autogen_agentchat.conditions.ExternalTermination"+def __init__(self) -> None:self._terminated = Falseself._setted = False@@ -254,8 +367,19 @@ class ExternalTermination(TerminationCondition):self._terminated = Falseself._setted = False+ def _to_config(self) -> ExternalTerminationConfig:+ return ExternalTerminationConfig()++ @classmethod+ def _from_config(cls, config: ExternalTerminationConfig) -> Self:+ return cls()+-class SourceMatchTermination(TerminationCondition):+class SourceMatchTerminationConfig(BaseModel):+ sources: List[str]+++class SourceMatchTermination(TerminationCondition, Component[SourceMatchTerminationConfig]):"""Terminate the conversation after a specific source responds.Args:@@ -265,6 +389,10 @@ class SourceMatchTermination(TerminationCondition):TerminatedException: If the termination condition has already been reached."""+ component_type = "termination"+ component_config_schema = SourceMatchTerminationConfig+ component_provider_override = "autogen_agentchat.conditions.SourceMatchTermination"+def __init__(self, sources: List[str]) -> None:self._sources = sourcesself._terminated = False@@ -286,3 +414,10 @@ class SourceMatchTermination(TerminationCondition):async def reset(self) -> None:self._terminated = False++ def _to_config(self) -> SourceMatchTerminationConfig:+ return SourceMatchTerminationConfig(sources=self._sources)++ @classmethod+ def _from_config(cls, config: SourceMatchTerminationConfig) -> Self:+ return cls(sources=config.sources)diff --git a/python/packages/autogen-agentchat/tests/test_declarative_components.py b/python/packages/autogen-agentchat/tests/test_declarative_components.pynew file mode 100644index 000000000..35cf54f86--- /dev/null+++ b/python/packages/autogen-agentchat/tests/test_declarative_components.py@@ -0,0 +1,94 @@+import pytest+from autogen_agentchat.base import AndTerminationCondition+from autogen_agentchat.conditions import (+ ExternalTermination,+ HandoffTermination,+ MaxMessageTermination,+ SourceMatchTermination,+ StopMessageTermination,+ TextMentionTermination,+ TimeoutTermination,+ TokenUsageTermination,+)+from autogen_core import ComponentLoader, ComponentModel+++async def test_termination_declarative() -> None:+ """Test that termination conditions can be declared and serialized properly."""+ # Create basic termination conditions+ max_term = MaxMessageTermination(5)+ stop_term = StopMessageTermination()+ text_term = TextMentionTermination("stop")+ token_term = TokenUsageTermination(max_total_token=100, max_prompt_token=50, max_completion_token=100)+ handoff_term = HandoffTermination(target="human")+ timeout_term = TimeoutTermination(timeout_seconds=30)+ external_term = ExternalTermination()+ source_term = SourceMatchTermination(sources=["human"])++ # Test basic serialization+ max_config = max_term.dump_component()+ assert isinstance(max_config, ComponentModel)+ assert max_config.provider == "autogen_agentchat.conditions.MaxMessageTermination"+ assert max_config.config.get("max_messages") == 5++ # Test serialization of new conditions+ text_config = text_term.dump_component()+ assert text_config.provider == "autogen_agentchat.conditions.TextMentionTermination"+ assert text_config.config.get("text") == "stop"++ token_config = token_term.dump_component()+ assert token_config.provider == "autogen_agentchat.conditions.TokenUsageTermination"+ assert token_config.config.get("max_total_token") == 100++ handoff_config = handoff_term.dump_component()+ assert handoff_config.provider == "autogen_agentchat.conditions.HandoffTermination"+ assert handoff_config.config.get("target") == "human"++ timeout_config = timeout_term.dump_component()+ assert timeout_config.provider == "autogen_agentchat.conditions.TimeoutTermination"+ assert timeout_config.config.get("timeout_seconds") == 30++ external_config = external_term.dump_component()+ assert external_config.provider == "autogen_agentchat.conditions.ExternalTermination"++ source_config = source_term.dump_component()+ assert source_config.provider == "autogen_agentchat.conditions.SourceMatchTermination"+ assert source_config.config.get("sources") == ["human"]++ # Test basic deserialization+ loaded_max = ComponentLoader.load_component(max_config, MaxMessageTermination)+ assert isinstance(loaded_max, MaxMessageTermination)++ # Test deserialization of new conditions+ loaded_text = ComponentLoader.load_component(text_config, TextMentionTermination)+ assert isinstance(loaded_text, TextMentionTermination)++ loaded_token = ComponentLoader.load_component(token_config, TokenUsageTermination)+ assert isinstance(loaded_token, TokenUsageTermination)++ loaded_handoff = ComponentLoader.load_component(handoff_config, HandoffTermination)+ assert isinstance(loaded_handoff, HandoffTermination)++ loaded_timeout = ComponentLoader.load_component(timeout_config, TimeoutTermination)+ assert isinstance(loaded_timeout, TimeoutTermination)++ loaded_external = ComponentLoader.load_component(external_config, ExternalTermination)+ assert isinstance(loaded_external, ExternalTermination)++ loaded_source = ComponentLoader.load_component(source_config, SourceMatchTermination)+ assert isinstance(loaded_source, SourceMatchTermination)++ # Test composition with new conditions+ composite_term = (max_term | stop_term) & (token_term | handoff_term)+ composite_config = composite_term.dump_component()++ assert composite_config.provider == "autogen_agentchat.base.AndTerminationCondition"+ conditions = composite_config.config["conditions"]+ assert len(conditions) == 2+ assert conditions[0]["provider"] == "autogen_agentchat.base.OrTerminationCondition"+ assert conditions[1]["provider"] == "autogen_agentchat.base.OrTerminationCondition"++ # Test loading complex composition+ loaded_composite = ComponentLoader.load_component(composite_config)+ assert isinstance(loaded_composite, AndTerminationCondition)diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.mdindex 9754bd8ca..7a764c4c7 100644--- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md@@ -91,6 +91,7 @@ tutorial/human-in-the-looptutorial/terminationtutorial/custom-agentstutorial/state+tutorial/declarative``````{toctree}diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/declarative.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/declarative.ipynbnew file mode 100644index 000000000..274135c11--- /dev/null+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/declarative.ipynb@@ -0,0 +1,119 @@+{+ "cells": [+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "# Declarative Components \n",+ "\n",+ "AutoGen provides a declarative {py:class}`~autogen_core.Component` configuration class that defines behaviours for declarative import/export. This is useful for debugging, visualizing, and even for sharing your work with others. In this notebook, we will demonstrate how to export a declarative representation of a multiagent team in the form of a JSON file. \n",+ "\n",+ "\n",+ "```{note}\n",+ "This is work in progress\n",+ "``` \n",+ "\n",+ "We will be implementing declarative support for the following components:\n",+ "\n",+ "- Termination conditions ✔️\n",+ "- Tools \n",+ "- Agents \n",+ "- Teams \n",+ "\n",+ "\n",+ "### Termination Condition Example \n",+ "\n",+ "In the example below, we will define termination conditions (a part of an agent team) in python, export this to a dictionary/json and also demonstrate how the termination condition object can be loaded from the dictionary/json. \n",+ " "+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 1,+ "metadata": {},+ "outputs": [],+ "source": [+ "from autogen_agentchat.conditions import MaxMessageTermination, StopMessageTermination\n",+ "\n",+ "max_termination = MaxMessageTermination(5)\n",+ "stop_termination = StopMessageTermination()"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 2,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "provider='autogen_agentchat.conditions.MaxMessageTermination' component_type='termination' version=1 component_version=1 description=None config={'max_messages': 5}\n"+ ]+ }+ ],+ "source": [+ "print(max_termination.dump_component())"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 3,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "{'provider': 'autogen_agentchat.conditions.MaxMessageTermination', 'component_type': 'termination', 'version': 1, 'component_version': 1, 'description': None, 'config': {'max_messages': 5}}\n"+ ]+ }+ ],+ "source": [+ "print(max_termination.dump_component().model_dump())"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 4,+ "metadata": {},+ "outputs": [+ {+ "data": {+ "text/plain": [+ "ComponentModel(provider='autogen_agentchat.base.OrTerminationCondition', component_type='termination', version=1, component_version=1, description=None, config={'conditions': [{'provider': 'autogen_agentchat.conditions.MaxMessageTermination', 'component_type': 'termination', 'version': 1, 'component_version': 1, 'config': {'max_messages': 5}}, {'provider': 'autogen_agentchat.conditions.StopMessageTermination', 'component_type': 'termination', 'version': 1, 'component_version': 1, 'config': {}}]})"+ ]+ },+ "execution_count": 4,+ "metadata": {},+ "output_type": "execute_result"+ }+ ],+ "source": [+ "or_termination = max_termination | stop_termination\n",+ "or_termination.dump_component()"+ ]+ }+ ],+ "metadata": {+ "kernelspec": {+ "display_name": ".venv",+ "language": "python",+ "name": "python3"+ },+ "language_info": {+ "codemirror_mode": {+ "name": "ipython",+ "version": 3+ },+ "file_extension": ".py",+ "mimetype": "text/x-python",+ "name": "python",+ "nbconvert_exporter": "python",+ "pygments_lexer": "ipython3",+ "version": "3.11.9"+ }+ },+ "nbformat": 4,+ "nbformat_minor": 2+}