# Composio Providers This directory contains various providers that implement the Composio SDK for different platforms and frameworks. Each provider provides a way to interact with the Composio Platform using the specific platform's conventions and requirements. ## Types of Providers Composio SDK supports two types of providers, each with different modifier capabilities: ### 1. Non-Agentic Providers These providers only support schema modifiers for transforming tool schemas. They are suitable for simple integrations like OpenAI, Anthropic, etc. Example implementation: ```typescript import { BaseNonAgenticProvider } from '@composio/core'; import type { Tool, SchemaModifiersParams } from '@composio/core'; export class NonAgenticProvider extends BaseNonAgenticProvider { async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise { // Apply schema modifiers if provided if (modifiers?.schema) { return modifiers.schema(toolSlug, tool); } return tool; } async getTools(): Promise { // Fetch tools from Composio API const response = await this.client.getTools(); return response.data; } async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise { // Fetch tool from Composio API const response = await this.client.getToolBySlug(slug); // Apply schema modifiers if provided return this.wrapTool(slug, response.data, modifiers); } } ``` ### 2. Agentic Providers These providers support full modifier capabilities, making them suitable for complex integrations like Vercel, Langchain, etc. They support: 1. **Schema Modifiers**: Transform tool schemas using `TransformToolSchemaModifier` 2. **Execution Modifiers**: Transform tool execution behavior - `beforeExecute`: Transform input parameters before execution - `afterExecute`: Transform output after execution 3. **Execute Modifiers**: Used during tool execution - `beforeExecute`: Transform input parameters - `afterExecute`: Transform output Example implementation: ```typescript import { BaseAgenticProvider } from '@composio/core'; import type { Tool, ModifiersParams, ToolExecuteParams, ToolExecuteResponse } from '@composio/core'; export class AgenticProvider extends BaseAgenticProvider { async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise { let wrappedTool = tool; // Apply schema modifiers if provided if (modifiers?.schema) { wrappedTool = modifiers.schema(toolSlug, wrappedTool); } return wrappedTool; } async getTools(modifiers?: ModifiersParams): Promise { // Fetch tools from Composio API const response = await this.client.getTools(); // Apply modifiers to each tool return Promise.all(response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers))); } async getToolBySlug(slug: string, modifiers?: ModifiersParams): Promise { // Fetch tool from Composio API const response = await this.client.getToolBySlug(slug); // Apply modifiers return this.wrapTool(slug, response.data, modifiers); } async executeTool( tool: Tool, params: ToolExecuteParams, modifiers?: ModifiersParams ): Promise { let executeParams = params; // Apply beforeExecute modifier if provided if (modifiers?.beforeExecute) { executeParams = modifiers.beforeExecute(tool.slug, executeParams); } // Execute the tool const response = await this.client.executeTool(tool.slug, executeParams); // Apply afterExecute modifier if provided if (modifiers?.afterExecute) { return modifiers.afterExecute(tool.slug, response.data); } return response.data; } } ``` ## Creating a New Provider To create a new provider, you can use the provided script: ```bash # Create a non-agentic provider (default) pnpm run create-provider # Create an agentic provider pnpm run create-provider --agentic ``` The script will create a new provider with the following structure: ``` / ├── src/ │ └── index.ts # Provider implementation ├── package.json # Package configuration ├── tsconfig.json # TypeScript configuration ├── tsup.config.ts # Build configuration └── README.md # Provider documentation ``` ## Required Methods Each provider must implement the following methods: ### For Non-Agentic Providers ```typescript class NonAgenticProvider extends BaseNonAgenticProvider { // Wrap a tool with schema modifiers async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise; // Get all available tools async getTools(modifiers?: SchemaModifiersParams): Promise; // Get a specific tool by slug async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise; } ``` ### For Agentic Providers ```typescript class AgenticProvider extends BaseAgenticProvider { // Wrap a tool with modifiers async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise; // Get all available tools async getTools(modifiers?: ModifiersParams): Promise; // Get a specific tool by slug async getToolBySlug(slug: string, modifiers?: ModifiersParams): Promise; // Execute a tool with modifiers async executeTool( tool: Tool, params: ToolExecuteParams, modifiers?: ModifiersParams ): Promise; } ``` ## Modifier Types ### Schema Modifiers (Both Types) ```typescript type SchemaModifiersParams = { schema?: TransformToolSchemaModifier; }; type TransformToolSchemaModifier = (toolSlug: string, tool: Tool) => Tool; ``` ### Execution Modifiers (Agentic Only) ```typescript type ModifiersParams = { schema?: TransformToolSchemaModifier; beforeExecute?: beforeExecuteModifier; afterExecute?: afterExecuteModifier; }; type beforeExecuteModifier = (toolSlug: string, params: ToolExecuteParams) => ToolExecuteParams; type afterExecuteModifier = ( toolSlug: string, response: ToolExecuteResponse ) => ToolExecuteResponse; ``` ## Best Practices 1. **Type Safety**: Always use TypeScript and ensure proper type definitions for all methods and parameters. 2. **Error Handling**: Implement proper error handling for API calls and tool execution. 3. **Documentation**: Document your provider's features, requirements, and usage examples. 4. **Testing**: Write tests for your provider implementation. 5. **Modifier Support**: - For non-agentic providers, implement schema modifiers to transform tool schemas - For agentic providers, implement both schema and execution modifiers for full control over tool behavior ## Example Implementation Here's a complete example of a non-agentic provider implementation: ```typescript import { BaseNonAgenticProvider } from '@composio/core'; import type { Tool, SchemaModifiersParams } from '@composio/core'; export class OpenAIProvider extends BaseNonAgenticProvider { async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise { // Apply schema modifiers if provided if (modifiers?.schema) { return modifiers.schema(toolSlug, tool); } return tool; } async getTools(modifiers?: SchemaModifiersParams): Promise { // Fetch tools from Composio API const response = await this.client.getTools(); // Apply modifiers to each tool return Promise.all(response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers))); } async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise { // Fetch tool from Composio API const response = await this.client.getToolBySlug(slug); // Apply modifiers return this.wrapTool(slug, response.data, modifiers); } } ``` And here's a complete example of an agentic provider implementation: ```typescript import { BaseAgenticProvider } from '@composio/core'; import type { Tool, ModifiersParams, ToolExecuteParams, ToolExecuteResponse } from '@composio/core'; export class VercelProvider extends BaseAgenticProvider { async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise { let wrappedTool = tool; // Apply schema modifiers if provided if (modifiers?.schema) { wrappedTool = modifiers.schema(toolSlug, wrappedTool); } return wrappedTool; } async getTools(modifiers?: ModifiersParams): Promise { // Fetch tools from Composio API const response = await this.client.getTools(); // Apply modifiers to each tool return Promise.all(response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers))); } async getToolBySlug(slug: string, modifiers?: ModifiersParams): Promise { // Fetch tool from Composio API const response = await this.client.getToolBySlug(slug); // Apply modifiers return this.wrapTool(slug, response.data, modifiers); } async executeTool( tool: Tool, params: ToolExecuteParams, modifiers?: ModifiersParams ): Promise { let executeParams = params; // Apply beforeExecute modifier if provided if (modifiers?.beforeExecute) { executeParams = modifiers.beforeExecute(tool.slug, executeParams); } // Execute the tool const response = await this.client.executeTool(tool.slug, executeParams); // Apply afterExecute modifier if provided if (modifiers?.afterExecute) { return modifiers.afterExecute(tool.slug, response.data); } return response.data; } } ``` ## Usage Examples ### Using a Non-Agentic Provider ```typescript import { Composio } from '@composio/core'; import { OpenAIProvider } from '@composio/openai-provider'; import type { Tool } from '@composio/core'; const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY, provider: new OpenAIProvider(), }); // Get a tool with schema modifiers const tool = await composio.getToolBySlug('HACKERNEWS_SEARCH_POSTS', { schema: (toolSlug: string, tool: Tool) => ({ ...tool, description: 'Search HackerNews posts with improved description', inputParameters: { ...tool.inputParameters, limit: { type: 'number', description: 'Maximum number of posts to return', }, }, }), }); ``` ### Using an Agentic Provider ```typescript import { Composio } from '@composio/core'; import { VercelProvider } from '@composio/vercel-provider'; import type { Tool, ToolExecuteParams, ToolExecuteResponse } from '@composio/core'; const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY, provider: new VercelProvider(), }); // Get a tool with full modifier support const tool = await composio.getToolBySlug('HACKERNEWS_SEARCH_POSTS', { // Schema modifier schema: (toolSlug: string, tool: Tool) => ({ ...tool, description: 'Search HackerNews posts with improved description', inputParameters: { ...tool.inputParameters, limit: { type: 'number', description: 'Maximum number of posts to return', }, }, }), // Execution modifiers beforeExecute: (toolSlug: string, params: ToolExecuteParams) => ({ ...params, arguments: { ...params.arguments, limit: Math.min((params.arguments?.limit as number) || 10, 100), }, }), afterExecute: (toolSlug: string, response: ToolExecuteResponse) => ({ ...response, data: { ...response.data, posts: (response.data?.posts as any[]).map(post => ({ ...post, url: post.url || `https://news.ycombinator.com/item?id=${post.id}`, })), }, }), }); // Execute the tool with execution modifiers const result = await composio.provider.executeTool( tool, { arguments: { query: 'AI', limit: 20 }, }, { beforeExecute: (toolSlug: string, params: ToolExecuteParams) => ({ ...params, arguments: { ...params.arguments, limit: Math.min((params.arguments?.limit as number) || 10, 100), }, }), afterExecute: (toolSlug: string, response: ToolExecuteResponse) => ({ ...response, data: { ...response.data, posts: (response.data?.posts as any[]).map(post => ({ ...post, url: post.url || `https://news.ycombinator.com/item?id=${post.id}`, })), }, }), } ); ```