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

docs: name deprecated SDK packages at the install step (#4232)

## Summary - Adds a `warn` callout under the quickstart's Python install step: the current package is `composio`; `composio-core` and `composio-openai` are the legacy v1 SDK — do not install them. - Names the legacy package names explicitly in the migration guide's intro, so searches for those names land on the migration path. ## Why (measured) From the docs-agent-eval transcripts (202 agent runs, waves 4–5): **85% of agents on prod docs and 63% on the current IA attempt a legacy-package install first**, then discover the mistake, uninstall, and redo — **+64s (+14%) mean build time**. The failure mode is visible verbatim in transcripts: after reading the quickstart, agents search "how to install **composio-core or composio** python package" — the docs never disambiguated. LLM training priors will keep suggesting the old names; the install step is where the correction lands. ## Deliberately out of scope - Package-registry fixes (PyPI DEPRECATED banner on composio-core, `python_requires>=3.10` on composio — currently installs on 3.9 then crashes on import) — SDK-side, being raised separately. - A machine-readable current-versions manifest — follow-up proposal. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Soumya Medapati <soumyamedapati@mac.local.meter> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Soumya Medapati committed Aug 24, 2026 at 15:59 UTC 3ea113b04cf2b4c1f5f9a9ccf816dd6f3f8cd138
2 files changed +9 -1
docs/content/docs/migration-guide/new-sdk.mdx
+1 -1
@@ -6,7 +6,7 @@ written: "December 2025"
6 ---
7
8 <Callout type="info">
9 -This guide covers migrating from the legacy SDK (v1) to the current SDK (v3). The recommended way to use Composio is now through **sessions** — see [Migrating from Direct Tools to Sessions](/docs/migration-guide/direct-to-sessions) or [Configuring Sessions](/docs/configuring-sessions) if you're starting fresh.
9 +This guide covers migrating from the legacy SDK (v1) — `composio-core` on PyPI and npm — to the current SDK (v3): `composio` on PyPI, `@composio/core` on npm. Provider packages such as `composio-openai` kept their names across the rewrite: current releases work with v3, v1-era releases don't. The recommended way to use Composio is now through **sessions** — see [Migrating from Direct Tools to Sessions](/docs/migration-guide/direct-to-sessions) or [Configuring Sessions](/docs/configuring-sessions) if you're starting fresh.
10 </Callout>
11
12 In the last few months, we have experienced very rapid growth in usage of our platform. As such, our team has been working hard to radically improve the performance and developer experience of our platform.
docs/content/docs/quickstart.mdx
+8
@@ -25,6 +25,10 @@ The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `impor
25 The Composio Python SDK requires **Python 3.10 or newer**.
26
27 <PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" />
28 +
29 +<Callout type="warn" title="Do not install composio-core">
30 +The current Python package is `composio`. The package `composio-core` is the legacy v1 SDK — it calls deprecated APIs and does not work with sessions. If an older tutorial or an AI coding assistant suggests it, install `composio` instead. See the [migration guide](/docs/migration-guide/new-sdk).
31 +</Callout>
32 </Tab>
33 <Tab value="TypeScript">
34 <PackageInstall
@@ -178,6 +182,10 @@ readline.close();
182 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
183 <Tab value="Python">
184 <PackageInstall ecosystem="python" packages="python-dotenv composio composio-claude-agent-sdk claude-agent-sdk" />
185 +
186 +<Callout type="warn" title="Do not install composio-core">
187 +The current Python package is `composio`. The package `composio-core` is the legacy v1 SDK — it calls deprecated APIs and does not work with sessions. If an older tutorial or an AI coding assistant suggests it, install `composio` instead. See the [migration guide](/docs/migration-guide/new-sdk).
188 +</Callout>
189 </Tab>
190 <Tab value="TypeScript">
191 <PackageInstall