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, 19:30 UTC
Add readme (#2047)
Co-authored-by: Prateek <prateek@composio.dev> Co-authored-by: Musthaq Ahamad <53584487+haxzie@users.noreply.github.com>
prateek committed
Oct 10, 2025 at 15:39 UTC
99d21fc16ca0ce549670db9e0cf50af2a0e6be55
1 file changed
+484
-7
python/README.md
+484
-7
@@ -1,13 +1,490 @@
1
-# Composio SDK
1
+
2
3
-## Setup
3
+# Composio
4
+
5
+The Composio Python SDK allows you to interact with the Composio Platform. It provides a powerful and flexible way to manage and execute tools, handle authentication, and integrate with various AI frameworks and platforms.
6
+
7
+[Learn more about the SDK from our docs](https://docs.composio.dev)
8
+
9
+## Core Features
10
+
11
+- **Tools**: Manage and execute tools within the Composio ecosystem. Includes functionality to list, retrieve, and execute tools.
12
+- **Toolkits**: Organize and manage collections of tools for specific use cases.
13
+- **Triggers**: Create and manage event triggers that can execute tools based on specific conditions.
14
+- **AuthConfigs**: Configure authentication providers and settings.
15
+- **ConnectedAccounts**: Manage third-party service connections.
16
+- **ActionExecution**: Track and manage the execution of actions within the platform.
17
+- **Provider Integrations**: Built-in support for OpenAI, Anthropic, LangChain, CrewAI, AutoGen, and more.
18
+
19
+## Installation
20
21
```bash
6
-make env
7
-source .venv/bin/activate
22
+pip install composio
23
+# or
24
+pip install composio-core
25
+```
26
+
27
+### Provider-Specific Installations
28
+
29
+For specific AI framework integrations:
30
+
31
+```bash
32
+# OpenAI integration
33
+pip install composio-openai
34
+
35
+# LangChain integration
36
+pip install composio-langchain
37
+
38
+# CrewAI integration
39
+pip install composio-crewai
40
+
41
+# Anthropic integration
42
+pip install composio-anthropic
43
+
44
+# AutoGen integration
45
+pip install composio-autogen
46
+
47
+# And many more...
48
+```
49
+
50
+## Getting Started
51
+
52
+### Basic Usage with OpenAI
53
+
54
+```python
55
+import os
56
+from composio import Composio
57
+from openai import OpenAI
58
+
59
+# Initialize OpenAI client
60
+openai_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
61
+
62
+# Initialize Composio with your API key
63
+composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))
64
+
65
+def main():
66
+ try:
67
+ # Fetch tools - single tool or multiple tools
68
+ tools = composio.tools.get(user_id="default", slug="HACKERNEWS_GET_USER")
69
+ # Or fetch multiple tools: composio.tools.get(user_id="default", toolkits=["hackernews"])
70
+
71
+ query = "Find information about the HackerNews user 'pg'"
72
+
73
+ # Create chat completion with tools
74
+ response = openai_client.chat.completions.create(
75
+ model="gpt-4o",
76
+ messages=[
77
+ {
78
+ "role": "system",
79
+ "content": "You are a helpful assistant that can use tools to answer questions."
80
+ },
81
+ {"role": "user", "content": query}
82
+ ],
83
+ tools=tools,
84
+ tool_choice="auto"
85
+ )
86
+
87
+ # Handle tool calls if the assistant decides to use them
88
+ if response.choices[0].message.tool_calls:
89
+ print("🔧 Assistant is using tool:", response.choices[0].message.tool_calls[0].function.name)
90
+
91
+ # Execute the tool call
92
+ tool_result = composio.provider.handle_tool_calls(
93
+ response=response,
94
+ user_id="default"
95
+ )
96
+
97
+ print("✅ Tool execution result:", tool_result)
98
+
99
+ # Get final response from assistant with tool result
100
+ final_response = openai_client.chat.completions.create(
101
+ model="gpt-4o",
102
+ messages=[
103
+ {
104
+ "role": "system",
105
+ "content": "You are a helpful assistant that can use tools to answer questions."
106
+ },
107
+ {"role": "user", "content": query},
108
+ response.choices[0].message,
109
+ {
110
+ "role": "tool",
111
+ "tool_call_id": response.choices[0].message.tool_calls[0].id,
112
+ "content": str(tool_result)
113
+ }
114
+ ]
115
+ )
116
+
117
+ print("🤖 Final response:", final_response.choices[0].message.content)
118
+ else:
119
+ print("🤖 Response:", response.choices[0].message.content)
120
+
121
+ except Exception as error:
122
+ print("❌ Error:", error)
123
+
124
+if __name__ == "__main__":
125
+ main()
126
+```
127
+
128
+### Using with Provider Integrations
129
+
130
+#### OpenAI Provider
131
+
132
+```python
133
+from composio_openai import OpenAIProvider
134
+from openai import OpenAI
135
+from composio import Composio
136
+
137
+# Initialize with OpenAI provider
138
+openai_client = OpenAI()
139
+composio = Composio(provider=OpenAIProvider())
140
+
141
+# Define task
142
+task = "Star a repo composiohq/composio on GitHub"
143
+
144
+# Get GitHub tools that are pre-configured
145
+tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])
146
+
147
+# Get response from the LLM
148
+response = openai_client.chat.completions.create(
149
+ model="gpt-4o-mini",
150
+ tools=tools,
151
+ messages=[
152
+ {"role": "system", "content": "You are a helpful assistant."},
153
+ {"role": "user", "content": task},
154
+ ],
155
+)
156
+
157
+# Execute the function calls
158
+result = composio.provider.handle_tool_calls(response=response, user_id="default")
159
+print(result)
160
+```
161
+
162
+#### LangChain Integration
163
+
164
+```python
165
+from composio_langchain import ComposioToolSet
166
+from langchain_openai import ChatOpenAI
167
+
168
+# Initialize the toolset
169
+toolset = ComposioToolSet()
170
+
171
+# Get tools for a specific toolkit
172
+tools = toolset.get_tools(toolkits=["GITHUB"])
173
+
174
+# Initialize LLM
175
+llm = ChatOpenAI(model="gpt-4o")
176
+
177
+# Create agent with tools
178
+from langchain.agents import create_openai_functions_agent, AgentExecutor
179
+from langchain.prompts import ChatPromptTemplate
180
+
181
+prompt = ChatPromptTemplate.from_messages([
182
+ ("system", "You are a helpful assistant"),
183
+ ("user", "{input}"),
184
+ ("assistant", "{agent_scratchpad}")
185
+])
186
+
187
+agent = create_openai_functions_agent(llm, tools, prompt)
188
+agent_executor = AgentExecutor(agent=agent, tools=tools)
189
+
190
+# Execute task
191
+result = agent_executor.invoke({"input": "Star the composiohq/composio repository"})
192
+print(result)
193
+```
194
+
195
+## Configuration
196
+
197
+The Composio constructor accepts the following configuration options:
198
+
199
+```python
200
+from composio import Composio
201
+from composio.core.provider import OpenAIProvider
202
+
203
+composio = Composio(
204
+ api_key="your-api-key", # Your Composio API key
205
+ base_url="https://api.composio.dev", # Custom API base URL (optional)
206
+ timeout=60, # Request timeout in seconds
207
+ max_retries=3, # Maximum number of retries
208
+ allow_tracking=True, # Enable/disable telemetry (default: True)
209
+ file_download_dir="./downloads", # Directory for file downloads
210
+ provider=OpenAIProvider(), # Custom provider (default: OpenAIProvider)
211
+ toolkit_versions="latest" # Toolkit versions to use
212
+)
213
+```
214
+
215
+## Modifiers
216
+
217
+Composio SDK supports powerful modifiers to transform tool schemas and execution behavior.
218
+
219
+### Schema Modifiers
220
+
221
+Schema modifiers allow you to transform tool schemas before they are used:
222
+
223
+```python
224
+from composio import schema_modifier
225
+from composio.types import Tool
226
+
227
+@schema_modifier(tools=["HACKERNEWS_GET_USER"])
228
+def modify_schema(tool: str, toolkit: str, schema: Tool) -> Tool:
229
+ # Perform modifications on the schema
230
+ schema["description"] = "Enhanced HackerNews user lookup with additional features"
231
+ schema["parameters"]["properties"]["include_karma"] = {
232
+ "type": "boolean",
233
+ "description": "Include user karma in response",
234
+ "default": True
235
+ }
236
+ return schema
237
+
238
+# Use the modifier when getting tools
239
+tools = composio.tools.get(
240
+ user_id="default",
241
+ slug="HACKERNEWS_GET_USER",
242
+ modifiers=[modify_schema]
243
+)
244
+```
245
+
246
+### Execution Modifiers
247
+
248
+Transform tool execution behavior with before and after execute modifiers:
249
+
250
+```python
251
+from composio import before_execute, after_execute
252
+from composio.types import ToolExecuteParams, ToolExecutionResponse
253
+
254
+@before_execute(tools=["HACKERNEWS_GET_USER"])
255
+def before_execute_modifier(
256
+ tool: str,
257
+ toolkit: str,
258
+ params: ToolExecuteParams
259
+) -> ToolExecuteParams:
260
+ # Transform input before execution
261
+ print(f"Executing {tool} with params: {params}")
262
+ return params
263
+
264
+@after_execute(tools=["HACKERNEWS_GET_USER"])
265
+def after_execute_modifier(
266
+ tool: str,
267
+ toolkit: str,
268
+ response: ToolExecutionResponse
269
+) -> ToolExecutionResponse:
270
+ # Transform output after execution
271
+ return {
272
+ **response,
273
+ "data": {
274
+ **response["data"],
275
+ "processed_at": "2024-01-01T00:00:00Z"
276
+ }
277
+ }
278
+
279
+# Execute tool with modifiers
280
+response = composio.tools.execute(
281
+ user_id="default",
282
+ slug="HACKERNEWS_GET_USER",
283
+ arguments={"username": "pg"},
284
+ modifiers=[before_execute_modifier, after_execute_modifier]
285
+)
286
+```
287
+
288
+## Connected Accounts
289
+
290
+Composio SDK provides a powerful way to manage third-party service connections through Connected Accounts. This feature allows you to authenticate with various services and maintain those connections.
291
+
292
+### Creating a Connected Account
293
+
294
+```python
295
+from composio import Composio
296
+from composio.types import auth_scheme
297
+
298
+composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))
299
+
300
+# Create a connected account with OAuth
301
+connection_request = composio.connected_accounts.initiate(
302
+ user_id="user123",
303
+ auth_config_id="ac_12343544", # You can create it from the dashboard
304
+ callback_url="https://your-app.com/callback",
305
+ data={
306
+ # Additional data for the connection
307
+ "scope": ["read", "write"]
308
+ }
309
+)
310
+
311
+# Wait for the connection to be established
312
+# Default timeout is 60 seconds
313
+connected_account = connection_request.wait_for_connection()
314
+print(connected_account)
315
+```
316
+
317
+### API Key Authentication
318
+
319
+```python
320
+# Create a connected account with API Key
321
+connection_request = composio.connected_accounts.initiate(
322
+ user_id="user123",
323
+ auth_config_id="ac_12343544",
324
+ config=auth_scheme.api_key(
325
+ options={
326
+ "api_key": "your-api-key-here"
327
+ }
328
+ )
329
+)
330
+```
331
+
332
+### Managing Connected Accounts
333
+
334
+```python
335
+# List all connected accounts
336
+accounts = composio.connected_accounts.list(user_id="user123")
337
+
338
+# Get a specific connected account
339
+account = composio.connected_accounts.get("account_id")
340
+
341
+# Enable/Disable a connected account
342
+composio.connected_accounts.enable("account_id")
343
+composio.connected_accounts.disable("account_id")
344
+
345
+# Refresh credentials
346
+composio.connected_accounts.refresh("account_id")
347
+
348
+# Delete a connected account
349
+composio.connected_accounts.delete("account_id")
350
+```
351
+
352
+### Connection Statuses
353
+
354
+Connected accounts can have the following statuses:
355
+
356
+- `ACTIVE`: Connection is established and working
357
+- `INACTIVE`: Connection is temporarily disabled
358
+- `PENDING`: Connection is being processed
359
+- `INITIATED`: Connection request has started
360
+- `EXPIRED`: Connection credentials have expired
361
+- `FAILED`: Connection attempt failed
362
+
363
+## Tools and Toolkits
364
+
365
+### Working with Tools
366
+
367
+```python
368
+# Get tools by toolkit
369
+tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])
370
+
371
+# Get tools by search
372
+tools = composio.tools.get(user_id="default", search="user")
373
+
374
+# Get tools by toolkit and search
375
+tools = composio.tools.get(user_id="default", toolkits=["GITHUB"], search="star")
376
+
377
+# Execute a tool directly
378
+response = composio.tools.execute(
379
+ user_id="default",
380
+ slug="HACKERNEWS_GET_USER",
381
+ arguments={"username": "pg"}
382
+)
383
+print(response)
384
+```
385
+
386
+### Proxy Calls
387
+
388
+Make direct API calls through connected accounts:
389
+
390
+```python
391
+# Execute proxy call (GitHub API)
392
+proxy_response = composio.tools.proxy(
393
+ endpoint="/repos/composiohq/composio/issues/1",
394
+ method="GET",
395
+ connected_account_id="ac_1234", # Use connected account for GitHub
396
+ parameters=[
397
+ {
398
+ "name": "Accept",
399
+ "value": "application/vnd.github.v3+json",
400
+ "type": "header"
401
+ }
402
+ ]
403
+)
404
+print(proxy_response)
405
+```
406
+
407
+## Authentication Schemes
408
+
409
+Composio supports various authentication schemes:
410
+
411
+- OAuth2
412
+- OAuth1
413
+- OAuth1a
414
+- API Key
415
+- Basic Auth
416
+- Bearer Token
417
+- Google Service Account
418
+- And more...
419
+
420
+## Environment Variables
421
+
422
+- `COMPOSIO_API_KEY`: Your Composio API key
423
+- `COMPOSIO_BASE_URL`: Custom API base URL
424
+- `COMPOSIO_LOGGING_LEVEL`: Logging level (silent, error, warn, info, debug)
425
+- `DEVELOPMENT`: Development mode flag
426
+- `COMPOSIO_TOOLKIT_VERSION_<TOOLKITNAME>`: Version of the specific toolkit
427
+- `CI`: CI environment flag
428
+
429
+## MCP (Model Context Protocol)
430
+
431
+Create MCP servers for seamless integration with Claude, Cursor, and other MCP-compatible tools:
432
+
433
+```python
434
+from composio import Composio
435
+
436
+composio = Composio()
437
+
438
+# Create MCP server
439
+mcp_server = composio.mcp.create(
440
+ "my-mcp-server",
441
+ toolkits=["github", "gmail"],
442
+ manually_manage_connections=False
443
+)
444
+
445
+# Generate server instance for a user
446
+server_instance = mcp_server.generate("user123")
447
+print(f"MCP Server URL: {server_instance['url']}")
448
```
449
10
-## Usage
450
+## Supported AI Frameworks
451
+
452
+Composio provides dedicated integrations for popular AI frameworks:
453
+
454
+- **OpenAI** - Direct integration with OpenAI's API
455
+- **LangChain** - Tools and agents for LangChain workflows
456
+- **LangGraph** - State machine workflows with LangGraph
457
+- **CrewAI** - Multi-agent systems with CrewAI
458
+- **AutoGen** - Microsoft's AutoGen framework
459
+- **Anthropic** - Claude integration
460
+- **Google AI** - Gemini and other Google AI services
461
+- **LlamaIndex** - RAG and data framework integration
462
+
463
+## Error Handling
464
+
465
+```python
466
+from composio import Composio
467
+from composio.exceptions import ComposioError, ApiKeyNotProvidedError
468
+
469
+try:
470
+ composio = Composio() # Will raise ApiKeyNotProvidedError if no API key
471
+ tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])
472
+except ApiKeyNotProvidedError:
473
+ print("Please provide COMPOSIO_API_KEY environment variable")
474
+except ComposioError as e:
475
+ print(f"Composio error: {e}")
476
+except Exception as e:
477
+ print(f"Unexpected error: {e}")
478
+```
479
+
480
+## Contributing
481
+
482
+We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for more details.
483
+
484
+## License
485
+
486
+Apache License 2.0
487
+
488
+## Support
489
12
-> 📌 **NOTE**
13
-> Ensure you've set the `COMPOSIO_API_KEY` and the `OPENAI_API_KEY` for these examples to work.
490
+For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).