Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Update scripts and readme

haxziec43bf494eda9
diff --git a/README.md b/README.md
index 37996a181..8d11d5952 100644
--- a/README.md
+++ b/README.md
@@ -11,62 +11,98 @@ The core Composio SDK which allows users to interact with the Composio Platform.
- **ConnectedAccounts**: Manage third-party service connections. Includes functionality to create, list, refresh, and manage the status of connected accounts.
- **ActionExecution**: Track and manage the execution of actions within the platform.
+## Toolsets
+
+Composio SDK supports two types of toolsets:
+
+1. **Non-Agentic Toolsets**: These toolsets only support schema modifiers for transforming tool schemas. They are suitable for simple integrations like OpenAI, Anthropic, etc.
+2. **Agentic Toolsets**: These toolsets support full modifier capabilities including tool execution modifiers, schema modifiers, and custom modifiers. They are suitable for more complex integrations like Vercel, Langchain, etc.
## Usage
-@composio/core ships with openai toolset by default. You can directly use the tools from composio in `openai` methods.
-```
-import { Composio } from "@composio/core";
-// By default composio ships with OpenAI toolset
+@composio/core ships with OpenAI toolset by default. You can directly use the tools from composio in `openai` methods.
+
+```typescript
+import { Composio } from '@composio/core';
+
+// By default composio ships with OpenAI toolset (non-agentic)
const composio = new Composio({
apiKey: process.env.COMPOSIO_API_KEY,
});
-const tool = await composio.getTool("HACKERNEWS_SEARCH_POSTS");
+const tool = await composio.getToolBySlug('HACKERNEWS_SEARCH_POSTS');
console.log(tool);
```
For more examples, please check the `/examples` directory.
## Using with a different toolset
+
To use a different toolset, please install the recommended toolset packages.
-```
-import { Composio } from "@composio/core";
-import { VercelToolset } from "@composio/vercel"
+```typescript
+import { Composio } from '@composio/core';
+import { VercelToolset } from '@composio/vercel-toolset'; // Agentic toolset
+// or
+import { OpenAIToolset } from '@composio/openai-toolset'; // Non-agentic toolset
const composio = new Composio({
apiKey: process.env.COMPOSIO_API_KEY,
- toolset: new VercelToolset();
+ toolset: new VercelToolset(), // or new OpenAIToolset()
});
-const tool = await composio.getTool("HACKERNEWS_SEARCH_POSTS");
+const tool = await composio.getToolBySlug('HACKERNEWS_SEARCH_POSTS');
console.log(tool);
```
-
## Creating a new toolset
-To create a new Toolset, you need to extend the `BaseComposioToolset<YourToolType>` and implement the `_wrapTool` method to return the tool type of your choice.
-To Quickly create a toolset project, execute the following command from the root of the project
+To create a new Toolset, you need to extend either `BaseNonAgenticToolset` or `BaseAgenticToolset` from `@composio/core` and implement the required methods.
+
+To quickly create a toolset project, execute the following command from the root of the project:
+
+```bash
+# Create a non-agentic toolset (default)
+pnpm run create-toolset <your-toolset-name>
+
+# Create an agentic toolset
+pnpm run create-toolset <your-toolset-name> --agentic
```
-pnpm run create-toolset <your toolset name>
+
+For example:
+
+```bash
+# Create a non-agentic toolset for Anthropic
+pnpm run create-toolset anthropic
+
+# Create an agentic toolset for Langchain
+pnpm run create-toolset langchain --agentic
```
-eg:
+
+The script will create a new toolset with the following structure:
+
```
-pnpm run create-toolset langchain
+<toolset-name>/
+├── src/
+│ └── index.ts # Toolset implementation
+├── package.json # Package configuration
+├── tsconfig.json # TypeScript configuration
+├── tsup.config.ts # Build configuration
+└── README.md # Toolset documentation
```
## Internal
+
What's not included from @composio/client
-- [X] Org/Project Mangement with API Keys
-- [X] Trigger Subscriptions
+
+- [x] Org/Project Mangement with API Keys
+- [x] Trigger Subscriptions
- [ ] Zod Schemas for type checking `Ideally strike a minimal balance, since backend has most`
- [ ] Action Execution
- [ ] CLI `Do we need this in the core SDK?`
- [ ] MCP `Not required as this is not necessary`
-- [ ] Team Members
+- [ ] Team Members
- [ ] File uploads/user files
- [ ] Tests
-These models can be still be accessed via the SDK explicitly by using the `@composio/client`.
\ No newline at end of file
+These models can be still be accessed via the SDK explicitly by using the `@composio/client`.
diff --git a/packages/toolsets/README.md b/packages/toolsets/README.md
index a03286829..20de6e8e0 100644
--- a/packages/toolsets/README.md
+++ b/packages/toolsets/README.md
@@ -2,61 +2,119 @@
This package contains various toolsets that integrate with Composio's core functionality. Each toolset provides a collection of tools that can be used to interact with different services and APIs.
-## Creating a New Toolset
+## Types of Toolsets
-To create a new toolset, you can use the provided script:
+Composio SDK supports two types of toolsets:
-```bash
-npm run create-toolset <toolset-name>
-```
+### 1. Non-Agentic Toolsets
-This will create a new toolset with the following structure:
-```
-<toolset-name>/
-├── src/
-│ └── index.ts
-├── package.json
-├── tsconfig.json
-└── tsup.config.ts
+These toolsets only support schema modifiers for transforming tool schemas. They are suitable for simple integrations like OpenAI, Anthropic, etc.
+
+```typescript
+import { BaseNonAgenticToolset } from '@composio/core';
+import type { Tool, ToolListParams, SchemaModifiersParams } from '@composio/core';
+
+interface ToolType {
+ // Define your tool type here
+}
+
+interface ToolCollection {
+ // Define your tool collection here
+}
+
+export class NonAgenticToolset extends BaseNonAgenticToolset<ToolCollection, ToolType> {
+ static FRAMEWORK_NAME = 'non-agentic-toolset';
+ readonly FILE_NAME: string = 'toolsets/non-agentic-toolset/src/index.ts';
+
+ wrapTool = (tool: Tool): ToolType => {
+ // Implement tool wrapping logic
+ return tool as ToolType;
+ };
+
+ getTools = async (
+ params?: ToolListParams,
+ modifiers?: SchemaModifiersParams
+ ): Promise<ToolCollection> => {
+ // Implement tool collection logic
+ return [];
+ };
+
+ getToolBySlug = async (slug: string, modifiers?: SchemaModifiersParams): Promise<ToolType> => {
+ const tool = await this.getComposio().tools.getToolBySlug(slug, modifiers?.schema);
+ return this.wrapTool(tool);
+ };
+}
```
-## Toolset Implementation
+### 2. Agentic Toolsets
-Each toolset extends the `BaseComposioToolset` class from `@composio/core`. Here's a basic structure of a toolset:
+These toolsets support full modifier capabilities including tool execution modifiers, schema modifiers, and custom modifiers. They are suitable for more complex integrations like Vercel, Langchain, etc.
```typescript
-import { BaseComposioToolset } from "@composio/core";
-import type { Tool, ToolListParams } from "@composio/core";
+import { BaseAgenticToolset } from '@composio/core';
+import type { Tool, ToolListParams, ModifiersParams } from '@composio/core';
interface ToolType {
- // Define your tool type here
+ // Define your tool type here
}
interface ToolCollection {
- // Define your tool collection here
+ // Define your tool collection here
+}
+
+export class AgenticToolset extends BaseAgenticToolset<ToolCollection, ToolType> {
+ static FRAMEWORK_NAME = 'agentic-toolset';
+ readonly FILE_NAME: string = 'toolsets/agentic-toolset/src/index.ts';
+
+ wrapTool = (tool: Tool): ToolType => {
+ // Implement tool wrapping logic
+ return tool as ToolType;
+ };
+
+ getTools = async (
+ params?: ToolListParams,
+ modifiers?: ModifiersParams
+ ): Promise<ToolCollection> => {
+ // Implement tool collection logic with full modifier support
+ return [];
+ };
+
+ getToolBySlug = async (slug: string, modifiers?: ModifiersParams): Promise<ToolType> => {
+ const tool = await this.getComposio().tools.getToolBySlug(slug, modifiers?.schema);
+ return this.wrapTool(tool);
+ };
}
+```
-export class YourToolset extends BaseComposioToolset<ToolCollection, ToolType> {
- static FRAMEWORK_NAME = "your-toolset";
- private DEFAULT_ENTITY_ID = "default";
- readonly FILE_NAME: string = "toolsets/your-toolset/src/index.ts";
+## Creating a New Toolset
- _wrapTool = (tool: Tool): ToolType => {
- // Implement tool wrapping logic
- return tool as ToolType;
- }
+To create a new toolset, you can use the provided script:
- getTools = async (query?: ToolListParams): Promise<ToolCollection> => {
- // Implement tool collection logic
- return [];
- }
-}
+```bash
+# Create a non-agentic toolset (default)
+pnpm run create-toolset <toolset-name>
+
+# Create an agentic toolset
+pnpm run create-toolset <toolset-name> --agentic
+```
+
+This will create a new toolset with the following structure:
+
+```
+<toolset-name>/
+├── src/
+│ └── index.ts # Toolset implementation
+├── package.json # Package configuration
+├── tsconfig.json # TypeScript configuration
+├── tsup.config.ts # Build configuration
+└── README.md # Toolset documentation
```
### Required Methods
-1. `_wrapTool`: This method is responsible for wrapping a tool in the toolset's specific format.
+1. `wrapTool`: This method is responsible for wrapping a tool in the toolset's specific format.
2. `getTools`: This method retrieves all available tools from the Composio API.
+3. `getToolBySlug`: This method retrieves a specific tool by its slug.
### Configuration
@@ -81,44 +139,55 @@ pnpm build
2. **Error Handling**: Implement proper error handling in your tool methods
3. **Documentation**: Document your tools and their parameters clearly
4. **Testing**: Write unit tests for your toolset functionality
+5. **Modifier Support**:
+ - For non-agentic toolsets, implement schema modifiers to transform tool schemas
+ - For agentic toolsets, implement full modifier support including execution and custom modifiers
## Example Implementation
-Here's a simple example of implementing a toolset:
+Here's a simple example of implementing a non-agentic toolset:
```typescript
interface MyToolType {
- name: string;
- description: string;
- execute: (params: any) => Promise<any>;
+ name: string;
+ description: string;
+ execute: (params: any) => Promise<any>;
}
interface MyToolCollection {
- [key: string]: MyToolType;
+ [key: string]: MyToolType;
}
-export class MyToolset extends BaseComposioToolset<MyToolCollection, MyToolType> {
- static FRAMEWORK_NAME = "my-toolset";
- readonly FILE_NAME:string = "toolsets/MyToolset/src/index.ts"
-
- _wrapTool = (tool: Tool): MyToolType => {
- return {
- name: tool.name,
- description: tool.description,
- execute: async (params) => {
- // Implement tool execution logic
- return await this.executeTool(tool, params);
- }
- };
- }
-
- getTools = async (query?: ToolListParams): Promise<MyToolCollection> => {
- const tools = await this.listTools(query);
- return tools.reduce((acc, tool) => {
- acc[tool.name] = this._wrapTool(tool);
- return acc;
- }, {} as MyToolCollection);
- }
+export class MyNonAgenticToolset extends BaseNonAgenticToolset<MyToolCollection, MyToolType> {
+ static FRAMEWORK_NAME = 'my-toolset';
+ readonly FILE_NAME: string = 'toolsets/my-toolset/src/index.ts';
+
+ wrapTool = (tool: Tool): MyToolType => {
+ return {
+ name: tool.name,
+ description: tool.description,
+ execute: async params => {
+ // Implement tool execution logic
+ return await this.getComposio().tools.execute(tool.slug, params);
+ },
+ };
+ };
+
+ getTools = async (
+ params?: ToolListParams,
+ modifiers?: SchemaModifiersParams
+ ): Promise<MyToolCollection> => {
+ const tools = await this.getComposio().tools.getTools(params, modifiers?.schema);
+ return tools.reduce((acc, tool) => {
+ acc[tool.slug] = this.wrapTool(tool);
+ return acc;
+ }, {} as MyToolCollection);
+ };
+
+ getToolBySlug = async (slug: string, modifiers?: SchemaModifiersParams): Promise<MyToolType> => {
+ const tool = await this.getComposio().tools.getToolBySlug(slug, modifiers?.schema);
+ return this.wrapTool(tool);
+ };
}
```
@@ -130,3 +199,4 @@ When contributing a new toolset:
2. Include proper documentation
3. Add tests for your implementation
4. Update this README if necessary
+5. Choose the appropriate base class (agentic or non-agentic) based on your toolset's needs
diff --git a/scripts/create-toolset.sh b/scripts/create-toolset.sh
index 3bb2aee21..6ad85b2d0 100644
--- a/scripts/create-toolset.sh
+++ b/scripts/create-toolset.sh
@@ -3,7 +3,7 @@
# Check if toolset name is provided
if [ -z "$1" ]; then
echo "Please provide a toolset name"
- echo "Usage: npm run create-toolset <toolset-name>"
+ echo "Usage: npm run create-toolset <toolset-name> [--agentic]"
exit 1
fi
@@ -11,6 +11,12 @@ TOOLSET_NAME=$1
TOOLSET_PATH="packages/toolsets/$TOOLSET_NAME"
CAPITAL_TOOLSET_NAME="$(tr '[:lower:]' '[:upper:]' <<< ${TOOLSET_NAME:0:1})${TOOLSET_NAME:1}"
+# Check if toolset should be agentic
+IS_AGENTIC=false
+if [ "$2" = "--agentic" ]; then
+ IS_AGENTIC=true
+fi
+
# Create directory structure
mkdir -p "$TOOLSET_PATH/src"
@@ -19,7 +25,7 @@ cat > "$TOOLSET_PATH/package.json" << EOL
{
"name": "@composio/${TOOLSET_NAME}-toolset",
"version": "1.0.0",
- "description": "",
+ "description": "${IS_AGENTIC:+Agentic }Toolset for ${TOOLSET_NAME}",
"main": "src/index.ts",
"type": "module",
"publishConfig": {
@@ -38,7 +44,7 @@ cat > "$TOOLSET_PATH/package.json" << EOL
"build": "tsup",
"test": "echo \\"Error: no test specified\\" && exit 1"
},
- "keywords": [],
+ "keywords": ["composio", "toolset", "${TOOLSET_NAME}"],
"author": "",
"license": "ISC",
"packageManager": "[email protected]",
@@ -87,8 +93,9 @@ EOL
# Create src/index.ts
cat > "$TOOLSET_PATH/src/index.ts" << EOL
-import { BaseComposioToolset } from "@composio/core";
+import { ${IS_AGENTIC:+BaseAgenticToolset}${!IS_AGENTIC:+BaseNonAgenticToolset} } from "@composio/core";
import type { Tool, ToolListParams } from "@composio/core";
+import type { ${IS_AGENTIC:+ModifiersParams}${!IS_AGENTIC:+SchemaModifiersParams} } from "@composio/core";
interface ToolType {
// Add your tool type here
@@ -98,37 +105,114 @@ interface ToolCollection {
// Add your tool collection here
}
-export class ${CAPITAL_TOOLSET_NAME}Toolset extends BaseComposioToolset<ToolCollection, ToolType> {
+/**
+ * ${CAPITAL_TOOLSET_NAME} Toolset
+ * ${IS_AGENTIC:+This is an agentic toolset that supports full modifier capabilities.}
+${!IS_AGENTIC:+This is a non-agentic toolset that only supports schema modifiers.}
+ *
+ * @example
+ * \`\`\`typescript
+ * import { Composio } from "@composio/core";
+ * import { ${CAPITAL_TOOLSET_NAME}Toolset } from "@composio/${TOOLSET_NAME}-toolset";
+ *
+ * const composio = new Composio({
+ * apiKey: "your-api-key",
+ * toolset: new ${CAPITAL_TOOLSET_NAME}Toolset()
+ * });
+ * \`\`\`
+ */
+export class ${CAPITAL_TOOLSET_NAME}Toolset extends ${IS_AGENTIC:+BaseAgenticToolset}${!IS_AGENTIC:+BaseNonAgenticToolset}<ToolCollection, ToolType> {
static FRAMEWORK_NAME = "${TOOLSET_NAME}";
- private DEFAULT_ENTITY_ID = "default";
readonly FILE_NAME: string = "toolsets/${TOOLSET_NAME}/src/index.ts";
/**
- * Abstract method to wrap a tool in the toolset.
+ * Wraps a tool in the toolset format.
* This method is implemented by the toolset.
* @param tool - The tool to wrap.
* @returns The wrapped tool.
*/
- _wrapTool = (tool: Tool): ToolType => {
+ wrapTool = (tool: Tool): ToolType => {
return tool as ToolType;
}
/**
* Get all the tools from the Composio API
- * @param query - The query to get the tools
+ * @param params - The query parameters to get the tools
+ * @param modifiers - ${IS_AGENTIC:+Full modifiers to apply to the tools}${!IS_AGENTIC:+Schema modifiers to apply to the tools}
* @returns The tools
*/
- getTools = async (query?: ToolListParams): Promise<ToolCollection> => {
+ getTools = async (
+ params?: ToolListParams,
+ modifiers?: ${IS_AGENTIC:+ModifiersParams}${!IS_AGENTIC:+SchemaModifiersParams}
+ ): Promise<ToolCollection> => {
return [];
}
+
+ /**
+ * Get a tool from the Composio API by its slug
+ * @param slug - The slug of the tool to get
+ * @param modifiers - ${IS_AGENTIC:+Full modifiers to apply to the tool}${!IS_AGENTIC:+Schema modifiers to apply to the tool}
+ * @returns The tool
+ */
+ getToolBySlug = async (
+ slug: string,
+ modifiers?: ${IS_AGENTIC:+ModifiersParams}${!IS_AGENTIC:+SchemaModifiersParams}
+ ): Promise<ToolType> => {
+ const tool = await this.getComposio().tools.getToolBySlug(slug, modifiers?.schema);
+ return this.wrapTool(tool);
+ }
}
EOL
+# Create README.md
+cat > "$TOOLSET_PATH/README.md" << EOL
+# @composio/${TOOLSET_NAME}-toolset
+
+${IS_AGENTIC:+Agentic }Toolset for ${TOOLSET_NAME} in Composio SDK.
+
+## Installation
+
+\`\`\`bash
+pnpm add @composio/${TOOLSET_NAME}-toolset
+\`\`\`
+
+## Usage
+
+\`\`\`typescript
+import { Composio } from "@composio/core";
+import { ${CAPITAL_TOOLSET_NAME}Toolset } from "@composio/${TOOLSET_NAME}-toolset";
+
+const composio = new Composio({
+ apiKey: "your-api-key",
+ toolset: new ${CAPITAL_TOOLSET_NAME}Toolset()
+});
+
+// Get all tools
+const tools = await composio.getTools();
+
+// Get a specific tool by slug
+const tool = await composio.getToolBySlug("tool-slug");
+\`\`\`
+
+## Features
+
+${IS_AGENTIC:+This is an agentic toolset that supports full modifier capabilities, including:
+- Tool execution modifiers
+- Schema modifiers
+- Custom modifiers
+
+}${!IS_AGENTIC:+This is a non-agentic toolset that supports schema modifiers for transforming tool schemas.}
+
+## License
+
+ISC
+EOL
+
# Make the script executable
chmod +x "$TOOLSET_PATH"
# Install dependencies using pnpm
cd "$TOOLSET_PATH" && pnpm install
-echo "✨ Created new toolset at $TOOLSET_PATH"
+echo "✨ Created new ${IS_AGENTIC:+agentic }toolset at $TOOLSET_PATH"
echo "✨ Dependencies installed successfully"
\ No newline at end of file