@devries-cameron20 / composio-1 / commits / 4a9167d76
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.

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 +