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

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 +![Composio Banner](https://github.com/user-attachments/assets/9ba0e9c1-85a4-4b51-ae60-f9fe7992e819)
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).