crewAI ComposioTool 完全指南让 AI Agent 通过 Composio 调用海量第三方 SaaS 工具【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI本文基于 crewAI 仓库中 composio_tool/README.md 及其配套实现 composio_tool.py 编写完整覆盖ComposioTool的安装认证、三种初始化方式from_action、from_apptags/use_case、Agent 与 Task 的实战示例并深入源码剖析工具封装、账号连接校验与参数 Schema 生成的底层机制帮助你将 Composio 生态中的 SaaS 工具如 GitHub、Gmail 等无缝接入 crewAI Agent。什么是 ComposioToolComposioTool是 crewAI 对 Composio 工具集toolset的封装层使 Agent 能够访问 Composio SDK 提供的各类第三方工具。从源码注释可以看到它的类文档字符串非常简洁Wrapper for composio tools.位于 composio_tool.py。其定位可以概括为三点桥接角色把 Composio 的Action一次可执行的第三方 API 操作包装成 crewAI 的BaseTool让 LLM 能够以标准函数调用的方式触发Schema 自动转换从 Composio 拉取 Action 的 JSON Schema并转成 Pydantic 模型作为工具的args_schema使工具参数可被 LLM 正确填充和校验认证前置校验在工具创建阶段就检查目标应用是否已有已连接账号connected account避免运行期才暴露认证问题。ComposioTool在包内通过 crewai_tools/init.py 与 tools/init.py 两处导出因此既可以用from crewai_tools import ComposioTool也可以从crewai_tools.tools子包导入。安装与认证按照原文档说明安装需要两个依赖pip install composio-core pip install crewai[tools]其中composio-core的最低版本约束可以在 pyproject.toml 中确认composio-core [ composio-core0.6.11.post1, ]也就是说crewai[tools]的composio-core可选依赖实际对应的是pip install crewai-tools[composio-core]这一依赖组版本下限为0.6.11.post1。安装完成后认证有两种方式原文档原文运行composio login完成交互式登录或者将 Composio API Key 导出为环境变量COMPOSIO_API_KEY。从源码看COMPOSIO_API_KEY不是一个建议配置而是被显式声明为必填环境变量ComposioTool的env_vars字段默认值中注册了EnvVar(nameCOMPOSIO_API_KEY, descriptionAPI key for Composio services, requiredTrue)见 composio_tool.py。crewAI 的BaseTool基类base_tool.py中定义了EnvVar模型name/description/required/default四个字段以及env_vars字段Agent 运行时可以据此提示用户补齐缺失的环境变量。三种工具初始化方式方式一from_action—— 精确指定单个 Action当你确切知道要用哪个 Action 时直接传入枚举from composio import Action from crewai_tools import ComposioTool from crewai import Agent, Task tools [ComposioTool.from_action(actionAction.GITHUB_ACTIVITY_STAR_REPO_FOR_AUTHENTICATED_USER)]注意返回值是一个单工具实例示例中用列表包裹是因为Agent(tools...)接收列表。方式二from_apptags—— 按标签筛选不确定具体 Action 名时可以按应用加标签过滤from composio import App from crewai_tools import ComposioTool tools ComposioTool.from_app(App.GITHUB, tags[important])方式三from_appuse_case—— 按自然语言用例检索最贴近 LLM 使用习惯的方式用一句自然语言描述需求来检索相关 Actiontools ComposioTool.from_app(App.GITHUB, use_caseStar a github repository)从源码实现看composio_tool.pyfrom_app有严格的前置校验校验规则触发异常未提供任何 applen(apps) 0ValueError(You need to provide at least one app name)use_case与tags同时为NoneValueError(Both use_case and tags cannot be None)use_case与tags同时提供ValueError(Cannot use both use_case and tags to filter the actions)检索路径也不同use_case走toolset.find_actions_by_use_case(*apps, use_caseuse_case)tags走toolset.find_actions_by_tags(*apps, tagstags)两者最终都会对每个命中的 Action 递归调用cls.from_action(actionaction, **kwargs)因此from_app的返回值是list[ComposioTool]可直接赋给Agent的tools参数。完整实战示例让 Agent Star 一个 GitHub 仓库以下示例完整继承自原文档演示了初始化工具 → 定义 Agent → 执行 Task的全流程初始化工具集见上一节三种方式任选其一定义 Agentcrewai_agent Agent( roleGithub Agent, goalYou take action on Github using Github APIs, backstory( You are AI agent that is responsible for taking actions on Github on users behalf. You need to take action on Github using Github APIs ), verboseTrue, toolstools, )执行 Tasktask Task( descriptionStar a repo ComposioHQ/composio on GitHub, agentcrewai_agent, expected_outputif the star happened, ) task.execute()Composio 侧更完整的工具目录可以在其官方工具目录中查阅原文档指向 Composio 工具目录页此处不重复外链。源码剖析from_action如何把一个 Action 变成 crewAI 工具from_actioncomposio_tool.py是整个封装的核心执行链路可以拆成六步构建 ToolSet实例化ComposioToolSet()并容忍传入字符串——如果action不是Action实例会自动执行Action(action)转换账号连接校验调用_check_connected_accountcomposio_tool.py。若该 Action 标记了no_auth则直接放行否则拉取toolset.client.connected_accounts.get()检查tool.app是否出现在已连接账号的appUniqueId列表中未命中则抛出RuntimeError( fNo connected account found for app {tool.app}; fRun composio add {tool.app} to fix this )也就是说报错信息本身就给出了修复命令composio add app拉取 Schematoolset.get_action_schemas(actions[action])拿到该 Action 的参数 Schema并model_dump(exclude_noneTrue)序列化为字典构造执行闭包内部定义的function(**kwargs)调用toolset.execute_action(actionAction(schema[name]), paramskwargs, entity_identity_id)。注意entity_id从kwargs中弹出kwargs.pop(entity_id, DEFAULT_ENTITY_ID)默认取 Composio 的DEFAULT_ENTITY_ID常量因此调用方仍可通过ComposioTool.from_action(action..., entity_idyour-entity)指定自定义实体注入元信息将闭包的__name__与__doc__分别设置为 Schema 中的name与description保证日志与提示词中能显示真实工具名实例化ComposioToolname、description取自 Schemaargs_schema通过json_schema_to_model(action_schema.parameters.model_dump(exclude_noneTrue))将 JSON Schema 转成 Pydantic 模型——这就是 LLM 得以看懂工具参数、并让 crewAI 框架在调用前完成参数校验的关键一步。运行时行为_run只做纯委托ComposioTool的运行时逻辑极为薄composio_tool.pydef _run(self, *args: t.Any, **kwargs: t.Any) - t.Any: Run the composio action with given arguments. return self.composio_action(*args, **kwargs)它只是把参数原样透传给from_action阶段构造的闭包最终落到ComposioToolSet.execute_action。从源码结构看这意味着所有认证、重试、网络请求细节都留在 Composio SDK 内部crewAI 侧只负责Schema 描述 执行委托。与BaseTool的关系ComposioTool继承自 base_tool.py 中的BaseTool。BaseTool通过 Pydantic 约束了name、description、env_vars、args_schema、result_schema等字段并提供工具类型注册__init_subclass__中写入_TOOL_TYPE_REGISTRY。因此ComposioTool无需自己实现任何序列化与注册逻辑只需提供composio_action字段与_run方法即可获得完整的 crewAI 工具行为可被 Agent 调用、可随 Crew 序列化、环境变量会被统一检查。关键行为速查项说明依据from_action(action...)返回单个ComposioTool实例支持传字符串自动转Actioncomposio_tool.pyfrom_app(*apps, tags...)/from_app(*apps, use_case...)返回list[ComposioTool]tags与use_case必须且只能提供其一同上 L96-L127entity_id可作为from_action的 keyword 参数透传默认DEFAULT_ENTITY_ID同上 L71必填环境变量COMPOSIO_API_KEYrequiredTrue同上 L14-L22未连接账号时报错RuntimeError提示执行composio add app同上 L28-L46依赖版本composio-core0.6.11.post1pyproject.toml常见问题与排查思路RuntimeError: No connected account found for app ...说明该应用如 GitHub在 Composio 侧还没有已授权账号。按报错提示执行composio add app完成连接后重试这是创建工具时抛出的属于 fail-fast 设计便于尽早发现认证缺失。ValueError: Both use_case and tags cannot be None调用from_app时忘了提供筛选条件二选一地补上tags或use_case即可。工具参数 LLM 填错检查args_schema是否正确生成——它直接来自toolset.get_action_schemas的返回如果 Composio 侧 Schema 变更可重新拉取确认字段名与类型。认证方式选择无头/CI 环境建议使用COMPOSIO_API_KEY环境变量这也是env_vars声明的必填项本地开发可以用composio login交互式登录。延伸阅读官方文档站中的 Composio Tool 页面 介绍了基于composio-crewaiProvider 与ComposioSession 的较新接入路径session.tools()、手动authorize等与本文 README 描述的composio-coreSDK 路径并存可按项目实际选用的 SDK 版本参考工具基类实现base_tool.py其中EnvVarL96-L100与BaseToolL103 起定义了本文涉及的全部字段契约本模块源码与文档原文composio_tool.py、README.md。【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
crewAI ComposioTool 完全指南：让 AI Agent 通过 Composio 调用海量第三方 SaaS 工具
crewAI ComposioTool 完全指南让 AI Agent 通过 Composio 调用海量第三方 SaaS 工具【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI本文基于 crewAI 仓库中 composio_tool/README.md 及其配套实现 composio_tool.py 编写完整覆盖ComposioTool的安装认证、三种初始化方式from_action、from_apptags/use_case、Agent 与 Task 的实战示例并深入源码剖析工具封装、账号连接校验与参数 Schema 生成的底层机制帮助你将 Composio 生态中的 SaaS 工具如 GitHub、Gmail 等无缝接入 crewAI Agent。什么是 ComposioToolComposioTool是 crewAI 对 Composio 工具集toolset的封装层使 Agent 能够访问 Composio SDK 提供的各类第三方工具。从源码注释可以看到它的类文档字符串非常简洁Wrapper for composio tools.位于 composio_tool.py。其定位可以概括为三点桥接角色把 Composio 的Action一次可执行的第三方 API 操作包装成 crewAI 的BaseTool让 LLM 能够以标准函数调用的方式触发Schema 自动转换从 Composio 拉取 Action 的 JSON Schema并转成 Pydantic 模型作为工具的args_schema使工具参数可被 LLM 正确填充和校验认证前置校验在工具创建阶段就检查目标应用是否已有已连接账号connected account避免运行期才暴露认证问题。ComposioTool在包内通过 crewai_tools/init.py 与 tools/init.py 两处导出因此既可以用from crewai_tools import ComposioTool也可以从crewai_tools.tools子包导入。安装与认证按照原文档说明安装需要两个依赖pip install composio-core pip install crewai[tools]其中composio-core的最低版本约束可以在 pyproject.toml 中确认composio-core [ composio-core0.6.11.post1, ]也就是说crewai[tools]的composio-core可选依赖实际对应的是pip install crewai-tools[composio-core]这一依赖组版本下限为0.6.11.post1。安装完成后认证有两种方式原文档原文运行composio login完成交互式登录或者将 Composio API Key 导出为环境变量COMPOSIO_API_KEY。从源码看COMPOSIO_API_KEY不是一个建议配置而是被显式声明为必填环境变量ComposioTool的env_vars字段默认值中注册了EnvVar(nameCOMPOSIO_API_KEY, descriptionAPI key for Composio services, requiredTrue)见 composio_tool.py。crewAI 的BaseTool基类base_tool.py中定义了EnvVar模型name/description/required/default四个字段以及env_vars字段Agent 运行时可以据此提示用户补齐缺失的环境变量。三种工具初始化方式方式一from_action—— 精确指定单个 Action当你确切知道要用哪个 Action 时直接传入枚举from composio import Action from crewai_tools import ComposioTool from crewai import Agent, Task tools [ComposioTool.from_action(actionAction.GITHUB_ACTIVITY_STAR_REPO_FOR_AUTHENTICATED_USER)]注意返回值是一个单工具实例示例中用列表包裹是因为Agent(tools...)接收列表。方式二from_apptags—— 按标签筛选不确定具体 Action 名时可以按应用加标签过滤from composio import App from crewai_tools import ComposioTool tools ComposioTool.from_app(App.GITHUB, tags[important])方式三from_appuse_case—— 按自然语言用例检索最贴近 LLM 使用习惯的方式用一句自然语言描述需求来检索相关 Actiontools ComposioTool.from_app(App.GITHUB, use_caseStar a github repository)从源码实现看composio_tool.pyfrom_app有严格的前置校验校验规则触发异常未提供任何 applen(apps) 0ValueError(You need to provide at least one app name)use_case与tags同时为NoneValueError(Both use_case and tags cannot be None)use_case与tags同时提供ValueError(Cannot use both use_case and tags to filter the actions)检索路径也不同use_case走toolset.find_actions_by_use_case(*apps, use_caseuse_case)tags走toolset.find_actions_by_tags(*apps, tagstags)两者最终都会对每个命中的 Action 递归调用cls.from_action(actionaction, **kwargs)因此from_app的返回值是list[ComposioTool]可直接赋给Agent的tools参数。完整实战示例让 Agent Star 一个 GitHub 仓库以下示例完整继承自原文档演示了初始化工具 → 定义 Agent → 执行 Task的全流程初始化工具集见上一节三种方式任选其一定义 Agentcrewai_agent Agent( roleGithub Agent, goalYou take action on Github using Github APIs, backstory( You are AI agent that is responsible for taking actions on Github on users behalf. You need to take action on Github using Github APIs ), verboseTrue, toolstools, )执行 Tasktask Task( descriptionStar a repo ComposioHQ/composio on GitHub, agentcrewai_agent, expected_outputif the star happened, ) task.execute()Composio 侧更完整的工具目录可以在其官方工具目录中查阅原文档指向 Composio 工具目录页此处不重复外链。源码剖析from_action如何把一个 Action 变成 crewAI 工具from_actioncomposio_tool.py是整个封装的核心执行链路可以拆成六步构建 ToolSet实例化ComposioToolSet()并容忍传入字符串——如果action不是Action实例会自动执行Action(action)转换账号连接校验调用_check_connected_accountcomposio_tool.py。若该 Action 标记了no_auth则直接放行否则拉取toolset.client.connected_accounts.get()检查tool.app是否出现在已连接账号的appUniqueId列表中未命中则抛出RuntimeError( fNo connected account found for app {tool.app}; fRun composio add {tool.app} to fix this )也就是说报错信息本身就给出了修复命令composio add app拉取 Schematoolset.get_action_schemas(actions[action])拿到该 Action 的参数 Schema并model_dump(exclude_noneTrue)序列化为字典构造执行闭包内部定义的function(**kwargs)调用toolset.execute_action(actionAction(schema[name]), paramskwargs, entity_identity_id)。注意entity_id从kwargs中弹出kwargs.pop(entity_id, DEFAULT_ENTITY_ID)默认取 Composio 的DEFAULT_ENTITY_ID常量因此调用方仍可通过ComposioTool.from_action(action..., entity_idyour-entity)指定自定义实体注入元信息将闭包的__name__与__doc__分别设置为 Schema 中的name与description保证日志与提示词中能显示真实工具名实例化ComposioToolname、description取自 Schemaargs_schema通过json_schema_to_model(action_schema.parameters.model_dump(exclude_noneTrue))将 JSON Schema 转成 Pydantic 模型——这就是 LLM 得以看懂工具参数、并让 crewAI 框架在调用前完成参数校验的关键一步。运行时行为_run只做纯委托ComposioTool的运行时逻辑极为薄composio_tool.pydef _run(self, *args: t.Any, **kwargs: t.Any) - t.Any: Run the composio action with given arguments. return self.composio_action(*args, **kwargs)它只是把参数原样透传给from_action阶段构造的闭包最终落到ComposioToolSet.execute_action。从源码结构看这意味着所有认证、重试、网络请求细节都留在 Composio SDK 内部crewAI 侧只负责Schema 描述 执行委托。与BaseTool的关系ComposioTool继承自 base_tool.py 中的BaseTool。BaseTool通过 Pydantic 约束了name、description、env_vars、args_schema、result_schema等字段并提供工具类型注册__init_subclass__中写入_TOOL_TYPE_REGISTRY。因此ComposioTool无需自己实现任何序列化与注册逻辑只需提供composio_action字段与_run方法即可获得完整的 crewAI 工具行为可被 Agent 调用、可随 Crew 序列化、环境变量会被统一检查。关键行为速查项说明依据from_action(action...)返回单个ComposioTool实例支持传字符串自动转Actioncomposio_tool.pyfrom_app(*apps, tags...)/from_app(*apps, use_case...)返回list[ComposioTool]tags与use_case必须且只能提供其一同上 L96-L127entity_id可作为from_action的 keyword 参数透传默认DEFAULT_ENTITY_ID同上 L71必填环境变量COMPOSIO_API_KEYrequiredTrue同上 L14-L22未连接账号时报错RuntimeError提示执行composio add app同上 L28-L46依赖版本composio-core0.6.11.post1pyproject.toml常见问题与排查思路RuntimeError: No connected account found for app ...说明该应用如 GitHub在 Composio 侧还没有已授权账号。按报错提示执行composio add app完成连接后重试这是创建工具时抛出的属于 fail-fast 设计便于尽早发现认证缺失。ValueError: Both use_case and tags cannot be None调用from_app时忘了提供筛选条件二选一地补上tags或use_case即可。工具参数 LLM 填错检查args_schema是否正确生成——它直接来自toolset.get_action_schemas的返回如果 Composio 侧 Schema 变更可重新拉取确认字段名与类型。认证方式选择无头/CI 环境建议使用COMPOSIO_API_KEY环境变量这也是env_vars声明的必填项本地开发可以用composio login交互式登录。延伸阅读官方文档站中的 Composio Tool 页面 介绍了基于composio-crewaiProvider 与ComposioSession 的较新接入路径session.tools()、手动authorize等与本文 README 描述的composio-coreSDK 路径并存可按项目实际选用的 SDK 版本参考工具基类实现base_tool.py其中EnvVarL96-L100与BaseToolL103 起定义了本文涉及的全部字段契约本模块源码与文档原文composio_tool.py、README.md。【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考