@composio/core

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.

Learn more about the SDK from our docs

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

npm install @composio/core
# or
yarn add @composio/core
# or
pnpm add @composio/core

Getting Started

Basic Usage with OpenAI Provider

import { Composio } from '@composio/core';
import { OpenAI } from 'openai';

// Initialize OpenAI client
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Initialize Composio with your API key
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

async function main() {
  try {
    // Fetch tools - single tool or multiple tools
    const tools = await composio.tools.get('default', 'HACKERNEWS_GET_USER');
    // Or fetch multiple tools: await composio.tools.get('default', { toolkits: ['hackernews'] });

    const query = "Find information about the HackerNews user 'pg'";

    // Create chat completion with tools
    const response = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages: [
        {
          role: 'system',
          content: 'You are a helpful assistant that can use tools to answer questions.',
        },
        { role: 'user', content: query },
      ],
      tools: tools,
      tool_choice: 'auto',
    });

    // Handle tool calls if the assistant decides to use them
    if (response.choices[0].message.tool_calls) {
      console.log(
        '🔧 Assistant is using tool:',
        response.choices[0].message.tool_calls[0].function.name
      );

      // Execute the tool call
      const toolResult = await composio.provider.executeToolCall(
        'default',
        response.choices[0].message.tool_calls[0],
        {
          connectedAccountId: '', // Optional: specify connected account
        }
      );

      console.log('✅ Tool execution result:', JSON.parse(toolResult));

      // Get final response from assistant with tool result
      const finalResponse = await openai.chat.completions.create({
        model: 'gpt-4o',
        messages: [
          {
            role: 'system',
            content: 'You are a helpful assistant that can use tools to answer questions.',
          },
          { role: 'user', content: query },
          response.choices[0].message,
          {
            role: 'tool',
            tool_call_id: response.choices[0].message.tool_calls[0].id,
            content: toolResult,
          },
        ],
      });

      console.log('🤖 Final response:', finalResponse.choices[0].message.content);
    } else {
      console.log('🤖 Response:', response.choices[0].message.content);
    }
  } catch (error) {
    console.error('❌ Error:', error);
  }
}

main();

Configuration

The Composio constructor accepts the following configuration options:

interface ComposioConfig {
  apiKey?: string | null; // Your Composio API key
  baseURL?: string | null; // Custom API base URL (optional)
  allowTracking?: boolean; // Enable/disable telemetry (default: true)
  autoUploadDownloadFiles?: boolean; // Whether to automatically upload and download files during tool execution (default: true)
  provider?: TProvider; // Custom provider (default: OpenAIProvider)
  host?: string; // Name of the host service which is using the SDK, this is for telemetry
  defaultHeaders?: ComposioRequestHeaders; // Request headers to be passed to the Composio API client
  disableVersionCheck?: boolean; // Whether to disable version check for the Composio SDK (default: false)
}

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:

const tools = await composio.tools.get('user123', 'HACKERNEWS_SEARCH_POSTS', {
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => ({
    ...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:

const tools = await composio.tools.get('user123', 'HACKERNEWS_SEARCH_POSTS', {
  // Transform input before execution
  beforeExecute: ({ toolSlug, toolkitSlug, params }) => ({
    ...params,
    arguments: {
      ...params.arguments,
      limit: Math.min((params.arguments?.limit as number) || 10, 100),
    },
  }),

  // Transform output after execution
  afterExecute: ({ toolSlug, toolkitSlug, result }) => ({
    ...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

import { Composio } from '@composio/core';

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

// Create a connected account
const connectionRequest = await composio.connectedAccounts.initiate(
  'user123', // userId
  'ac_12343544', // authConfigId: You can create it from the dashboard
  {
    callbackUrl: '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();
console.log({ connectedAccount });

Waiting for Connection Establishment

The waitForConnection method is available on both the ConnectionRequest and ConnectedAccounts classes. It allows you to poll for a connection to become active:

// From a ConnectionRequest instance (returned by createConnectedAccount)
const connectedAccount = await connectionRequest.waitForConnection(120000); // 2 minute timeout

// From the ConnectedAccounts class (using a connected account ID)
const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_abc123', 60000); // 1 minute timeout

The method continuously polls the Composio API until the connection:

• Becomes ACTIVE (returns the connected account)
• Enters a terminal state like FAILED, EXPIRED, or DELETED (throws an error)
• Exceeds the specified timeout (throws a timeout error)

If the connection does not complete within the provided timeout (default: 60 seconds), a ConnectionRequestTimeoutError is thrown.

Managing Connected Accounts

// 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...

Environment Variables

• COMPOSIO_API_KEY: Your Composio API key
• COMPOSIO_BASE_URL: Custom API base URL
• COMPOSIO_LOGGING_LEVEL: Logging level (silent, error, warn, info, debug)
• DEVELOPMENT: Development mode flag
• COMPOSIO_TOOLKIT_VERSION_<TOOLKITNAME>: Version of the specific tool
• 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.