composio

Imported from konstantinosmpouros/mAgenticX (magenticx/agents/harness/skill_registry/registry/integrations/composio/AGENTS.md). Install upstream with npx skills add konstantinosmpouros/mAgenticX --skill composio. Copyright stays with the author.

composio

Use 1000+ external apps via Composio - either directly through the CLI or by building AI agents and apps with the SDK

When to Apply

• User wants to access or interact with external apps (Gmail, Slack, GitHub, Notion, etc.)
• User wants to automate a task using an external service (send email, create issue, post message)
• Building an AI agent or app that integrates with external tools
• Multi-user apps that need per-user connections to external services

Table of Contents

1. Use Apps via Composio CLI 1.1. Composio CLI Guide

2. Building Apps and Agents with Composio 2.1. Building with Composio

1. Use Apps via Composio CLI

1.1. Composio CLI Guide

Impact: 🟠 HIGH

Use the Composio CLI to take actions on external apps directly - no code needed

Composio CLI Guide

Use the Composio CLI to search, connect, and execute tools directly — no code writing required. Ideal for agents taking actions on behalf of the user.

Prerequisites (first-time setup)

If the CLI is not installed or the user is not authenticated:

# Install
curl -fsSL https://composio.dev/install | bash
composio --version   # verify

# Authenticate
composio login       # OAuth flow; interactive org/project picker after login (use -y to skip)
composio whoami      # verify org_id, project_id, user_id (API keys are never displayed)
# Run upgrade in case you run into errors or starting with a new project
composio upgrade

Note: Use whoami only to verify login status — do not hardcode these values in code. whoami shows hints for composio manage orgs switch and composio init when relevant.

Login behavior: By default, composio login shows an interactive org/project picker after OAuth. Use composio login -y to skip the picker and use session defaults. JSON output is emitted only after the picker finishes (or immediately with -y), so piped/scripted usage gets the correct org_id and project_id.

Agent login (no direct browser access): For agents that cannot open a browser for the user, use a two-step flow:

1. Get login URL and session key — Print login URL and JSON (jq-parseable) then exit without opening browser or waiting:

   composio login --no-wait | jq

   Share the login URL with the agent's user to complete login in their browser.

2. Complete login with session key — Use the key from the previous output to check if the user has logged in:

   composio login --key "<key>"

   Without --no-wait: polls until the session is linked (same as browser flow after printing URL). With --no-wait: checks once and fails if not linked. For agents, once the user completes login, run with --no-wait to avoid blocking.

Primary Workflow: search → link → execute

Step 1 — Find the right tool

composio search "send an email"
composio search "create github issue"
composio search "post slack message"

The search results include connection status, so you can see immediately if the user is already connected to the required app.

Important: Do not trim the output of composio search (e.g. with head). Use the full results to pick the right tool — truncating can hide the best match.

Step 2 — Connect an account (if needed)

If the user is not connected to the app, link their account:

composio link gmail
composio link github
composio link slack

This opens an OAuth flow or prompts for credentials. Only needed once per app. By default, composio link waits until the connected account is ACTIVE (opens browser, polls). Use --no-wait for scripted or agent usage: it prints link info and JSON to stdout (JQ-friendly) and exits immediately. Output includes status, connected_account_id, redirect_url, and toolkit.

Step 3 — Execute the tool

composio execute GMAIL_SEND_EMAIL --data '{"recipient_email":"you@example.com","subject":"Hello","body":"Test"}'
composio execute GITHUB_CREATE_AN_ISSUE --data '{"owner":"acme","repo":"my-repo","title":"Bug report"}'

To see a tool's input parameters before executing:

composio execute GMAIL_SEND_EMAIL --help

Step 4 — Listen for events (optional)

composio listen

Streams real-time trigger events to the terminal.

Tips for Agents

• All commands output JSON — pipe to jq for filtering and extraction
• Agent login — When the agent has no direct browser access, use composio login --no-wait to get the URL and key, share the URL with the user, then composio login --key <key> --no-wait once they complete login
• Parallel execution — use & and wait or shell scripts for complex multi-step tasks
• The default user context is the project's test_user_id. Pass --user-id <id> to act on behalf of a specific user.

composio execute GMAIL_SEND_EMAIL --user-id "user_123" --data '{"recipient_email":"them@example.com","subject":"Hi"}'

Best Practices

1. Use jq for JSON — Pipe CLI output to jq for filtering and extraction instead of parsing raw JSON.
2. Control output at source — When fetching large amounts of data, use the tool's filters (if supported) to limit what is returned.
3. Offload analysis — After understanding the schema, use inline bash scripts for heavy data analysis instead of manual inspection. Avoid using composio SDK for personal usecases only use the SDKs when building apps.
4. Parallelize independent actions — For tools/actions that don't depend on each other, run them in parallel with & and wait. Use xargs -P or parallel only when the backend can handle the load.
5. Avoid large terminal dumps — Filter, search, and summarize instead of outputting full datasets:
   • Quick text filtering: grep -E, rg (ripgrep), awk, sed
   • Summarize: sort | uniq -c | sort -nr, wc -l, head, tail
   • For large output: less, lnav (logs), tail -f for streaming
6. Minimize file creation — Use ephemeral files only when needed; create files only when the user explicitly asks.
7. Respect rate limits — Be mindful of pagination and API/CLI rate limits when parallelizing.
8. Never invent tool slugs or app names — Only use tools returned by composio search. For app names, use composio manage toolkits info <slug> or composio manage tools info <tool> to verify.
9. Do not trim composio search output — Never pipe search results through head, tail, or similar. Use the full output to find the best tool match.

Advanced Commands

Discover Tools (when search isn't enough)

# List all toolkits
composio manage toolkits list

# Get details about a specific toolkit
composio manage toolkits info "gmail"

# List tools in a toolkit
composio manage tools list --toolkits "gmail"

# Get a tool's full schema
composio manage tools info "GMAIL_SEND_EMAIL"

Connected Accounts

# List active connections
composio manage connected-accounts list --status ACTIVE

# Link an account (full form with options)
composio manage connected-accounts link --auth-config "ac_..." --user-id "user_123"

# Delete a connection
composio manage connected-accounts delete <id>

Auth Configs

Only needed when building apps with custom OAuth credentials. For personal use and agents, composio link handles this automatically.

composio manage auth-configs list --toolkits "gmail"
composio manage auth-configs create
composio manage auth-configs info <id>
composio manage auth-configs delete <id>

Triggers

# List available trigger types
composio manage triggers list
composio manage triggers info "GMAIL_NEW_GMAIL_MESSAGE"

# Manage trigger instances
composio manage triggers create <trigger-name>
composio manage triggers enable <id>
composio manage triggers disable <id>
composio manage triggers status

Debugging & Logs

# View recent tool executions
composio manage logs tools

# Get detailed logs for a specific execution
composio manage logs tools "log_abc123"

# Monitor trigger events
composio manage logs triggers

jq Examples

# Extract toolkit slugs
composio manage toolkits list | jq -r '.[].slug'

# Get tool names from a toolkit
composio manage tools list --toolkits "gmail" | jq -r '.[].name'

# Filter active connections
composio manage connected-accounts list --status ACTIVE | jq -r '.[].id'

# Extract login URL and key from agent login flow
composio login --no-wait | jq -r '.login_url'
composio login --no-wait | jq -r '.key'

Command Help

Every command supports --help for detailed options:

composio --help
composio login --help
composio search --help
composio execute --help
composio link --help
composio listen --help
composio manage tools --help
composio manage toolkits --help
composio manage triggers --help

2. Building Apps and Agents with Composio

2.1. Building with Composio

Impact: 🟠 HIGH

SDK-based guide for building AI agents and applications that integrate with external tools via Composio

Building Apps and Agents with Composio

Use the Composio SDK to build AI agents, chat apps, and backend services that integrate with 200+ external tools.

Project Setup

Run inside your project directory to initialize and store the API key:

composio init

Install the SDK

TypeScript

pnpm install @composio/core@latest

Provider packages for agentic frameworks:

• @composio/vercel — Vercel AI SDK
• @composio/openai-agents — OpenAI Agents
• @composio/langchain — LangChain
• @composio/mastra — Mastra
• @composio/claude-agent-sdk — Claude Agent SDK

Python

pip install composio

Provider packages for agentic frameworks:

• composio-openai-agents — OpenAI Agents
• composio-langchain — LangChain
• composio-langgraph — LangGraph
• composio-crewai — CrewAI
• composio-claude-agent-sdk — Claude Agent SDK
• composio-google-adk — Google ADK

Pass the provider into the Composio constructor:

import { Composio } from '@composio/core'
import { VercelProvider } from '@composio/vercel'

const composio = new Composio({ provider: new VercelProvider() })

from composio import Composio
from composio_langchain import LangchainProvider

composio = Composio(provider=LangchainProvider())

Building Agents

Use Tool Router to create isolated MCP sessions per user with scoped tool access and automatic auth management. Compatible with any AI framework.

Session Management

• User ID Best Practices — choose user IDs for security and isolation
• Creating Basic Sessions — initialize Tool Router sessions
• Session Lifecycle — when to create vs reuse sessions
• Session Configuration — configure toolkits, tools, and filters
• Using Native Tools — prefer native tools for performance and control

Authentication Flows

• Auto Authentication in Chat — enable in-chat auth flows
• Manual Authorization — use session.authorize() for explicit flows
• Connection Management — configure manageConnections, waitForConnections, and callback URLs

Toolkit Querying & UI Building

• Building Chat UIs — toolkit selection, connection management, and session handling
• Query Toolkit States — use session.toolkits() to check connections and build connection UIs

Framework Integrations

• Framework Integration — LangChain, OpenAI Agents, general patterns
• Vercel AI SDK — native tools, MCP, and React
• Mastra — Mastra agents with native tools and MCP

Event-Driven Agents (Triggers)

• Creating Triggers — set up trigger instances for real-time events
• Subscribing to Events — listen to trigger events in real-time
• Webhook Verification — verify and process incoming webhook payloads
• Managing Triggers — enable, disable, update, and list triggers

Building Apps

Direct tool execution without agent frameworks — full control over auth, execution, and resource management. If building apps with agentic abilities, make sure the auth configs match the session's auth configs.

Core Operations

• Fetching Tools — get tools with filters and search
• Direct Tool Execution — execute tools manually with parameters
• Tool Version Management — version pinning strategies for stability

Resource Management

• Connected Accounts CRUD — create, read, update, delete connected accounts
• Auth Config Management — manage authentication configurations
• Toolkit Management — query toolkits, categories, and auth requirements
• Auth Popup UI — build popup-based OAuth flows

Extensibility

• Tool Modifiers — schema modification and execution hooks for logging and modifications

User Context & Multi-Tenancy

• User ID Patterns — user vs organization IDs, shared vs isolated connections

Event-Driven Applications

• Creating Triggers — set up trigger instances
• Subscribing to Events — listen to events in real-time
• Webhook Verification — verify incoming webhooks
• Managing Triggers — enable, disable, update triggers

Verify Tool Slugs Before Use

Never guess toolkit, tool, or trigger names. Always verify:

composio search "send email"
composio manage tools info "GMAIL_SEND_EMAIL"
composio manage toolkits info "gmail"

Using incorrect slugs causes runtime errors.

This file was automatically generated from individual rule files on 2026-03-13T12:37:41.138Z To update, run: npm run build:agents