Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Rename middlewares to modifiers
haxzied472f178634f
diff --git a/README.md b/README.mdindex e267db901..579b60193 100644--- a/README.md+++ b/README.md@@ -1,27 +1,214 @@-# Composio SDK+# Composio SDK v3-The core Composio SDK which allows users to interact with the Composio Platform. It provides a powerful and flexible way to manage and execute tools, handle authentication, and integrate with various platforms and frameworks.+The Composio SDK is a powerful toolkit that enables you to integrate third-party tools and services into your applications. It helps you connect to various services (toolkits), execute tools, and manage user connections seamlessly.++## Features++- Execute tools from various services (GitHub, Gmail, Slack, etc.)+- Manage user connections to external services+- Create custom tools with your own logic+- Integrate with AI providers like OpenAI+- Powerful middleware and modifier support+- Extensive error handling++## Documentation++The SDK is thoroughly documented in the [docs](./docs) directory:++- [Overview](./docs/overview.md) - Introduction and key concepts+- [Getting Started](./docs/getting-started.md) - Quick start guide+- [Core Concepts](./docs/core-concepts.md) - Fundamental SDK concepts++### API Reference++- [Composio Class](./docs/api/composio.md) - Main SDK class+- [Tools](./docs/api/tools.md) - Using and creating tools+- [Toolkits](./docs/api/toolkits.md) - Working with tool collections+- [Connected Accounts](./docs/api/connected-accounts.md) - User authentication+- [Auth Configs](./docs/api/auth-configs.md) - Authentication configuration+- [Custom Tools](./docs/api/custom-tools.md) - Creating your own tools+- [Providers](./docs/api/providers.md) - AI integration options++### Provider Documentation++- [OpenAI Provider](./docs/providers/openai.md) - Using OpenAI with Composio+- [Custom Providers](./docs/providers/custom.md) - Creating new providers++### Advanced Topics++- [Error Handling](./docs/advanced/error-handling.md) - Managing errors+- [Middleware and Modifiers](./docs/advanced/modifiers.md) - Customizing tools+- [Telemetry](./docs/advanced/telemetry.md) - SDK usage tracking+- [Custom Providers](./docs/advanced/custom-providers.md) - Detailed provider guide++## Installation++```bash+# Using npm+npm install @composio/core++# Using yarn+yarn add @composio/core++# Using pnpm+pnpm add @composio/core+```++## Quick Start++```typescript+import { Composio } from '@composio/core';++// Initialize the SDK+const composio = new Composio({+ apiKey: 'your-api-key',+});++// Get tools from a specific toolkit+const tools = await composio.tools.get('default', {+ toolkits: ['github'],+});++// Execute a tool+const result = await composio.tools.execute('GITHUB_GET_REPO', {+ userId: 'default',+ arguments: {+ owner: 'composio',+ repo: 'sdk',+ },+});++console.log(result.data);+```++## OpenAI Integration++```typescript+import { Composio } from '@composio/core';+import OpenAI from 'openai';++// Initialize Composio and OpenAI+const composio = new Composio({+ apiKey: 'your-composio-api-key',+});++const openai = new OpenAI({+ apiKey: 'your-openai-api-key',+});++// Get GitHub tools+const tools = await composio.tools.get('default', {+ toolkits: ['github'],+});++// Create a chat completion with the tools+const completion = await openai.chat.completions.create({+ model: 'gpt-4',+ messages: [+ { role: 'system', content: 'You are a helpful assistant with access to GitHub tools.' },+ { role: 'user', content: 'Find information about the Composio SDK repository' },+ ],+ tools, // Pass the tools to OpenAI+});++// If the model wants to use a tool+if (completion.choices[0].message.tool_calls) {+ const toolCall = completion.choices[0].message.tool_calls[0];+ const args = JSON.parse(toolCall.function.arguments);++ // Execute the tool+ const result = await composio.tools.execute(toolCall.function.name, {+ userId: 'default',+ arguments: args,+ });++ console.log(result.data);+}+```++## Creating Custom Tools++```typescript+// Create a custom tool+const customTool = await composio.tools.createCustomTool({+ name: 'Weather Forecast',+ description: 'Get the weather forecast for a location',+ slug: 'WEATHER_FORECAST',+ inputParameters: {+ type: 'object',+ properties: {+ location: {+ type: 'string',+ description: 'The location to get the forecast for',+ },+ days: {+ type: 'integer',+ description: 'Number of days for the forecast',+ default: 3,+ },+ },+ required: ['location'],+ },+ outputParameters: {+ type: 'object',+ properties: {+ forecast: {+ type: 'array',+ items: {+ type: 'object',+ properties: {+ date: { type: 'string' },+ temperature: { type: 'number' },+ conditions: { type: 'string' },+ },+ },+ },+ },+ },+ handler: async (params, context) => {+ try {+ const { location, days = 3 } = params.arguments;++ // Your implementation here+ const forecast = [+ { date: '2025-05-21', temperature: 72, conditions: 'Sunny' },+ { date: '2025-05-22', temperature: 68, conditions: 'Partly Cloudy' },+ { date: '2025-05-23', temperature: 65, conditions: 'Rainy' },+ ];++ return {+ data: { forecast },+ successful: true,+ error: null,+ };+ } catch (error) {+ return {+ data: {},+ successful: false,+ error: error.message,+ };+ }+ },+});+```## Project Structure```composio/├── packages/ # Main packages directory-│ ├── core/ # Core SDK package-│ │ └── core/ # Core SDK package-│ ├── providers/ # Provider implementations-│ │ ├── openai/ # OpenAI provider-│ │ ├── vercel/ # Vercel AI provider-│ │ ├── langchain/ # LangChain provider-│ │ └── cloudflare/ # Cloudflare provider-│ └── wrappers/ # Runtime-specific wrappers-├── examples/ # Example implementations-│ ├── langchain/ # LangChain example-│ ├── openai/ # OpenAI example-│ ├── pre-processors/ # Pre-processors example-│ └── vercel/ # Vercel AI example-├── scripts/ # Development and build scripts-└── .github/ # GitHub configuration+│ ├── core/ # Core SDK package+│ └── providers/ # Provider implementations+├── examples/ # Example implementations+│ ├── connected-accounts/ # Connected accounts examples+│ ├── langchain/ # LangChain integration examples+│ ├── openai/ # OpenAI integration examples+│ ├── modifiers/ # Modifiers examples+│ ├── toolkits/ # Toolkits examples+│ └── vercel/ # Vercel AI examples+├── docs/ # Documentation+├── scripts/ # Development and build scripts+└── .github/ # GitHub configuration```## Development Setup@@ -125,6 +312,15 @@ pnpm changeset:release- Follow the instructions to release the packages+## Environment Variables++- `COMPOSIO_API_KEY`: Your Composio API key+- `COMPOSIO_BASE_URL`: Custom API base URL (optional)+- `COMPOSIO_LOG_LEVEL`: Logging level (silent, error, warn, info, debug)+- `COMPOSIO_DISABLE_TELEMETRY`: Disable telemetry when set to "true"+- `DEVELOPMENT`: Development mode flag+- `CI`: CI environment flag+## ContributingWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.@@ -135,325 +331,4 @@ ISC License## Support-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).--## Core Features--- **Tools**: Manage and execute tools within the Composio ecosystem. Includes functionality to list, retrieve, and execute tools.-- **Toolkits**: Organize and manage collections of tools for specific use cases.-- **Triggers**: Create and manage event triggers that can execute tools based on specific conditions.-- **AuthConfigs**: Configure authentication providers and settings.-- **ConnectedAccounts**: Manage third-party service connections.-- **ActionExecution**: Track and manage the execution of actions within the platform.--## Installation--### Core SDK--```bash-npm install @composio/core-# or-yarn add @composio/core-# or-pnpm add @composio/core-```--### Providers--```bash-# Install OpenAI provider (included in core)-npm install @composio/openai--# Install Vercel AI provider-npm install @composio/vercel--# Install Langchain provider-npm install @composio/langchain-```--## Getting Started--### Basic Usage with OpenAI Provider--```typescript-import { Composio } from '@composio/core';-import { OpenAIProvider } from '@composio/openai-provider';--const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- // OpenAIProvider is the default, so this is optional- provider: new OpenAIProvider(),-});--// Fetch a single tool by it's slug-const tools = await composio.tools.get('user123', 'HACKERNEWS_SEARCH_POSTS');--// Fetch multiple tools-const tools = await composio.tools.get('user123', {- category: 'search',- limit: 10,-});-```--## Using with a Provider--### Example with Vercel AI Provider--```typescript-import { Composio } from '@composio/core';-import { VercelProvider } from '@composio/vercel-provider';--const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new VercelProvider(),-});--// Fetch tools for Vercel AI SDK-const tools = await composio.tools.get('user123', {- category: 'search',-});--// Use tools with Vercel AI SDK-const completion = await ai.chat({- messages: [{ role: 'user', content: 'Search for posts about React' }],- tools: tools,-});-```--## Modifiers--Composio SDK supports powerful modifiers to transform tool schemas and execution behavior.--### Schema Modifiers--Schema modifiers allow you to transform tool schemas before they are used:--```typescript-const tools = await composio.tools.get('user123', 'HACKERNEWS_SEARCH_POSTS', {- modifyToolSchema: (toolSlug: string, tool: Tool) => ({- ...tool,- description: 'Enhanced HackerNews search with additional features',- inputParameters: {- ...tool.inputParameters,- limit: {- type: 'number',- description: 'Maximum number of posts to return',- default: 10,- },- },- }),-});-```--### Execution Modifiers--For agentic providers (like Vercel AI and Langchain), you can also modify tool execution behavior:--```typescript-const tools = await composio.tools.get('user123', 'HACKERNEWS_SEARCH_POSTS', {- // Transform input before execution- beforeToolExecute: (toolSlug: string, params: ToolExecuteParams) => ({- ...params,- arguments: {- ...params.arguments,- limit: Math.min((params.arguments?.limit as number) || 10, 100),- },- }),-- // Transform output after execution- afterToolExecute: (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}`,- })),- },- }),-});-```--## Connected Accounts--Composio SDK provides a powerful way to manage third-party service connections through Connected Accounts. This feature allows you to authenticate with various services and maintain those connections.--### Creating a Connected Account--```typescript-import { Composio } from '@composio/core';--const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,-});--// Create a connected account-const connectionRequest = await composio.createConnectedAccount(- 'user123', // userId- 'id-of-auth-config', // authConfigId- {- redirectUrl: 'https://your-app.com/callback',- data: {- // Additional data for the connection- scope: ['read', 'write'],- },- }-);--// Wait for the connection to be established-// Default timeout is 60 seconds-const connectedAccount = await connectionRequest.waitForConnection();-```--### Waiting for Connection to be Established--The SDK provides a convenient way to wait for a connection to be established using the `waitForConnection` method:--```typescript-// From a ConnectionRequest instance (after creating a connected account)-// With default timeout (60 seconds)-const connectedAccount = await connectionRequest.waitForConnection();--// With custom timeout (2 minutes)-const connectedAccount = await connectionRequest.waitForConnection(120000);--// Directly from the ConnectedAccounts class (with an existing connected account ID)-const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_abc123', 60000);-```--The method polls the Composio API until:--- The connection becomes `ACTIVE` (returns the connected account)-- The connection enters a terminal state (`FAILED`, `EXPIRED`, `DELETED`) and throws an error-- The timeout is exceeded (throws a timeout error)--This is particularly useful for OAuth flows where the user needs to authorize the connection in a browser.--### Managing Connected Accounts--```typescript-// List all connected accounts-const accounts = await composio.connectedAccounts.list({- userId: 'user123',-});--// Get a specific connected account-const account = await composio.connectedAccounts.get('account_id');--// Enable/Disable a connected account-await composio.connectedAccounts.enable('account_id');-await composio.connectedAccounts.disable('account_id');--// Refresh credentials-await composio.connectedAccounts.refresh('account_id');--// Delete a connected account-await composio.connectedAccounts.delete('account_id');-```--### Connection Statuses--Connected accounts can have the following statuses:--- `ACTIVE`: Connection is established and working-- `INACTIVE`: Connection is temporarily disabled-- `PENDING`: Connection is being processed-- `INITIATED`: Connection request has started-- `EXPIRED`: Connection credentials have expired-- `FAILED`: Connection attempt failed--### Authentication Schemes--Composio supports various authentication schemes:--- OAuth2-- OAuth1-- OAuth1a-- API Key-- Basic Auth-- Bearer Token-- Google Service Account-- And more...--## Development--### Creating Custom Providers--You can create custom providers by extending either `BaseNonAgenticProvider` or `BaseAgenticProvider`:--#### Non-Agentic Provider--```typescript-import { BaseNonAgenticProvider } from '@composio/core';-import type { Tool } from '@composio/core';--interface CustomTool {- name: string;- // ... custom tool properties-}--export class CustomProvider extends BaseNonAgenticProvider<CustomTool[], CustomTool> {- readonly name = 'custom-provider';-- wrapTool = (tool: Tool): CustomTool => ({- name: tool.name,- // ... map other properties- });-- wrapTools = (tools: Tool[]): CustomTool[] => tools.map(tool => this.wrapTool(tool));-}-```--#### Agentic Provider--```typescript-import { BaseAgenticProvider } from '@composio/core';-import type { Tool, ToolExecuteParams, ToolExecuteResponse } from '@composio/core';--export class CustomAgenticProvider extends BaseAgenticProvider<CustomTool[], CustomTool> {- readonly name = 'custom-agentic-provider';-- wrapTool = (tool: Tool): CustomTool => ({- name: tool.name,- // ... map other properties- });-- wrapTools = (tools: Tool[]): CustomTool[] => tools.map(tool => this.wrapTool(tool));-- async executeToolCall(- userId: string,- tool: { name: string; arguments: unknown },- options: pppppp,- modifiers?: ExecuteToolModifiers- ): Promise<string> {- const result = await this.executeTool(- tool.name,- {- arguments: tool.arguments,- userId,- ...options,- },- modifiers- );- return JSON.stringify(result);- }-}-```--To quickly create a new provider project, use the provided script:--```bash-# Create a non-agentic provider-pnpm create:provider my-provider--# Create an agentic provider-pnpm create:provider my-provider --agentic-```--## Environment Variables--- `COMPOSIO_API_KEY`: Your Composio API key-- `COMPOSIO_BASE_URL`: Custom API base URL (optional)-- `COMPOSIO_LOGGING_LEVEL`: Logging level (silent, error, warn, info, debug)-- `DEVELOPMENT`: Development mode flag-- `CI`: CI environment flag+For support, please visit our [Documentation](./docs) or join our [Discord Community](https://discord.gg/composio).diff --git a/docs/README.md b/docs/README.mdindex 6748cd7e8..be3cc9c07 100644--- a/docs/README.md+++ b/docs/README.md@@ -109,4 +109,4 @@ Check out our [examples directory](../examples) for complete code samples:- [Error Handling](./advanced/error-handling.md)- [Telemetry](./advanced/telemetry.md)- [Custom Providers](./advanced/custom-providers.md)-- [Middleware and Modifiers](./advanced/middleware.md)+- [Modifiers](./advanced/modifiers.md)diff --git a/docs/getting-started.md b/docs/getting-started.mdindex 446b4be9e..bbaba39d5 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -270,4 +270,4 @@ Now that you understand the basics, you can:- Explore [more examples](../examples) to see how to use Composio in different scenarios- Learn about [custom providers](./api/providers.md) to integrate with other AI frameworks- Understand [error handling](./advanced/error-handling.md) to make your application more robust-- Implement [middleware and modifiers](./advanced/middleware.md) to customize tool execution+- Implement [modifiers](./advanced/modifiers.md) to customize tool execution