Tools Package (@astack-tech/tools)

Relevant source files

• examples/agent-with-tools/.gitignore
• examples/agent-with-tools/index.ts
• packages/components/src/tool-invoker/index.ts
• packages/tools/src/component-tool.ts
• packages/tools/src/tool-set.ts
• pnpm-lock.yaml

The @astack-tech/tools package provides the foundational abstractions and utilities for creating, managing, and invoking tools within the AStack framework. Tools are discrete units of functionality that can be called by agents to perform specific tasks like file I/O, web searches, calculations, or any custom operation. This package defines the Tool interface contract, provides the createTool() utility for simple function-based tools, implements ComponentTool for wrapping AStack Components as tools, and offers ToolSet for managing tool collections.

For information about how agents use tools for ReAct-style reasoning, see Agent System. For details on the ToolInvoker component that executes tool calls, see Components Package.

Tool Interface and Architecture

Core Tool Contract

The Tool interface defines the standard contract that all tools must implement. A tool consists of a name, description, optional JSON Schema parameters, and an invoke() method for execution.

Tool Interface Properties:

Property	Type	Description
name	string	Unique identifier for the tool
description	string	Human-readable description for LLM context
parameters	ToolParameters	JSON Schema defining expected arguments
invoke()	(args: Record<string, unknown>) => Promise<unknown>	Executes the tool with provided arguments

The ToolParameters type follows JSON Schema format, specifying the structure of arguments the tool expects. This schema is provided to language models to enable function calling.

Sources: The Tool interface is referenced in packages/components/src/agents/index.ts41-58 packages/tools/src/component-tool.ts2

Tool Lifecycle and Execution

Tools are invoked when an agent receives a response from an LLM containing tool_calls. The agent extracts the tool name and arguments, calls the corresponding tool's invoke() method, and returns results to the conversation context.

Sources: packages/components/src/agents/index.ts397-549

Creating Tools with createTool()

The createTool() utility provides the simplest way to create function-based tools. It wraps an async function with metadata to conform to the Tool interface.

Function Signature

Basic Usage Example

The agent-with-tools example demonstrates creating file I/O tools:

Example from the codebase at examples/agent-with-tools/index.ts26-61:

readFile Tool:

• Name: 'readFile'
• Description: '读取指定路径的文件内容'
• Parameters: Object with filePath property (string, required)
• Invoke: Async function that validates path, resolves to absolute path, reads file content

writeFile Tool:

• Name: 'writeFile'
• Description: '将内容写入指定路径的文件'
• Parameters: Object with filePath and content properties (both strings, required)
• Invoke: Async function that validates path, creates directories if needed, writes content

Both tools include security checks (preventing .. in paths) and comprehensive error handling.

Sources: examples/agent-with-tools/index.ts26-103

Parameter Schema Structure

The parameters argument follows JSON Schema format:

Schema Field	Purpose	Example
type	Root type (typically 'object')	type: 'object'
properties	Defines each parameter	properties: { filePath: { type: 'string', description: '...' } }
required	Array of required parameter names	required: ['filePath']

This schema is converted to OpenAI function calling format when passed to model providers at packages/integrations/src/model-provider/deepseek/index.ts156-163

Sources: examples/agent-with-tools/index.ts54-60 packages/integrations/src/model-provider/deepseek/index.ts154-167

ComponentTool: Wrapping Components as Tools

ComponentTool enables any AStack Component to be exposed as a tool, bridging the component architecture with the tool system. This allows reusing existing components in agent workflows.

ComponentTool Architecture

ComponentToolConfig Interface

The configuration object passed to ComponentTool constructor at packages/tools/src/component-tool.ts7-51:

Field	Type	Required	Description
name	string	Yes	Tool identifier
description	string	Yes	Tool description for LLM
component	Component	Yes	Component instance to wrap
parameters	ToolParameters	No	JSON Schema for arguments
transformArgs	(args) => unknown	No	Maps tool args to component input
transformResult	(result) => unknown	No	Maps component output to tool result
inputPort	string	No	Input port name (default: 'in')
outputPort	string	No	Output port name (default: 'out')

Execution Flow

The ComponentTool.invoke() method at packages/tools/src/component-tool.ts93-105:

1. Receives tool arguments as Record<string, unknown>
2. Applies transformArgs() to convert to component input format
3. Calls component.run() in standalone mode
4. Applies transformResult() to convert component output to tool result
5. Returns the transformed result

If the component doesn't support standalone run() mode, an error is thrown.

Creating ComponentTool via Factory

The createComponentTool() factory function at packages/tools/src/component-tool.ts113-115 provides a convenient wrapper:

This factory simply instantiates and returns a ComponentTool instance.

Sources: packages/tools/src/component-tool.ts1-116

ToolSet: Managing Tool Collections

ToolSet provides a registry pattern for managing multiple tools, enabling dynamic tool discovery and organization.

ToolSet Interface

DefaultToolSet Implementation

The DefaultToolSet class at packages/tools/src/tool-set.ts45-100 provides the standard implementation:

Constructor:

• Accepts optional array of initial tools
• Initializes internal Map<string, Tool>
• Adds all initial tools to the map

Key Methods:

Method	Implementation	Complexity
getTools()	Returns Array.from(this.tools.values())	O(n)
getTool(name)	Returns this.tools.get(name)	O(1)
addTool(tool)	this.tools.set(tool.name, tool) (with duplicate check)	O(1)
removeTool(name)	this.tools.delete(name)	O(1)
size()	Returns this.tools.size	O(1)

The addTool() method at packages/tools/src/tool-set.ts78-82 includes a duplicate name check to prevent accidentally overwriting existing tools.

Factory Function

The createToolSet() function at packages/tools/src/tool-set.ts107-109 provides a convenience wrapper:

Integration with Components

The ToolInvoker component accepts either format at packages/components/src/tool-invoker/index.ts106-114:

This design allows flexibility in how tools are provided while maintaining internal efficiency with Map-based storage.

Sources: packages/tools/src/tool-set.ts1-110 packages/components/src/tool-invoker/index.ts99-127

Tool Format and Model Provider Integration

Tool Call Data Structure

When an LLM requests tool execution, it returns messages with tool_calls arrays. The structure used in agent communication:

ToolCall Interface (from packages/components/src/agents/index.ts143-152):

• id: Unique identifier for tracking this specific call
• type: Always 'function' for OpenAI compatibility
• function.name: The tool name to invoke
• function.arguments: JSON string of arguments
• tool_name: Internal field for simplified access
• arguments: Parsed object form for direct use

Model Provider Tool Formatting

The Deepseek model provider converts tools to OpenAI function calling format at packages/integrations/src/model-provider/deepseek/index.ts154-167:

Transformation Pipeline:

1. Tool instances (name, description, parameters)
2. → OpenAI function format (type: 'function', function: {...})
3. → Included in chat completion request as tools parameter
4. → LLM response contains tool_calls array
5. → Agent extracts and executes via tool.invoke()

Sources: packages/integrations/src/model-provider/deepseek/index.ts49-60 packages/integrations/src/model-provider/deepseek/index.ts154-167 packages/components/src/agents/index.ts143-152

Tool Execution Patterns

Agent-Driven Tool Execution

The Agent component orchestrates multi-turn tool execution at packages/components/src/agents/index.ts397-549:

Key Implementation Details:

1. Iteration Loop (packages/components/src/agents/index.ts411-529):

   • Maximum iterations controlled by maxIterations config
   • Continues while hasMoreToolsToCall is true
   • Breaks when LLM response contains no tool_calls

2. Tool Discovery (packages/components/src/agents/index.ts444-448):

   • Extracts tool_name from call.function.name
   • Searches agent's tools array by name
   • Returns error message if tool not found

3. Argument Parsing (packages/components/src/agents/index.ts451-465):

   • Parses JSON from call.function.arguments
   • Handles both string and object formats
   • Returns error on parse failure

4. Tool Invocation (packages/components/src/agents/index.ts468-513):

   • Tries tool.execute() method first
   • Falls back to tool.invoke() method
   • Catches and records execution errors

5. Result Integration (packages/components/src/agents/index.ts518-528):

   • Adds assistant message with tool_calls
   • Adds user message with tool results
   • Formats results as text for LLM consumption

ToolInvoker Component Pattern

For more granular control, the ToolInvoker component at packages/components/src/tool-invoker/index.ts1-279 provides standalone tool execution:

Configuration:

• tools: Array or ToolSet of available tools
• parallel: Execute tool calls concurrently (default: false)
• timeout: Maximum execution time per tool (default: 30000ms)
• verbose: Enable debug logging

Execution Modes:

Mode	Behavior	Use Case
Sequential	Executes tool calls one at a time	Tools with shared state or ordering requirements
Parallel	Executes all tool calls concurrently	Independent tools, faster throughput

Timeout Handling (packages/components/src/tool-invoker/index.ts158-163):

Sources: packages/components/src/agents/index.ts397-549 packages/components/src/tool-invoker/index.ts142-182 packages/components/src/tool-invoker/index.ts214-226

Complete Example: File Operations

The agent-with-tools example demonstrates the complete tool lifecycle:

Implementation at examples/agent-with-tools/index.ts1-231:

1. Tool Creation (lines 26-103):

   • Define readFile with path validation and error handling
   • Define writeFile with directory creation and content writing
   • Both use createTool() with JSON Schema parameters

2. Agent Setup (lines 117-134):

   • Instantiate Deepseek model provider
   • Create Agent with tools array
   • Configure system prompt for file operations

3. Execution (lines 144-155):

   • Call agent.run(userRequest)
   • Agent orchestrates LLM → tool calls → results loop
   • Returns complete execution record

4. Result Handling (lines 214-225):

   • Display final message
   • List all tool calls with arguments and results
   • Provides full audit trail

Output Structure:

Sources: examples/agent-with-tools/index.ts1-231

Tool System Integration Summary

The @astack-tech/tools package provides the foundation for extensible, composable tool systems in AStack. Tools can be created from functions, wrapped from components, managed in collections, and executed by agents or standalone invokers. This architecture enables ReAct-style reasoning patterns where LLMs can iteratively use tools to solve complex problems.

Sources: packages/tools/src/tool-set.ts packages/tools/src/component-tool.ts packages/components/src/agents/index.ts packages/components/src/tool-invoker/index.ts examples/agent-with-tools/index.ts