@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
md 465 lines 16.6 KB
Rendered Raw
1 # Tools API
2
3 The `Tools` class provides methods to list, retrieve, and execute tools from various toolkits. It is one of the core components of the Composio SDK.
4
5 ## Methods
6
7 ### get(userId, filters, options?)
8
9 Retrieves and wraps tools based on the provided filters. Tool versions are controlled at the Composio SDK initialization level through the `toolkitVersions` configuration. See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for more details on version management.
10
11 #### Overload 1: Get multiple tools with filters
12
13 ```typescript
14 // Get important tools from a toolkit (auto-applies important filter)
15 const importantGithubTools = await composio.tools.get('default', {
16 toolkits: ['github']
17 });
18
19 // Get a limited number of tools (does NOT auto-apply important filter)
20 const githubTools = await composio.tools.get('default', {
21 toolkits: ['github'],
22 limit: 10
23 });
24
25 // Get tools with search (does NOT auto-apply important filter)
26 const searchTools = await composio.tools.get('default', {
27 search: 'user'
28 });
29
30 // Get tools with schema modifications
31 const customizedTools = await composio.tools.get('default', {
32 toolkits: ['github']
33 }, {
34 modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
35 return { ...schema, description: 'Custom description' };
36 }
37 });
38 ```
39
40 **Parameters:**
41 - `userId` (string): The user ID to get the tools for
42 - `filters` (ToolListParams): Filters object to specify which tools to retrieve
43 - `options` (ProviderOptions): Optional provider options including modifiers
44
45 #### Overload 2: Get a specific tool by slug
46
47 ```typescript
48 // Get a specific tool by slug
49 const tool = await composio.tools.get('default', 'GITHUB_GET_REPO');
50
51 // Get a tool with schema modifications
52 const customTool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
53 modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
54 return { ...schema, description: 'Enhanced GitHub repository tool' };
55 }
56 });
57 ```
58
59 **Parameters:**
60 - `userId` (string): The user ID to get the tool for
61 - `slug` (string): The slug of the specific tool to fetch
62 - `options` (ProviderOptions): Optional provider options including modifiers
63
64 **Returns:** The wrapped tools collection, formatted according to the provider being used
65
66 ### execute(slug, body, modifiers?)
67
68 Executes a given tool with the provided parameters manually.
69
70 > **Important:** When manually executing tools (especially in workflows), a specific version is **required**. The method will throw an error if toolkitVersion is not provided or `latest` is used as the version. This ensures there are no mismatches in tool arguments when new versions are released. You can bypass this requirement using `dangerouslySkipVersionCheck: true`, but this is **not recommended for production**.
71
72 ```typescript
73 // Execute with a pinned version (REQUIRED for workflows and manual execution)
74 const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
75 userId: 'default',
76 arguments: { owner: 'composio', repo: 'sdk' },
77 version: '12082025_00', // Specific version required
78 });
79
80 // Or configure versions at initialization (RECOMMENDED)
81 const composio = new Composio({
82 toolkitVersions: {
83 github: '12082025_00',
84 slack: '10082025_01'
85 }
86 });
87
88 const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
89 userId: 'default',
90 arguments: { owner: 'composio', repo: 'sdk' },
91 // Uses pinned version from initialization
92 });
93
94 // Execute with dangerouslySkipVersionCheck (NOT recommended for production)
95 // This allows using 'latest' version and bypasses version validation
96 const result = await composio.tools.execute('SLACK_SEND_MESSAGE', {
97 userId: 'default',
98 arguments: { channel: '#general', text: 'Hello!' },
99 dangerouslySkipVersionCheck: true, // Skip version validation (use with caution)
100 });
101
102 // Execute with modifiers
103 const result = await composio.tools.execute(
104 'GITHUB_GET_ISSUES',
105 {
106 userId: 'default',
107 arguments: { owner: 'composio', repo: 'sdk' },
108 version: '12082025_00', // Always specify version
109 },
110 {
111 beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
112 // Modify params before execution
113 return params;
114 },
115 afterExecute: ({ toolSlug, toolkitSlug, result }) => {
116 // Transform result after execution
117 return result;
118 },
119 }
120 );
121 ```
122
123 **Parameters:**
124
125 - `slug` (string): The slug/ID of the tool to be executed
126 - `body` (ToolExecuteParams): The parameters to be passed to the tool
127 - `modifiers` (ExecuteToolModifiers): Optional modifiers to transform the request or response
128
129 #### Version Requirements for Manual Tool Execution
130
131 When building workflows that require manually executing tools, **a specific pinned version is mandatory**. Using `'latest'` is not allowed and will throw an error. This strict requirement prevents argument mismatches that can occur when tool schemas change in newer versions.
132
133 **Why Version Pinning is Required:**
134 - Tool argument schemas can change between versions
135 - Using `'latest'` in workflows can cause runtime errors when tools are updated
136 - Pinned versions ensure workflow stability and predictability
137 - Version validation prevents production issues from schema mismatches
138
139 **Three Approaches to Handle Versions:**
140
141 **1. Specify a concrete version in the execute call** (Recommended):
142 ```typescript
143 const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
144 userId: 'default',
145 arguments: { owner: 'composio', repo: 'sdk' },
146 version: '12082025_00', // Explicit version for this tool
147 });
148 ```
149
150 **2. Configure toolkit versions at initialization** (Recommended for production):
151 ```typescript
152 const composio = new Composio({
153 toolkitVersions: {
154 github: '12082025_00',
155 slack: '10082025_01'
156 }
157 });
158
159 // Now execute without version parameter - uses pinned version from config
160 const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
161 userId: 'default',
162 arguments: { owner: 'composio', repo: 'sdk' },
163 });
164 ```
165
166 **3. Use `dangerouslySkipVersionCheck: true`** (NOT recommended for production):
167 ```typescript
168 const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
169 userId: 'default',
170 arguments: { owner: 'composio', repo: 'sdk' },
171 dangerouslySkipVersionCheck: true, // Bypasses version validation and uses 'latest'
172 });
173 ```
174
175 > ⚠️ **Warning:** Using `dangerouslySkipVersionCheck: true` bypasses version validation and allows the use of `'latest'` version. This can lead to unexpected behavior and argument mismatches when tool schemas change. **Only use this flag during development or testing.** Always pin specific versions in production environments to ensure workflow stability.
176
177 **Returns:** Promise<ToolExecuteResponse> - The response from the tool execution
178
179 **Throws:**
180
181 - `ComposioToolNotFoundError`: If the tool with the given slug is not found
182 - `ComposioToolExecutionError`: If there is an error during tool execution
183
184 ### getRawComposioTools(query, options?)
185
186 Lists all tools available from the Composio API. This method provides direct access to tool data without provider-specific wrapping.
187
188 ```typescript
189 // Get important tools from a toolkit (auto-applies important filter)
190 const importantGithubTools = await composio.tools.getRawComposioTools({
191 toolkits: ['github']
192 });
193
194 // Get a limited number of tools (does NOT auto-apply important)
195 const limitedTools = await composio.tools.getRawComposioTools({
196 toolkits: ['github'],
197 limit: 10
198 });
199
200 // Get specific tools by slug
201 const specificTools = await composio.tools.getRawComposioTools({
202 tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
203 });
204
205 // Get tools with schema transformation
206 const customizedTools = await composio.tools.getRawComposioTools({
207 toolkits: ['github'],
208 limit: 5
209 }, {
210 modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
211 return {
212 ...schema,
213 customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
214 tags: [...(schema.tags || []), 'customized']
215 };
216 }
217 });
218
219 // Search for tools
220 const searchResults = await composio.tools.getRawComposioTools({
221 search: 'user management'
222 });
223 ```
224
225 **Parameters:**
226
227 - `query` (ToolListParams): Query parameters to filter the tools (required)
228 - `options` (GetRawComposioToolsOptions): Optional configuration for tool retrieval
229 - `modifySchema` (TransformToolSchemaModifier): Function to transform tool schemas
230
231 **Returns:** Promise<ToolList> - List of tools matching the query criteria
232
233 ### getRawComposioToolBySlug(slug, options?)
234
235 Retrieves a specific tool by its slug from the Composio API. This method provides direct access to tool schema and metadata without provider-specific wrapping.
236
237 ```typescript
238 // Get a tool by slug
239 const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS');
240
241 // Get a tool with schema transformation
242 const customizedTool = await composio.tools.getRawComposioToolBySlug(
243 'SLACK_SEND_MESSAGE',
244 {
245 modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
246 return {
247 ...schema,
248 description: `Enhanced ${schema.description} with custom modifications`,
249 customMetadata: {
250 lastModified: new Date().toISOString(),
251 toolkit: toolkitSlug
252 }
253 };
254 }
255 }
256 );
257
258 // Access tool properties
259 const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_AN_ISSUE');
260 console.log({
261 slug: githubTool.slug,
262 name: githubTool.name,
263 toolkit: githubTool.toolkit?.name,
264 version: githubTool.version,
265 availableVersions: githubTool.availableVersions
266 });
267 ```
268
269 **Parameters:**
270
271 - `slug` (string): The unique identifier of the tool (e.g., 'GITHUB_GET_REPOS')
272 - `options` (GetRawComposioToolBySlugOptions): Optional configuration for tool retrieval
273 - `modifySchema` (TransformToolSchemaModifier): Function to transform the tool schema
274
275 **Returns:** Promise<Tool> - The requested tool with its complete schema and metadata
276
277 ## Types
278
279 ### ToolListParams
280
281 ```typescript
282 // You must provide one of the following parameter combinations:
283 // 1. tools array only
284 // 2. toolkits (optionally filter to important tools)
285 // 3. toolkits with search functionality
286
287 type ToolsOnlyParams = {
288 tools: string[]; // List of tool slugs to filter by
289 toolkits?: never; // Cannot be used with tools
290 limit?: never;
291 search?: never;
292 scopes?: never;
293 }
294
295 type ToolkitsOnlyParams = {
296 tools?: never; // Cannot be used with toolkits
297 toolkits: string[]; // List of toolkit slugs to filter by
298 limit?: number; // Limit the number of results (prevents auto-applying important)
299 search?: string; // Optional search term (prevents auto-applying important)
300 tags?: string[]; // Optional tags filter (prevents auto-applying important)
301 important?: boolean; // Filter to only important/featured tools (auto-applied when no limit/tags/search)
302 scopes?: never;
303 };
304
305 type ToolkitScopeOnlyParams = {
306 tools?: never;
307 toolkits: [string];
308 scopes: string[];
309 limit?: number; // Prevents auto-applying important
310 search?: string; // Prevents auto-applying important
311 tags?: string[]; // Prevents auto-applying important
312 important?: boolean; // Filter to only important/featured tools (auto-applied when no limit/tags/search)
313 };
314
315 type ToolkitSearchOnlyParams = {
316 tools?: never; // Cannot be used with search
317 toolkits?: string[]; // Optional list of toolkit slugs to filter by
318 limit?: number; // Limit the number of results
319 search: string; // Search term
320 scopes?: never;
321 };
322
323 type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | ToolkitScopeOnlyParams | ToolkitSearchOnlyParams;
324 ```
325
326 #### Auto-applying the `important` Filter
327
328 When querying by `toolkits` only (without `tools`, `tags`, `search`, or `limit`), the SDK automatically applies `important: true` to prioritize the most useful tools from that toolkit. This helps reduce the number of tools returned and focuses on the most commonly used ones.
329
330 **Auto-apply conditions:**
331 - ✅ `toolkits` is provided
332 - ✅ `tools` is NOT provided
333 - ✅ `tags` is NOT provided
334 - ✅ `search` is NOT provided
335 - ✅ `limit` is NOT provided
336 - ✅ `important` is NOT explicitly set to `false`
337
338 **Examples:**
339
340 ```typescript
341 // Auto-applies important: true
342 const tools = await composio.tools.getRawComposioTools({
343 toolkits: ['github']
344 });
345 // Result: Only important GitHub tools
346
347 // Does NOT auto-apply important (limit provided)
348 const tools = await composio.tools.getRawComposioTools({
349 toolkits: ['github'],
350 limit: 50
351 });
352 // Result: First 50 GitHub tools (including non-important)
353
354 // Does NOT auto-apply important (tags provided)
355 const tools = await composio.tools.getRawComposioTools({
356 toolkits: ['github'],
357 tags: ['important']
358 });
359 // Result: GitHub tools with 'important' tag
360
361 // Does NOT auto-apply important (search provided)
362 const tools = await composio.tools.getRawComposioTools({
363 toolkits: ['github'],
364 search: 'repository'
365 });
366 // Result: GitHub tools matching 'repository' search
367
368 // Explicitly disable auto-apply
369 const tools = await composio.tools.getRawComposioTools({
370 toolkits: ['github'],
371 important: false
372 });
373 // Result: All GitHub tools (including non-important)
374
375 // Explicitly enable important even with limit
376 const tools = await composio.tools.getRawComposioTools({
377 toolkits: ['github'],
378 limit: 20,
379 important: true
380 });
381 // Result: First 20 important GitHub tools
382 ```
383
384 **Why does `limit` prevent auto-applying `important`?**
385
386 When you provide a `limit`, you're indicating that you want a specific number of tools. Auto-applying the `important` filter could result in fewer tools than your limit if the toolkit has limited important tools. By not auto-applying, you get the exact number of tools you requested.
387
388 Note: The parameters are organized into three mutually exclusive combinations:
389
390 1. Using `tools` array to fetch specific tools by their slugs
391 2. Using `toolkits` with optional `important` flag to fetch tools from specific toolkits
392 3. Using `search` with optional `toolkits` to search for tools by name/description
393 4. Using `scopes` can only be done with a single `toolkits` slug
394
395 You can also filter tools by their scopes:
396
397 ```typescript
398 // Get tools with specific scopes
399 const scopedTools = await composio.tools.get('default', {
400 toolkits: ['github'],
401 scopes: ['read:repo', 'write:repo'], // Only get tools requiring these scopes
402 });
403
404 // Search tools with specific scopes
405 const searchedScopedTools = await composio.tools.get('default', {
406 search: 'repository',
407 scopes: ['read:repo'], // Only get tools requiring read:repo scope
408 limit: 10,
409 });
410 ```
411
412 The `scopes` parameter allows you to:
413 - Filter tools based on their required OAuth scopes
414 - Get tools that match specific permission levels
415 - Ensure tools align with available user permissions
416
417 Examples:
418
419 ```typescript
420 // Get specific tools by slug
421 const specificTools = await composio.tools.get('default', {
422 tools: ['GITHUB_GET_REPO', 'GITHUB_LIST_ISSUES'],
423 });
424
425 // Search for tools across all or specific toolkits
426 const searchResults = await composio.tools.get('default', {
427 search: 'repository',
428 toolkits: ['github'], // optional
429 limit: 10,
430 });
431 ```
432
433 ### ToolExecuteParams
434
435 ```typescript
436 interface ToolExecuteParams {
437 allowTracing?: boolean; // Enable/disable tracing
438 connectedAccountId?: string; // Connected account ID
439 customAuthParams?: CustomAuthParams; // Custom auth parameters
440 customConnectionData?: CustomConnectionData; // Custom connection data
441 arguments?: Record<string, unknown>; // Tool arguments
442 userId: string; // User ID (required)
443 version?: string; // Tool version (e.g., '12082025_00') - overrides global toolkit version
444 dangerouslySkipVersionCheck?: boolean; // Skip version validation (NOT recommended for production)
445 text?: string; // Text input
446 }
447 ```
448
449 **Parameter Details:**
450
451 - **`version`** (string, conditionally required): Specifies the toolkit version to use for this tool execution. **Required when manually executing tools** unless a specific version is configured at initialization or `dangerouslySkipVersionCheck` is set to `true`. Using `'latest'` will throw a `ValidationError` to prevent schema mismatches in workflows. Format: `'DDMMYYYY_NN'` (e.g., `'12082025_00'`). See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for more details.
452
453 - **`dangerouslySkipVersionCheck`** (boolean, optional): When set to `true`, bypasses version validation during tool execution and allows using `'latest'` version. This is useful for development and testing but **NOT recommended for production** as it can lead to unexpected behavior and argument mismatches when tool schemas change. Always pin specific toolkit versions at initialization or pass a `version` parameter in production environments.
454
455 ### ToolExecuteResponse
456
457 ```typescript
458 interface ToolExecuteResponse {
459 data: Record<string, unknown>; // Tool execution data
460 error: string | null; // Error message (if any)
461 successful: boolean; // Whether the execution was successful
462 logId?: string; // Log ID for debugging
463 sessionInfo?: unknown; // Session information
464 }
465 ```