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
Update readme.md
haxzie86760caf4773
diff --git a/packages/core/README.md b/packages/core/README.mdindex 4a36c893c..7b21fc61a 100644--- a/packages/core/README.md+++ b/packages/core/README.md@@ -1,26 +1,15 @@# @composio/core-The core package of Composio SDK, providing essential functionality for building and managing AI-powered tools and toolsets.+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.-## Features+## Core Features-### 1. Core Functionality-- **Composio Client Integration**: Seamless integration with Composio API-- **Tool Management**: Create, manage, and execute tools-- **Toolkit Support**: Organize tools into toolsets-- **Authentication & Authorization**: Built-in auth configuration and management-- **Connected Accounts**: Manage multiple account connections--### 2. Toolsets-- **Default OpenAI Toolset**: Ships with built-in OpenAI integration-- **Extensible Base Toolset**: Create custom toolsets by extending `BaseComposioToolset`-- **Tool Wrapping**: Standardized tool wrapping and execution--### 3. Advanced Features-- **Telemetry**: Built-in telemetry for monitoring and debugging-- **Logging**: Configurable logging system with multiple levels-- **Environment Management**: Flexible configuration through environment variables-- **Version Management**: Automatic version checking and updates+- **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@@ -32,23 +21,27 @@ yarn add @composio/corepnpm add @composio/core```-## Quick Start+## Getting Started++### Basic Usage with OpenAI Toolset```typescriptimport { Composio } from '@composio/core';+import { OpenAIToolset } from '@composio/openai-toolset';-// Initialize Composio with default OpenAI toolsetconst composio = new Composio({- apiKey: 'your-api-key',- baseURL: 'https://api.composio.dev', // optional+ apiKey: process.env.COMPOSIO_API_KEY,+ // OpenAIToolset is the default, so this is optional+ toolset: new OpenAIToolset(),});-// Get available tools-const tools = await composio.getTools();+// Fetch a single tool+const searchTool = await composio.tools.get('user123', 'HACKERNEWS_SEARCH_POSTS');-// Execute a specific tool-const result = await composio.tools.execute('tool-slug', {- // tool parameters+// Fetch multiple tools+const tools = await composio.tools.get('user123', {+ category: 'search',+ limit: 10,});```@@ -58,53 +51,146 @@ The Composio constructor accepts the following configuration options:```typescriptinterface ComposioConfig {- apiKey?: string; // Your Composio API key- baseURL?: string; // Custom API base URL (optional)- allowTracking?: boolean; // Enable/disable telemetry (default: true)- allowTracing?: boolean; // Enable/disable tracing (default: true)- toolset?: TToolset; // Custom toolset (default: OpenAIToolset)- userId?: string; // Custom user ID- connectedAccountIds?: Record<string, string>; // Connected account mappings+ apiKey?: string; // Your Composio API key+ baseURL?: string; // Custom API base URL (optional)+ allowTracking?: boolean; // Enable/disable telemetry (default: true)+ allowTracing?: boolean; // Enable/disable tracing (default: true)+ toolset?: TToolset; // Custom toolset (default: OpenAIToolset)telemetryTransport?: BaseTelemetryTransport; // Custom telemetry transport}```-## Toolsets+## 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 tool = 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-### Default OpenAI Toolset+For agentic toolsets (like Vercel AI and Langchain), you can also modify tool execution behavior:-The core package ships with OpenAI toolset by default. For more information about the OpenAI toolset and its capabilities, check out the [OpenAI Toolset Documentation](./toolset/OpenAIToolset.md).+```typescript+const tool = 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}`,+ })),+ },+ }),+});+```-### Creating Custom Toolsets+## Connected Accounts-You can create custom toolsets by extending the `BaseComposioToolset`:+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 { BaseComposioToolset, Tool } from '@composio/core';+import { Composio } from '@composio/core';-interface CustomTool {- name: string;- // ... custom tool properties-}+const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+});-class CustomToolset extends BaseComposioToolset<CustomTool[], CustomTool> {- readonly FILE_NAME = 'custom/toolset.ts';-- _wrapTool = (tool: Tool): CustomTool => {- // Implement tool wrapping logic- return {- name: tool.name,- // ... map other properties- };- };-- async getTools() {- const tools = await this.client?.tools.list();- return tools?.items.map(tool => this._wrapTool(tool)) ?? [];+// Create a connected account+const connectionRequest = await composio.createConnectedAccount(+ 'user123', // userId+ 'HACKERNEWS', // 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();+```++### 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...+## Environment Variables- `COMPOSIO_API_KEY`: Your Composio API key