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

next
md 163 lines 4.85 KB
Rendered Raw
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)