Tools#

This page presents all APIs and classes related to tools in PyAgentSpec.

Base Tool class#

class pyagentspec.tools.tool.Tool(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2, inputs=None, outputs=None, requires_confirmation=False)#

Bases: ComponentWithIO

A tool specifies a function made available to an agent or a flow.

It can be bound to one or more agents, which will use it when desired. It can be used in a flow by a dedicated tool execution step

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • inputs (List[Property] | None) – List of inputs accepted by this component

  • outputs (List[Property] | None) – List of outputs exposed by this component

  • requires_confirmation (bool) – Flag to make tool require user confirmation before execution.

Client Tool#

class pyagentspec.tools.clienttool.ClientTool(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2, inputs=None, outputs=None, requires_confirmation=False)#

Bases: Tool

A tool that needs to be run by the client application.

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • inputs (List[Property] | None) – List of inputs accepted by this component

  • outputs (List[Property] | None) – List of outputs exposed by this component

  • requires_confirmation (bool) – Flag to make tool require user confirmation before execution.

Remote Tool#

class pyagentspec.tools.remotetool.RemoteTool(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2, inputs=None, outputs=None, requires_confirmation=False, url, http_method, api_spec_uri=None, data=<factory>, query_params=<factory>, headers=<factory>)#

Bases: Tool

A tool that is run remotely and called through REST.

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • inputs (List[Property] | None) – List of inputs accepted by this component

  • outputs (List[Property] | None) – List of outputs exposed by this component

  • requires_confirmation (bool) – Flag to make tool require user confirmation before execution.

  • url (str) – The url of the API to which the call should be forwarded. Allows placeholders, which can define inputs

  • http_method (str) – The HTTP method to use for the API call (e.g., GET, POST, PUT, …). Allows placeholders, which can define inputs

  • api_spec_uri (str | None) – The uri of the specification of the API that is going to be called. Allows placeholders, which can define inputs

  • data (Dict[str, Any]) – The data to send as part of the body of this API call. Allows placeholders in dict values, which can define inputs

  • query_params (Dict[str, Any]) – Query parameters for the API call. Allows placeholders in dict values, which can define inputs

  • headers (Dict[str, Any]) – Additional headers for the API call. Allows placeholders in dict values, which can define inputs

api_spec_uri: str | None#

The uri of the specification of the API that is going to be called. Allows placeholders, which can define inputs

data: Dict[str, Any]#

The data to send as part of the body of this API call. Allows placeholders in dict values, which can define inputs

headers: Dict[str, Any]#

Additional headers for the API call. Allows placeholders in dict values, which can define inputs

http_method: str#

The HTTP method to use for the API call (e.g., GET, POST, PUT, …). Allows placeholders, which can define inputs

query_params: Dict[str, Any]#

Query parameters for the API call. Allows placeholders in dict values, which can define inputs

url: str#

The url of the API to which the call should be forwarded. Allows placeholders, which can define inputs

Server Tool#

class pyagentspec.tools.servertool.ServerTool(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2, inputs=None, outputs=None, requires_confirmation=False)#

Bases: Tool

A tool that is registered to and executed by the orchestrator.

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • inputs (List[Property] | None) – List of inputs accepted by this component

  • outputs (List[Property] | None) – List of outputs exposed by this component

  • requires_confirmation (bool) – Flag to make tool require user confirmation before execution.

MCP Tool#

class pyagentspec.mcp.tools.MCPTool(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2, inputs=None, outputs=None, requires_confirmation=False, client_transport)#

Bases: Tool

Class for tools exposed by MCP servers

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • inputs (List[Property] | None) – List of inputs accepted by this component

  • outputs (List[Property] | None) – List of outputs exposed by this component

  • requires_confirmation (bool) – Flag to make tool require user confirmation before execution.

  • client_transport (ClientTransport) – Transport to use for establishing and managing connections to the MCP server.

client_transport: ClientTransport#

Transport to use for establishing and managing connections to the MCP server.

ToolBox#

class pyagentspec.tools.toolbox.ToolBox(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2)#

Bases: Component

A ToolBox is a component that exposes one or more tools to agentic components.

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

MCP ToolBox#

class pyagentspec.mcp.tools.MCPToolSpec(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2, inputs=None, outputs=None, requires_confirmation=False)#

Bases: ComponentWithIO

Specification of MCP tool

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • inputs (List[Property] | None) – List of inputs accepted by this component

  • outputs (List[Property] | None) – List of outputs exposed by this component

  • requires_confirmation (bool) – Flag to make tool require user confirmation before execution.

class pyagentspec.mcp.tools.MCPToolBox(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2, client_transport, tool_filter=None)#

Bases: ToolBox

Class to dynamically expose a list of tools from a MCP Server.

Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • client_transport (ClientTransport) – Transport to use for establishing and managing connections to the MCP server.

  • tool_filter (List[MCPToolSpec | str] | None) –

client_transport: ClientTransport#

Transport to use for establishing and managing connections to the MCP server.

tool_filter: List[MCPToolSpec | str] | None#

Optional filter to select specific tools.

If None, exposes all tools from the MCP server.

  • Specifying a tool name (str) indicates that a tool of the given name is expected from the MCP server.

  • Specifying a tool signature (MCPToolSpec) validate the presence and signature of the specified tool in the MCP Server.

  • The name of the MCP tool should match the name of the tool from the MCP Server.

    • Specifying a non-empty description will override the description of the tool from the MCP Server.

    • Inputs can be provided with description of each input. The names and types should match the MCP tool schema.

  • If provided, the outputs must be a single StringProperty with the expected tool output name and optional description.

  • If the tool requires confirmation before use, it overrides the exposed tool’s confirmation flag.