Tool Service
Relevant source files
The following files were used as context for generating this wiki page:
The Tool Service is a central component of the Quix agent architecture responsible for dynamically loading and providing "tools" that the AI agent can use. These tools are functions that interact with external services like Jira, GitHub, HubSpot, and others. The service determines which tools are available based on the active integrations for a given Slack workspace, ensuring the agent's capabilities are tailored to each team's specific configuration.
The ToolService works in conjunction with the LlmService and QuixAgent to form the core of the agent's decision-making and action-taking process. It acts as a configuration-driven bridge, abstracting the specifics of each integration and presenting a unified set of capabilities for the agent to consume.
Sources: src/llm/tool.service.ts, src/llm/quix-agent.ts
Core Architecture
The ToolService class is the heart of this system. Its primary responsibility is to assemble a collection of available tools for a specific team (Slack workspace). This is accomplished through its main method, getAvailableTools(teamId: string).
The service has the following key dependencies:
SlackWorkspaceModel: To fetch the workspace and its associated integration configurations from the database.IntegrationsService: To refresh authentication tokens (e.g., for OAuth-based integrations like Jira and HubSpot) before creating the tools.McpService: To handle the loading of tools from MCP (Multi-Channel Platform) based integrations, such as Linear.
Sources: src/llm/tool.service.ts:21-30
The following diagram illustrates the sequence of operations when the agent needs to get the available tools.
This diagram shows the flow for retrieving and assembling tools for a given team.
Sources: src/llm/tool.service.ts:34-199
Tool Loading and Configuration
The getAvailableTools method orchestrates the loading process. It fetches the SlackWorkspace entity along with all its related integration configurations (e.g., jiraConfig, hubspotConfig, githubConfig). It then iterates through these configurations. If a configuration is present and enabled for the workspace, the service invokes a corresponding factory function (e.g., createJiraToolsExport) to generate the tools for that specific integration.
The result is an AvailableToolsWithConfig object, which is a map where keys are the integration names (e.g., "jira", "github") and values are objects containing the toolConfig and the original integration config.
Sources: src/llm/tool.service.ts:34-51
Tool Loading Flow
This flowchart depicts the step-by-step logic within getAvailableTools to build the final toolset.
Sources: src/llm/tool.service.ts:34-199
Tool Definition and Structure
Each integration package (e.g., @clearfeed-ai/quix-jira-agent) defines its own set of tools. A "tool" is an abstraction over a function that the LLM can decide to call to perform an action or retrieve information.
The structure of a tool and its configuration is defined by the ToolConfig type, which contains two main properties:
tools: An array ofDynamicStructuredToolinstances, which are the actual executable functions.prompts: An object containingtoolSelectionandresponseGenerationprompts that guide the LLM on when and how to use the tools.
Sources: agent-packages/packages/jira/src/tools.ts:100-107
The tool helper function is used to create each DynamicStructuredTool. A tool has several key properties:
name: A unique identifier for the tool (e.g.,find_jira_ticket).description: A natural language description of what the tool does, which the LLM uses to decide whether to call it.schema: Azodschema defining the input arguments for the tool. This provides strong typing and validation.operations: An array indicating the type of action (e.g.,READ,CREATE,UPDATE,DELETE).func: The asynchronous function that executes the tool's logic, taking the validated arguments as input.
Sources: agent-packages/packages/jira/src/tools.ts:34-40, agent-packages/packages/common/src/tools.ts
Example Tool Definitions (Jira)
The following table shows some of the tools defined for the Jira integration.
| Tool Name | Description | Operations |
|---|---|---|
find_jira_ticket | Search for Jira issues using a valid JQL query. | READ |
get_jira_issue | Retrieve detailed information about a specific Jira issue using its key or ID. | READ |
create_jira_issue | Create a new Jira issue. | CREATE |
assign_jira_issue | Assign a Jira issue to a user. | UPDATE |
add_jira_comment | Add a comment to a Jira issue. | CREATE |
update_jira_issue | Update an existing Jira issue. | UPDATE |
search_jira_users | Search for Jira users by name or email. | READ |
Sources: agent-packages/packages/jira/src/tools.ts:33-98
Supported Integrations and Tool Creation
The ToolService dynamically loads tools for any integration enabled for a workspace. The list of supported integrations is defined in the SUPPORTED_INTEGRATIONS enum.
Sources: src/lib/constants.ts:3-15
The table below maps each integration to its tool factory function, which is imported and called within ToolService.
| Integration | Factory Function | Source File |
|---|---|---|
| Jira | createJiraToolsExport | agent-packages/packages/jira/src/tools.ts |
| HubSpot | createHubspotToolsExport | agent-packages/packages/hubspot/src/tools.ts |
| GitHub | createGitHubToolsExport | agent-packages/packages/github/src/tools.ts |
| Postgres | createPostgresToolsExport | src/llm/tool.service.ts:112 |
| Salesforce | createSalesforceToolsExport | src/llm/tool.service.ts:128 |
| Slack | createSlackToolsExport | src/llm/tool.service.ts:55 |
| Okta | createOktaToolsExport | src/llm/tool.service.ts:144 |
| Notion | createNotionToolsExport | src/llm/tool.service.ts:153 |
| Zendesk | createZendeskToolsExport | src/llm/tool.service.ts:158 |
| JumpCloud | createJumpCloudToolsExport | src/llm/tool.service.ts:167 |
| Linear | mcpService.getMcpServerTools | src/llm/tool.service.ts:174 |
Sources: src/llm/tool.service.ts:1-20
MCP-Based Integrations
Integrations like Linear are handled via the McpService. The ToolService calls mcpService.getMcpServerTools to get the tool definitions. This process returns not only the tools but also a cleanup function. This function is stored and later called by shutDownMcpServers to gracefully terminate any background processes associated with the MCP tools, ensuring proper resource management.
Sources: src/llm/tool.service.ts:172-188, 201-204
Tool Consumption by the Agent
The AvailableToolsWithConfig map generated by the ToolService is consumed by the QuixAgent. The agent's process involves several stages:
- Tool Selection: The agent first performs a
toolSelectionstep. It uses thetoolSelectionprompts from eachToolConfigto ask the LLM which categories of tools (e.g., 'jira', 'hubspot') are relevant to the user's query. - Plan Generation: Once categories are selected, the agent uses the specific tools from those categories to generate a multi-step
plan. This plan outlines the sequence of tool calls needed to fulfill the request. - Execution: The agent executes the plan using the
createReactAgentfrom LangGraph. This executor invokes thefuncof each tool in the plan, captures the output, and feeds it back to the LLM to generate the final response.
Sources: src/llm/quix-agent.ts:21-81
The following diagram shows how the QuixAgent consumes the tools provided by the ToolService.
This diagram illustrates the agent's workflow, from receiving a message to using tools and generating a response.
Sources: src/llm/quix-agent.ts:21-198
Conclusion
The Tool Service is a critical architectural element that makes the Quix agent both powerful and extensible. By dynamically loading tools based on workspace-specific configurations, it allows the agent to adapt its capabilities to different environments. Its clear separation of concerns—where each integration package defines its own tools—enables developers to easily add new integrations without modifying the core agent logic. This modular design is fundamental to the Quix platform's ability to interact with a growing ecosystem of business applications.
Sources: src/llm/tool.service.ts, README.md