Alberto Schiabel
0e6b59ba14
This PR: - builds on top of https://github.com/ComposioHQ/composio/pull/4055 - resolves a tool's toolkit against what the CLI already knows — the slugs baked in at build time (https://github.com/ComposioHQ/composio/pull/4055) plus the ones this machine has learned since — so the common case costs one small local file read and no network. Every tool execution needed the toolkit, and the catalog was ~800 KB and ~2 s of the wall time of a command that then does one small API call - resolves that local knowledge once per run: `Effect.cached` on the catalog service means one file read, one parse, and one lookup set per process, where a single `composio execute` resolves a toolkit four times over (bootstrap telemetry, the execute context, the connection check, the execution itself) and `--parallel` multiplies that by the number of tools - falls through to the catalog only for a slug that matches nothing known, which is what a toolkit released after the binary looks like, and records what it finds in `known-toolkit-slugs.json` — so it costs a fetch once rather than every run. The recording forks at most once per run: every miss in a run merges the same memoized fetch, so later forks could only rewrite an identical file - refreshes learned slugs in the background once they are older than a week, which bounds how long a brand-new toolkit can be mistaken for a shorter one sharing its prefix - gives that background refresh ten seconds, then abandons it. A successful command ends when the event loop drains, not on an explicit `process.exit`, so an unbounded background fetch would hold the exiting `composio` process open until the network answered — visible to `&&` chains, `$(...)`, and CI step timing. An abandoned refresh costs a fetch on a later run, nothing more - keeps `FORCE_USE_CACHE` semantics intact: the learned file is derived data, not saved API responses, so it is read unconditionally. That distinction is documented in the module and in the README - cannot fail a command — a missing, unreadable, or corrupt file means "nothing learned yet", and an unreachable catalog still degrades to the first-underscore guess - writes cache files through a temp file and a rename, so an interrupted run leaves the previous cache intact instead of a truncated `toolkits.json` the next run reads back as a parse failure - drops the `toolkit` field from the cached tool model, which nothing reads once resolution goes through the catalog service - measured on a logged-in binary: `composio execute GOOGLE_ANALYTICS_RUN_REPORT --dry-run` goes from ~8.0-8.6 s before the stack, to ~3.4-4.3 s after https://github.com/ComposioHQ/composio/pull/4054, to ~1.7-2.0 s here — startup and the tool-schema fetch only - no visible command surface changed, so no VHS recording ## Summary Resolution now reads like this, with the catalog reached only on a genuine miss: ```mermaid graph TD A[tool slug] --> B{session meta tool?} B -->|yes| C[no toolkit] B -->|no| D[baked slugs + learned slugs] D --> E{longest prefix match?} E -->|yes| F[toolkit slug] E -->|no| G[fetch catalog] G -->|match| H[toolkit slug, slug remembered] G -->|unreachable| I[first-underscore guess] ``` Twelve tests cover the branches: baked hit and learned hit with zero fetches, first run seeding the file, a miss that fetches and persists, an unreachable catalog degrading to the guess, a corrupt file tolerated, a stale file refreshing in the background, a fresh file not refreshing, meta tools resolving to nothing without a fetch, the same run answering from its memo instead of re-reading the file, and a second recording in one run never reaching the file.
composio.dev • Documentation • Quickstart • Changelog
Composio
Composio gives your AI agents 1000+ pre-authenticated toolkits, per-user sessions, authentication, triggers, and a sandbox, so you can ship agents that turn intent into action.
This is the Composio SDK monorepo. It contains:
@composio/core: TypeScript SDKcomposio: Python SDKcomposioCLI: search, execute, and script tools from your shell- Provider adapters for OpenAI Agents, Claude Agent SDK, Vercel AI SDK, LangChain, and more
Quickstart
Create a session for a user, hand its tools to your agent, and let the agent take action across 1000+ apps. Grab a COMPOSIO_API_KEY from the dashboard first.
TypeScript
npm install @composio/core @composio/openai-agents @openai/agents
@composio/coreintentionally packages its TypeScript source and SDK docs so the installed package is inspectable to coding agents. If you want a smaller install with the same API, use@composio/slim.
import { Composio } from "@composio/core";
import { OpenAIAgentsProvider } from "@composio/openai-agents";
import { Agent, run } from "@openai/agents";
const composio = new Composio({ provider: new OpenAIAgentsProvider() });
// Each session is scoped to one of your users
const session = await composio.create("user_123");
const tools = await session.tools();
const agent = new Agent({
name: "Personal Assistant",
instructions: "You are a helpful assistant. Use Composio tools to take action.",
tools,
});
const result = await run(agent, "Summarize my emails from today");
console.log(result.finalOutput);
Python
pip install composio composio-openai-agents openai-agents
from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner
composio = Composio(provider=OpenAIAgentsProvider())
# Each session is scoped to one of your users
session = composio.create(user_id="user_123")
tools = session.tools()
agent = Agent(
name="Personal Assistant",
instructions="You are a helpful assistant. Use Composio tools to take action.",
tools=tools,
)
result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today")
print(result.final_output)
By default a session gets meta tools that discover, authenticate, and execute app tools at runtime, so you don't load hundreds of tool definitions into context. Store session.session_id and reuse it with composio.use() across turns. See what a session is and configuring sessions for restricting toolkits, auth configs, and connected accounts.
Prefer MCP? Every session also exposes a hosted MCP endpoint. Pass mcp: true to composio.create() and point Claude, Cursor, or any MCP client at session.mcp.url. See sessions via MCP.
CLI
The composio CLI runs Composio from your shell and gives coding agents like Claude Code a local tool surface.
curl -fsSL https://composio.dev/install | sh
The installer puts composio on your PATH for future terminals. Open a new terminal, then run composio login. See INSTALL.md for shell setup overrides, including COMPOSIO_INSTALL_SHELL=none for install-only runs.
Use composio search to find tools, composio execute to run them, composio link to connect accounts, and composio run to script workflows in TypeScript. See the CLI docs.
Providers
A provider adapts Composio tools to your agent framework's native tool format:
| Provider | TypeScript | Python |
|---|---|---|
| OpenAI | @composio/openai |
composio-openai |
| OpenAI Agents | @composio/openai-agents |
composio-openai-agents |
| Anthropic | @composio/anthropic |
composio-anthropic |
| Claude Agent SDK | @composio/claude-agent-sdk |
composio-claude-agent-sdk |
| Vercel AI SDK | @composio/vercel |
— |
| Google GenAI | @composio/google |
composio-gemini, composio-google |
| Google ADK | — | composio-google-adk |
| LangChain | @composio/langchain |
composio-langchain |
| LangGraph | via @composio/langchain |
composio-langgraph |
| LlamaIndex | @composio/llamaindex |
composio-llamaindex |
| Mastra | @composio/mastra |
— |
| Pi | @composio/experimental* |
— |
| Cloudflare Workers AI | @composio/cloudflare |
— |
| CrewAI | — | composio-crewai |
| AutoGen | — | composio-autogen |
* The Pi provider is experimental and ships from @composio/experimental.
Don't see your framework? Build a custom provider, or skip providers entirely and connect over MCP.
All packages
Everything published from this repo:
| Package | Description |
|---|---|
@composio/core |
TypeScript SDK |
@composio/slim |
@composio/core without packaged source or docs; same API, smaller install |
composio CLI |
Standalone CLI binary: curl -fsSL https://composio.dev/install | sh |
@composio/experimental |
Experimental integrations, including the Pi provider |
@composio/json-schema-to-zod |
JSON Schema to Zod conversion |
@composio/* provider adapters |
OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Vercel, Google, LangChain, LlamaIndex, Mastra, Cloudflare |
composio |
Python SDK |
composio-* provider adapters |
OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Gemini, Google, Google ADK, LangChain, LangGraph, LlamaIndex, CrewAI, AutoGen |
Repository layout
ts/ TypeScript SDK workspace
packages/core/ @composio/core
packages/providers/ Provider adapters
packages/cli/ Composio CLI
python/ Python SDK and provider packages
docs/ Documentation site (docs.composio.dev)
The TypeScript SDK is tested against Node 22+; the Python SDK supports Python 3.10+.
Development
mise install # pinned toolchain (Node, Python, pnpm)
pnpm install
pnpm build
pnpm test
Python commands run from python/; see python/README.md. We welcome contributions to both SDKs; read the contribution guidelines before submitting pull requests.
Support
License
MIT. See LICENSE.