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 22, 15:45 UTC
Update tool router sdk docs (#2369)
Musthaq Ahamad committed
Jan 12, 2026 at 21:13 UTC
4a9167d7682e5b71a34ee43002b89705807c2134
3 files changed
+422
-24
python/docs/tool-router.md
+143
-8
@@ -211,7 +211,24 @@ session = composio.tool_router.create(
211
toolkits=['gmail'],
212
manage_connections={
213
'enable': True, # Whether to use tools to manage connections
214
- 'callback_url': 'https://your-app.com/auth/callback' # Optional OAuth callback URL
214
+ 'callback_url': 'https://your-app.com/auth/callback', # Optional OAuth callback URL
215
+ 'wait_for_connections': True # NEW in v0.10.5: Wait for connections to complete
216
+ }
217
+)
218
+```
219
+
220
+#### Wait for Connections
221
+
222
+The `wait_for_connections` property (new in v0.10.5) allows the tool router session to wait for users to complete authentication before proceeding to the next step. When set to `True`, the session will block execution until all required connections are established.
223
+
224
+```python
225
+session = composio.tool_router.create(
226
+ user_id='user_123',
227
+ toolkits=['gmail', 'slack'],
228
+ manage_connections={
229
+ 'enable': True,
230
+ 'callback_url': 'https://your-app.com/auth/callback',
231
+ 'wait_for_connections': True # Session waits for connections to complete
232
}
233
)
234
```
@@ -261,13 +278,67 @@ Retrieve the tools available in the session, formatted for your AI framework.
278
# Basic usage
279
tools = session.tools()
280
264
-# With modifiers
265
-tools = session.tools(modifiers={
266
- 'pre_execute': lambda tool, args: print(f"Executing {tool}"),
267
- 'post_execute': lambda tool, result: print(f"Result: {result}"),
268
-})
281
+# With session-specific modifiers (new in v0.10.5)
282
+from composio.core.models import before_execute_meta, after_execute_meta
283
+
284
+@before_execute_meta
285
+def before_modifier(tool, toolkit, session_id, params):
286
+ print(f"[Session: {session_id}] Executing {tool} from {toolkit}")
287
+ # Add custom logging, validation, or parameter transformation
288
+ return params
289
+
290
+@after_execute_meta
291
+def after_modifier(tool, toolkit, session_id, response):
292
+ print(f"[Session: {session_id}] Completed {tool}")
293
+ # Transform results, add telemetry, or handle errors
294
+ return response
295
+
296
+tools = session.tools(modifiers=[before_modifier, after_modifier])
297
```
298
299
+#### Session-Specific Modifiers
300
+
301
+Tool Router sessions now support enhanced modifiers (introduced in v0.10.5) that include session context:
302
+
303
+- **`@before_execute_meta`**: Modify parameters before execution, with access to session ID
304
+- **`@after_execute_meta`**: Transform results after execution, with access to session ID
305
+- **`@modify_schema_meta`**: Customize tool schemas before they're sent to the AI model
306
+
307
+These modifiers provide better context for session-based tool execution, allowing you to track which session is executing which tools.
308
+
309
+### Meta Tools
310
+
311
+Tool Router provides meta tools for managing connections and session state. You can access these directly using the `get_raw_tool_router_meta_tools` method (introduced in v0.10.5):
312
+
313
+```python
314
+from composio import Composio
315
+from composio.core.models import modify_schema_meta
316
+
317
+composio = Composio()
318
+
319
+# Define schema modifier
320
+@modify_schema_meta
321
+def schema_modifier(tool, toolkit, schema):
322
+ # Customize meta tool schemas
323
+ print(f"Modifying schema for {tool}")
324
+ return schema
325
+
326
+# Get raw meta tools for a session
327
+meta_tools = composio.tools.get_raw_tool_router_meta_tools(
328
+ session_id='session_123',
329
+ modifiers=[schema_modifier]
330
+)
331
+
332
+print(f"Available meta tools: {[t.name for t in meta_tools]}")
333
+```
334
+
335
+Meta tools allow you to:
336
+- Authorize new toolkit connections within a session
337
+- Query toolkit connection states
338
+- Manage session configuration
339
+
340
+This method is useful when you need direct access to the underlying meta tools without creating a full session object.
341
+
342
### `authorize(toolkit, *, callback_url=None)`
343
344
Initiate an authorization flow for a toolkit.
@@ -672,12 +743,13 @@ tags: List[Literal['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWor
743
# Manage connections configuration
744
ToolRouterManageConnectionsConfig = TypedDict('ToolRouterManageConnectionsConfig', {
745
'enable': bool,
675
- 'callback_url': str # Optional
746
+ 'callback_url': str, # Optional
747
+ 'wait_for_connections': bool # NEW in v0.10.5: Wait for connections to complete
748
})
749
750
manage_connections: Union[
751
bool,
680
- ToolRouterManageConnectionsConfig # {'enable': True, 'callback_url': 'https://...'}
752
+ ToolRouterManageConnectionsConfig # {'enable': True, 'callback_url': 'https://...', 'wait_for_connections': True}
753
]
754
755
# Workbench configuration
@@ -689,3 +761,66 @@ ToolRouterWorkbenchConfig = TypedDict('ToolRouterWorkbenchConfig', {
761
workbench: ToolRouterWorkbenchConfig
762
```
763
764
+## What's New in v0.10.5
765
+
766
+### 1. Wait for Connections
767
+
768
+The new `wait_for_connections` property allows sessions to wait for users to complete authentication before proceeding:
769
+
770
+```python
771
+session = composio.tool_router.create(
772
+ user_id='user_123',
773
+ toolkits=['gmail', 'slack'],
774
+ manage_connections={
775
+ 'enable': True,
776
+ 'callback_url': 'https://your-app.com/callback',
777
+ 'wait_for_connections': True # NEW
778
+ }
779
+)
780
+```
781
+
782
+### 2. Enhanced Session Modifiers
783
+
784
+Session-specific modifiers now include session context, making it easier to track and manage tool execution:
785
+
786
+```python
787
+from composio.core.models import before_execute_meta, after_execute_meta
788
+
789
+@before_execute_meta
790
+def before_modifier(tool, toolkit, session_id, params):
791
+ print(f"[{session_id}] Executing {tool}")
792
+ return params
793
+
794
+@after_execute_meta
795
+def after_modifier(tool, toolkit, session_id, response):
796
+ print(f"[{session_id}] Completed {tool}")
797
+ return response
798
+
799
+tools = session.tools(modifiers=[before_modifier, after_modifier])
800
+```
801
+
802
+### 3. Direct Meta Tools Access
803
+
804
+New method to fetch meta tools directly from a session:
805
+
806
+```python
807
+from composio.core.models import modify_schema_meta
808
+
809
+@modify_schema_meta
810
+def schema_modifier(tool, toolkit, schema):
811
+ return schema
812
+
813
+meta_tools = composio.tools.get_raw_tool_router_meta_tools(
814
+ session_id='session_123',
815
+ modifiers=[schema_modifier]
816
+)
817
+```
818
+
819
+### 4. Performance Improvements
820
+
821
+- Optimized tool fetching with fewer API calls
822
+- Improved session API architecture for better reliability
823
+- Simplified internal tool execution paths
824
+
825
+All changes in v0.10.5 are fully backward compatible with existing code.
826
+
ts/docs/advanced/modifiers.md
+114
@@ -563,6 +563,88 @@ const result = await openaiProvider.executeToolCall(
563
);
564
```
565
566
+## Tool Router Modifiers (v0.4.0+)
567
+
568
+Tool Router sessions support enhanced modifier types that include session context. This is useful for tracking and managing tool execution across different user sessions.
569
+
570
+### Using Session Modifiers with Tool Router
571
+
572
+```typescript
573
+import { Composio } from '@composio/core';
574
+import { SessionExecuteMetaModifiers } from '@composio/core';
575
+
576
+const composio = new Composio();
577
+
578
+const session = await composio.create('user_123', {
579
+ toolkits: ['gmail', 'slack'],
580
+});
581
+
582
+// Use session-specific modifiers
583
+const tools = await session.tools({
584
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
585
+ // Customize tool schemas
586
+ console.log(`Modifying schema for ${toolSlug} from ${toolkitSlug}`);
587
+ return schema;
588
+ },
589
+ beforeExecute: ({ toolSlug, toolkitSlug, sessionId, params }) => {
590
+ // Access session ID for tracking
591
+ console.log(`[Session: ${sessionId}] Executing ${toolSlug} from ${toolkitSlug}`);
592
+
593
+ // Add session-specific metadata
594
+ params.sessionMetadata = {
595
+ sessionId,
596
+ timestamp: new Date().toISOString(),
597
+ };
598
+
599
+ return params;
600
+ },
601
+ afterExecute: ({ toolSlug, toolkitSlug, sessionId, result }) => {
602
+ // Transform results with session context
603
+ console.log(`[Session: ${sessionId}] Completed ${toolSlug}`);
604
+
605
+ if (result.successful) {
606
+ result.data.sessionId = sessionId;
607
+ result.data.executedAt = new Date().toISOString();
608
+ }
609
+
610
+ return result;
611
+ },
612
+});
613
+```
614
+
615
+### Session-Specific Modifier Benefits
616
+
617
+The session-specific modifiers provide several advantages:
618
+
619
+1. **Session Tracking**: Access to `sessionId` allows you to track which session executed which tools
620
+2. **User Context**: Associate tool executions with specific users through session IDs
621
+3. **Audit Logging**: Log tool executions with session context for compliance and debugging
622
+4. **Performance Monitoring**: Track tool execution performance per session
623
+
624
+### Getting Meta Tools Directly
625
+
626
+You can also fetch tool router meta tools directly using the new method:
627
+
628
+```typescript
629
+import { Composio } from '@composio/core';
630
+
631
+const composio = new Composio();
632
+
633
+// Get raw meta tools for a session
634
+const metaTools = await composio.tools.getRawToolRouterMetaTools('session_123', {
635
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
636
+ // Customize meta tool schemas
637
+ if (toolSlug === 'composio_authorize_toolkit') {
638
+ schema.description = 'Custom description for authorization';
639
+ }
640
+ return schema;
641
+ }
642
+});
643
+
644
+// Use the meta tools with your AI framework
645
+console.log('Available meta tools:', metaTools.map(t => t.name));
646
+```
647
+
648
## Type Definitions
649
650
```typescript
@@ -595,4 +677,36 @@ interface ProviderOptions<TProvider> {
677
beforeExecute?: beforeExecuteModifier; // Only applied by agentic providers
678
afterExecute?: afterExecuteModifier; // Only applied by agentic providers
679
}
680
+
681
+// Session-Specific Modifiers (v0.4.0+)
682
+interface SessionExecuteMetaModifiers {
683
+ modifySchema?: (context: {
684
+ toolSlug: string;
685
+ toolkitSlug: string;
686
+ schema: any;
687
+ }) => any;
688
+
689
+ beforeExecute?: (context: {
690
+ toolSlug: string;
691
+ toolkitSlug: string;
692
+ sessionId: string;
693
+ params: any;
694
+ }) => any;
695
+
696
+ afterExecute?: (context: {
697
+ toolSlug: string;
698
+ toolkitSlug: string;
699
+ sessionId: string;
700
+ result: any;
701
+ }) => any;
702
+}
703
+
704
+// Session Meta Tool Options (v0.4.0+)
705
+interface SessionMetaToolOptions {
706
+ modifySchema?: (context: {
707
+ toolSlug: string;
708
+ toolkitSlug: string;
709
+ schema: any;
710
+ }) => any;
711
+}
712
```
ts/docs/api/tool-router.md
+165
-16
@@ -24,13 +24,13 @@ When using Tool Router with MCP clients, you don't need to pass a provider:
24
25
```bash
26
# npm
27
-npm install @composio/core@0.2.7-alpha.1
27
+npm install @composio/core@0.4.0
28
29
# pnpm
30
-pnpm add @composio/core@0.2.7-alpha.1
30
+pnpm add @composio/core@0.4.0
31
32
# yarn
33
-yarn add @composio/core@0.2.7-alpha.1
33
+yarn add @composio/core@0.4.0
34
```
35
36
```typescript
@@ -206,7 +206,23 @@ const session = await composio.create('user_123', {
206
toolkits: ['gmail'],
207
manageConnections: {
208
enable: true,
209
- callbackUrl: 'https://your-app.com/auth/callback'
209
+ callbackUrl: 'https://your-app.com/auth/callback',
210
+ waitForConnections: true // Wait for user to complete authentication before proceeding
211
+ }
212
+});
213
+```
214
+
215
+#### Wait for Connections
216
+
217
+The `waitForConnections` property (new in v0.4.0) allows the tool router session to wait for users to complete authentication before proceeding to the next step. When set to `true`, the session will block execution until all required connections are established.
218
+
219
+```typescript
220
+const session = await composio.create('user_123', {
221
+ toolkits: ['gmail', 'slack'],
222
+ manageConnections: {
223
+ enable: true,
224
+ callbackUrl: 'https://your-app.com/auth/callback',
225
+ waitForConnections: true // Session waits for connections to complete
226
}
227
});
228
```
@@ -254,19 +270,61 @@ Retrieve the tools available in the session, formatted for your AI framework.
270
```typescript
271
const tools = await session.tools();
272
257
-// With modifiers
273
+// With session-specific modifiers (new in v0.4.0)
274
const tools = await session.tools({
259
- beforeExecute: ({ toolSlug, params }) => {
260
- console.log(`Executing ${toolSlug}`);
275
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
276
+ // Customize the tool schema
277
+ return schema;
278
+ },
279
+ beforeExecute: ({ toolSlug, toolkitSlug, sessionId, params }) => {
280
+ console.log(`Executing ${toolSlug} in session ${sessionId}`);
281
return params;
282
},
263
- afterExecute: ({ toolSlug, result }) => {
264
- console.log(`Completed ${toolSlug}`);
283
+ afterExecute: ({ toolSlug, toolkitSlug, sessionId, result }) => {
284
+ console.log(`Completed ${toolSlug} in session ${sessionId}`);
285
return result;
286
}
287
});
288
```
289
290
+#### Session-Specific Modifiers
291
+
292
+Tool Router sessions now support enhanced modifier types (introduced in v0.4.0) that include session context:
293
+
294
+- **`modifySchema`**: Customize tool schemas before they're sent to the AI model
295
+- **`beforeExecute`**: Modify parameters before execution, with access to session ID
296
+- **`afterExecute`**: Transform results after execution, with access to session ID
297
+
298
+These modifiers provide better context for session-based tool execution, allowing you to track which session is executing which tools.
299
+
300
+### Meta Tools
301
+
302
+Tool Router provides meta tools for managing connections and session state. You can access these directly using the `getRawToolRouterMetaTools` method (introduced in v0.4.0):
303
+
304
+```typescript
305
+import { Composio } from '@composio/core';
306
+
307
+const composio = new Composio();
308
+
309
+// Get raw meta tools for a session
310
+const metaTools = await composio.tools.getRawToolRouterMetaTools('session_123', {
311
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
312
+ // Customize meta tool schemas
313
+ console.log(`Modifying schema for ${toolSlug}`);
314
+ return schema;
315
+ }
316
+});
317
+
318
+console.log('Available meta tools:', metaTools.map(t => t.name));
319
+```
320
+
321
+Meta tools allow you to:
322
+- Authorize new toolkit connections within a session
323
+- Query toolkit connection states
324
+- Manage session configuration
325
+
326
+This method is useful when you need direct access to the underlying meta tools without creating a full session object.
327
+
328
### `authorize()`
329
330
Initiate an authorization flow for a toolkit.
@@ -611,18 +669,25 @@ The response includes:
669
670
## Using Modifiers
671
614
-Add custom behavior before and after tool execution:
672
+Add custom behavior before and after tool execution. Tool Router supports enhanced session-specific modifiers (v0.4.0+):
673
674
```typescript
617
-import { ExecuteToolModifiers } from "@composio/core";
675
+import { SessionExecuteMetaModifiers } from "@composio/core";
676
619
-const modifiers: ExecuteToolModifiers = {
620
- beforeExecute: ({ toolSlug, params }) => {
621
- console.log(`Executing ${toolSlug}`);
677
+const modifiers: SessionExecuteMetaModifiers = {
678
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
679
+ // Customize tool schema
680
+ console.log(`Modifying schema for ${toolSlug}`);
681
+ return schema;
682
+ },
683
+ beforeExecute: ({ toolSlug, toolkitSlug, sessionId, params }) => {
684
+ console.log(`[Session: ${sessionId}] Executing ${toolSlug} from ${toolkitSlug}`);
685
+ // Add custom logging, validation, or parameter transformation
686
return params;
687
},
624
- afterExecute: ({ toolSlug, result }) => {
625
- console.log(`Executed ${toolSlug}`);
688
+ afterExecute: ({ toolSlug, toolkitSlug, sessionId, result }) => {
689
+ console.log(`[Session: ${sessionId}] Executed ${toolSlug} from ${toolkitSlug}`);
690
+ // Transform results, add telemetry, or handle errors
691
return result;
692
},
693
};
@@ -630,6 +695,15 @@ const modifiers: ExecuteToolModifiers = {
695
const tools = await session.tools(modifiers);
696
```
697
698
+### Modifier Types
699
+
700
+Tool Router provides specialized modifier types for session-based execution:
701
+
702
+- **`SessionExecuteMetaModifiers`**: Complete set of modifiers with session context
703
+- **`SessionMetaToolOptions`**: Configuration options for meta tools
704
+
705
+These types include the `sessionId` in their parameters, allowing you to track and manage tool execution across different user sessions.
706
+
707
## Best Practices
708
709
1. **User Isolation**: Create separate sessions per user to ensure proper isolation of connections and tools.
@@ -673,6 +747,7 @@ interface ToolRouterCreateSessionConfig {
747
manageConnections?: boolean | {
748
enable?: boolean;
749
callbackUrl?: string;
750
+ waitForConnections?: boolean; // NEW in v0.4.0: Wait for connections to complete
751
};
752
workbench?: {
753
enableProxyExecution?: boolean;
@@ -724,3 +799,77 @@ interface ToolkitConnectionState {
799
}
800
```
801
802
+### SessionExecuteMetaModifiers (v0.4.0+)
803
+
804
+```typescript
805
+interface SessionExecuteMetaModifiers {
806
+ modifySchema?: (context: {
807
+ toolSlug: string;
808
+ toolkitSlug: string;
809
+ schema: any;
810
+ }) => any;
811
+
812
+ beforeExecute?: (context: {
813
+ toolSlug: string;
814
+ toolkitSlug: string;
815
+ sessionId: string;
816
+ params: any;
817
+ }) => any;
818
+
819
+ afterExecute?: (context: {
820
+ toolSlug: string;
821
+ toolkitSlug: string;
822
+ sessionId: string;
823
+ result: any;
824
+ }) => any;
825
+}
826
+```
827
+
828
+## What's New in v0.4.0
829
+
830
+### 1. Wait for Connections
831
+
832
+The new `waitForConnections` property allows sessions to wait for users to complete authentication before proceeding:
833
+
834
+```typescript
835
+const session = await composio.create('user_123', {
836
+ toolkits: ['gmail', 'slack'],
837
+ manageConnections: {
838
+ enable: true,
839
+ callbackUrl: 'https://your-app.com/callback',
840
+ waitForConnections: true // NEW
841
+ }
842
+});
843
+```
844
+
845
+### 2. Enhanced Session Modifiers
846
+
847
+Session-specific modifiers now include session context, making it easier to track and manage tool execution:
848
+
849
+```typescript
850
+const tools = await session.tools({
851
+ beforeExecute: ({ toolSlug, toolkitSlug, sessionId, params }) => {
852
+ console.log(`[${sessionId}] Executing ${toolSlug}`);
853
+ return params;
854
+ }
855
+});
856
+```
857
+
858
+### 3. Direct Meta Tools Access
859
+
860
+New method to fetch meta tools directly from a session:
861
+
862
+```typescript
863
+const metaTools = await composio.tools.getRawToolRouterMetaTools('session_123', {
864
+ modifySchema: ({ toolSlug, schema }) => schema
865
+});
866
+```
867
+
868
+### 4. Performance Improvements
869
+
870
+- Optimized tool fetching with fewer API calls
871
+- Improved session API architecture for better reliability
872
+- Simplified internal tool execution paths
873
+
874
+All changes in v0.4.0 are fully backward compatible with existing code.
875
+