A programming framework for agentic AI
Overhaul tools (#53)
Jack Gerritsab420cc9eeb0
diff --git a/examples/futures.py b/examples/futures.pyindex 948075798..765fabfdc 100644--- a/examples/futures.py+++ b/examples/futures.py@@ -2,7 +2,7 @@ import asynciofrom dataclasses import dataclassfrom agnext.application import SingleThreadedAgentRuntime-from agnext.components.type_routed_agent import TypeRoutedAgent, message_handler+from agnext.components import TypeRoutedAgent, message_handlerfrom agnext.core import Agent, AgentRuntime, CancellationTokendiff --git a/examples/orchestrator.py b/examples/orchestrator.pyindex 4f86ced7a..e38b7cbb3 100644--- a/examples/orchestrator.py+++ b/examples/orchestrator.py@@ -3,7 +3,7 @@ import asyncioimport jsonimport loggingimport os-from typing import Annotated, Callable+from typing import Callableimport openaifrom agnext.application import (@@ -13,19 +13,44 @@ from agnext.chat.agents.chat_completion_agent import ChatCompletionAgentfrom agnext.chat.agents.oai_assistant import OpenAIAssistantAgentfrom agnext.chat.patterns.orchestrator_chat import OrchestratorChatfrom 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, CancellationTokenfrom agnext.core.intervention import DefaultInterventionHandler, DropMessage-from tavily import TavilyClient+from pydantic import BaseModel, Field+from tavily import TavilyClient # type: ignorefrom typing_extensions import Any, overridelogging.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: ignoresend_color = "\033[31m"response_color = "\033[34m"@@ -76,16 +101,6 @@ def software_development(runtime: AgentRuntime) -> OrchestratorChat: # type: igthread_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: igSystemMessage("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.tomlindex 693431d50..0a6dc535a 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -75,7 +75,7 @@ disallow_untyped_decorators = truedisallow_any_unimported = true[tool.pyright]-include = ["src", "tests"]+include = ["src", "tests", "examples"]typeCheckingMode = "strict"reportUnnecessaryIsInstance = falsereportMissingTypeStubs = falsediff --git a/src/agnext/chat/agents/chat_completion_agent.py b/src/agnext/chat/agents/chat_completion_agent.pyindex 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 asyncioimport json-from typing import Any, Coroutine, Dict, List, Mapping, Tuple+from typing import Any, Coroutine, Dict, List, Mapping, Sequence, Tuplefrom agnext.chat.agents.base import BaseChatAgentfrom 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 Toolfrom 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_messagesself._client = model_clientself._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) > 0and 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.pyindex 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 AssistantResponseFormatParamfrom agnext.chat.agents.base import BaseChatAgentfrom agnext.chat.types import Reset, RespondNow, ResponseFormat, TextMessage-from agnext.components.type_routed_agent import TypeRoutedAgent, message_handler+from agnext.components import TypeRoutedAgent, message_handlerfrom agnext.core import AgentRuntime, CancellationTokendiff --git a/src/agnext/chat/patterns/group_chat.py b/src/agnext/chat/patterns/group_chat.pyindex 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_handlerfrom ...core import AgentRuntime, CancellationTokenfrom ..agents.base import BaseChatAgentfrom ..types import Reset, RespondNow, TextMessagediff --git a/src/agnext/chat/patterns/orchestrator_chat.py b/src/agnext/chat/patterns/orchestrator_chat.pyindex 420b771cb..6bc9999ff 100644--- a/src/agnext/chat/patterns/orchestrator_chat.py+++ b/src/agnext/chat/patterns/orchestrator_chat.py@@ -1,7 +1,7 @@import jsonfrom typing import Any, Sequence, Tuple-from ...components.type_routed_agent import TypeRoutedAgent, message_handler+from ...components import TypeRoutedAgent, message_handlerfrom ...core import AgentRuntime, CancellationTokenfrom ..agents.base import BaseChatAgentfrom ..types import Reset, RespondNow, ResponseFormat, TextMessagediff --git a/src/agnext/chat/types.py b/src/agnext/chat/types.pyindex 2c3ba65e2..308f135db 100644--- a/src/agnext/chat/types.py+++ b/src/agnext/chat/types.py@@ -4,9 +4,8 @@ from dataclasses import dataclass, fieldfrom enum import Enumfrom typing import List, Union-from agnext.components.image import Image+from agnext.components import FunctionCall, Imagefrom 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__.pyindex 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.pyindex 15cce58c1..4596e3617 100644--- a/src/agnext/components/_function_utils.py+++ b/src/agnext/components/_function_utils.py@@ -4,6 +4,7 @@import inspectfrom logging import getLoggerfrom 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 Literalfrom ._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.pysimilarity index 100%rename from src/agnext/components/image.pyrename to src/agnext/components/_image.pydiff --git a/src/agnext/components/type_routed_agent.py b/src/agnext/components/_type_routed_agent.pysimilarity index 100%rename from src/agnext/components/type_routed_agent.pyrename to src/agnext/components/_type_routed_agent.pydiff --git a/src/agnext/components/types.py b/src/agnext/components/_types.pysimilarity index 58%rename from src/agnext/components/types.pyrename to src/agnext/components/_types.pyindex a62762465..5e3850ffa 100644--- a/src/agnext/components/types.py+++ b/src/agnext/components/_types.py@@ -1,7 +1,6 @@from __future__ import annotationsfrom dataclasses import dataclass-from typing import Any, Dict@dataclass@@ -11,10 +10,3 @@ class FunctionCall:arguments: str# Function to callname: str---@dataclass-class FunctionSignature:- name: str- parameters: Dict[str, Any]- description: strdiff --git a/src/agnext/components/code_executor/__init__.py b/src/agnext/components/code_executor/__init__.pyindex 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_requirementsfrom ._impl.command_line_code_result import CommandLineCodeResultfrom ._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.pysimilarity index 100%rename from src/agnext/components/func_with_reqs.pyrename to src/agnext/components/code_executor/_func_with_reqs.pydiff --git a/src/agnext/components/code_executor/_impl/local_commandline_code_executor.py b/src/agnext/components/code_executor/_impl/local_commandline_code_executor.pyindex 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, Unionfrom 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, CodeExecutorfrom .command_line_code_result import CommandLineCodeResultfrom .utils import PYTHON_VARIANTS, get_file_name_from_content, lang_to_cmd, silence_pip # type: ignorediff --git a/src/agnext/components/function_executor/__init__.py b/src/agnext/components/function_executor/__init__.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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__.pydeleted file mode 100644index e69de29bb..000000000diff --git a/src/agnext/components/function_executor/_impl/in_process_function_executor.py b/src/agnext/components/function_executor/_impl/in_process_function_executor.pydeleted file mode 100644index 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.pyindex 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 Toolfrom ._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 constructorjson_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 constructorjson_output: Optional[bool] = None,diff --git a/src/agnext/components/models/_openai_client.py b/src/agnext/components/models/_openai_client.pyindex 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 Unpackfrom ...application.logging import EVENT_LOGGER_NAME, LLMCallEvent-from ..image import Image-from ..types import (+from .. import (FunctionCall,- FunctionSignature,+ Image,)+from ..tools import Toolfrom . import _model_infofrom ._model_client import ModelCapabilities, ModelClientfrom ._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.pyindex 3995303fc..ac0913756 100644--- a/src/agnext/components/models/_types.py+++ b/src/agnext/components/models/_types.py@@ -1,8 +1,7 @@from dataclasses import dataclassfrom typing import List, Literal, Union-from ..image import Image-from ..types import FunctionCall+from .. import FunctionCall, Image@dataclassdiff --git a/src/agnext/components/tools/__init__.py b/src/agnext/components/tools/__init__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 resultdiff --git a/tests/execution/test_commandline_code_executor.py b/tests/execution/test_commandline_code_executor.pyindex fb543d701..672ac3440 100644--- a/tests/execution/test_commandline_code_executor.py+++ b/tests/execution/test_commandline_code_executor.py@@ -6,8 +6,7 @@ import tempfilefrom pathlib import Pathimport pytest--from agnext.components.code_executor import LocalCommandLineCodeExecutor, CodeBlock+from agnext.components.code_executor import CodeBlock, LocalCommandLineCodeExecutorUNIX_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.pyindex 7c7b6eff0..f36edc72e 100644--- a/tests/execution/test_user_defined_functions.py+++ b/tests/execution/test_user_defined_functions.py@@ -7,10 +7,8 @@ import polarsimport pytestfrom 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.pyindex 2d44f724a..2f888554f 100644--- a/tests/test_cancellation.py+++ b/tests/test_cancellation.py@@ -1,12 +1,11 @@import asyncio-import pytestfrom dataclasses import dataclass-from agnext.components.type_routed_agent import TypeRoutedAgent, message_handler+import pytestfrom 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+@dataclassclass MessageType:@@ -95,8 +94,8 @@ async def test_nested_cancellation_only_outer_called() -> None:assert response.done()assert nested.calledassert 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.asyncioasync def test_nested_cancellation_inner_called() -> None:@@ -121,4 +120,4 @@ async def test_nested_cancellation_inner_called() -> None:assert nested.calledassert nested.cancelledassert long_running.called- assert long_running.cancelled\ No newline at end of file+ assert long_running.cancelleddiff --git a/tests/test_intervention.py b/tests/test_intervention.pyindex e7780204f..b0ccd83f9 100644--- a/tests/test_intervention.py+++ b/tests/test_intervention.py@@ -1,14 +1,13 @@-import pytestfrom dataclasses import dataclass-from agnext.components.type_routed_agent import TypeRoutedAgent, message_handler+import pytestfrom 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, CancellationTokenfrom agnext.core.exceptions import MessageDroppedExceptionfrom agnext.core.intervention import DefaultInterventionHandler, DropMessage+@dataclassclass MessageType:...diff --git a/tests/test_llm_usage.py b/tests/test_llm_usage.pyindex 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 handlerdiff --git a/tests/test_runtime.py b/tests/test_runtime.pyindex 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 pytestfrom 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.pyindex 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 pytestfrom 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.pynew file mode 100644index 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 Nonediff --git a/tests/test_types.py b/tests/test_types.pyindex d214eece2..0cbbcd6ad 100644--- a/tests/test_types.py+++ b/tests/test_types.py@@ -1,7 +1,7 @@from types import NoneTypefrom 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_handlerfrom agnext.core import CancellationToken