Skip to content

A programming framework for agentic AI

Overhaul tools (#53)

Jack Gerritsab420cc9eeb0
diff --git a/examples/futures.py b/examples/futures.py
index 948075798..765fabfdc 100644
--- a/examples/futures.py
+++ b/examples/futures.py
@@ -2,7 +2,7 @@ import asyncio
from dataclasses import dataclass
from agnext.application import SingleThreadedAgentRuntime
-from agnext.components.type_routed_agent import TypeRoutedAgent, message_handler
+from agnext.components import TypeRoutedAgent, message_handler
from agnext.core import Agent, AgentRuntime, CancellationToken
diff --git a/examples/orchestrator.py b/examples/orchestrator.py
index 4f86ced7a..e38b7cbb3 100644
--- a/examples/orchestrator.py
+++ b/examples/orchestrator.py
@@ -3,7 +3,7 @@ import asyncio
import json
import logging
import os
-from typing import Annotated, Callable
+from typing import Callable
import openai
from agnext.application import (
@@ -13,19 +13,44 @@ from agnext.chat.agents.chat_completion_agent import ChatCompletionAgent
from agnext.chat.agents.oai_assistant import OpenAIAssistantAgent
from agnext.chat.patterns.orchestrator_chat import OrchestratorChat
from agnext.chat.types import TextMessage
-from agnext.components.function_executor._impl.in_process_function_executor import (
- InProcessFunctionExecutor,
-)
from agnext.components.models import OpenAI, SystemMessage
-from agnext.core import Agent, AgentRuntime
+from agnext.components.tools import BaseTool
+from agnext.core import Agent, AgentRuntime, CancellationToken
from agnext.core.intervention import DefaultInterventionHandler, DropMessage
-from tavily import TavilyClient
+from pydantic import BaseModel, Field
+from tavily import TavilyClient # type: ignore
from typing_extensions import Any, override
logging.basicConfig(level=logging.WARNING)
logging.getLogger("agnext").setLevel(logging.DEBUG)
+class SearchQuery(BaseModel):
+ query: str = Field(description="The search query.")
+
+
+class SearchResult(BaseModel):
+ result: str = Field(description="The search results.")
+
+
+class SearchTool(BaseTool[SearchQuery, SearchResult]):
+ def __init__(self) -> None:
+ super().__init__(
+ args_type=SearchQuery,
+ return_type=SearchResult,
+ name="search",
+ description="Search the web.",
+ )
+
+ async def run(self, args: SearchQuery, cancellation_token: CancellationToken) -> SearchResult:
+ client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY")) # type: ignore
+ result = await asyncio.create_task(client.search(args.query)) # type: ignore
+ if result:
+ return SearchResult(result=json.dumps(result, indent=2, ensure_ascii=False))
+
+ return SearchResult(result="No results found.")
+
+
class LoggingHandler(DefaultInterventionHandler): # type: ignore
send_color = "\033[31m"
response_color = "\033[34m"
@@ -76,16 +101,6 @@ def software_development(runtime: AgentRuntime) -> OrchestratorChat: # type: ig
thread_id=tester_oai_thread.id,
)
- def search(query: Annotated[str, "The search query."]) -> Annotated[str, "The search results."]:
- """Search the web."""
- client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))
- result = client.search(query) # type: ignore
- if result:
- return json.dumps(result, indent=2, ensure_ascii=False) # type: ignore
- return "No results found."
-
- function_executor = InProcessFunctionExecutor(functions=[search])
-
product_manager = ChatCompletionAgent(
name="ProductManager",
description="A product manager that performs research and comes up with specs.",
@@ -95,7 +110,7 @@ def software_development(runtime: AgentRuntime) -> OrchestratorChat: # type: ig
SystemMessage("You can use the search tool to find information on the web."),
],
model_client=OpenAI(model="gpt-4-turbo"),
- function_executor=function_executor,
+ tools=[SearchTool()],
)
planner = ChatCompletionAgent(
diff --git a/pyproject.toml b/pyproject.toml
index 693431d50..0a6dc535a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -75,7 +75,7 @@ disallow_untyped_decorators = true
disallow_any_unimported = true
[tool.pyright]
-include = ["src", "tests"]
+include = ["src", "tests", "examples"]
typeCheckingMode = "strict"
reportUnnecessaryIsInstance = false
reportMissingTypeStubs = false
diff --git a/src/agnext/chat/agents/chat_completion_agent.py b/src/agnext/chat/agents/chat_completion_agent.py
index 80ac13c26..6fac52817 100644
--- a/src/agnext/chat/agents/chat_completion_agent.py
+++ b/src/agnext/chat/agents/chat_completion_agent.py
@@ -1,6 +1,6 @@
import asyncio
import json
-from typing import Any, Coroutine, Dict, List, Mapping, Tuple
+from typing import Any, Coroutine, Dict, List, Mapping, Sequence, Tuple
from agnext.chat.agents.base import BaseChatAgent
from agnext.chat.types import (
@@ -12,13 +12,13 @@ from agnext.chat.types import (
TextMessage,
)
from agnext.chat.utils import convert_messages_to_llm_messages
-from agnext.components.function_executor import FunctionExecutor
-from agnext.components.models import FunctionExecutionResult, FunctionExecutionResultMessage, ModelClient, SystemMessage
-from agnext.components.type_routed_agent import TypeRoutedAgent, message_handler
-from agnext.components.types import (
+from agnext.components import (
FunctionCall,
- FunctionSignature,
+ TypeRoutedAgent,
+ message_handler,
)
+from agnext.components.models import FunctionExecutionResult, FunctionExecutionResultMessage, ModelClient, SystemMessage
+from agnext.components.tools import Tool
from agnext.core import AgentRuntime, CancellationToken
@@ -30,13 +30,13 @@ class ChatCompletionAgent(BaseChatAgent, TypeRoutedAgent):
runtime: AgentRuntime,
system_messages: List[SystemMessage],
model_client: ModelClient,
- function_executor: FunctionExecutor | None = None,
+ tools: Sequence[Tool] = [],
) -> None:
super().__init__(name, description, runtime)
self._system_messages = system_messages
self._client = model_client
self._chat_messages: List[Message] = []
- self._function_executor = function_executor
+ self._tools = tools
@message_handler()
async def on_text_message(self, message: TextMessage, cancellation_token: CancellationToken) -> None:
@@ -52,15 +52,10 @@ class ChatCompletionAgent(BaseChatAgent, TypeRoutedAgent):
async def on_respond_now(
self, message: RespondNow, cancellation_token: CancellationToken
) -> TextMessage | FunctionCallMessage:
- # Get function signatures.
- function_signatures: List[FunctionSignature] = (
- [] if self._function_executor is None else list(self._function_executor.function_signatures)
- )
-
# Get a response from the model.
response = await self._client.create(
self._system_messages + convert_messages_to_llm_messages(self._chat_messages, self.name),
- functions=function_signatures,
+ tools=self._tools,
json_output=message.response_format == ResponseFormat.json_object,
)
@@ -68,7 +63,7 @@ class ChatCompletionAgent(BaseChatAgent, TypeRoutedAgent):
# tool calls, iterate with itself until we get a response that is not a
# list of tool calls.
while (
- self._function_executor is not None
+ len(self._tools) > 0
and isinstance(response.content, list)
and all(isinstance(x, FunctionCall) for x in response.content)
):
@@ -81,7 +76,7 @@ class ChatCompletionAgent(BaseChatAgent, TypeRoutedAgent):
# Make an assistant message from the response.
response = await self._client.create(
self._system_messages + convert_messages_to_llm_messages(self._chat_messages, self.name),
- functions=function_signatures,
+ tools=self._tools,
json_output=message.response_format == ResponseFormat.json_object,
)
@@ -105,8 +100,8 @@ class ChatCompletionAgent(BaseChatAgent, TypeRoutedAgent):
async def on_tool_call_message(
self, message: FunctionCallMessage, cancellation_token: CancellationToken
) -> FunctionExecutionResultMessage:
- if self._function_executor is None:
- raise ValueError("Function executor is not set.")
+ if len(self._tools) == 0:
+ raise ValueError("No tools available")
# Add a tool call message.
self._chat_messages.append(message)
@@ -127,7 +122,9 @@ class ChatCompletionAgent(BaseChatAgent, TypeRoutedAgent):
)
continue
# Execute the function.
- future = self.execute_function(function_call.name, arguments, function_call.id)
+ future = self.execute_function(
+ function_call.name, arguments, function_call.id, cancellation_token=cancellation_token
+ )
# Append the async result.
execution_futures.append(future)
if execution_futures:
@@ -146,14 +143,25 @@ class ChatCompletionAgent(BaseChatAgent, TypeRoutedAgent):
# Return the results.
return tool_call_result_msg
- async def execute_function(self, name: str, args: Dict[str, Any], call_id: str) -> Tuple[str, str]:
- if self._function_executor is None:
- raise ValueError("Function executor is not set.")
+ async def execute_function(
+ self, name: str, args: Dict[str, Any], call_id: str, cancellation_token: CancellationToken
+ ) -> Tuple[str, str]:
+ # Find tool
+ tool = next((t for t in self._tools if t.name == name), None)
+ if tool is None:
+ raise ValueError(f"Tool {name} not found.")
try:
- result = await self._function_executor.execute_function(name, args)
+ result = await tool.run_json(args, cancellation_token)
+ result_json_or_str = result.model_dump()
+ if isinstance(result, dict):
+ result_str = json.dumps(result_json_or_str)
+ elif isinstance(result_json_or_str, str):
+ result_str = result_json_or_str
+ else:
+ raise ValueError(f"Unexpected result type: {type(result)}")
except Exception as e:
- result = f"Error: {str(e)}"
- return (result, call_id)
+ result_str = f"Error: {str(e)}"
+ return (result_str, call_id)
def save_state(self) -> Mapping[str, Any]:
return {
diff --git a/src/agnext/chat/agents/oai_assistant.py b/src/agnext/chat/agents/oai_assistant.py
index 1dd437812..b4bb8439f 100644
--- a/src/agnext/chat/agents/oai_assistant.py
+++ b/src/agnext/chat/agents/oai_assistant.py
@@ -5,7 +5,7 @@ from openai.types.beta import AssistantResponseFormatParam
from agnext.chat.agents.base import BaseChatAgent
from agnext.chat.types import Reset, RespondNow, ResponseFormat, TextMessage
-from agnext.components.type_routed_agent import TypeRoutedAgent, message_handler
+from agnext.components import TypeRoutedAgent, message_handler
from agnext.core import AgentRuntime, CancellationToken
diff --git a/src/agnext/chat/patterns/group_chat.py b/src/agnext/chat/patterns/group_chat.py
index f6498ba52..33d3c8c68 100644
--- a/src/agnext/chat/patterns/group_chat.py
+++ b/src/agnext/chat/patterns/group_chat.py
@@ -1,6 +1,6 @@
from typing import Any, List, Protocol, Sequence
-from ...components.type_routed_agent import TypeRoutedAgent, message_handler
+from ...components import TypeRoutedAgent, message_handler
from ...core import AgentRuntime, CancellationToken
from ..agents.base import BaseChatAgent
from ..types import Reset, RespondNow, TextMessage
diff --git a/src/agnext/chat/patterns/orchestrator_chat.py b/src/agnext/chat/patterns/orchestrator_chat.py
index 420b771cb..6bc9999ff 100644
--- a/src/agnext/chat/patterns/orchestrator_chat.py
+++ b/src/agnext/chat/patterns/orchestrator_chat.py
@@ -1,7 +1,7 @@
import json
from typing import Any, Sequence, Tuple
-from ...components.type_routed_agent import TypeRoutedAgent, message_handler
+from ...components import TypeRoutedAgent, message_handler
from ...core import AgentRuntime, CancellationToken
from ..agents.base import BaseChatAgent
from ..types import Reset, RespondNow, ResponseFormat, TextMessage
diff --git a/src/agnext/chat/types.py b/src/agnext/chat/types.py
index 2c3ba65e2..308f135db 100644
--- a/src/agnext/chat/types.py
+++ b/src/agnext/chat/types.py
@@ -4,9 +4,8 @@ from dataclasses import dataclass, field
from enum import Enum
from typing import List, Union
-from agnext.components.image import Image
+from agnext.components import FunctionCall, Image
from agnext.components.models import FunctionExecutionResultMessage
-from agnext.components.types import FunctionCall
@dataclass(kw_only=True)
diff --git a/src/agnext/components/__init__.py b/src/agnext/components/__init__.py
index 2725f6641..e1bdf5cd7 100644
--- a/src/agnext/components/__init__.py
+++ b/src/agnext/components/__init__.py
@@ -1,3 +1,9 @@
"""
The :mod:`agnext.components` module provides building blocks for creating single agents
"""
+
+from ._image import Image
+from ._type_routed_agent import TypeRoutedAgent, message_handler
+from ._types import FunctionCall
+
+__all__ = ["Image", "TypeRoutedAgent", "message_handler", "FunctionCall"]
diff --git a/src/agnext/components/_function_utils.py b/src/agnext/components/_function_utils.py
index 15cce58c1..4596e3617 100644
--- a/src/agnext/components/_function_utils.py
+++ b/src/agnext/components/_function_utils.py
@@ -4,6 +4,7 @@
import inspect
from logging import getLogger
from typing import (
+ Annotated,
Any,
Callable,
Dict,
@@ -15,10 +16,13 @@ from typing import (
Type,
TypeVar,
Union,
+ get_args,
+ get_origin,
)
-from pydantic import BaseModel, Field
-from typing_extensions import Annotated, Literal
+from pydantic import BaseModel, Field, create_model # type: ignore
+from pydantic_core import PydanticUndefined
+from typing_extensions import Literal
from ._pydantic_compat import evaluate_forwardref, model_dump, type2schema
@@ -125,6 +129,18 @@ class ToolFunction(BaseModel):
function: Annotated[Function, Field(description="Function under tool")]
+def type2description(k: str, v: Union[Annotated[Type[Any], str], Type[Any]]) -> str:
+ # handles Annotated
+ if hasattr(v, "__metadata__"):
+ retval = v.__metadata__[0]
+ if isinstance(retval, str):
+ return retval
+ else:
+ raise ValueError(f"Invalid description {retval} for parameter {k}, should be a string.")
+ else:
+ return k
+
+
def get_parameter_json_schema(k: str, v: Any, default_values: Dict[str, Any]) -> Dict[str, Any]:
"""Get a JSON schema for a parameter as defined by the OpenAI API
@@ -137,17 +153,6 @@ def get_parameter_json_schema(k: str, v: Any, default_values: Dict[str, Any]) ->
A Pydanitc model for the parameter
"""
- def type2description(k: str, v: Union[Annotated[Type[Any], str], Type[Any]]) -> str:
- # handles Annotated
- if hasattr(v, "__metadata__"):
- retval = v.__metadata__[0]
- if isinstance(retval, str):
- return retval
- else:
- raise ValueError(f"Invalid description {retval} for parameter {k}, should be a string.")
- else:
- return k
-
schema = type2schema(v)
if k in default_values:
dv = default_values[k]
@@ -297,3 +302,48 @@ def get_function_schema(f: Callable[..., Any], *, name: Optional[str] = None, de
)
return model_dump(function)
+
+
+def normalize_annotated_type(type_hint: Type[Any]) -> Type[Any]:
+ """Normalize typing.Annotated types to the inner type."""
+ if get_origin(type_hint) is Annotated:
+ # Extract the inner type from Annotated
+ return get_args(type_hint)[0] # type: ignore
+ return type_hint
+
+
+def args_base_model_from_signature(name: str, sig: inspect.Signature) -> Type[BaseModel]:
+ fields: List[tuple[str, Any]] = []
+ for name, param in sig.parameters.items():
+ # This is handled externally
+ if name == "cancellation_token":
+ continue
+
+ if param.annotation is inspect.Parameter.empty:
+ raise ValueError("No annotation")
+
+ type = normalize_annotated_type(param.annotation)
+ description = type2description(name, param.annotation)
+ default_value = param.default if param.default is not inspect.Parameter.empty else PydanticUndefined
+
+ fields.append((name, (type, Field(default=default_value, description=description))))
+
+ return create_model(name, *fields)
+
+
+def return_value_base_model_from_signature(name: str, sig: inspect.Signature) -> Type[BaseModel]:
+ if issubclass(BaseModel, sig.return_annotation):
+ return sig.return_annotation # type: ignore
+
+ fields: List[tuple[str, Any]] = []
+ for name, param in sig.return_annotation:
+ if param.annotation is inspect.Parameter.empty:
+ raise ValueError("No annotation")
+
+ type = normalize_annotated_type(param.annotation)
+ description = type2description(name, param.annotation)
+ default_value = param.default if param.default is not inspect.Parameter.empty else PydanticUndefined
+
+ fields.append((name, (type, Field(default=default_value, description=description))))
+
+ return create_model(name, *fields)
diff --git a/src/agnext/components/image.py b/src/agnext/components/_image.py
similarity index 100%
rename from src/agnext/components/image.py
rename to src/agnext/components/_image.py
diff --git a/src/agnext/components/type_routed_agent.py b/src/agnext/components/_type_routed_agent.py
similarity index 100%
rename from src/agnext/components/type_routed_agent.py
rename to src/agnext/components/_type_routed_agent.py
diff --git a/src/agnext/components/types.py b/src/agnext/components/_types.py
similarity index 58%
rename from src/agnext/components/types.py
rename to src/agnext/components/_types.py
index a62762465..5e3850ffa 100644
--- a/src/agnext/components/types.py
+++ b/src/agnext/components/_types.py
@@ -1,7 +1,6 @@
from __future__ import annotations
from dataclasses import dataclass
-from typing import Any, Dict
@dataclass
@@ -11,10 +10,3 @@ class FunctionCall:
arguments: str
# Function to call
name: str
-
-
-@dataclass
-class FunctionSignature:
- name: str
- parameters: Dict[str, Any]
- description: str
diff --git a/src/agnext/components/code_executor/__init__.py b/src/agnext/components/code_executor/__init__.py
index adedcb8bb..e62545fdd 100644
--- a/src/agnext/components/code_executor/__init__.py
+++ b/src/agnext/components/code_executor/__init__.py
@@ -1,4 +1,5 @@
from ._base import CodeBlock, CodeExecutor, CodeResult
+from ._func_with_reqs import Alias, FunctionWithRequirements, Import, ImportFromModule, with_requirements
from ._impl.command_line_code_result import CommandLineCodeResult
from ._impl.local_commandline_code_executor import LocalCommandLineCodeExecutor
@@ -8,4 +9,9 @@ __all__ = [
"CodeBlock",
"CodeResult",
"CodeExecutor",
+ "Alias",
+ "ImportFromModule",
+ "Import",
+ "FunctionWithRequirements",
+ "with_requirements",
]
diff --git a/src/agnext/components/func_with_reqs.py b/src/agnext/components/code_executor/_func_with_reqs.py
similarity index 100%
rename from src/agnext/components/func_with_reqs.py
rename to src/agnext/components/code_executor/_func_with_reqs.py
diff --git a/src/agnext/components/code_executor/_impl/local_commandline_code_executor.py b/src/agnext/components/code_executor/_impl/local_commandline_code_executor.py
index fe65a39e6..194a1eace 100644
--- a/src/agnext/components/code_executor/_impl/local_commandline_code_executor.py
+++ b/src/agnext/components/code_executor/_impl/local_commandline_code_executor.py
@@ -12,13 +12,13 @@ from typing import Any, Callable, ClassVar, List, Sequence, Union
from typing_extensions import ParamSpec
-from ...func_with_reqs import (
+from .._base import CodeBlock, CodeExecutor
+from .._func_with_reqs import (
FunctionWithRequirements,
FunctionWithRequirementsStr,
build_python_functions_file,
to_stub,
)
-from .._base import CodeBlock, CodeExecutor
from .command_line_code_result import CommandLineCodeResult
from .utils import PYTHON_VARIANTS, get_file_name_from_content, lang_to_cmd, silence_pip # type: ignore
diff --git a/src/agnext/components/function_executor/__init__.py b/src/agnext/components/function_executor/__init__.py
deleted file mode 100644
index 0300488af..000000000
--- a/src/agnext/components/function_executor/__init__.py
+++ /dev/null
@@ -1,9 +0,0 @@
-from ._base import Function, FunctionExecutor, into_function_signature
-from ._impl.in_process_function_executor import InProcessFunctionExecutor
-
-__all__ = [
- "FunctionExecutor",
- "Function",
- "into_function_signature",
- "InProcessFunctionExecutor",
-]
diff --git a/src/agnext/components/function_executor/_base.py b/src/agnext/components/function_executor/_base.py
deleted file mode 100644
index 1b3284b62..000000000
--- a/src/agnext/components/function_executor/_base.py
+++ /dev/null
@@ -1,40 +0,0 @@
-from collections.abc import Sequence
-from typing import Any, Callable, Dict, Protocol, TypedDict, Union, runtime_checkable
-
-from typing_extensions import NotRequired, Required
-
-from .._function_utils import get_function_schema
-from ..types import FunctionSignature
-
-
-class Function(TypedDict):
- func: Required[Callable[..., Any]]
- name: NotRequired[str]
- description: NotRequired[str]
-
-
-@runtime_checkable
-class FunctionExecutor(Protocol):
- async def execute_function(self, function_name: str, arguments: Dict[str, Any]) -> str: ...
-
- @property
- def functions(self) -> Sequence[Function]: ...
-
- @property
- def function_signatures(self) -> Sequence[FunctionSignature]:
- return [into_function_signature(func) for func in self.functions]
-
-
-def into_function_signature(
- func_data: Union[Function, FunctionSignature, Callable[..., Any]],
-) -> FunctionSignature:
- if isinstance(func_data, FunctionSignature):
- return func_data
- elif isinstance(func_data, dict):
- name = func_data.get("name", func_data["func"].__name__)
- description = func_data.get("description", "")
- parameters = get_function_schema(func_data["func"], description="", name="")["function"]["parameters"]
- return FunctionSignature(name=name, description=description, parameters=parameters)
- else:
- parameters = get_function_schema(func_data, description="", name="")["function"]["parameters"]
- return FunctionSignature(name=func_data.__name__, description="", parameters=parameters)
diff --git a/src/agnext/components/function_executor/_impl/__init__.py b/src/agnext/components/function_executor/_impl/__init__.py
deleted file mode 100644
index e69de29bb..000000000
diff --git a/src/agnext/components/function_executor/_impl/in_process_function_executor.py b/src/agnext/components/function_executor/_impl/in_process_function_executor.py
deleted file mode 100644
index 03bf69b34..000000000
--- a/src/agnext/components/function_executor/_impl/in_process_function_executor.py
+++ /dev/null
@@ -1,53 +0,0 @@
-import asyncio
-import functools
-from collections.abc import Sequence
-from typing import Any, Callable, Dict, Union
-
-from .._base import Function, FunctionExecutor
-
-
-class InProcessFunctionExecutor(FunctionExecutor):
- def __init__(
- self,
- functions: Sequence[Union[Callable[..., Any], Function]] = [],
- ) -> None:
- def _name(func: Union[Callable[..., Any], Function]) -> str:
- if isinstance(func, dict):
- return func.get("name", func["func"].__name__)
- else:
- return func.__name__
-
- def _func(func: Union[Callable[..., Any], Function]) -> Any:
- if isinstance(func, dict):
- return func.get("func")
- else:
- return func
-
- def _description(func: Union[Callable[..., Any], Function]) -> str:
- if isinstance(func, dict):
- return func.get("description", "")
- else:
- return ""
-
- self._functions: Dict[str, Function] = dict()
- for func in functions:
- name = _name(func)
- self._functions[name] = Function(
- func=_func(func),
- name=name,
- description=_description(func),
- )
-
- async def execute_function(self, function_name: str, arguments: dict[str, Any]) -> str:
- if function_name in self._functions:
- function = self._functions[function_name]["func"]
- if asyncio.iscoroutinefunction(function):
- return str(function(**arguments))
- else:
- return await asyncio.get_event_loop().run_in_executor(None, functools.partial(function, **arguments))
-
- raise ValueError(f"Function {function_name} not found.")
-
- @property
- def functions(self) -> Sequence[Function]:
- return list(self._functions.values())
diff --git a/src/agnext/components/models/_model_client.py b/src/agnext/components/models/_model_client.py
index d582e689e..2f3705073 100644
--- a/src/agnext/components/models/_model_client.py
+++ b/src/agnext/components/models/_model_client.py
@@ -11,7 +11,7 @@ from typing_extensions import (
Union,
)
-from ..types import FunctionSignature
+from ..tools import Tool
from ._types import CreateResult, LLMMessage, RequestUsage
@@ -27,7 +27,7 @@ class ModelClient(Protocol):
async def create(
self,
messages: Sequence[LLMMessage],
- functions: Sequence[FunctionSignature] = [],
+ tools: Sequence[Tool] = [],
# None means do not override the default
# A value means to override the client default - often specified in the constructor
json_output: Optional[bool] = None,
@@ -37,7 +37,7 @@ class ModelClient(Protocol):
def create_stream(
self,
messages: Sequence[LLMMessage],
- functions: Sequence[FunctionSignature] = [],
+ tools: Sequence[Tool] = [],
# None means do not override the default
# A value means to override the client default - often specified in the constructor
json_output: Optional[bool] = None,
diff --git a/src/agnext/components/models/_openai_client.py b/src/agnext/components/models/_openai_client.py
index 619e9b05c..0676fb341 100644
--- a/src/agnext/components/models/_openai_client.py
+++ b/src/agnext/components/models/_openai_client.py
@@ -30,11 +30,11 @@ from openai.types.chat import (
from typing_extensions import Unpack
from ...application.logging import EVENT_LOGGER_NAME, LLMCallEvent
-from ..image import Image
-from ..types import (
+from .. import (
FunctionCall,
- FunctionSignature,
+ Image,
)
+from ..tools import Tool
from . import _model_info
from ._model_client import ModelCapabilities, ModelClient
from ._types import (
@@ -200,19 +200,15 @@ def _add_usage(usage1: RequestUsage, usage2: RequestUsage) -> RequestUsage:
)
-def convert_functions(
- functions: Sequence[FunctionSignature],
+def convert_tools(
+ tools: Sequence[Tool],
) -> List[ChatCompletionToolParam]:
result: List[ChatCompletionToolParam] = []
- for func in functions:
+ for tool in tools:
result.append(
{
"type": "function",
- "function": {
- "name": func.name,
- "parameters": func.parameters,
- "description": func.description,
- },
+ "function": tool.schema, # type: ignore
}
)
return result
@@ -255,7 +251,7 @@ class BaseOpenAI(ModelClient):
async def create(
self,
messages: Sequence[LLMMessage],
- functions: Sequence[FunctionSignature] = [],
+ tools: Sequence[Tool] = [],
json_output: Optional[bool] = None,
extra_create_args: Mapping[str, Any] = {},
) -> CreateResult:
@@ -291,13 +287,13 @@ class BaseOpenAI(ModelClient):
oai_messages_nested = [to_oai_type(m) for m in messages]
oai_messages = [item for sublist in oai_messages_nested for item in sublist]
- if self.capabilities["function_calling"] is False and len(functions) > 0:
+ if self.capabilities["function_calling"] is False and len(tools) > 0:
raise ValueError("Model does not support function calling")
- if len(functions) > 0:
- tools = convert_functions(functions)
+ if len(tools) > 0:
+ converted_tools = convert_tools(tools)
result = await self._client.chat.completions.create(
- messages=oai_messages, stream=False, tools=tools, **create_args
+ messages=oai_messages, stream=False, tools=converted_tools, **create_args
)
else:
result = await self._client.chat.completions.create(messages=oai_messages, stream=False, **create_args)
@@ -354,7 +350,7 @@ class BaseOpenAI(ModelClient):
async def create_stream(
self,
messages: Sequence[LLMMessage],
- functions: Sequence[FunctionSignature] = [],
+ tools: Sequence[Tool] = [],
json_output: Optional[bool] = None,
extra_create_args: Mapping[str, Any] = {},
) -> AsyncGenerator[Union[str, CreateResult], None]:
@@ -387,10 +383,10 @@ class BaseOpenAI(ModelClient):
else:
create_args["response_format"] = {"type": "text"}
- if len(functions) > 0:
- tools = convert_functions(functions)
+ if len(tools) > 0:
+ converted_tools = convert_tools(tools)
stream = await self._client.chat.completions.create(
- messages=oai_messages, stream=True, tools=tools, **create_args
+ messages=oai_messages, stream=True, tools=converted_tools, **create_args
)
else:
stream = await self._client.chat.completions.create(messages=oai_messages, stream=True, **create_args)
diff --git a/src/agnext/components/models/_types.py b/src/agnext/components/models/_types.py
index 3995303fc..ac0913756 100644
--- a/src/agnext/components/models/_types.py
+++ b/src/agnext/components/models/_types.py
@@ -1,8 +1,7 @@
from dataclasses import dataclass
from typing import List, Literal, Union
-from ..image import Image
-from ..types import FunctionCall
+from .. import FunctionCall, Image
@dataclass
diff --git a/src/agnext/components/tools/__init__.py b/src/agnext/components/tools/__init__.py
new file mode 100644
index 000000000..7054e173f
--- /dev/null
+++ b/src/agnext/components/tools/__init__.py
@@ -0,0 +1,13 @@
+from ._base import BaseTool, BaseToolWithState, Tool
+from ._code_execution import CodeExecutionInput, CodeExecutionResult, PythonCodeExecutionTool
+from ._function_tool import FunctionTool
+
+__all__ = [
+ "Tool",
+ "BaseTool",
+ "BaseToolWithState",
+ "PythonCodeExecutionTool",
+ "CodeExecutionInput",
+ "CodeExecutionResult",
+ "FunctionTool",
+]
diff --git a/src/agnext/components/tools/_base.py b/src/agnext/components/tools/_base.py
new file mode 100644
index 000000000..e74eafd01
--- /dev/null
+++ b/src/agnext/components/tools/_base.py
@@ -0,0 +1,103 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Generic, Mapping, Protocol, Type, TypeVar
+
+from pydantic import BaseModel
+
+from ...core import CancellationToken
+
+T = TypeVar("T", bound=BaseModel, contravariant=True)
+
+
+class Tool(Protocol):
+ @property
+ def name(self) -> str: ...
+
+ @property
+ def description(self) -> str: ...
+
+ @property
+ def schema(self) -> Mapping[str, Any]: ...
+
+ def args_type(self) -> Type[BaseModel]: ...
+
+ def return_type(self) -> Type[BaseModel]: ...
+
+ def state_type(self) -> Type[BaseModel] | None: ...
+
+ async def run_json(self, args: Mapping[str, Any], cancellation_token: CancellationToken) -> BaseModel: ...
+
+ def save_state_json(self) -> Mapping[str, Any]: ...
+
+ def load_state_json(self, state: Mapping[str, Any]) -> None: ...
+
+
+ArgsT = TypeVar("ArgsT", bound=BaseModel, contravariant=True)
+ReturnT = TypeVar("ReturnT", bound=BaseModel, covariant=True)
+StateT = TypeVar("StateT", bound=BaseModel)
+
+
+class BaseTool(ABC, Tool, Generic[ArgsT, ReturnT]):
+ def __init__(self, args_type: Type[ArgsT], return_type: Type[ReturnT], name: str, description: str) -> None:
+ self._args_type = args_type
+ self._return_type = return_type
+ self._name = name
+ self._description = description
+
+ @property
+ def schema(self) -> Mapping[str, Any]:
+ model_schema = self._args_type.model_json_schema()
+ parameter_schema: Dict[str, Any] = dict()
+ parameter_schema["parameters"] = model_schema["properties"]
+ parameter_schema["name"] = self._name
+ parameter_schema["description"] = self._description
+ return parameter_schema
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def description(self) -> str:
+ return self._description
+
+ def args_type(self) -> Type[BaseModel]:
+ return self._args_type
+
+ def return_type(self) -> Type[BaseModel]:
+ return self._return_type
+
+ def state_type(self) -> Type[BaseModel] | None:
+ return None
+
+ @abstractmethod
+ async def run(self, args: ArgsT, cancellation_token: CancellationToken) -> ReturnT: ...
+
+ async def run_json(self, args: Mapping[str, Any], cancellation_token: CancellationToken) -> BaseModel:
+ return_value = await self.run(self._args_type.model_validate(args), cancellation_token)
+ return return_value
+
+ def save_state_json(self) -> Mapping[str, Any]:
+ return {}
+
+ def load_state_json(self, state: Mapping[str, Any]) -> None:
+ pass
+
+
+class BaseToolWithState(BaseTool[ArgsT, ReturnT], ABC, Generic[ArgsT, ReturnT, StateT]):
+ def __init__(
+ self, args_type: Type[ArgsT], return_type: Type[ReturnT], state_type: Type[StateT], name: str, description: str
+ ) -> None:
+ super().__init__(args_type, return_type, name, description)
+ self._state_type = state_type
+
+ @abstractmethod
+ def save_state(self) -> StateT: ...
+
+ @abstractmethod
+ def load_state(self, state: StateT) -> None: ...
+
+ def save_state_json(self) -> Mapping[str, Any]:
+ return self.save_state().model_dump()
+
+ def load_state_json(self, state: Mapping[str, Any]) -> None:
+ self.load_state(self._state_type.model_validate(state))
diff --git a/src/agnext/components/tools/_code_execution.py b/src/agnext/components/tools/_code_execution.py
new file mode 100644
index 000000000..a959686ee
--- /dev/null
+++ b/src/agnext/components/tools/_code_execution.py
@@ -0,0 +1,37 @@
+import asyncio
+import functools
+
+from pydantic import BaseModel, Field, model_serializer
+
+from ...core import CancellationToken
+from ..code_executor import CodeBlock, CodeExecutor
+from ._base import BaseTool
+
+
+class CodeExecutionInput(BaseModel):
+ code: str = Field(description="The contents of the Python code block that should be executed")
+
+
+class CodeExecutionResult(BaseModel):
+ success: bool
+ output: str
+
+ @model_serializer
+ def ser_model(self) -> str:
+ return self.output
+
+
+class PythonCodeExecutionTool(BaseTool[CodeExecutionInput, CodeExecutionResult]):
+ def __init__(self, executor: CodeExecutor):
+ super().__init__(CodeExecutionInput, CodeExecutionResult, "CodeExecutor", "Execute Python code blocks.")
+ self._executor = executor
+
+ async def run(self, args: CodeExecutionInput, cancellation_token: CancellationToken) -> CodeExecutionResult:
+ code_blocks = [CodeBlock(code=args.code, language="python")]
+ future = asyncio.get_event_loop().run_in_executor(
+ None, functools.partial(self._executor.execute_code_blocks, code_blocks=code_blocks)
+ )
+ cancellation_token.link_future(future)
+ result = await future
+
+ return CodeExecutionResult(success=result.exit_code == 0, output=result.output)
diff --git a/src/agnext/components/tools/_function_tool.py b/src/agnext/components/tools/_function_tool.py
new file mode 100644
index 000000000..81043283e
--- /dev/null
+++ b/src/agnext/components/tools/_function_tool.py
@@ -0,0 +1,46 @@
+import asyncio
+import functools
+from typing import Any, Callable
+
+from pydantic import BaseModel
+
+from ...core import CancellationToken
+from .._function_utils import (
+ args_base_model_from_signature,
+ get_typed_signature,
+ return_value_base_model_from_signature,
+)
+from ._base import BaseTool
+
+
+class FunctionTool(BaseTool[BaseModel, BaseModel]):
+ def __init__(self, func: Callable[..., Any], description: str, name: str | None = None) -> None:
+ self._func = func
+ signature = get_typed_signature(func)
+ func_name = name or func.__name__
+ args_model = args_base_model_from_signature(func_name + "args", signature)
+ return_model = return_value_base_model_from_signature(func_name + "return", signature)
+ self._has_cancellation_support = "cancellation_token" in signature.parameters
+
+ super().__init__(args_model, return_model, func_name, description)
+
+ async def run(self, args: BaseModel, cancellation_token: CancellationToken) -> BaseModel:
+ if asyncio.iscoroutinefunction(self._func):
+ if self._has_cancellation_support:
+ result = await self._func(**args.model_dump(), cancellation_token=cancellation_token)
+ else:
+ result = await self._func(**args.model_dump())
+ else:
+ if self._has_cancellation_support:
+ result = await asyncio.get_event_loop().run_in_executor(
+ None, functools.partial(self._func, **args.model_dump(), cancellation_token=cancellation_token)
+ )
+ else:
+ future = asyncio.get_event_loop().run_in_executor(
+ None, functools.partial(self._func, **args.model_dump())
+ )
+ cancellation_token.link_future(future)
+ result = await future
+
+ assert isinstance(result, BaseModel)
+ return result
diff --git a/tests/execution/test_commandline_code_executor.py b/tests/execution/test_commandline_code_executor.py
index fb543d701..672ac3440 100644
--- a/tests/execution/test_commandline_code_executor.py
+++ b/tests/execution/test_commandline_code_executor.py
@@ -6,8 +6,7 @@ import tempfile
from pathlib import Path
import pytest
-
-from agnext.components.code_executor import LocalCommandLineCodeExecutor, CodeBlock
+from agnext.components.code_executor import CodeBlock, LocalCommandLineCodeExecutor
UNIX_SHELLS = ["bash", "sh", "shell"]
WINDOWS_SHELLS = ["ps1", "pwsh", "powershell"]
diff --git a/tests/execution/test_user_defined_functions.py b/tests/execution/test_user_defined_functions.py
index 7c7b6eff0..f36edc72e 100644
--- a/tests/execution/test_user_defined_functions.py
+++ b/tests/execution/test_user_defined_functions.py
@@ -7,10 +7,8 @@ import polars
import pytest
from agnext.components.code_executor import (
CodeBlock,
- LocalCommandLineCodeExecutor,
-)
-from agnext.components.func_with_reqs import (
FunctionWithRequirements,
+ LocalCommandLineCodeExecutor,
with_requirements,
)
diff --git a/tests/test_cancellation.py b/tests/test_cancellation.py
index 2d44f724a..2f888554f 100644
--- a/tests/test_cancellation.py
+++ b/tests/test_cancellation.py
@@ -1,12 +1,11 @@
import asyncio
-import pytest
from dataclasses import dataclass
-from agnext.components.type_routed_agent import TypeRoutedAgent, message_handler
+import pytest
from agnext.application import SingleThreadedAgentRuntime
-from agnext.core import Agent
-from agnext.core import AgentRuntime
-from agnext.core import CancellationToken
+from agnext.components import TypeRoutedAgent, message_handler
+from agnext.core import Agent, AgentRuntime, CancellationToken
+
@dataclass
class MessageType:
@@ -95,8 +94,8 @@ async def test_nested_cancellation_only_outer_called() -> None:
assert response.done()
assert nested.called
assert nested.cancelled
- assert long_running.called == False
- assert long_running.cancelled == False
+ assert long_running.called is False
+ assert long_running.cancelled is False
@pytest.mark.asyncio
async def test_nested_cancellation_inner_called() -> None:
@@ -121,4 +120,4 @@ async def test_nested_cancellation_inner_called() -> None:
assert nested.called
assert nested.cancelled
assert long_running.called
- assert long_running.cancelled
\ No newline at end of file
+ assert long_running.cancelled
diff --git a/tests/test_intervention.py b/tests/test_intervention.py
index e7780204f..b0ccd83f9 100644
--- a/tests/test_intervention.py
+++ b/tests/test_intervention.py
@@ -1,14 +1,13 @@
-import pytest
from dataclasses import dataclass
-from agnext.components.type_routed_agent import TypeRoutedAgent, message_handler
+import pytest
from agnext.application import SingleThreadedAgentRuntime
-from agnext.core import Agent
-from agnext.core import AgentRuntime
-from agnext.core import CancellationToken
+from agnext.components import TypeRoutedAgent, message_handler
+from agnext.core import Agent, AgentRuntime, CancellationToken
from agnext.core.exceptions import MessageDroppedException
from agnext.core.intervention import DefaultInterventionHandler, DropMessage
+
@dataclass
class MessageType:
...
diff --git a/tests/test_llm_usage.py b/tests/test_llm_usage.py
index 5de57fa71..47845e99a 100644
--- a/tests/test_llm_usage.py
+++ b/tests/test_llm_usage.py
@@ -1,7 +1,8 @@
-from agnext.application.logging import LLMUsageTracker, EVENT_LOGGER_NAME, LLMCallEvent
-
import logging
+from agnext.application.logging import EVENT_LOGGER_NAME, LLMCallEvent, LLMUsageTracker
+
+
def test_llm_usage() -> None:
# Set up the logging configuration to use the custom handler
diff --git a/tests/test_runtime.py b/tests/test_runtime.py
index d47771e93..5acf11ed5 100644
--- a/tests/test_runtime.py
+++ b/tests/test_runtime.py
@@ -1,10 +1,9 @@
from typing import Any, Sequence
-import pytest
+import pytest
from agnext.application import SingleThreadedAgentRuntime
-from agnext.core import AgentRuntime
-from agnext.core import BaseAgent
-from agnext.core import CancellationToken
+from agnext.core import AgentRuntime, BaseAgent, CancellationToken
+
class NoopAgent(BaseAgent):
def __init__(self, name: str, router: AgentRuntime) -> None:
diff --git a/tests/test_state.py b/tests/test_state.py
index f0db7de59..52e6bff4c 100644
--- a/tests/test_state.py
+++ b/tests/test_state.py
@@ -1,10 +1,9 @@
from typing import Any, Mapping, Sequence
-import pytest
+import pytest
from agnext.application import SingleThreadedAgentRuntime
-from agnext.core import AgentRuntime
-from agnext.core import BaseAgent
-from agnext.core import CancellationToken
+from agnext.core import AgentRuntime, BaseAgent, CancellationToken
+
class StatefulAgent(BaseAgent):
def __init__(self, name: str, runtime: AgentRuntime) -> None:
diff --git a/tests/test_tools.py b/tests/test_tools.py
new file mode 100644
index 000000000..954c3022b
--- /dev/null
+++ b/tests/test_tools.py
@@ -0,0 +1,60 @@
+
+import pytest
+from agnext.components.tools import BaseTool
+from agnext.core import CancellationToken
+from pydantic import BaseModel, Field
+
+
+class MyArgs(BaseModel):
+ query: str = Field(description="The description.")
+
+
+class MyResult(BaseModel):
+ result: str = Field(description="The other description.")
+
+
+class MyTool(BaseTool[MyArgs, MyResult]):
+ def __init__(self) -> None:
+ super().__init__(
+ args_type=MyArgs,
+ return_type=MyResult,
+ name="TestTool",
+ description="Description of test tool.",
+ )
+ self.called_count = 0
+
+ async def run(self, args: MyArgs, cancellation_token: CancellationToken) -> MyResult:
+ self.called_count += 1
+ return MyResult(result="value")
+
+def test_tool_schema_generation() -> None:
+ schema = MyTool().schema
+
+ assert schema["name"] == "TestTool"
+ assert schema["description"] == "Description of test tool."
+ assert schema["parameters"]["query"]["description"] == "The description."
+ assert len(schema["parameters"]) == 1
+
+async def test_tool_run()-> None:
+ tool = MyTool()
+ result = await tool.run_json({"query": "test"}, CancellationToken())
+
+ assert isinstance(result, MyResult)
+ assert result.result == "value"
+ assert tool.called_count == 1
+
+ result = await tool.run_json({"query": "test"}, CancellationToken())
+ result = await tool.run_json({"query": "test"}, CancellationToken())
+
+ assert tool.called_count == 3
+
+
+def test_tool_properties()-> None:
+ tool = MyTool()
+
+ assert tool.name == "TestTool"
+ assert tool.description == "Description of test tool."
+ assert tool.args_type() == MyArgs
+ assert tool.return_type() == MyResult
+ assert tool.state_type() is None
diff --git a/tests/test_types.py b/tests/test_types.py
index d214eece2..0cbbcd6ad 100644
--- a/tests/test_types.py
+++ b/tests/test_types.py
@@ -1,7 +1,7 @@
from types import NoneType
from typing import Any, Optional, Union
-from agnext.components.type_routed_agent import AnyType, get_types, message_handler
+from agnext.components._type_routed_agent import AnyType, get_types, message_handler
from agnext.core import CancellationToken