trading_agent.tools.tool

The base class for every tool the agent can use, and the result a tool returns.

A tool describes its arguments as a pydantic model. The model gives the JSON schema the AI model sees, and checks the arguments the AI model sends before the tool runs.

Typical usage example:

class GetTimeTool(Tool): name = 'get_time' description = 'Returns the current date and time in India.' arguments_model = NoArguments

  async def run(self, arguments: NoArguments) -> ToolResult:
      return ToolResult.success('10:15')

ToolResult dataclass

ToolResult(text, is_error=False, image=None, picture_desk_path=None)

What a tool returns to the model.

Attributes:

Name	Type	Description
text	str	The output the model reads.
is_error	bool	Whether the tool failed, so the model knows to change course.
image	MessageImage | None	A picture for the model to look at, such as a screenshot, or None.
picture_desk_path	str | None	Where that picture is saved, relative to the desk folder, so the web page can show it in the tool's card; None when it is not saved in the desk folder.

success classmethod

success(text)

Creates a successful result.

Parameters:

Name	Type	Description	Default
text	str	The output.	required

Returns:

Type	Description
ToolResult	The result.

Source code in src/trading_agent/tools/tool.py

@classmethod
def success(cls, text: str) -> Self:
    """Creates a successful result.

    Args:
        text (str): The output.

    Returns:
        ToolResult: The result.
    """
    return cls(text=text, is_error=False)

error classmethod

error(text)

Creates a failed result.

Parameters:

Name	Type	Description	Default
text	str	What went wrong, written so the model can act on it.	required

Returns:

Type	Description
ToolResult	The result.

Source code in src/trading_agent/tools/tool.py

@classmethod
def error(cls, text: str) -> Self:
    """Creates a failed result.

    Args:
        text (str): What went wrong, written so the model can act on it.

    Returns:
        ToolResult: The result.
    """
    return cls(text=text, is_error=True)

NoArguments

Bases: BaseModel

The arguments of a tool that takes none.

Tool

One tool. Subclasses set the class attributes and override run.

Attributes:

Name	Type	Description
name		The name the model calls the tool by.
description		What the tool does, written for the model.
arguments_model	type[BaseModel]	The pydantic model that describes and checks the arguments.
timeout_seconds	float | None	How long one call may run, or None for the registry's default.

input_schema

input_schema()

The JSON schema of the tool's arguments, as the model sees it.

Returns:

Type	Description
dict[str, Any]	A JSON schema object.

Source code in src/trading_agent/tools/tool.py

def input_schema(self) -> dict[str, Any]:
    """The JSON schema of the tool's arguments, as the model sees it.

    Returns:
        dict[str, Any]: A JSON schema object.
    """
    schema = self.arguments_model.model_json_schema()
    schema.pop('title', None)
    schema.setdefault('properties', {})
    schema.setdefault('required', [])
    return schema

run async

run(arguments)

Runs the tool.

Parameters:

Name	Type	Description	Default
arguments	BaseModel	The checked arguments, an instance of arguments_model.	required

Returns:

Type	Description
ToolResult	The output.

Raises:

Type	Description
NotImplementedError	Always, because subclasses must override this method.

Source code in src/trading_agent/tools/tool.py

async def run(self, arguments: pydantic.BaseModel) -> ToolResult:
    """Runs the tool.

    Args:
        arguments (pydantic.BaseModel): The checked arguments, an instance of arguments_model.

    Returns:
        ToolResult: The output.

    Raises:
        NotImplementedError: Always, because subclasses must override this method.
    """
    raise NotImplementedError

close async

close()

Releases anything the tool started, such as a bash process.

Tools that start nothing keep this empty default.

Source code in src/trading_agent/tools/tool.py

async def close(self) -> None:
    """Releases anything the tool started, such as a bash process.

    Tools that start nothing keep this empty default.
    """