Action System¶

Overview¶

The action system enables function calling within LionAGI:

Tools wrap a Python callable with optional pre/post processors and schema-based validation.
FunctionCalling is a specialized Event that executes these tools.
ActionManager registers multiple Tools for invocation by requests.
ActionRequestModel and ActionResponseModel define standardized protocols for specifying which function to call, with what arguments, and returning the function’s output.

Contents¶

FunctionCalling¶

The FunctionCalling class extends Event to manage the entire lifecycle of a tool invocation, including optional pre and post processing. It updates execution with status, duration, and any output or error.

Class Documentation¶

class lionagi.operatives.action.function_calling.FunctionCalling¶

Inherits from: Event

Handles asynchronous function execution with pre/post processing.

This class manages function calls with optional preprocessing and postprocessing, handling both synchronous and asynchronous functions.

func_toolTool: Tool instance containing the function to be called
argumentsdict[str, Any]: Dictionary of arguments to pass to the function

invoke(): Execute the function call with pre/post processing.
to_dict(): Convert instance to dictionary.

function: Returns the underlying function from func_tool.

>>> def multiply(x, y):
...     return x * y
>>> tool = Tool(func_callable=multiply)
>>> func_call = FunctionCalling(func_tool=tool, arguments={"x": 3, "y": 4})
>>> await func_call.invoke()
>>> print(func_call.execution.response)  # Should show 12

Method Documentation¶

FunctionCalling.invoke()¶

Execute the function call with pre/post processing.

Handles both synchronous and asynchronous functions, including optional preprocessing of arguments and postprocessing of results. Updates the execution status, duration, and response/error.

Returns¶

None

FunctionCalling.to_dict()¶

Convert instance to dictionary.

Returns¶

dict[str, Any]: Dictionary representation of the instance including function name and arguments.

ActionManager¶

A specialized Manager that keeps a registry of tools (functions). It also provides an invoke method for easily executing a registered function, given an ActionRequest or its Pydantic model.

Class Documentation¶

class lionagi.operatives.action.manager.ActionManager¶

Inherits from: Manager

A manager that registers function-based tools and invokes them

when triggered by an ActionRequest. Tools can be registered individually or in bulk, and each tool must have a unique name.

*argsFuncTool: A variable number of tools or callables.
**kwargs: Additional named arguments that are also considered tools.

registrydict[str, Tool]: Dictionary mapping function names to Tool instances.

register_tool(tool, update=False): Register a single tool/callable in the manager.
register_tools(tools, update=False): Register multiple tools at once.
match_tool(action_request): Convert an ActionRequest into a FunctionCalling instance.
invoke(func_call): High-level API to parse and run a function call.
get_tool_schema(tools=False, auto_register=True, update=False): Retrieve schemas for a subset of tools or for all.

schema_list: Return the list of JSON schemas for all registered tools.

Method Documentation¶

ActionManager.register_tool(tool, update=False)¶

Parameters¶

toolFuncTool: A Tool object or a raw callable function.
updatebool, default=False: If True, allow replacing an existing tool with the same name.

Raises¶

ValueError: If tool already registered and update=False.
TypeError: If tool is not a Tool or callable.

ActionManager.register_tools(tools, update=False)¶

Parameters¶

toolslist[FuncTool] | FuncTool: A single or list of tools/callables.
updatebool, default=False: If True, allow updating existing tools.

Raises¶

ValueError: If a duplicate tool is found and update=False.
TypeError: If any item is not a Tool or callable.

ActionManager.match_tool(action_request)¶

Convert an ActionRequest (or dict with “function”/”arguments”) into a FunctionCalling instance by finding the matching tool.

Parameters¶

action_requestActionRequest | ActionRequestModel | dict: The request specifying which function to call and with what arguments.

Returns¶

FunctionCalling: The event object that can be invoked.

Raises¶

TypeError: If action_request is an unsupported type.
ValueError: If no matching tool is found in the registry.

ActionManager.invoke(func_call)¶

High-level API to parse and run a function call.

Steps:

Convert func_call to FunctionCalling via match_tool.
invoke() the resulting object.
Return the FunctionCalling, which includes execution.

Parameters¶

func_callActionRequestModel | ActionRequest: The action request model or ActionRequest object.

Returns¶

FunctionCalling: The event object after execution completes.

ActionManager.get_tool_schema(tools=False, auto_register=True, update=False)¶

Retrieve schemas for a subset of tools or for all.

Parameters¶

toolsToolRef, default=False

If True, return schema for all tools.
If False, return an empty dict.
If specific tool(s), returns only those schemas.

auto_registerbool, default=True

If a tool (callable) is not yet in the registry, register if True.

updatebool, default=False

If True, allow updating existing tools.

Returns¶

dict: Dictionary containing tool schemas, e.g., {“tools”: [list of schemas]}

Raises¶

ValueError: If requested tool is not found and auto_register=False.
TypeError: If tool specification is invalid.

Request & Response Models¶

Contains Pydantic models for action requests and responses. These models typically map to conversation messages describing which function is called, with what arguments, and any returned output.

Class Documentation¶

class lionagi.operatives.action.request_response_model.ActionRequestModel¶

Inherits from: pydantic.BaseModel

Captures a single action request.

Includes the name of the function and the arguments.

functionstr | None: Name of the function to call (e.g., “multiply”, “create_user”)
argumentsdict[str, Any] | None: Dictionary of arguments to pass to the function

create(content): Class method to parse a string into one or more ActionRequestModel instances.

>>> request = ActionRequestModel(
...     function="multiply",
...     arguments={"x": 3, "y": 4}
... )

Method Documentation¶

ActionRequestModel.create(content)¶

Attempt to parse a string (usually from a conversation or JSON) into one or more ActionRequestModel instances.

Parameters¶

contentstr: String content to parse.

Returns¶

list[ActionRequestModel]: List of parsed request models. Returns empty list if no valid structure found.

class lionagi.operatives.action.request_response_model.ActionResponseModel¶

Inherits from: pydantic.BaseModel

Encapsulates a function’s output after being called. Typically

references the original function name, arguments, and the result.

functionstr: Name of the function that was called
argumentsdict[str, Any]: Dictionary of arguments that were passed
outputAny: The function’s return value or output

>>> response = ActionResponseModel(
...     function="multiply",
...     arguments={"x": 3, "y": 4},
...     output=12
... )

Field Models¶

The module also defines two field models for use in other Pydantic models:

ACTION_REQUESTS_FIELD: For lists of action requests
ACTION_RESPONSES_FIELD: For lists of action responses

Tool¶

The Tool module provides functionality for wrapping Python callables with additional features like pre/post-processing and automatic schema generation.

Class Documentation¶

class lionagi.operatives.action.tool.Tool¶

Inherits from: pydantic.BaseModel

Wraps a callable function with optional preprocessing of arguments,

postprocessing of results, and strict or partial argument matching. The tool_schema is auto-generated from the function signature if not provided.

func_callableCallable[…, Any]: The callable function to be wrapped by the tool
tool_schemadict[str, Any] | None, optional: Schema describing the function’s parameters and structure
preprocessorCallable[[Any], Any] | None, optional: Optional function for preprocessing inputs before execution
preprocessor_kwargsdict[str, Any], optional: Keyword arguments passed to the preprocessor function
postprocessorCallable[[Any], Any] | None, optional: Optional function for postprocessing outputs after execution
postprocessor_kwargsdict[str, Any], optional: Keyword arguments passed to the postprocessor function
strict_func_callbool, default=False: Whether to enforce strict validation of function parameters

functionstr: Return the function name from the auto-generated schema
required_fieldsset[str]: Return the set of required parameter names from the schema
minimum_acceptable_fieldsset[str]: Return the set of parameters that have no default values

to_dict(): Serialize the Tool to a dict, including the function name

Type Aliases¶

FuncTool¶: Type alias representing either a Tool instance or a raw callable function. Tool | Callable[..., Any]

FuncToolRef¶: Type alias for a reference to a function-based tool, by either the actual object, the raw callable, or the function name as a string. FuncTool | str

ToolRef¶: Type alias used for specifying one or more tool references, or a boolean indicating ‘all’ or ‘none’. FuncToolRef | list[FuncToolRef] | bool

Helper Functions¶

func_to_tool(func, **kwargs)¶

Convenience function that wraps a raw function in a Tool.

Parameters¶

funcCallable[…, Any]: The function to wrap
**kwargs: Additional arguments passed to the Tool constructor

Returns¶

Tool: A new Tool instance wrapping func

Examples¶

def greet(name: str, greeting: str = "Hello") -> str:
    return f"{greeting}, {name}!"

# Basic tool creation
tool = Tool(func_callable=greet)

# With preprocessing
def preprocess(args):
    args["name"] = args["name"].title()
    return args

tool_with_prep = Tool(
    func_callable=greet,
    preprocessor=preprocess,
    strict_func_call=True
)

Utilities¶

Internal helpers for parsing action requests and validating fields.

Functions¶

parse_action_request(content)¶

Attempt to parse a string or dictionary into a list of action request dictionaries. Handles various input formats including JSON strings, Python code blocks, and dictionaries.

Parameters¶

contentstr | dict: The content to parse, either as a string or dictionary.

Returns¶

list[dict]: List of dictionaries, each containing ‘function’ and ‘arguments’ keys.

Field Models¶

FUNCTION_FIELD¶

Field model for function names with validation.

Attributes¶

namestr: “function”
defaultNone: Default value is None
annotationstr | None: Type annotation
descriptionstr: Description of how to use the function field
exampleslist: Example function names like [“add”, “multiply”, “divide”]

ARGUMENTS_FIELD¶

Field model for function arguments with validation.

Attributes¶

namestr: “arguments”
default_factorydict: Default value is an empty dict
annotationdict | None: Type annotation
descriptionstr: Description of how to use the arguments field
exampleslist: Example argument dictionaries

ACTION_REQUIRED_FIELD¶

Field model indicating whether actions are required.

Attributes¶

namestr: “action_required”
defaultbool: Default value is False
annotationbool: Type annotation
descriptionstr: Description of when actions are required vs optional

Field Descriptions¶

The module provides several constant strings describing fields:

function_field_description: Guidelines for function name field
arguments_field_description: Guidelines for arguments field
action_required_field_description: Guidelines for required flag
action_requests_field_description: Guidelines for request lists

Example Usage¶

A short example of how to use these classes:

from lionagi.operatives.action.manager import ActionManager
from lionagi.operatives.action.request_response_model import ActionRequestModel

# 1. Create an action manager and register a function
def multiply(x, y):
    return x * y

manager = ActionManager()
manager.register_tool(multiply)

# 2. Build an ActionRequestModel
request_data = {"function": "multiply", "arguments": {"x": 3, "y": 4}}
action_request = ActionRequestModel.model_validate(request_data)

# 3. Invoke
result_event = await manager.invoke(action_request)
print(result_event.execution.response)  # Should show 12

File Locations¶

function_calling.py: The FunctionCalling event for executing tools.
manager.py (ActionManager): The main manager for registering and invoking Tools.
request_response_model.py: Pydantic-based models for requests/responses.
tool.py: The Tool class that wraps a callable function with schema info.
utils.py: Shared utility constants and a simple parser method for requests.