Skip to content

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.py
index 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 dataclass
from typing import AsyncGenerator, Protocol, Sequence
from autogen_core import CancellationToken
+from pydantic import BaseModel
from ..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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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.md
index 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_agentchat
python/autogen_agentchat.messages
python/autogen_agentchat.agents
+python/autogen_agentchat.tools
python/autogen_agentchat.teams
python/autogen_agentchat.base
python/autogen_agentchat.conditions
diff --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.rst
new file mode 100644
index 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.py
index 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
@abstractmethod
def 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))