Composio TypeScript SDK 全解析从 monorepo 架构到会话式工具执行【免费下载链接】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本指南以ts/目录Composio TypeScript SDK monorepo 工作区为讲解主线系统梳理其包划分、目录布局、开发工作流与底层实现原理。你将掌握如何用composio/core创建会话、接入 Provider 适配器、配置工具包版本与文件安全策略并理解会话Session、工具路由ToolRouter与元工具机制背后的源码实现从而在实际项目中正确选用并深度使用这套 SDK。TypeScript 工作区是什么ts/README.md开篇即点明这个目录承载着 Composio SDK 的 TypeScript 半边——核心 SDK、Provider 适配器、CLI、示例与端到端测试全部集中于此与python/目录中的 Python SDK 共同构成 Composio 的完整 SDK 家族。若想了解 Composio 平台本身的定位可阅读根目录 README本文则专注于 TypeScript 侧的一切。整个工作区是标准的 pnpm monorepo根 package.json 通过workspaces字段声明了全部子包ts/packages/core、ts/packages/slim、ts/packages/cli以及ts/packages/providers/*下的全部 Provider 包配合turbo进行任务编排turbo build、turbo test等实现一次构建、全包共享缓存的效果。快速开始两行代码拿到工具如果你只想使用 SDK安装与初始化都非常简洁。以核心包为例npm install composio/coreimport { Composio } from composio/core; const composio new Composio({ apiKey: process.env.COMPOSIO_API_KEY }); const session await composio.create(user_123); const tools await session.tools();这段代码背后是三层关键设计详见 ts/packages/core/README.md会话Session按用户隔离每个会话都绑定到你的一个终端用户如user_123工具执行、连接授权、账户管理都发生在该用户上下文内默认只暴露元工具会话默认给 Agent 一小撮用于发现、认证、执行的元工具meta tools避免一次性把数百个应用工具定义全部塞进上下文未配置 Provider 时返回 OpenAI 函数调用格式session.tools()在无 Provider 时默认输出 OpenAI function-calling 形态的 JSON Schema。会话的复用与持久化会话保存在服务端。多轮对话场景下请保存session.sessionId并在下一轮复用而不是反复create()const session await composio.use(sessionId);从源码看composio.create/composio.use只是composio.sessions.create/composio.sessions.use的向后兼容别名。在 composio.ts 中可以看到构造函数将this.sessions实例化后通过this.create this.sessions.create.bind(this.sessions)完成别名绑定并明确注释toolRouter已更名为sessions仅保留旧名以兼容存量代码——新项目请直接使用composio.sessions系列 API。Sessions类本身继承自ToolRouter见 Sessions.ts真正的创建逻辑在 ToolRouter.tscreate()内部先对配置做 Zod 校验ToolRouterCreateSessionConfigSchema.parse再把toolkits、tools、connectedAccounts、manageConnections、workbench沙箱、multiAccount、experimental自定义工具/工具包等参数序列化后 POST 到后端toolRouter.session.create接口。包清单一份可以对照源码阅读的目录ts/README.md给出了完整包表格下面逐项结合源码补充实现细节。已发布Published包包说明源码位置composio/coreComposio SDK 主包随包发布 TypeScript 源码与 SDK 文档安装后代码型 Agent 可直接检视ts/packages/corecomposio/slim与composio/core相同 API但不打包源码与文档安装体积更小ts/packages/slimcomposioCLI独立 CLI 二进制在 shell 中搜索、执行、编写工具脚本ts/packages/clicomposio/*providers把 Composio 工具格式化为各 Agent 框架原生工具格式的适配器OpenAI、Anthropic、Vercel AI SDK、LangChain 等ts/packages/providerscomposio/experimental实验性集成目前为 Pi providerts/packages/experimentalcomposio/json-schema-to-zodJSON Schema 到 Zod schema 的转换工具ts/packages/json-schema-to-zod其中值得展开说明的是core 随包发布源码的设计意图该包 README 明确写道intentionally ships its TypeScript source and SDK docs so the installed package is inspectable by coding agents。这意味着当你的 Agent如 Claude、Cursor 等编码助手安装了composio/core后可以直接在node_modules里读到.ts源码与 SDK 文档来理解 API 行为无需翻阅外部文档站点若在意安装体积则换用composio/slim两者 API 完全一致。Provider 适配器全家桶ts/packages/providers/README.md 将适配器分为两类基类位于 core 的 provider 目录非 AgenticBaseNonAgenticProvider只为裸模型 API 格式化工具 SchemaOpenAI、Anthropic、Cloudflare工具循环tool loop由你的代码驱动通过 provider 上的executeToolCall/handleToolCalls等辅助方法执行AgenticBaseAgenticProvider把带执行函数execute function的工具直接打包好交给框架LangChain、LlamaIndex、Mastra、Vercel、OpenAI Agents由框架自行驱动工具循环。当前仓库内置的 Provider 包与框架对应关系如下每个包都带自己的 README、src/index.ts与测试包目标框架composio/openaiOpenAI Chat Completions / Responses APIcomposio/openai-agentsOpenAI Agents SDKcomposio/anthropicAnthropic Messages APIcomposio/claude-agent-sdkClaude Agent SDKcomposio/vercelVercel AI SDKcomposio/googleGoogle GenAIcomposio/langchainLangChain / LangGraphcomposio/llamaindexLlamaIndexcomposio/mastraMastracomposio/cloudflareCloudflare Workers AI使用方式是在Composio构造函数里注入 Providerimport { Composio } from composio/core; import { OpenAIAgentsProvider } from composio/openai-agents; const composio new Composio({ provider: new OpenAIAgentsProvider() }); const session await composio.create(user_123); const tools await session.tools(); // 直接可交给 OpenAI Agents SDK从 composio.ts 可见未显式传入时 SDK 默认使用new OpenAIProvider()。内部未发布包cli-keyring与cli-local-tools为 CLI 提供密钥环与本地工具支持ts-builders则负责生成 TypeScript 源码。它们不对外发布仅在 monorepo 内部被引用。目录布局每个目录放什么ts/ packages/ Published and internal packages (见上文包清单) examples/ Runnable examples per feature and framework e2e-tests/ Runtime E2E tests (Node, Deno, Cloudflare Workers, CLI) docs/ Workspace SDK docs: API notes and internal guides scripts/ Build, validation, and scaffolding scripts vendor/ Read-only reference submodules; do not edit对照当前仓库实际内容ts/examples/按功能 框架双维度组织既有tools/、tool-router/、session-management/、connected-accounts/、triggers/、mcp/、modifiers/、file-handling/等功能向示例也有openai/、anthropic/、langchain/、llamaindex/、mastra/、google/、vercel/、cloudflare-wrangler/等框架向示例外加versioning/、json-schema-to-zod/、error-handling-demo/等专题ts/e2e-tests/按运行时拆分Node、Deno、Cloudflare Workers、CLI对应根 package.json 中的test:e2e:node、test:e2e:deno、test:e2e:cloudflare、test:e2e:cli任务ts/docs/存放工作区级 SDK 文档getting-started.md、core-concepts.md两篇入门文档advanced/下的自动上传下载、自定义 Provider、错误处理、modifiers、会话管理、遥测、webhook 校验专题api/下的各模型 API 说明以及internal/的配置、发布、触发器内部指南。开发工作流从零开始构建与验证所有命令都在仓库根目录执行。首先安装锁定的工具链mise install pnpm installmise install依据根目录的 mise.toml 与 toolchain-versions.json 安装钉死的 Node 版本根 package.json 的devEngines要求 Node24.17.0 25与包管理器pnpm 11.8.0。构建与校验pnpm build:packages # 构建全部 TS 包turbo build --filter./ts/packages/** pnpm typecheck # 全包类型检查 pnpm lint:packages # 对 ts/packages 执行 oxlint pnpm test # 包单元测试 示例校验从根 package.json 的脚本定义可以看出pnpm test是一长串串联任务先跑工具链与发布流程测试test:toolchain、test:install-sh、test:release-workflow、test:provider-compatibility再通过turbo test执行各包测试最后用validate-examples.ts校验示例可运行性。运行时 E2E 套件需要凭据API Key 等环境变量pnpm test:e2e:node pnpm test:e2e:deno pnpm test:e2e:cloudflare pnpm test:e2e:cli脚手架命令用于创建新 Provider 包与示例pnpm create:provider name [--agentic] # 新建 Provider 包 pnpm create:example name # 在 ts/examples 下新建示例前者对应ts/scripts/create-provider.sh会生成ts/packages/providers/provider-name骨架src/index.ts、package.json、构建配置若添加--agentic标记则按 Agentic 基类骨架生成。新建 Provider 时需实现wrapTool/wrapTools非 Agentic 类型还需executeToolCall并补充覆盖打包与执行处理的测试——这与 providers/README.md 中的指引一致。另外凡改动已发布包都必须附带 Changesets见仓库根 CONTRIBUTING.md根目录提供了changeset、changeset:version、changeset:releasets/scripts/changeset-release.sh等配套命令并有validate:changesetsvalidate-changesets.mjs在 CI 中校验 Changeset 格式。深入Composio类配置项全解在 composio.ts 中定义了完整的ComposioConfigTProvider类型。除了 README 提到的几个常规项结合源码注释可得到如下完整配置面配置项类型/默认值说明apiKeystring \| null默认取COMPOSIO_API_KEY环境变量Composio API 密钥baseURLstring \| null默认生产环境地址自定义 API 基础地址自托管或内网代理时使用providerTProvider默认new OpenAIProvider()Provider 适配器决定工具输出格式与执行方式allowTrackingboolean默认true是否启用遥测关闭可避免向服务端上报匿名使用数据defaultHeadersComposioRequestHeaders追加到每次 API 请求的自定义头如x-request-id便于链路追踪disableVersionCheckboolean默认false是否跳过启动时的 NPM 最新版本检查dangerouslyAllowAutoUploadDownloadFilesboolean默认false执行期间自动上传/下载文件读取工具 Schema 中标为可上传的本地路径与 URLsensitiveFileUploadProtectionboolean默认true自动上传与files.upload时对本地路径做敏感目录黑名单检查如.ssh、.aws、.env等fileUploadPathDenySegmentsstring[]额外的敏感路径片段与内置黑名单合并fileUploadDirsstring[] \| false默认[home/.composio/temp]自动上传的目录白名单传false拒绝一切本地路径URL 与File/Blob对象不受影响传数组则替换默认值fileDownloadDirstring默认home/.composio/files执行中下载文件及composio.files.download()的落盘目录相对路径基于process.cwd()解析toolkitVersionsToolkitVersionParam默认latest按工具包钉版本见下文版本管理hoststring当前宿主服务名供遥测标记非遥测场景可忽略构造函数内部会通过getSDKConfig解析 baseURL/apiKey、用getToolkitVersionsFromEnv合并环境变量中的版本配置、以expandHomeAndResolve(Many)展开fileUploadDirs/fileDownloadDir中的~随后初始化全部领域模型并挂到实例上this.tools new Tools(this.client, this.config); this.toolkits new Toolkits(this.client); this.triggers new Triggers(this.client, this.config); this.authConfigs new AuthConfigs(this.client); this.files new Files(this.client, { /* 文件安全配置 */ }); this.connectedAccounts new ConnectedAccounts(this.client); this.experimental new Experimental(this.client); this.sessions new Sessions(this.client, this.config);对应关系见 composio.ts。tools、toolkits、triggers、authConfigs、connectedAccounts、files等即为会话之外的资源管理入口而旧的直接执行流程composio.tools.get/composio.tools.execute虽然仍可用但官方明确标注为 legacy新代码应优先使用会话 API。环境变量COMPOSIO_API_KEYAPI 密钥COMPOSIO_BASE_URL自定义 API 基础地址COMPOSIO_LOG_LEVEL日志级别取值silent/error/warn/info/debugCOMPOSIO_TOOLKIT_VERSION_TOOLKIT钉住某工具包版本例如COMPOSIO_TOOLKIT_VERSION_GITHUB20250902_00。工具包版本管理工具包版本号遵循DDMMYYYY_NN格式日/月/年 当日序号。生产环境建议按包钉版本开发环境可用latestconst composio new Composio({ apiKey: process.env.COMPOSIO_API_KEY, toolkitVersions: { github: 20250909_00, slack: 20250902_00, gmail: latest, // 可混用 }, });需要注意的版本行为见 ts/docs/getting-started.md 与 composio.ts 注释版本配置同时作用于工具与触发器手动执行tools.execute()时若版本解析为latest则必须显式传version参数或设置dangerouslySkipVersionCheck: true不推荐用于生产否则会被拒绝触发器类型始终使用初始化时配置的全局toolkitVersions。会话、MCP 与 Modifiers三个高频能力会话的 MCP 端点每个会话都暴露一个托管的 MCP 端点。传入mcp: true会在类型层面暴露session.mcpconst session await composio.create(user_123, { mcp: true }); console.log(session.mcp.url); console.log(session.mcp.headers);把url与headers填入 Claude、Cursor 或任何 MCP 客户端即可连接。从 ToolRouter.ts 的重载签名可以看到只有当配置包含{ mcp: true }时返回类型才带session.mcp字段运行时其实一直存在composio.mcp这一独立服务器管理 API 已标记为废弃官方建议一律改用会话级 MCP 端点。ModifiersSchema 变换与执行拦截session.tools()支持传入 modifiers 来改写工具 Schema、拦截执行前后const tools await session.tools({ modifySchema: ({ toolSlug, toolkitSlug, schema }) ({ ...schema, description: ${schema.description} (via my-app), }), beforeExecute: ({ toolSlug, toolkitSlug, params }) params, afterExecute: ({ toolSlug, toolkitSlug, result }) result, });这在白标场景、统一封装、审计打点等场景非常实用类型定义位于 core 的 modifiers.types.ts工作区文档 ts/docs/advanced/modifiers.md 有专门讲解。自定义工具Custom Tools可以通过experimental_createTool定义本地工具并挂到会话上Zod 定义入参import { Composio, experimental_createTool } from composio/core; import { z } from zod; const customTool experimental_createTool(WEATHER_FORECAST, { name: Weather Forecast, description: Get the weather forecast for a location, inputParams: z.object({ location: z.string().describe(The location to get the forecast for), days: z.number().optional().default(3), }), execute: async (input) getWeatherForecast(input.location, input.days ?? 3), }); const session await composio.create(user_123, { experimental: { customTools: [customTool] }, }); const result await session.execute(WEATHER_FORECAST, { location: SF, days: 5 });对应实现细节ToolRouter.create会通过prepareInlineCustomTools把自定义工具打包进experimental.custom_tools载荷并在响应后依据 slug 映射构建customToolsMap见 ToolRouter.ts。支持渠道与进一步学习完整 API 文档位于工作区 ts/docs入门见 getting-started.md核心概念userId 隔离、工具/工具包/连接账户/触发器见 core-concepts.md会话管理进阶见 advanced/session-management.md更多可运行示例见 ts/examples每个示例目录都带 package.json 与 README可独立安装运行Provider 机制与自定义适配器见 ts/packages/providers/README.md 与 ts/docs/providers/custom.md核心模型源码可从 ts/packages/core/src/models 直接阅读覆盖Sessions、ToolRouter、Tools、Toolkits、Triggers、AuthConfigs、ConnectedAccounts、MCP、Files等全部领域对象。小结ts/工作区把 SDK 的使用、适配、测试、脚手架完整收敛到一个 pnpm monorepo 中composio/core提供以会话为中心的现代 API元工具按需发现、服务端持久化、随包源码便于 Agent 检视composio/slim提供瘦身替代十余个 Provider 包把工具无缝注入主流 Agent 框架CLI 满足 shell 场景examples/与e2e-tests/则保证了从示例到多运行时Node/Deno/Cloudflare Workers的可靠性。理解这份包划分与源码结构后无论是集成使用、贡献新 Provider还是排查执行链路都能快速定位到对应代码。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考