Composio CrewAI Integration

0.11.5 · active · verified Thu Apr 16

Composio-crewai is a Python library that integrates Composio's extensive array of tools with CrewAI agents. It allows AI agents to connect to over 250 external services and applications, providing enterprise-grade authentication, full observability, and a streamlined way to empower AI workflows with real-world actions. The current version is 0.11.5, and the project demonstrates a rapid release cadence with frequent updates across the core Composio ecosystem.

Common errors

```
ValueError: COMPOSIO_API_KEY environment variable not set.
```
cause The `COMPOSIO_API_KEY` environment variable is missing, which is required for authenticating with the Composio platform.

fix Set the `COMPOSIO_API_KEY` environment variable with your Composio API key. For development, create a `.env` file with `COMPOSIO_API_KEY=your_key_here` and use `dotenv.load_dotenv()` in your script.
```
ValueError: COMPOSIO_USER_ID environment variable not set.
```
cause The `COMPOSIO_USER_ID` environment variable is missing, which is necessary for creating a user-scoped session with Composio to access tools.

fix Set the `COMPOSIO_USER_ID` environment variable to a unique identifier for your user in the `.env` file (e.g., `COMPOSIO_USER_ID=my_unique_user_id`).
```
No tools found for the agent / Agent cannot use tools.
```
cause This can happen if: 1) The specified toolkits in `composio_client.create()` are not authenticated in your Composio dashboard, or 2) `COMPOSIO_USER_ID` is incorrect, preventing Composio from associating tools with the session.

fix Verify that the `toolkits` list passed to `composio_client.create()` corresponds to tools you have authenticated within the Composio platform. Ensure `COMPOSIO_USER_ID` is correctly set and matches the user ID used during toolkit authentication.
```
ModuleNotFoundError: No module named 'crewai_tools'
```
cause The `crewai-tools` library, specifically the `mcp` extra, is not installed.

fix Install the necessary package: `pip install crewai-tools[mcp]`.

Warnings

breaking Composio utilizes the Model Context Protocol (MCP) for tool integration. Older, non-MCP based integration patterns might be deprecated or require a different setup. Always refer to the latest Composio and CrewAI documentation for the recommended integration method.
Fix: Migrate to the MCP-based integration using `crewai.mcp.MCPServerHTTP` as shown in current quickstart examples. Ensure `crewai-tools[mcp]` is installed.
gotcha Authentication to individual service providers (e.g., Gmail, GitHub, Neon) connected via Composio is separate from authenticating to the Composio platform itself. You need to link your accounts within the Composio dashboard or via the `composio add <toolkit>` CLI command.
Fix: After setting `COMPOSIO_API_KEY`, log into your Composio dashboard and connect the specific third-party accounts (e.g., Gmail, GitHub) your agents will use. Alternatively, use `composio add <toolkit>` via the Composio CLI.
gotcha The `COMPOSIO_USER_ID` environment variable is crucial for scoping the Composio session and correctly identifying the user for whom tools are being provided. Without it, Composio might not be able to retrieve or manage tools for the session.
Fix: Ensure `COMPOSIO_USER_ID` is consistently set and passed to `composio_client.create(user_id=...)`. This ID should ideally be a stable identifier for your user.
gotcha CrewAI's `Agent` class requires an `llm` parameter. If not explicitly provided, it might default to a non-existent or unsupported LLM, leading to errors. Additionally, using `gpt-4o-mini` or similar models requires `OPENAI_API_KEY` to be set.
Fix: Always provide an `llm` argument to your `Agent` instances, typically by importing and configuring an LLM from `langchain_openai` (e.g., `ChatOpenAI`) or passing the model name if using OpenAI directly. Ensure the relevant API key (e.g., `OPENAI_API_KEY`) is set.

Install

pip install composio composio-crewai crewai crewai-tools[mcp] python-dotenv Full Installation

Imports

Composio
```
from composio import Composio
```
CrewAIProvider
```
from composio_crewai import CrewAIProvider
```
This provider adapts Composio tools for CrewAI's native tool format.
Agent
```
from crewai import Agent
```
Task
```
from crewai import Task
```
Crew
```
from crewai import Crew
```
MCPServerHTTP
```
from crewai.mcp import MCPServerHTTP
```
Used for Model Context Protocol integration, common in Composio-CrewAI examples.

Quickstart

This quickstart demonstrates how to set up a CrewAI agent with Composio tools using the Model Context Protocol (MCP). It initializes Composio, creates a session for a user, and then exposes Composio's tools to a CrewAI agent via an `MCPServerHTTP` instance. The agent is then given a task to use these tools. Ensure `COMPOSIO_API_KEY`, `COMPOSIO_USER_ID`, and `OPENAI_API_KEY` are set as environment variables. You must also authorize the desired toolkits (e.g., 'gmail', 'github') within your Composio dashboard or via the CLI for them to be available to the agent.

import os
from crewai import Agent, Task, Crew
from crewai.mcp import MCPServerHTTP
from composio import Composio
from dotenv import load_dotenv

load_dotenv() # Load environment variables from .env file

COMPOSIO_API_KEY = os.environ.get('COMPOSIO_API_KEY', '')
COMPOSIO_USER_ID = os.environ.get('COMPOSIO_USER_ID', '')
OPENAI_API_KEY = os.environ.get('OPENAI_API_KEY', '')

if not COMPOSIO_API_KEY:
    raise ValueError("COMPOSIO_API_KEY environment variable not set.")
if not COMPOSIO_USER_ID:
    raise ValueError("COMPOSIO_USER_ID environment variable not set.")
if not OPENAI_API_KEY:
    raise ValueError("OPENAI_API_KEY environment variable not set.")

# Initialize Composio client and create a session
composio_client = Composio(api_key=COMPOSIO_API_KEY)
# Specify the toolkits your agent needs access to (e.g., 'gmail', 'github', 'composio')
# Ensure these toolkits are authenticated in your Composio dashboard.
session = composio_client.create(user_id=COMPOSIO_USER_ID, toolkits=['composio'])

# Create an MCPServerHTTP instance from the Composio session
mcp_server = MCPServerHTTP(
    url=session.mcp.url,
    headers=session.mcp.headers,
)

# Define the agent with Composio MCP tools
researcher = Agent(
    role="Research Analyst",
    goal="Gather and summarize information using available tools.",
    backstory="An expert at finding and synthesizing information from various sources.",
    verbose=True,
    allow_delegation=False,
    llm=os.environ.get('OPENAI_MODEL_NAME', 'gpt-4o-mini'), # Use an LLM, e.g., OpenAI's
    mcps=[mcp_server]
)

# Define a task that leverages Composio tools (e.g., 'composio' toolkit offers general Composio actions)
task = Task(
    description="List all available toolkits connected to Composio and summarize their purpose.",
    expected_output="A concise list of all connected Composio toolkits and a one-sentence summary for each.",
    agent=researcher
)

# Create and run the Crew
crew = Crew(agents=[researcher], tasks=[task], verbose=True)
result = crew.kickoff()

print("\n\n------------------------")
print("Crew Work Results:")
print(result)

view raw JSON →