Agent Packages Monorepo

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• link.sh
• package.json
• agent-packages/packages/common/package.json
• agent-packages/packages/github/package.json
• agent-packages/packages/jira/package.json
• src/lib/constants.ts
• src/llm/quix-agent.ts
• agent-packages/packages/github/src/schema.ts

The agent-packages directory is a monorepo within the Quix project that contains individual packages for each third-party service integration. This modular architecture allows the AI-powered Slack agent to interact with various business tools like JIRA, GitHub, and HubSpot. Each package encapsulates the logic, types, and tools necessary to communicate with a specific service's API.

This design promotes scalability and maintainability, making it straightforward to add new integrations or update existing ones without affecting the core application. The packages are consumed by the main Nest.js application, which orchestrates the tool selection and execution based on user queries from Slack.

Sources: README.md:1-4, 21-36

Architecture and Structure

The monorepo is located in the agent-packages/ directory and contains a packages/ subdirectory. Each folder within packages/ represents a distinct integration and is a self-contained NPM package.

Sources: README.md:21-36

This diagram shows the directory structure of the agent-packages monorepo, highlighting how individual integration packages depend on the common package.

The common Package

The @clearfeed-ai/quix-common-agent package is a crucial component of the monorepo. It provides shared utilities, TypeScript types, and base configurations that are used by all other integration packages. This ensures consistency and reduces code duplication across the different agents. All integration packages list it as a dependency.

Sources: agent-packages/packages/common/package.json:2, agent-packages/packages/github/package.json:15, agent-packages/packages/jira/package.json:18

Integration Packages

Each integration package is responsible for a single service. For example, @clearfeed-ai/quix-github-agent handles all interactions with the GitHub API. A typical package includes:

• src/index.ts: Main exports, including the service and tool creation functions.
• src/schema.ts: Zod schemas for validating tool inputs.
• src/types.ts: TypeScript interfaces for API responses and configurations.
• src/tools.ts: Definitions of the agent tools for LangChain.
• package.json: Package metadata and dependencies.

Sources: README.md:144-148, agent-packages/packages/github/src/schema.ts

Available Packages

The following table lists the agent packages available in the monorepo, which are consumed by the root application.

Package Name	Service	Description
@clearfeed-ai/quix-assetpanda-agent	AssetPanda	Manages assets, licenses, and employees.
@clearfeed-ai/quix-bamboohr-agent	BambooHR	HR management functionalities.
@clearfeed-ai/quix-common-agent	Common	Shared utilities and types for all agents.
@clearfeed-ai/quix-github-agent	GitHub	Create, update, and search issues or PRs.
@clearfeed-ai/quix-hubspot-agent	HubSpot	Track contacts, companies, and deals.
@clearfeed-ai/quix-jumpcloud-agent	JumpCloud	Look up users and groups.
@clearfeed-ai/quix-jira-agent	JIRA	Create, search, and update issues.
@clearfeed-ai/quix-kandji-agent	Kandji	(Functionality not detailed in provided files)
@clearfeed-ai/quix-notion-agent	Notion	Search, browse, and retrieve content.
@clearfeed-ai/quix-okta-agent	Okta	Look up users, groups, and apps.
@clearfeed-ai/quix-postgres-agent	PostgreSQL	Run natural-language queries on a database.
@clearfeed-ai/quix-salesforce-agent	Salesforce	View and update opportunities, contacts, and accounts.
@clearfeed-ai/quix-slack-agent	Slack	Interact with the Slack API for messaging and channel management.
@clearfeed-ai/quix-zendesk-agent	Zendesk	Create, update, and view tickets.

Sources: package.json:29-41, src/lib/constants.ts:40, 60, 78, 96, 114, 132, 150, 168, 186, 204, agent-packages/packages/assetpanda/README.md:5-15, agent-packages/packages/bamboohr/package.json:2, agent-packages/packages/kandji/package.json:2

Development Workflow

The monorepo includes scripts to streamline the development process, particularly for building packages and linking them for local development.

Building and Linking

The link.sh script is used to set up a local development environment. It uses yarn link to create symbolic links for each package. This allows the main Quix application to use the local, in-development versions of the agent packages instead of the published versions from the NPM registry.

The script performs the following steps:

1. Navigates into the agent-packages directory.
2. Links the common package first, as other packages depend on it.
3. Iterates through each integration package, links its dependency on @clearfeed-ai/quix-common-agent, and then registers the package itself with yarn link.
4. Navigates back to the project root.
5. Links all the agent packages to the root node_modules directory, making them available to the main application.

Sources: link.sh

This diagram illustrates the local development linking process managed by link.sh.

Extending with New Integrations

To add a new integration, a developer can follow the process outlined in the main README.md:

1. Create a new directory for the integration inside agent-packages/packages/.
2. Implement the package structure, including index.ts, types.ts, and tools.ts.
3. Run ./link.sh to build the new package and link it to the main application for testing.

Sources: README.md:139-149

Consumption by Quix Agent

The main application's QuixAgent is responsible for utilizing the tools provided by these packages. The agent's logic dynamically selects and executes tools based on the user's query.

The process is as follows:

1. Tool Selection: The QuixAgent first determines which integration categories (e.g., jira, github) are relevant to the user's request.
2. Plan Generation: It then generates a multi-step plan to fulfill the request using the specific tools available from the selected packages.
3. Execution: The agent executes the plan, calling the tools from the agent packages as needed. Each tool is a DynamicStructuredTool from LangChain, with its input schema defined using Zod within its respective package.

Sources: src/llm/quix-agent.ts:18-80, agent-packages/packages/github/src/schema.ts

This diagram shows how a user query leads to the execution of a tool from an agent package.