Composio TypeScript SDK 核心包（@composio/core）完全指南：会话、Provider、MCP 与工具修饰器实战

@composio/core 是 Composio 的 TypeScript SDK 核心包，它把"为 1000+ 应用执行工具"这件事封装为一个会话（session）抽象：为你的每个用户创建一个会话，把会话中的工具交给你的 Agent，认证（authentication）由 Composio 后端统一托管。读完本文，你将掌握如何初始化 SDK、创建与复用会话、按框架接入 Provider、启用会话级 MCP 端点、用修饰器改造工具行为，以及如何通过配置项与环境变量精细控制 SDK 的运行行为——所有结论均可在当前仓库 ts/packages/core 目录下找到源码级佐证。

包概览：@composio/core 是什么

@composio/core 是整个 TypeScript SDK 的入口包，其核心导出位于 src/index.ts，其中最重要的是 Composio 类（src/composio.ts）——它是 SDK 的根对象，负责初始化 API 客户端并挂载所有领域模型。

从源码结构看，一个 Composio 实例在构造时（src/composio.ts#L304-L403）会依次初始化以下模型：

模型属性	类型	职责
composio.tools	Tools	列出、获取、执行工具（直接执行流程，legacy）
composio.toolkits	Toolkits	获取 toolkit 元数据、发起用户授权
composio.triggers	Triggers	管理 Webhook 触发器与事件订阅
composio.authConfigs	AuthConfigs	管理各 toolkit 的认证配置
composio.connectedAccounts	ConnectedAccounts	管理已认证的连接（connected accounts）
composio.files	Files	文件上传与下载
composio.sessions	Sessions	创建与复用会话（推荐入口）
composio.experimental	Experimental	实验性 API 兼容别名

需要注意的是，composio.create / composio.use 是 composio.sessions.create / composio.sessions.use 的向后兼容别名（src/composio.ts#L259-L272），而 composio.toolRouter 则被标记为 @deprecated，是 sessions 的重命名遗留，新代码应优先使用 composio.sessions。此外，独立的 MCP 服务管理接口 composio.mcp 也已被标记为弃用，官方推荐改用会话级 MCP 端点（见下文 MCP 一节）。

该包"刻意"在安装产物中附带 TypeScript 源码与 SDK 文档，目的是让编码 Agent 能够直接检查已安装的包；如果你希望获得更小的安装体积且 API 相同，可以使用同 API 的 @composio/slim 包。

安装

npm install @composio/core

包管理器同样适用 pnpm / yarn / bun。当前仓库使用 pnpm workspace 管理，包定义见 ts/packages/core/package.json。

快速上手：创建会话并获取工具

第一步：准备 API Key

从 Composio Dashboard 的设置页获取 COMPOSIO_API_KEY。SDK 的 API Key 解析优先级在 src/utils/sdk.ts#L44-L60 中有明确定义：

1. 构造时显式传入的 apiKey 参数；
2. 环境变量 COMPOSIO_API_KEY；
3. 用户数据文件 ~/.composio/user_data.json 中的 api_key 字段；
4. 兜底为空字符串，此时构造函数会抛出 ComposioNoAPIKeyError（见 src/errors/SDKErrors.ts）。

baseURL 的优先级与此类似（src/utils/sdk.ts#L48-L49）：baseURL 参数 → COMPOSIO_BASE_URL 环境变量 → 用户数据文件 base_url → 默认值 https://backend.composio.dev（定义于 src/utils/constants.ts#L7）。

第二步：创建会话

import { 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();

这里有几个关键设计：

• 会话是用户级的隔离单元：create(userId) 以用户 ID 为维度创建会话，会话内获取、执行工具都绑定在该用户身份下；
• 默认返回 meta 工具而非全部工具定义：默认情况下，会话只给 Agent 一小撮 meta 工具，这些工具在运行时负责"发现 → 认证 → 执行"应用工具，这样你就不必把数百个工具定义一次性塞进 LLM 的上下文窗口；
• 默认格式是 OpenAI function calling：当没有配置 Provider 时，session.tools() 返回的是 OpenAI 函数调用格式的工具数组。这一点在源码中有直接对应：Composio 构造函数在未指定 provider 时会实例化默认的 OpenAIProvider（src/composio.ts#L317）。

从实现上看，composio.create 实际调用的是 Sessions.create（src/models/Sessions.ts），而 Sessions 继承自 ToolRouter（src/models/ToolRouter.ts）。create 会先把你的配置通过 ToolRouterCreateSessionConfigSchema 做 Zod 校验，再组装成后端载荷（toolkits、tools、tags、manage_connections、workbench/sandbox、preload 等字段），最终返回一个 ToolRouterSession 实例（src/models/ToolRouterSession.ts）。

第三步：多轮对话中复用会话

会话持久化在服务端。对于多轮对话，请保存 session.sessionId 并复用，而不是反复调用 create()：

const session = await composio.use(sessionId);

use 内部会执行会话的 retrieve（若附带自定义工具则走 attach）流程，恢复出同一个 ToolRouterSession 实例（src/models/ToolRouter.ts#L311-L392）。会话还支持按需限制 toolkits、auth configs 与 connected accounts，也支持通过 session.delete(id) 删除会话。

会话的完整能力面

ToolRouterSession（src/models/ToolRouterSession.ts）除了 tools() 之外还提供了丰富的会话级方法，这是 README 之外的源码级延伸：

• session.authorize(toolkit, options?)：为某个 toolkit 发起授权流程，返回带重定向 URL 的 ConnectionRequest；支持 callbackUrl、alias，以及实验性的 accountType: 'SHARED' + aclConfigForShared 共享连接（src/models/ToolRouterSession.ts#L412-L471）；
• session.search({ query, toolkits? })：按语义用例搜索工具，返回带 schema 与使用指引的工具结果；
• session.execute(toolSlug, arguments?)：在会话内执行某个工具；绑定到会话的自定义工具（custom tools）会在进程内直接执行，远端工具则发往 Composio 后端；
• session.toolkits(options?)：查询会话内各 toolkit 的连接状态（支持分页与按 slug 过滤）；
• session.proxyExecute(params)：通过会话的连接账户代理转发 API 调用，返回 status/data/headers；
• session.update(config)：部分更新会话配置，会同步变更本地的 configVersion、preload、sandbox、warnings；
• session.delete()：删除会话，删除后立即不可检索、不可执行。

Provider：把工具格式化为你的 Agent 框架

Provider 的职责有两个：把会话工具格式化成你的 Agent 框架期望的工具格式，并接通执行链路。源码中 Provider 的抽象基类与实现位于 src/provider 目录：

• BaseProvider.ts：BaseComposioProvider、BaseNonAgenticProvider、BaseAgenticProvider 抽象基类；
• OpenAIProvider.ts：默认 Provider，随 SDK 内置，无需额外安装；
• ComposioProvider.ts：通用 Provider。

使用示例：

import { 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

以默认的 OpenAIProvider 为例，wrapTool 会把 Composio 工具转成 OpenAI ChatCompletionTool（type: 'function' + name/description/parameters），并对输入参数做 deduplicateJsonSchemaRequiredArrays 处理（src/provider/OpenAIProvider.ts#L100-L110）；executeToolCall 则会先通过 normalizeToolArguments 容错解析 OpenAI 序列化后的 JSON 字符串参数，再执行并返回 JSON 字符串结果（src/provider/OpenAIProvider.ts#L186-L213）。handleToolCalls 支持单条 assistant 消息携带多个并行工具调用的情况，会为每个 tool_call_id 生成对应的 tool 消息（src/provider/OpenAIProvider.ts#L257-L298）。

适配器覆盖 OpenAI、OpenAI Agents、Anthropic、Claude Agent SDK、Vercel AI SDK、Google GenAI、LangChain、LlamaIndex、Mastra、Cloudflare Workers AI 等框架，各适配器分布在仓库 ts/packages/providers 目录下。

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

每个会话都会暴露一个托管的 MCP（Model Context Protocol）端点。传入 mcp: true 让它在类型层面显式出现，然后把地址交给 Claude、Cursor 或任意 MCP 客户端即可：

const session = await composio.create('user_123', { mcp: true });

console.log(session.mcp.url);
console.log(session.mcp.headers);

实现细节：ToolRouter.create 在 config: { mcp: true } 的重载下返回带 session.mcp 的 Session 类型；运行时每个会话都真实存在 MCP 配置（mcp.url 与 mcp.headers，headers 中包含 x-api-key），只是默认情况下从返回类型中隐藏，属于显式 opt-in（src/models/ToolRouter.ts#L133-L147、src/models/ToolRouterSession.ts#L117-L119）。类型层面的区分也有专门的测试覆盖，见 ts/packages/core/type-tests/sessions-mcp.test-d.ts。

配套的 session.mcp.headers 中 x-api-key 来自构造时的 API Key，MCP 客户端连接时需带上该请求头。仓库中还有独立的 MCP 模型实现与测试（src/models/MCP.ts、test/models/mcp.test.ts），但正如前文所述，composio.mcp 独立服务管理接口已废弃，新代码一律走会话 MCP 端点。

Modifiers：改造工具 schema 与拦截执行

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,
});

所有修饰器的类型定义集中在 src/types/modifiers.types.ts：

• modifySchema（类型 TransformToolSchemaModifier）：在工具 schema 暴露给消费者之前转换它，典型用途是定制输入参数定义、改名、改描述、做版本控制或按组织定制（如给所有 GitHub 工具加上企业级 rate limit 元数据）；
• beforeExecute（类型 beforeExecuteModifier）：在工具真正执行前拦截并修改执行参数，可用于注入认证参数、转换输入格式、附加上下文或做请求校验；
• afterExecute（类型 afterExecuteModifier）：在工具执行完成后拦截响应，可用于响应数据转换、错误增强、日志与监控等横切关注点；
• beforeFileUpload（类型 beforeFileUploadModifier）：针对每个 file_uploadable 值在上传前拦截，返回字符串可替换输入（重写路径、重定向 URL、把 File 换成文件系统路径），返回 false 则中止上传并抛出 ComposioFileUploadAbortedError，抛错同样中止。

对于会话上下文，还提供了 beforeExecuteMeta / afterExecuteMeta（SessionExecuteMetaModifiers），它们的回调额外携带 sessionId，专门用于会话内 helper 工具与预加载应用工具的执行拦截。会话工具获取时的 schema 修饰在 src/models/ToolRouterSession.ts#L247-L266 中实现：非函数修饰器会抛出 ComposioInvalidModifierError，schema 会先经过 ToolSchema.parse 校验再交给修饰器。

Configuration：构造参数与默认值

Composio 构造器接受的配置（源码定义见 src/composio.ts#L26-L159）：

interface ComposioConfig {
  apiKey?: string | null; // 默认读取 COMPOSIO_API_KEY
  baseURL?: string | null; // 自定义 API base URL（默认 https://backend.composio.dev）
  provider?: TProvider; // Provider 适配器（默认 OpenAIProvider）
  allowTracking?: boolean; // 是否启用遥测（默认 true）
  defaultHeaders?: ComposioRequestHeaders; // 附加到 API 请求的额外请求头
  disableVersionCheck?: boolean; // 跳过 SDK 版本检查（默认 false）
  dangerouslyAllowAutoUploadDownloadFiles?: boolean; // 执行期间自动上传/下载文件（默认 false）
}

在 README 列出的配置之外，仓库源码还实现了以下与文件安全相关的扩展配置项（在 README 基础上补充，同样属于 ComposioConfig）：

配置项	默认值	说明
sensitiveFileUploadProtection	true	自动上传与 files.upload 时对本地路径做内置敏感路径段检查（如 .ssh、.aws 目录，.env、默认 SSH 私钥文件名等）；URL 与 File 对象不做路径检查
fileUploadPathDenySegments	内置列表	追加视为敏感的单一路径组件，与内置列表合并
fileUploadDirs	[<home>/.composio/temp]	自动上传时允许 SDK 读取本地文件的目录白名单；false 拒绝所有本地路径（URL 与 File 仍可用）；传入数组会整体替换默认值，在 Windows 上大小写不敏感
fileDownloadDir	<home>/.composio/files	工具执行下载文件与 composio.files.download() 的写入目录，相对路径基于 process.cwd() 解析
toolkitVersions	'latest'	全局或按 toolkit 指定版本（如 { github: '20250909_00', slack: '20250902_00' }），生产环境推荐显式固定版本
host	无	标识 SDK 所在宿主服务名（供遥测使用，如 'mcp'）

关于 toolkitVersions 有一个重要的执行约束：当通过 tools.execute() 手动执行工具且版本解析为 "latest" 时，必须显式传入具体版本（构造参数、环境变量或 execute 的 version 参数），否则需要设置 dangerouslySkipVersionCheck: true（不推荐用于生产）。版本解析的优先级实现在 src/utils/sdk.ts#L74-L111：全局字符串版本 > 用户提供的 toolkit 版本映射 > COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> 环境变量 > 兜底 'latest'。

其他值得注意的构造行为

• 构造器会把 fileUploadDirs / fileDownloadDir 中的 ~ 展开为绝对路径（expandHomeAndResolve）；
• allowTracking 为 true 时会初始化遥测（telemetry）并埋点；在 Cloudflare Workers 这类不支持 process exit 事件的环境里，需要手动调用 composio.flush() 确保遥测上报完成（src/composio.ts#L506-L508）；
• 版本检查默认开启：SDK 会向 npm 请求最新版本做提示，可通过 disableVersionCheck: true 关闭；
• getConfig() 返回冻结（frozen）的配置快照——因为 SDK 在初始化时已把 dangerouslyAllowAutoUploadDownloadFiles、fileUploadDirs、fileDownloadDir 等快照进内部模型，修改活配置对象是静默无效的，冻结让这一契约在调用点可见。

环境变量

SDK 支持以下环境变量：

• COMPOSIO_API_KEY：你的 Composio API Key；
• COMPOSIO_BASE_URL：自定义 API base URL；
• COMPOSIO_LOG_LEVEL：日志级别，可选 silent、error、warn、info、debug（源码 src/utils/constants.ts#L13-L18 仅读取其中四个级别，silent 由 logger 层处理）；
• COMPOSIO_TOOLKIT_VERSION_<TOOLKIT>：固定某个 toolkit 的版本，例如 COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00。

此外源码中还用到 CLIENT_PUSHER_KEY（Pusher 实时订阅密钥，触发器相关）与 DEVELOPMENT / CI（用于调试日志开关），属于内部实现细节。

会话之外的资源管理

Composio 实例同样暴露 composio.toolkits、composio.triggers、composio.authConfigs、composio.connectedAccounts，用于在会话之外管理资源：

• toolkits：获取 toolkit 元数据、发起用户连接授权；
• triggers：管理 Webhook 触发器与事件订阅（触发器模型与测试见 src/models/Triggers.ts、test/models/triggers.test.ts）；
• authConfigs：管理各 toolkit 的认证配置（Auth Scheme 等，见 src/models/AuthConfigs.ts）；
• connectedAccounts：管理已认证连接，包括连接状态、ACL 与共享连接（见 src/models/ConnectedAccounts.ts）。

旧的直接工具执行流程（composio.tools.get 与 composio.tools.execute）仍然可用，但已被标记为 legacy，新代码应优先使用会话（session）方案。

会话创建参数速查

composio.sessions.create(userId, config) 的 config 由 ToolRouterCreateSessionConfigSchema 校验（src/types/toolRouter.types.ts），常用字段包括：

• toolkits：要在会话中启用的 toolkit 列表，如 ['gmail']；
• tools：按 toolkit 细粒度启用/禁用具体工具（如 { gmail: ['gmail_search', 'gmail_send'] } 或 { slack: { disable: ['slack_delete_message'] } }）；
• tags：按标签过滤工具，可选 readOnlyHint、destructiveHint、idempotentHint、openWorldHint（支持 { enable, disable } 形式）；
• manageConnections：是否让会话使用工具管理连接（默认 true），可附带 callbackUrl 与 waitForConnections；
• authConfigs / connectedAccounts：为会话指定认证配置与已连接账户（connectedAccounts 支持多账户，如 { github: 'conn_id' } 或 { github: ['conn_1', 'conn_2'] }）；
• sandbox（workbench）：会话沙箱配置，支持 enable（默认 true，关闭后无 COMPOSIO_REMOTE_WORKBENCH / COMPOSIO_REMOTE_BASH_TOOL 等代码执行工具）、enableProxyExecution、autoOffloadThreshold、sandboxSize（standard 1 vCPU/1 GB、medium 2 vCPU/2 GB、large 4 vCPU/4 GB、xlarge 8 vCPU/8 GB，默认 standard）；
• sessionPreset：SessionPreset.DIRECT_TOOLS 预置，让所有需要的工具直接暴露，同时后端会关闭 search 与多工具执行；
• preload：预加载配置，{ tools: 'all' } 时所有（含自定义）工具都会预加载；
• experimental.customTools / experimental.customToolkits：把自定义工具/工具组内联绑定到会话；
• mcp: true：在返回类型中显式暴露 session.mcp。

测试与验证

本包在 ts/packages/core/test 下提供了覆盖面很广的测试，可以作为你理解与验证行为的第一手资料：

• 会话与工具路由：core/session.test.ts、models/toolRouter.test.ts、models/ToolRouterSessionFilesMount.test.ts；
• Provider：provider/provider.test.ts、provider/openai-provider.test.ts；
• 修饰器：tools/modifiers.test.ts、tools/fileModifiers.test.ts、tools/fileUploadMatrix.test.ts；
• MCP：models/mcp.test.ts 与类型测试 type-tests/sessions-mcp.test-d.ts；
• 配置与环境：core/versions.test.ts（toolkit 版本解析）、utils/version.test.ts；
• 工具 schema 处理：utils/jsonSchema.test.ts、utils/toolArguments.test.ts 等。

小结

@composio/core 的核心心智模型可以概括为：一个 Composio 实例管理全局配置与 API 客户端，多个按用户隔离的 session 承载工具发现、认证与执行，Provider 负责把工具格式化为目标框架的形态，Modifiers 提供 schema 与执行的拦截钩子，MCP 端点让任意 MCP 客户端直接消费会话能力。无论你接入的是 OpenAI、Anthropic、LangChain 还是 Mastra，入口代码都保持同一形态：初始化 Composio → 为用户 create 会话 → session.tools() 交给 Agent → 多轮对话中 use(sessionId) 复用。结合本文给出的源码路径，你可以随时深入 src/composio.ts 与 src/models/ToolRouterSession.ts 验证每个行为背后的实现细节。