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, 06:00 UTC
| 1 | # Session Management |
| 2 | |
| 3 | The Composio SDK provides powerful session management capabilities through the `createSession` method. This feature allows you to create new instances of the SDK with custom request options while preserving your existing configuration. This is particularly useful when you need to add request-specific headers, track request contexts, or customize request behavior for specific operations. |
| 4 | |
| 5 | ## Composio Constructor Options |
| 6 | |
| 7 | When initializing the SDK, you can provide the following options: |
| 8 | |
| 9 | ```typescript |
| 10 | const composio = new Composio({ |
| 11 | apiKey: 'your-api-key', // required |
| 12 | baseURL: 'https://api.composio.dev', // optional |
| 13 | allowTracking: true, // optional, default: true |
| 14 | allowTracing: true, // optional, default: true |
| 15 | provider: new OpenAIProvider(), // optional |
| 16 | telemetryTransport: customTransport, // optional |
| 17 | defaultHeaders: { 'x-request-id': 'global-id' }, // optional, applies to all requests |
| 18 | }); |
| 19 | ``` |
| 20 | |
| 21 | - `apiKey` (**required**): Your Composio API key |
| 22 | - `baseURL` (optional): Custom API endpoint |
| 23 | - `allowTracking` (optional, default: true): Enable/disable telemetry |
| 24 | - `allowTracing` (optional, default: true): Enable/disable tracing |
| 25 | - `provider` (optional): Custom provider (defaults to OpenAIProvider) |
| 26 | - `telemetryTransport` (optional): Custom telemetry transport |
| 27 | - `defaultHeaders` (optional): Default headers for all requests (applies globally) |
| 28 | |
| 29 | ## Overview |
| 30 | |
| 31 | When you create a new session using `createSession`, you get a new Composio instance that: |
| 32 | |
| 33 | - Inherits all configuration from the parent instance (apiKey, baseURL, provider, etc.) |
| 34 | - Allows you to specify custom request headers that will be applied to all API calls made through that session |
| 35 | - Maintains isolation between different sessions, enabling parallel operations with different contexts |
| 36 | |
| 37 | ## Use Cases |
| 38 | |
| 39 | Sessions are particularly useful for: |
| 40 | |
| 41 | 1. **Request Tracking** |
| 42 | |
| 43 | - Adding correlation IDs |
| 44 | - Including request IDs for tracing |
| 45 | - Setting custom headers for monitoring |
| 46 | |
| 47 | 2. **Context Management** |
| 48 | |
| 49 | - Managing user-specific contexts |
| 50 | - Handling different authentication contexts |
| 51 | - Implementing tenant-specific headers |
| 52 | |
| 53 | 3. **Request Customization** |
| 54 | - Modifying request behavior for specific operations |
| 55 | - Adding custom metadata |
| 56 | - Implementing custom retry logic |
| 57 | |
| 58 | ## Usage |
| 59 | |
| 60 | Here's how to use session management in your application: |
| 61 | |
| 62 | ```typescript |
| 63 | // Create your base Composio instance |
| 64 | const composio = new Composio({ |
| 65 | apiKey: 'your-api-key', |
| 66 | }); |
| 67 | |
| 68 | // Create a session with custom headers |
| 69 | const sessionWithHeaders = composio.createSession({ |
| 70 | headers: { |
| 71 | 'x-request-id': '1234567890', |
| 72 | 'x-correlation-id': 'session-abc-123', |
| 73 | 'x-custom-header': 'custom-value', |
| 74 | }, |
| 75 | }); |
| 76 | |
| 77 | // Use the session for making API calls |
| 78 | await sessionWithHeaders.tools.list(); |
| 79 | ``` |
| 80 | |
| 81 | ## Advanced Usage |
| 82 | |
| 83 | You can create multiple sessions with different configurations: |
| 84 | |
| 85 | ```typescript |
| 86 | // Session for user A |
| 87 | const userASession = composio.createSession({ |
| 88 | headers: { |
| 89 | 'x-user-id': 'user-a', |
| 90 | 'x-tenant-id': 'tenant-1', |
| 91 | }, |
| 92 | }); |
| 93 | |
| 94 | // Session for user B |
| 95 | const userBSession = composio.createSession({ |
| 96 | headers: { |
| 97 | 'x-user-id': 'user-b', |
| 98 | 'x-tenant-id': 'tenant-2', |
| 99 | }, |
| 100 | }); |
| 101 | |
| 102 | // Each session maintains its own context |
| 103 | await Promise.all([ |
| 104 | userASession.tools.get('a'), // Will include user A's headers |
| 105 | userBSession.tools.list('b'), // Will include user B's headers |
| 106 | ]); |
| 107 | ``` |
| 108 | |
| 109 | ## Best Practices |
| 110 | |
| 111 | 1. **Session Lifecycle** |
| 112 | |
| 113 | - Create sessions for specific contexts or operations |
| 114 | - Don't share sessions across different contexts |
| 115 | - Create new sessions when context changes |
| 116 | |
| 117 | 2. **Header Management** |
| 118 | |
| 119 | - Use consistent header naming conventions |
| 120 | - Include relevant tracking IDs |
| 121 | - Document custom headers used in your application |
| 122 | |
| 123 | 3. **Error Handling** |
| 124 | - Sessions inherit error handling from the parent instance |
| 125 | - Add context-specific error handling when needed |
| 126 | |
| 127 | ## Request Options |
| 128 | |
| 129 | The session accepts custom headers via the `headers` property. These headers will be used for all API calls made through that session: |
| 130 | |
| 131 | ```typescript |
| 132 | const session = composio.createSession({ |
| 133 | headers: { |
| 134 | // Custom headers |
| 135 | 'x-request-id': 'unique-id', |
| 136 | 'x-correlation-id': 'correlation-id', |
| 137 | 'content-type': 'application/json', |
| 138 | }, |
| 139 | }); |
| 140 | ``` |
| 141 | |
| 142 | If you want to set default headers for all requests (even outside sessions), use the `defaultHeaders` property in the main constructor: |
| 143 | |
| 144 | ```typescript |
| 145 | const composio = new Composio({ |
| 146 | apiKey: 'your-api-key', |
| 147 | defaultHeaders: { |
| 148 | 'x-global-header': 'global-value', |
| 149 | }, |
| 150 | }); |
| 151 | ``` |
| 152 | |
| 153 | ## Limitations and Considerations |
| 154 | |
| 155 | 1. Sessions are immutable – once created, their configuration (including headers) cannot be changed. |
| 156 | 2. Each session is a new Composio instance with its own context and headers. |
| 157 | 3. Headers set in a session apply to all API calls made through that session. |
| 158 | |
| 159 | ## Related Topics |
| 160 | |
| 161 | - [Error Handling](./error-handling.md) |
| 162 | - [Custom Providers](./custom-providers.md) |
| 163 | - [Telemetry](./telemetry.md) |