Skip to content

Tool & ToolCall API Reference

These classes define how external capabilities (Tools) are represented and invoked within the Proxy Base Agent (PBA).

agent.tools.Tool

Represents a callable capability available to the agent.

class Tool:
    def __init__(
        self,
        name: str,
        description: str | None = None,
        callable: Callable | None = None,
        schema: dict[str, Any] | None = None,
        mcp_server: str | None = None,
    ):
        # ... implementation ...

    async def call(self, caller: Any, **kwargs) -> Any:
        # ... implementation ...

    @staticmethod
    def from_file(filepath: str) -> Tool | None:
        # ... implementation ...

    @staticmethod
    def load(
        filepath: str | None = None,
        file_name: str | list[str] | None = None,
    ) -> list[Tool]:
        # ... implementation ...

    def to_dict(self) -> dict[str, Any]:
        # ... implementation ...

    @staticmethod
    def from_mcp_tool(mcp_tool: MCPTool, server_id: str) -> Tool:
        # ... implementation ...

Initialization (__init__)

  • name (str): The unique identifier for the tool (e.g., calculator, send_message). This name is used by the LLM in the ToolCallState.
  • description (str | None, optional): A natural language description of the tool's purpose and usage. Used in the system prompt. If derived from a callable, this is often taken from the docstring.
  • callable (Callable | None, optional): The actual Python function (sync or async) that implements the tool's logic. If provided, the schema is usually auto-generated.
  • schema (dict[str, Any] | None, optional): A JSON Schema dictionary describing the tool's input parameters (arguments). If callable is provided, this is auto-generated using callable_to_schema. If callable is not provided (e.g., for an MCP tool where the implementation is remote), this schema must be provided.
  • mcp_server (str | None, optional): If this tool is provided by an external MCP server, this attribute stores the server's identifier.

Key Methods

  • async call(self, caller: Any, **kwargs) -> Any: Executes the tool's underlying callable. It handles both synchronous and asynchronous functions. The caller argument (which is the Agent instance invoking the tool) is automatically passed as the first argument (conventionally named self) to the tool's callable function. **kwargs are the arguments extracted from the LLM's tool call, matching the tool's defined schema.
  • to_dict() -> dict: Generates a JSON Schema representation suitable for inclusion in the ToolCallState's schema definition and the system prompt. It wraps the tool's argument schema within a structure that also requires an intention field from the LLM.
  • load(...) (staticmethod): Discovers and loads tools from Python files in a specified directory (defaults to agent/tools/).
  • from_file(...) (staticmethod): Loads a single tool from a specific Python file.
  • from_mcp_tool(...) (staticmethod): Converts a tool definition received via the MCP protocol into a PBA Tool instance.

agent.tools.ToolCall

A Pydantic BaseModel representing a structured request from the LLM to invoke a tool. PSE guarantees that the output within the ToolCallState conforms to this structure (or specifically, the structure generated by Tool.to_dict()).

python class ToolCall(BaseModel): intention: str name: str arguments: dict[str, Any] | None = None

Fields:

  • intention (str): A description generated by the LLM explaining why it is calling the tool and what it intends to achieve. This provides valuable context for understanding the agent's reasoning.
  • name (str): The exact name of the Tool to be invoked. Must match the name attribute of one of the loaded Tool instances.
  • arguments (dict[str, Any] | None, optional): A dictionary containing the arguments for the tool call. The structure and types within this dictionary must conform to the schema defined for the specified Tool. PSE enforces this conformance.

PBA uses the ToolCall model to parse the validated JSON output from the ToolCallState before passing the name and arguments to the Agent.use_tool method for execution.