A programming framework for agentic AI
Introduce AgentTool and TeamTool (#5924)
Eitan Yarmush1035065c4e1f
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/base/_task.py b/python/packages/autogen-agentchat/src/autogen_agentchat/base/_task.pyindex 950ebf0c5..747535c90 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/base/_task.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/base/_task.py@@ -1,13 +1,12 @@-from dataclasses import dataclassfrom typing import AsyncGenerator, Protocol, Sequencefrom autogen_core import CancellationToken+from pydantic import BaseModelfrom ..messages import BaseAgentEvent, BaseChatMessage-@dataclass-class TaskResult:+class TaskResult(BaseModel):"""Result of running a task."""messages: Sequence[BaseAgentEvent | BaseChatMessage]diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/tools/__init__.py b/python/packages/autogen-agentchat/src/autogen_agentchat/tools/__init__.pynew file mode 100644index 000000000..9884ddcd8--- /dev/null+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/tools/__init__.py@@ -0,0 +1,4 @@+from ._agent import AgentTool+from ._team import TeamTool++__all__ = ["AgentTool", "TeamTool"]diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/tools/_agent.py b/python/packages/autogen-agentchat/src/autogen_agentchat/tools/_agent.pynew file mode 100644index 000000000..3d6ff9160--- /dev/null+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/tools/_agent.py@@ -0,0 +1,71 @@+from autogen_core import Component, ComponentModel+from pydantic import BaseModel+from typing_extensions import Self++from autogen_agentchat.agents import BaseChatAgent++from ._task_runner_tool import TaskRunnerTool+++class AgentToolConfig(BaseModel):+ """Configuration for the AgentTool."""++ agent: ComponentModel+++class AgentTool(TaskRunnerTool, Component[AgentToolConfig]):+ """Tool that can be used to run a task using an agent.++ The tool returns the result of the task execution as a :class:`~autogen_agentchat.base.TaskResult` object.++ Args:+ agent (BaseChatAgent): The agent to be used for running the task.++ Example:++ .. code-block:: python++ import asyncio++ from autogen_agentchat.agents import AssistantAgent+ from autogen_agentchat.tools import AgentTool+ from autogen_agentchat.ui import Console+ from autogen_ext.models.openai import OpenAIChatCompletionClient+++ async def main() -> None:+ model_client = OpenAIChatCompletionClient(model="gpt-4")+ writer = AssistantAgent(+ name="writer",+ description="A writer agent for generating text.",+ model_client=model_client,+ system_message="Write well.",+ )+ writer_tool = AgentTool(agent=writer)+ assistant = AssistantAgent(+ name="assistant",+ model_client=model_client,+ tools=[writer_tool],+ system_message="You are a helpful assistant.",+ )+ await Console(assistant.run_stream(task="Write a poem about the sea."))+++ asyncio.run(main())+ """++ component_config_schema = AgentToolConfig+ component_provider_override = "autogen_agentchat.tools.AgentTool"++ def __init__(self, agent: BaseChatAgent) -> None:+ self._agent = agent+ super().__init__(agent, agent.name, agent.description)++ def _to_config(self) -> AgentToolConfig:+ return AgentToolConfig(+ agent=self._agent.dump_component(),+ )++ @classmethod+ def _from_config(cls, config: AgentToolConfig) -> Self:+ return cls(BaseChatAgent.load_component(config.agent))diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/tools/_task_runner_tool.py b/python/packages/autogen-agentchat/src/autogen_agentchat/tools/_task_runner_tool.pynew file mode 100644index 000000000..5aa8672d7--- /dev/null+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/tools/_task_runner_tool.py@@ -0,0 +1,51 @@+from abc import ABC+from typing import Annotated, Any, List, Mapping++from autogen_core import CancellationToken+from autogen_core.tools import BaseTool+from pydantic import BaseModel++from ..agents import BaseChatAgent+from ..base import TaskResult+from ..messages import BaseChatMessage+from ..teams import BaseGroupChat+++class TaskRunnerToolArgs(BaseModel):+ """Input for the TaskRunnerTool."""++ task: Annotated[str, "The task to be executed."]+++class TaskRunnerTool(BaseTool[TaskRunnerToolArgs, TaskResult], ABC):+ """An base class for tool that can be used to run a task using a team or an agent."""++ component_type = "tool"++ def __init__(self, task_runner: BaseGroupChat | BaseChatAgent, name: str, description: str) -> None:+ self._task_runner = task_runner+ super().__init__(+ args_type=TaskRunnerToolArgs,+ return_type=TaskResult,+ name=name,+ description=description,+ )++ async def run(self, args: TaskRunnerToolArgs, cancellation_token: CancellationToken) -> TaskResult:+ return await self._task_runner.run(task=args.task, cancellation_token=cancellation_token)++ def return_value_as_string(self, value: TaskResult) -> str:+ """Convert the task result to a string."""+ parts: List[str] = []+ for message in value.messages:+ if isinstance(message, BaseChatMessage):+ if message.source == "user":+ continue+ parts.append(f"{message.source}: {message.to_model_text()}")+ return "\n\n".join(parts)++ async def save_state_json(self) -> Mapping[str, Any]:+ return await self._task_runner.save_state()++ async def load_state_json(self, state: Mapping[str, Any]) -> None:+ await self._task_runner.load_state(state)diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/tools/_team.py b/python/packages/autogen-agentchat/src/autogen_agentchat/tools/_team.pynew file mode 100644index 000000000..c7d9e6025--- /dev/null+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/tools/_team.py@@ -0,0 +1,45 @@+from autogen_core import Component, ComponentModel+from pydantic import BaseModel+from typing_extensions import Self++from autogen_agentchat.teams import BaseGroupChat++from ._task_runner_tool import TaskRunnerTool+++class TeamToolConfig(BaseModel):+ """Configuration for the TeamTool."""++ name: str+ description: str+ team: ComponentModel+++class TeamTool(TaskRunnerTool, Component[TeamToolConfig]):+ """Tool that can be used to run a task.++ The tool returns the result of the task execution as a :class:`~autogen_agentchat.base.TaskResult` object.++ Args:+ team (BaseGroupChat): The team to be used for running the task.+ name (str): The name of the tool.+ description (str): The description of the tool.+ """++ component_config_schema = TeamToolConfig+ component_provider_override = "autogen_agentchat.tools.TeamTool"++ def __init__(self, team: BaseGroupChat, name: str, description: str) -> None:+ self._team = team+ super().__init__(team, name, description)++ def _to_config(self) -> TeamToolConfig:+ return TeamToolConfig(+ name=self._name,+ description=self._description,+ team=self._team.dump_component(),+ )++ @classmethod+ def _from_config(cls, config: TeamToolConfig) -> Self:+ return cls(BaseGroupChat.load_component(config.team), config.name, config.description)diff --git a/python/packages/autogen-agentchat/tests/test_group_chat.py b/python/packages/autogen-agentchat/tests/test_group_chat.pyindex 9cf9a1b58..947d9595b 100644--- a/python/packages/autogen-agentchat/tests/test_group_chat.py+++ b/python/packages/autogen-agentchat/tests/test_group_chat.py@@ -82,6 +82,16 @@ class _EchoAgent(BaseChatAgent):async def on_reset(self, cancellation_token: CancellationToken) -> None:self._last_message = None+ async def save_state(self) -> Mapping[str, Any]:+ return {+ "last_message": self._last_message,+ "total_messages": self._total_messages,+ }++ async def load_state(self, state: Mapping[str, Any]) -> None:+ self._last_message = state.get("last_message")+ self._total_messages = state.get("total_messages", 0)+class _FlakyAgent(BaseChatAgent):def __init__(self, name: str, description: str) -> None:diff --git a/python/packages/autogen-agentchat/tests/test_task_runner_tool.py b/python/packages/autogen-agentchat/tests/test_task_runner_tool.pynew file mode 100644index 000000000..3d3d58b7d--- /dev/null+++ b/python/packages/autogen-agentchat/tests/test_task_runner_tool.py@@ -0,0 +1,100 @@+import pytest+from autogen_agentchat.agents import AssistantAgent+from autogen_agentchat.conditions import MaxMessageTermination+from autogen_agentchat.teams import RoundRobinGroupChat+from autogen_agentchat.tools import AgentTool, TeamTool+from autogen_core import (+ CancellationToken,+)+from autogen_ext.models.replay import ReplayChatCompletionClient+from test_group_chat import _EchoAgent # type: ignore[reportPrivateUsage]+++async def test_agent_tool_run() -> None:+ """Test running a task with AgentTool."""+ mock_chat_agent = _EchoAgent("Mock_Agent", "A mock agent for testing")+ tool = AgentTool(agent=mock_chat_agent)+ task_result = await tool.run_json({"task": "Test task"}, cancellation_token=CancellationToken())+ assert task_result.messages[1].content == "Test task"+++async def test_agent_tool_state() -> None:+ """Test saving state of AgentTool."""+ mock_chat_agent = _EchoAgent("Mock_Agent", "A mock agent for testing")+ tool = AgentTool(agent=mock_chat_agent)+ state = await tool.save_state_json()+ assert state == {"last_message": None, "total_messages": 0}++ await tool.run_json({"task": "Test task"}, cancellation_token=CancellationToken())+ state = await tool.save_state_json()+ assert state == {"last_message": "Test task", "total_messages": 1}++ mock_chat_agent_2 = _EchoAgent("Mock_Agent_2", "A mock agent for testing")+ tool_2 = AgentTool(agent=mock_chat_agent_2)+ await tool_2.load_state_json(state)+ state2 = await tool_2.save_state_json()+ assert state2 == {"last_message": "Test task", "total_messages": 1}+++def test_agent_tool_component() -> None:+ """Test serialization of AgentTool to config."""+ model_client = ReplayChatCompletionClient(["test"])+ agent = AssistantAgent(name="assistant", model_client=model_client)+ tool = AgentTool(agent=agent)+ config = tool.dump_component()+ assert config.provider == "autogen_agentchat.tools.AgentTool"++ tool2 = AgentTool.load_component(config)+ assert isinstance(tool2, AgentTool)+ assert tool2.name == agent.name+ assert tool2.description == agent.description+++async def test_team_tool() -> None:+ """Test running a task with TeamTool."""+ agent1 = _EchoAgent("Agent1", "An agent for testing")+ agent2 = _EchoAgent("Agent2", "Another agent for testing")+ termination = MaxMessageTermination(max_messages=3)+ team = RoundRobinGroupChat(+ [agent1, agent2],+ termination_condition=termination,+ )+ tool = TeamTool(team=team, name="Team Tool", description="A team tool for testing")+ task_result = await tool.run_json(args={"task": "test task"}, cancellation_token=CancellationToken())+ assert task_result.messages[1].content == "test task"+ assert task_result.messages[2].content == "test task"++ # Validate state.+ state = await tool.save_state_json()+ # Reload the state and check if it matches.+ agent2 = _EchoAgent("Agent1", "Another agent for testing")+ agent3 = _EchoAgent("Agent2", "Another agent for testing")+ team2 = RoundRobinGroupChat(+ [agent2, agent3],+ termination_condition=termination,+ )+ tool2 = TeamTool(team=team2, name="Team Tool", description="A team tool for testing")+ await tool2.load_state_json(state)+ state2 = await tool2.save_state_json()+ assert state == state2+++async def test_team_tool_component() -> None:+ """Test serialization of TeamTool to config."""+ model_client = ReplayChatCompletionClient(["test"])+ agent1 = AssistantAgent(name="assistant1", model_client=model_client)+ agent2 = AssistantAgent(name="assistant2", model_client=model_client)+ team = RoundRobinGroupChat([agent1, agent2])+ tool = TeamTool(team=team, name="Team Tool", description="A team tool for testing")+ config = tool.dump_component()+ assert config.provider == "autogen_agentchat.tools.TeamTool"++ tool2 = TeamTool.load_component(config)+ assert isinstance(tool2, TeamTool)+ assert tool2.name == "Team Tool"+ assert tool2.description == "A team tool for testing"+ assert isinstance(tool2._team, RoundRobinGroupChat) # type: ignore[reportPrivateUsage]diff --git a/python/packages/autogen-core/docs/src/reference/index.md b/python/packages/autogen-core/docs/src/reference/index.mdindex e0aecafb4..98988b791 100644--- a/python/packages/autogen-core/docs/src/reference/index.md+++ b/python/packages/autogen-core/docs/src/reference/index.md@@ -14,6 +14,7 @@ myst:python/autogen_agentchatpython/autogen_agentchat.messagespython/autogen_agentchat.agents+python/autogen_agentchat.toolspython/autogen_agentchat.teamspython/autogen_agentchat.basepython/autogen_agentchat.conditionsdiff --git a/python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.tools.rst b/python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.tools.rstnew file mode 100644index 000000000..3a7f5f125--- /dev/null+++ b/python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.tools.rst@@ -0,0 +1,8 @@+autogen\_agentchat.tools+========================+++.. automodule:: autogen_agentchat.tools+ :members:+ :undoc-members:+ :show-inheritance:diff --git a/python/packages/autogen-core/src/autogen_core/tools/_base.py b/python/packages/autogen-core/src/autogen_core/tools/_base.pyindex eb8909ada..ea00c50f9 100644--- a/python/packages/autogen-core/src/autogen_core/tools/_base.py+++ b/python/packages/autogen-core/src/autogen_core/tools/_base.py@@ -54,9 +54,9 @@ class Tool(Protocol):async def run_json(self, args: Mapping[str, Any], cancellation_token: CancellationToken) -> Any: ...- def save_state_json(self) -> Mapping[str, Any]: ...+ async def save_state_json(self) -> Mapping[str, Any]: ...- def load_state_json(self, state: Mapping[str, Any]) -> None: ...+ async def load_state_json(self, state: Mapping[str, Any]) -> None: ...ArgsT = TypeVar("ArgsT", bound=BaseModel, contravariant=True)@@ -169,10 +169,10 @@ class BaseTool(ABC, Tool, Generic[ArgsT, ReturnT], ComponentBase[BaseModel]):return return_value- def save_state_json(self) -> Mapping[str, Any]:+ async def save_state_json(self) -> Mapping[str, Any]:return {}- def load_state_json(self, state: Mapping[str, Any]) -> None:+ async def load_state_json(self, state: Mapping[str, Any]) -> None:pass@@ -196,8 +196,8 @@ class BaseToolWithState(BaseTool[ArgsT, ReturnT], ABC, Generic[ArgsT, ReturnT, S@abstractmethoddef load_state(self, state: StateT) -> None: ...- def save_state_json(self) -> Mapping[str, Any]:+ async def save_state_json(self) -> Mapping[str, Any]:return self.save_state().model_dump()- def load_state_json(self, state: Mapping[str, Any]) -> None:+ async def load_state_json(self, state: Mapping[str, Any]) -> None:self.load_state(self._state_type.model_validate(state))