Composio SDK 集成指南：为 AI Agent 接入 1000+ 预认证工具包的 TypeScript / Python 开发实践

Composio SDK 集成指南：为 AI Agent 接入 1000+ 预认证工具包的 TypeScript / Python 开发实践

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio

Composio 是一个面向 AI Agent 的工具接入平台，通过 TypeScript 与 Python 双 SDK，为你的 Agent 提供 1000+ 预认证工具包（toolkits）、按用户隔离的会话（session）、身份认证（authentication）、触发器（triggers）与沙箱环境，让 Agent 真正"把意图转化为行动"。本文以仓库根目录 README.md 为主线，结合 @composio/core 与 composio Python SDK 的源码实现，完整讲解快速上手、会话机制、Provider 适配器、CLI 与 SDK 配置项，帮助你为任意 Agent 框架快速接入可执行工具的完整能力。

Composio 是什么：Agent 与 1000+ 应用之间的工具接入层

Composio 的核心定位是把"工具"这件事从 Agent 开发中抽象出去。它不是一个具体应用，而是一个 SDK monorepo，仓库根目录 README.md 明确列出了四大组成部分：

• @composio/core：TypeScript SDK；
• composio：Python SDK；
• composioCLI：在 Shell 中搜索、执行与脚本化工具的命令行工具；
• Provider 适配器：面向 OpenAI Agents、Claude Agent SDK、Vercel AI SDK、LangChain 等框架的工具格式转换层。

一句话概括其工作方式：为某个用户创建一个会话（session），把该会话的工具交给你的 Agent，Agent 就能跨 1000+ 应用采取行动——而认证、连接管理、工具执行环境都由 Composio 托管。

准备：获取 API Key

在使用任一 SDK 之前，需要先从 Composio Dashboard 获取COMPOSIO_API_KEY。该密钥是 SDK 初始化的硬性前置条件——在 Python SDK 初始化逻辑 中，若构造函数未显式传入api_key且环境变量COMPOSIO_API_KEY不存在，会直接抛出ApiKeyNotProvidedError。TypeScript SDK 同理，Composio构造函数 通过getSDKConfig从配置与环境变量解析密钥。

TypeScript 快速上手

安装与最小示例

npm install @composio/core @composio/openai-agents @openai/agents

提示：@composio/core有意将 TypeScript 源码与 SDK 文档一并打包进安装产物，使已安装的包对编码 Agent 可检视。若希望安装体积更小且 API 完全一致，可改用@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() }); // 每个会话只对某一个用户生效 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);

Composio 配置项

TypeScript 的Composio构造函数接受以下配置（定义见 ts/packages/core/src/composio.ts#L26-L159）：

对应的环境变量（详见 ts/packages/core/README.md）：

• COMPOSIO_API_KEY：API 密钥；
• COMPOSIO_BASE_URL：自定义 API 基础地址；
• COMPOSIO_LOG_LEVEL：日志级别，取值silent、error、warn、info、debug；
• COMPOSIO_TOOLKIT_VERSION_<TOOLKIT>：钉扎单个工具包版本，例如COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00。

工具包版本控制

toolkitVersions是生产环境的关键配置。它支持三种形态（见 ts/packages/core/src/composio.ts#L122-L157）：

• 省略：所有工具包使用latest；
• 对象：为不同工具包指定不同版本，例如{ github: '20250909_00', slack: '20250902_00' }；
• 环境变量：通过COMPOSIO_TOOLKIT_VERSION_GITHUB=20250909_00这类变量单独钉扎。

值得注意的约束：当通过tools.execute()手动执行工具且版本解析为latest时，要么在 execute 参数中设置dangerouslySkipVersionCheck: true（不推荐用于生产），要么在构造配置或环境变量中指定具体版本。这保证了生产环境工具行为可复现。

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()) # 每个会话只对某一个用户生效 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)

Python SDK 要求 Python 3.10+（见 python/README.md）。

SDKConfig 配置项

Python SDK 的构造参数在 python/composio/sdk.py#L34-L46 中定义：

file_upload_dirs的语义值得细读（见 python/composio/sdk.py#L112-L126）：None（默认）仅允许~/.composio/temp；False拒绝所有本地路径（URL 与内存字节不受影响）；非空字符串序列则作为白名单，文件仅当符号链接解析后的绝对路径位于这些目录内、且在路径分量边界上时才被接受（/tmp/foo允许/tmp/foo/bar但拒绝/tmp/foo-bar）；传入值会替换默认白名单，若仍需默认暂存目录需显式包含它。

会话级认证与触发器

Python SDK 还提供了会话级认证与触发器能力（详见 python/README.md）：

# 主动驱动认证流程 connection_request = session.authorize("gmail") print(connection_request.redirect_url) # 引导用户前往授权 connection_request.wait_for_connection() # 订阅已连接应用的事件 trigger = composio.triggers.create( slug="GITHUB_COMMIT_EVENT", user_id="user_123", trigger_config={"owner": "composiohq", "repo": "composio"}, ) subscription = composio.triggers.subscribe() @subscription.handle(trigger_id=trigger.trigger_id) def handle_event(data): print("Event received:", data) subscription.wait_forever()

subscribe()通过 WebSocket 流式接收事件，适合本地开发；生产环境应注册 Webhook URL，并用composio.triggers.parse()解析投递内容。

Session（会话）机制：按用户隔离的工具上下文

create / use / sessions

Session 是本项目 Agent 集成的核心单元：它为一套工具与工具包提供发现、认证与执行的作用域。使用方式为：

// TypeScript：会话在服务端持久化 const session = await composio.create("user_123"); const sessionId = session.sessionId; // 多轮对话时直接复用，而不是再次 create() const same = await composio.use(sessionId);

# Python session = composio.create(user_id="user_123") session_id = session.session_id same = composio.use(session_id)

在 Python SDK 源码中，create与use是ToolRouter会话对象的顶层快捷方式：构造函数将其绑定为self.create = self._sessions.create、self.use = self._sessions.use，同时暴露规范入口composio.sessions（见 python/composio/sdk.py#L187-L223）。注意composio.tool_router已被标记为弃用别名（deprecated since 0.17.0），新代码应统一使用composio.sessions或composio.create/composio.use。TypeScript SDK 结构完全一致：composio.ts中sessions为规范入口，toolRouter为弃用别名，create/use为绑定好this的快捷方法。

Meta tools：默认只加载少量工具定义

默认情况下，会话给 Agent 的是一小撮 meta tools——它们在运行时负责发现、认证和执行应用工具，从而避免把数百条工具定义一次性灌进上下文（context）。这是控制 token 消耗与上下文长度的关键设计。若需要所有工具直接暴露，可在创建会话时使用sessionPreset: SessionPreset.DIRECT_TOOLS之类的预设（见 ts/packages/core/src/composio.ts#L230-L257）。要限制会话可用的工具包、认证配置与已连接账号，可在composio.create()上配置toolkits、tools、auth_configs、connected_accounts等参数。

MCP：每个会话一个托管 MCP 端点

偏好 MCP 的团队无需写任何 Provider 适配代码。每个会话都暴露一个托管的 MCP 端点：创建会话时传mcp: true，然后让 Claude、Cursor 或任意 MCP 客户端直接指向该端点：

// TypeScript const session = await composio.create("user_123", { mcp: true }); console.log(session.mcp.url); console.log(session.mcp.headers);

# Python session = composio.create(user_id="user_123", mcp=True) print(session.mcp.url) # 会话的 MCP 端点 print(session.mcp.headers) # 端点认证请求头

与之相关的一个弃用说明：TypeScript SDK 中顶层composio.mcp（独立服务器管理 API）已弃用，MCP 现在按会话按需启用，新代码应使用composio.create(userId, { mcp: true })返回的会话端点（见 ts/packages/core/src/composio.ts#L208-L216）。

CLI：在 Shell 中搜索、执行与脚本化工具

composioCLI 把 Composio 能力带到 Shell 层，同时也为 Claude Code 这类编码 Agent 提供本地工具表面（local tool surface）：

curl -fsSL https://composio.dev/install | sh

安装脚本会把composio加入 PATH（对未来的终端生效）。安装后请打开新终端再执行composio login。Shell 安装覆盖项（包括仅安装不写配置的COMPOSIO_INSTALL_SHELL=none）详见 INSTALL.md。

CLI 的核心命令（README 明确列出的）：composio search搜索工具、composio execute执行工具、composio link连接账号、composio run用 TypeScript 脚本化工作流。从 CLI 命令目录 的源码结构看，命令还覆盖了login、logout、whoami、setup、signup、upgrade、version、install、listen、proxy、dev、init、artifacts以及config、tools、toolkits、triggers、connected-accounts、auth-configs、connections、orgs、projects、agent、generate、local-tools等子命令组，可作为浏览 CLI 全貌的入口。

Providers：把工具适配到你的 Agent 框架

Provider（适配器）负责把 Composio 工具转换成对应 Agent 框架的原生工具格式并接管执行链路。README 给出了完整的支持矩阵：

* Pi Provider 为实验性功能，随@composio/experimental发布。

未在列表中的框架有两种出路：其一，构建自定义 Provider（适配器只需实现框架原生工具格式转换）；其二，跳过 Provider 直接走 MCP 端点。Provider 适配器的源码分别位于 ts/packages/providers 与 python/providers 目录下。

全量包清单与仓库布局

README 列出的所有发布包：

仓库布局（见 README.md）：

ts/ TypeScript SDK workspace packages/core/ @composio/core packages/providers/ Provider 适配器 packages/cli/ Composio CLI python/ Python SDK 与 Provider 包 docs/ 文档站点（docs.composio.dev）

环境要求：TypeScript SDK 针对 Node 22+ 测试；Python SDK 支持 Python 3.10+。

本地开发与贡献

使用仓库根目录的 package.json 与 mise.toml 提供的固定工具链（Node、Python、pnpm）进行开发：

mise install # 安装钉扎的工具链 pnpm install pnpm build pnpm test

Python 相关命令在python/目录下执行，细节见 python/README.md。提交 Pull Request 前请阅读 CONTRIBUTING.md。本仓库以 MIT 协议开源，见 LICENSE。

结语

从根目录 README.md 出发可以看到，Composio 的集成路径非常清晰：取 API Key → 创建按用户隔离的 session →session.tools()拿到框架原生格式的工具 → 交给 Agent 执行。默认的 meta tools 机制控制了上下文体积，MCP 端点让非适配框架零成本接入，Provider 矩阵则覆盖了主流 TypeScript 与 Python Agent 框架。配合toolkitVersions版本钉扎、文件上传目录白名单等生产级配置（TS 配置 与 Python 配置 两套实现保持语义一致），可以在一开始就把认证、上下文管理与工具执行环境等工程问题交给平台，把精力集中在 Agent 业务逻辑本身。

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio