composiohq__composio/README.md

Composio SDK v3

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 directory:

• Overview - Introduction and key concepts
• Getting Started - Quick start guide
• Core Concepts - Fundamental SDK concepts
• Configuration - Environment variables and SDK configuration

API Reference

• Composio Class - Main SDK class
• Tools - Using and creating tools
• Toolkits - Working with tool collections
• Connected Accounts - User authentication
• Auth Configs - Authentication configuration
• Custom Tools - Creating your own tools
• Providers - AI integration options

Provider Documentation

• OpenAI Provider - Using OpenAI with Composio
• Google Provider - Using Google GenAI with Composio
• Custom Providers - Creating new providers

Advanced Topics

• Error Handling - Managing errors
• Middleware and Modifiers - Customizing tools
• Telemetry - SDK usage tracking
• Custom Providers - Detailed provider guide

Internal Documentation

For SDK maintainers and contributors:

• Configuration and Environment Variables - Detailed guide on SDK configuration
• Triggers Implementation - Internal workings of the trigger system

Installation

# Using npm
npm install @composio/core

# Using yarn
yarn add @composio/core

# Using pnpm
pnpm add @composio/core

Quick Start

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

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

// 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
│   └── 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

1. Prerequisites

   • Node.js (Latest LTS version recommended)
   • pnpm (v10.8.0 or later)
   • bun for productivity (optional)

2. Clone and Install

   git clone https://github.com/ComposioHQ/sdk-v3-ts.git
   cd composio
   pnpm install
   

3. Build

   pnpm build
   

4. Development Commands

   # Lint code
   pnpm lint
   
   # Fix linting issues
   pnpm lint:fix
   
   # Format code
   pnpm format
   
   # Create a new provider
   pnpm create:provider <provider-name> [--agentic]
   
   # Create a new example
   pnpm create:example <example-name>
   
   # Check peer dependencies
   pnpm check:peer-deps
   
   # Update peer dependencies
   pnpm update:peer-deps
   

Creating a New Example

1. Use the create:example script:

   pnpm create:example my-example
   

2. The script will create a new example in examples/my-example with:

   • package.json with minimal dependencies (@composio/core and dotenv)
   • tsconfig.json for TypeScript configuration
   • .env.example and .env files for environment variables
   • src/index.ts with basic Composio SDK setup
   • README.md with setup and usage instructions
   • Dependencies automatically installed

3. Next steps after creation:

   • Edit .env and add your COMPOSIO_API_KEY
   • Customize src/index.ts with your example logic
   • Add any additional dependencies as needed
   • Run with pnpm start or pnpm dev (with file watching)

Creating a New Provider

1. Use the create:provider script:

   pnpm create:provider my-provider [--agentic]
   

2. The script will create a new provider in packages/providers/my-provider with:

   • Basic provider implementation
   • TypeScript configuration
   • Package configuration
   • README template

3. Implement the required methods in src/index.ts:

   • For non-agentic providers: wrapTool and wrapTools
   • For agentic providers: wrapTool, wrapTools, and execution handlers

Release Process

For detailed information about both automated and manual release processes, please refer to our Release Process Documentation.

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

Contributing

We welcome contributions! Please see our Contributing Guide for more details.

License

ISC License

Support

For support, please visit our Documentation or join our Discord Community.