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/composioComposio 是一个面向 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/coreTypeScript SDKcomposioPython SDKcomposioCLI在 Shell 中搜索、执行与脚本化工具的命令行工具Provider 适配器面向 OpenAI Agents、Claude Agent SDK、Vercel AI SDK、LangChain 等框架的工具格式转换层。一句话概括其工作方式为某个用户创建一个会话session把该会话的工具交给你的 AgentAgent 就能跨 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配置项说明默认值apiKeyAPI 密钥读取COMPOSIO_API_KEYbaseURL自定义 API 基础地址生产环境 URLproviderProvider 适配器OpenAIProviderallowTracking是否允许匿名使用统计truedefaultHeaders附加到 API 请求的额外请求头无disableVersionCheck跳过 SDK 版本检查falsedangerouslyAllowAutoUploadDownloadFiles工具执行期间自动上传/下载文件读取本地路径并抓取 schema 中标记为可上传文件的 URLfalsesensitiveFileUploadProtection自动上传与files.upload时用内置敏感路径黑名单如.ssh、.aws、.env及默认 SSH 私钥文件名检查本地路径truefileUploadPathDenySegments追加到内置黑名单的额外敏感路径段无fileUploadDirs自动上传时允许读取本地文件的目录白名单false表示拒绝所有本地路径~/.composio/tempfileDownloadDir工具执行下载文件的写入目录~/.composio/fileshost标识 SDK 运行宿主服务用于遥测无toolkitVersions工具包版本钉扎详见下文版本控制latest对应的环境变量详见 ts/packages/core/README.mdCOMPOSIO_API_KEYAPI 密钥COMPOSIO_BASE_URL自定义 API 基础地址COMPOSIO_LOG_LEVEL日志级别取值silent、error、warn、info、debugCOMPOSIO_TOOLKIT_VERSION_TOOLKIT钉扎单个工具包版本例如COMPOSIO_TOOLKIT_VERSION_GITHUB20250902_00。工具包版本控制toolkitVersions是生产环境的关键配置。它支持三种形态见 ts/packages/core/src/composio.ts#L122-L157省略所有工具包使用latest对象为不同工具包指定不同版本例如{ github: 20250909_00, slack: 20250902_00 }环境变量通过COMPOSIO_TOOLKIT_VERSION_GITHUB20250909_00这类变量单独钉扎。值得注意的约束当通过tools.execute()手动执行工具且版本解析为latest时要么在 execute 参数中设置dangerouslySkipVersionCheck: true不推荐用于生产要么在构造配置或环境变量中指定具体版本。这保证了生产环境工具行为可复现。Python 快速上手安装与最小示例pip install composio composio-openai-agents openai-agentsfrom composio import Composio from composio_openai_agents import OpenAIAgentsProvider from agents import Agent, Runner composio Composio(providerOpenAIAgentsProvider()) # 每个会话只对某一个用户生效 session composio.create(user_iduser_123) tools session.tools() agent Agent( namePersonal Assistant, instructionsYou are a helpful assistant. Use Composio tools to take action., toolstools, ) result Runner.run_sync(starting_agentagent, inputSummarize 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 中定义参数说明默认值environmentAPI 环境productionapi_keyAPI 密钥读取COMPOSIO_API_KEYbase_url自定义 API 基础地址读取COMPOSIO_BASE_URLtimeout请求超时无max_retries最大重试次数客户端默认值allow_tracking是否允许遥测Truefile_download_dir文件下载目录无toolkit_versions工具包版本可为对象、latest或形如20250906_01的统一版本字符串latestdangerously_allow_auto_upload_download_files工具执行期间自动上传/下载文件Falsesensitive_file_upload_protection上传前用内置敏感路径黑名单拦截本地路径Truefile_upload_path_deny_segments追加的敏感路径段无file_upload_dirs自动上传文件目录白名单[~/.composio/temp]file_upload_dirs的语义值得细读见 python/composio/sdk.py#L112-L126None默认仅允许~/.composio/tempFalse拒绝所有本地路径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( slugGITHUB_COMMIT_EVENT, user_iduser_123, trigger_config{owner: composiohq, repo: composio}, ) subscription composio.triggers.subscribe() subscription.handle(trigger_idtrigger.trigger_id) def handle_event(data): print(Event received:, data) subscription.wait_forever()subscribe()通过 WebSocket 流式接收事件适合本地开发生产环境应注册 Webhook URL并用composio.triggers.parse()解析投递内容。Session会话机制按用户隔离的工具上下文create / use / sessionsSession 是本项目 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_iduser_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_iduser_123, mcpTrue) 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 surfacecurl -fsSL https://composio.dev/install | sh安装脚本会把composio加入 PATH对未来的终端生效。安装后请打开新终端再执行composio login。Shell 安装覆盖项包括仅安装不写配置的COMPOSIO_INSTALL_SHELLnone详见 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 给出了完整的支持矩阵ProviderTypeScriptPythonOpenAIcomposio/openaicomposio-openaiOpenAI Agentscomposio/openai-agentscomposio-openai-agentsAnthropiccomposio/anthropiccomposio-anthropicClaude Agent SDKcomposio/claude-agent-sdkcomposio-claude-agent-sdkVercel AI SDKcomposio/vercel—Google GenAIcomposio/googlecomposio-gemini、composio-googleGoogle ADK—composio-google-adkLangChaincomposio/langchaincomposio-langchainLangGraph经由composio/langchaincomposio-langgraphLlamaIndexcomposio/llamaindexcomposio-llamaindexMastracomposio/mastra—Picomposio/experimental*—Cloudflare Workers AIcomposio/cloudflare—CrewAI—composio-crewaiAutoGen—composio-autogen* Pi Provider 为实验性功能随composio/experimental发布。未在列表中的框架有两种出路其一构建自定义 Provider适配器只需实现框架原生工具格式转换其二跳过 Provider 直接走 MCP 端点。Provider 适配器的源码分别位于 ts/packages/providers 与 python/providers 目录下。全量包清单与仓库布局README 列出的所有发布包包说明composio/coreTypeScript SDKcomposio/slim不含打包源码与文档的composio/coreAPI 相同安装更小composioCLI独立 CLI 二进制curl -fsSL https://composio.dev/install \| shcomposio/experimental实验性集成包括 Pi Providercomposio/json-schema-to-zodJSON Schema 到 Zod 的转换composio/*Provider 适配器OpenAI、OpenAI Agents、Anthropic、Claude Agent SDK、Vercel、Google、LangChain、LlamaIndex、Mastra、CloudflarecomposioPython SDKcomposio-*Provider 适配器OpenAI、OpenAI Agents、Anthropic、Claude Agent SDK、Gemini、Google、Google ADK、LangChain、LangGraph、LlamaIndex、CrewAI、AutoGen仓库布局见 README.mdts/ 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 testPython 相关命令在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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考