Composio Python SDK 开发指南:掌握代码布局、核心领域模型与完整开发检查流程

发布时间:2026/9/10 22:19:33

Composio Python SDK 开发指南:掌握代码布局、核心领域模型与完整开发检查流程 Composio Python SDK 开发指南掌握代码布局、核心领域模型与完整开发检查流程【免费下载链接】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 仓库中面向 Python SDK 开发者的技能文档.agents/skills/python-sdk/SKILL.md及其配套布局参考.agents/skills/python-sdk/references/sdk-layout.md系统梳理python/composio的代码结构、核心领域对象tools、toolkits、sessions、auth configs、connected accounts 等、工程约定与开发检查流水线。读完本文你将掌握在 Composio 仓库中开展 Python SDK 实现与扩展工作的完整路径从理解代码布局、定位要改的模块到搭建开发环境、通过格式化 / 静态检查 / 类型检查 / 单测 / 类型推断验证的全套流程并理解其与 TypeScript SDK 保持对等的跨 SDK 一致性要求。一、技能文档定位SDK 开发任务的入口仓库中的.agents/skills/目录为 AI Agent 与开发者提供了按领域划分的技能卡片其中python-sdk技能用于实现或修改 Python SDK 行为。该技能文档明确划定了工作边界涉及范围python/composio下的 tools工具、toolkits工具包、sessions会话、auth configs认证配置、connected accounts连接账户、client 集成以及共享的 Python 模型使用前提面向 Python 核心运行时 / API 工作协作约定当 TypeScript 端需要保持一致时应与python-testingPython 测试和cross-sdk-parity跨 SDK 一致性技能配对使用首要动作在编辑python/composio之前必须先阅读references/sdk-layout.md——这保证了任何改动都建立在对仓库布局与工程约定的统一认知之上而非凭感觉修改。这一先读布局、再动手改的约束是技能文档的核心方法论SDK 是大量领域对象与 provider 适配层的组合体贸然修改很容易破坏类型契约或破坏与生成客户端generated client的衔接。二、Python SDK 代码布局五个关键区域sdk-layout.md将 Python 端划分为五个关键区域是定位任何开发任务的坐标地图区域路径职责核心 SDKpython/composio/SDK 的主实现入口类、领域模型、客户端封装测试python/tests/pytest 覆盖单测、类型推断、schema 语义等Provider 包python/providers/面向各 Agent 框架的适配包OpenAI、Anthropic、LangChain 等脚本python/scripts/发布与维护脚本版本 bump、文档生成、provider 脚手架等配置python/config/Ruff、pytest、mypy 等工具链配置2.1 核心 SDKpython/composio/从目录结构看核心 SDK 由四个部分组成client/HTTP 客户端与类型层。其中 client/types.py 是围绕自动生成的 composio client 类型的一层轻量包装以类型别名形式暴露Tool、ToolkitMinimal、AuthConfig以及AuthSchemeL认证方案字面量如OAUTH1、OAUTH2、API_KEY、BASIC、NO_AUTH、BEARER_TOKEN等并定义了tool_execute_params、tool_execute_response等请求 / 响应参数类型core/models/领域模型层覆盖auth_configs.py、connected_accounts.py、toolkits.py、tools.py、triggers.py、tool_router.py、tool_router_session*.py会话与会话文件、custom_tool*.py自定义工具、mcp.py、webhook_events.py等另有_modifiers.py、_files.py、_telemetry.py等内部支撑模块core/provider/Provider 抽象层定义BaseProvider、Agentic / Non-agentic provider 以及针对 OpenAI 的_openai.py与_openai_responses.py实现utils/工具函数如 JSON Schema 转换、URL 安全校验、敏感文件上传路径保护、日志脱敏redaction、严格 schema 处理等。2.2 SDK 入口Composio类python/composio/sdk.py 是 SDK 的门面。Composio是一个泛型类class Composio(t.Generic[TTool, TToolCollection], WithLogger):泛型参数TTool与TToolCollection由传入的 provider 自动推断不传 provider 时默认使用OpenAIProvider此时类型为Composio[OpenAITool, list[OpenAITool]]传入AnthropicProvider则自动推断为 Anthropic 的工具参数类型。这种设计让类型安全贯穿 provider 适配层composio.tools.get()的返回类型随 provider 变化而自动变化。Composio.__init__还承担了环境探测与各领域对象的装配API Key 解析优先取api_key参数否则读环境变量COMPOSIO_API_KEY两者皆缺则抛出ApiKeyNotProvidedError环境与地址environment默认production、base_url或环境变量COMPOSIO_BASE_URL、timeout、max_retries默认DEFAULT_MAX_RETRIES领域对象装配构造tools、toolkits、triggers、auth_configs、connected_accounts、mcp、experimental以及会话入口self._sessionsToolRouter实例。其中会话SessionsAPI 是推荐的规范入口源码 docstring 中明确说明应使用composio.sessions或快捷方式composio.create/composio.use创建会话而composio.tool_router是自 0.17.0 起标记为 deprecated 的别名python/composio/sdk.py 中使用te.deprecated装饰提示改用sessions。例如session composio.sessions.create(user_iduserexample.com) tools session.tools()2.3 配置项SDKConfigSDKConfig是一个 TypedDict集中定义了Composio()可接收的配置项python/composio/sdk.py配置项默认值说明environmentproduction目标 API 环境api_keyCOMPOSIO_API_KEY认证密钥base_urlCOMPOSIO_BASE_URL自定义 API 地址timeout/max_retries客户端默认请求超时与重试次数allow_trackingTrue是否允许遥测file_download_dir无工具执行结果文件下载目录toolkit_versionslatest工具包版本字典、全局字符串如20250906_01或省略dangerously_allow_auto_upload_download_filesFalse是否开启工具执行期间的自动文件上传 / 下载sensitive_file_upload_protectionTrue上传前是否拦截内置敏感路径黑名单上的本地路径file_upload_path_deny_segments无追加到内置黑名单的路径段名file_upload_dirs[~/.composio/temp]自动上传允许读取的本地目录白名单False表示拒绝所有本地路径URL 与内存字节不受影响传Sequence[str]会替换默认值其中file_upload_dirs的语义值得注意允许条件基于符号链接解析后的绝对路径位于这些目录内且按路径组件边界匹配——/tmp/foo允许/tmp/foo/bar但不允许/tmp/foo-barWindows 下比较不区分大小写。这些文件上传安全参数在Tools与ToolRouter会话两处被一致地透传保证自动上传策略在直接执行与会话执行两条路径上行为一致。2.4 Provider 包python/providers/仓库中每个 provider 对应一个独立包如anthropic、langchain、crewai、gemini、google_adk、openai_agents等它们将session.tools()的产物适配为各框架原生的工具格式。sdk-layout.md对此给出了明确的架构纪律provider 特定行为不得进入核心包除非它是共享抽象的一部分——这正是核心 SDK 保持框架无关、provider 包承担适配的分层原则。2.5 配置与脚本python/config/ruff.toml行宽 88与 Black 一致缩进 4lint 规则集select [E4, E7, E9, F]、忽略E741保持显式的 Pyflakes / pycodestyle 基线python/config/下另有mypy.ini、pytest.ini、vulture_allowlist.py死代码检测的允许清单与codecov.ymlpython/scripts/ 承载发布与维护bump.py版本号 bump、generate-docs.py、create-provider.sh新 provider 脚手架等。三、开发模式与工程约定sdk-layout.md明确了四条贯穿 SDK 开发的模式约束保留 Python 命名约定不引入与现有风格冲突的命名习惯保持代码库可读性与一致性核心不含 provider 特定行为框架适配逻辑收敛在providers/包中除非该行为属于共享抽象的一部分这保护了核心 SDK 的框架无关性优先添加本地类型而非引入易变动的生成客户端内部实现当只需一个小的类型化形状时用本地类型如 client/types.py 中的类型别名替代直接依赖生成客户端内部细节以降低升级生成客户端时的破坏风险。从源码看core/models/tools.py 中的_normalize_tool正是这种防御性设计的体现——它将生成客户端响应规整为 SDK 的工具模型形状并以_toolkit_slug这类函数安全解析不可信的 toolkit 元数据而不假设生成形状检查 TypeScript parity对共享的 SDK 概念tools、toolkits、sessions、auth configs 等必须核对 TypeScript 端的对等实现保证两个 SDK 行为一致。四、开发环境搭建与检查流水线技能文档规定所有开发命令均在python/目录下执行标准流程如下make env source .venv/bin/activate make chk make tst4.1make env创建开发环境从 python/Makefile 的实现看make env基于uv管理环境当未处于虚拟环境时创建 Python 3.12 虚拟环境.venvprompt 为composio执行uv sync、uv sync --dev安装开发依赖随后安装全部 provider 包并以可编辑模式安装 SDKuv pip install -e .若已处于虚拟环境则只做增量同步并提示先deactivate再重建。环境就绪后运行source .venv/bin/activate进入开发环境。4.2make chk静态检查与类型检查chk会话python/noxfile.py安装核心包、dev 依赖组、mypy 及一组类型桩types-requests、types-protobuf、types-jsonschema以及crewai、langchain、langgraph、llama-index、openai-agents、google-cloud-aiplatform等 provider 库后执行ruff check按 config/ruff.toml 检查composio/、providers/、tests/、examples/、scripts/mypy --config-file config/mypy.ini对composio/、providers/、tests/、scripts/逐模块类型检查。noxfile 注释解释了类型桩不能放入锁定的 dev 依赖组的原因provider 库crewai、langchain、llama-index 等会向根解析拖入冲突的传递依赖因此这些库仅作为 mypy 的 import 解析目标按需安装。4.3make tst单元测试tst会话安装核心包、dev 组及 crewai / langchain / langgraph 三个 provider 后运行pytest默认测试路径为tests/可用位置参数覆盖输出详细报告-v --tbshort。测试仓库覆盖了极为细致的领域schema 转换与语义回归test_schema_converter.py、test_schema_semantic_regressions.py、严格 schematest_strict_schema*.py、类型推断test_type_inference*.py、文件上传安全test_sensitive_file_upload_paths.py、test_upload_dir_allowlist.py、URL 安全test_url_safety*.py、路径拼接护栏test_path_join_guardrail.py、日志脱敏test_logging_redaction.py等从测试即可反推 SDK 在安全与类型正确性上的关注点。4.4 其他开发检查make fmt运行nox -s fmt执行 ruff 的 import 排序修复--select I --fix与ruff formatmake snt即sanity快速冒烟测试默认跑tests/test_imports.py与tests/test_sdk.py验证导入与 SDK 初始化make type_inference安装全部provider 包后用 mypy 校验Composio.tools.get()基于overload签名对各 provider 返回类型的推断是否正确——这是跨 provider 类型安全的关键验证独立于chk会话后者不安装全部 provider 因而无法解析 provider 类型make dead-code运行 vulture最低置信度 80%排除build/、dist/、.venv/、.nox/、__pycache__/仅报告疑似死代码不阻断会话确认为误报的符号应加入 python/config/vulture_allowlist.py另有tst_autogen会话在 protobuf 兼容环境中单独验证 autogen provider 的skip_defaults签名行为体现provider 间依赖冲突需隔离测试的思路友好别名make formatfmt、make checkchk、make sanitysnt、make testtst。五、从技能到实践一次典型的 SDK 开发任务综合技能文档、布局参考与源码一次典型的 Python SDK 开发任务可以按以下路径推进定位根据改动目标确定落点——工具 / 工具包逻辑在 python/composio/core/models/tools.py 与toolkits.py会话相关在tool_router*.py系列认证在auth_configs.py/connected_accounts.py客户端类型在 python/composio/client/types.py入口装配在 python/composio/sdk.py环境在python/下执行make env并激活.venv实现遵守命名约定与核心不含 provider 特定行为的纪律优先使用本地类型而非生成客户端内部细节对共享 SDK 概念同步核对 TypeScript 端实现保持 cross-SDK parity验证make fmt→make chk→make tst涉及工具类型推断时补跑make type_inference仅需快速确认时用make snt如需冒烟级别回归测试覆盖可参考 python/tests/ 中对应领域的用例如test_tool_router.py、test_auth_configs.py、test_connected_accounts.py发布涉及版本变更时通过 python/scripts/bump.py对应make bump与make build完成打包。六、总结Composio 的 Python SDK 技能文档为 SDK 开发定义了一条清晰、可复现的工程路径以 SKILL.md 划定任务边界以 references/sdk-layout.md 建立布局与约定共识再以make env/make chk/make tst形成环境搭建—静态与类型检查—单元测试的完整质量闭环。配合 noxfile 中隔离依赖冲突的会话设计tst_autogen、type_inference与 vulture 死代码巡检这套流水线在保证核心 SDK 框架无关性、跨 provider 类型安全与跨 SDK 一致性的同时也让新贡献者能够快速、安全地介入 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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/9/10 22:19:33

CANN/ge 离线编译API文档

OfflineCompile 【免费下载链接】ge GE(Graph Engine)是面向昇腾的图编译器和执行器,提供了计算图优化、多流并行、内存复用和模型下沉等技术手段,加速模型执行效率,减少模型内存占用。 GE 提供对 PyTorch、TensorFlow…

2026/9/10 23:09:39

金额转人民币大写全攻略:中文数字规则与边界条件实现解析

1. 从“最简单功能”到“最稳函数”:大写金额转换为什么这么容易翻车做财务系统、ERP、报销模块、电子发票,甚至简单的记账工具,几乎都会碰到同一个需求:把阿拉伯数字金额转成人民币大写。就是那种“壹佰贰拾叁元肆角伍分”的输出。乍一看太简…

2026/9/10 23:09:39

大数据环境下的数据质量保障与安全实践

1. 大数据时代的数据质量挑战与安全困局当企业数据量从GB级跃迁到PB甚至EB级别时,数据质量问题就像隐藏在深海中的冰山逐渐浮出水面。某电商平台曾因商品分类标签错误率超过15%,导致大促期间推荐系统准确率下降40%,直接损失超亿元。这个真实案…

2026/9/10 23:09:39

专科生必备:8款AI降干扰率工具实测与指南

1. 项目概述:专科生如何应对AI时代的挑战 2026届专科生正面临一个前所未有的技术变革时代。作为从业多年的职业教育观察者,我注意到AI技术已深度渗透到各行各业的工作场景中。对于专科生群体而言,掌握降低AI干扰率的实用工具,将成…

2026/9/10 16:39:38

超人会飞不算本事:系统稳定依赖清晰规则与边界设计

开头先不绕弯子。“#斯坦李吐槽dc 所以超人是无缘无故会飞的嘛哈哈哈哈哈哈哈锤哥真是技术人才啊!#雷神 #复联”这类调侃式短标题,第一波冲击力在于它把两个宇宙的角色塞进同一个吐槽箱里,但细想一下就能发现,它真正碰到的根本不是…

2026/9/10 11:16:38

超人VS蜘蛛侠:拆解超级IP的影响力与传播方法论

把“蜘蛛侠 vs 超人”放在 CSDN 上聊,可能很多人第一反应是走错片场了。但如果把这两个角色看成“两个持续运营了 80 多年的文化产品”,你会发现,这场比较本质上是两个不同 IP 策略的长期结果对比:超人赢在定义了整个超级英雄题材…

2026/9/9 16:31:09

基于CNN的调制信号识别:MATLAB实现时频图分类实战

简介:本资源是一套面向通信工程与信号处理方向学习者、研究者的深度学习实践方案,聚焦调制信号自动检测与识别这一典型无线通信任务,解决传统方法依赖人工特征、低信噪比下性能下降等痛点。压缩包共12个文件(10.73MB)&…

2026/9/10 0:00:55

目录对比去重实战:用哈希算法精准清理重复文件

我电脑里现在还有一块换了三次机的“数据墓地”硬盘,里面存着2016年以前所有旧笔记本的完整备份。平时不觉得有什么,直到前阵子想把它整理归档,发现同一个安装包、同一批照片、同一份论文草稿,在几个不同的备份目录里反复出现。更…

2026/9/10 0:00:55

Leaflet离线地图完整Demo合集:内网部署与坐标纠偏实战

简介:这是一份面向Web GIS开发者的LeafLet离线地图示例合集,帮助开发者快速掌握离线地图从搭建到交互的完整流程。压缩包共723个文件,大小14.06MB,以319个js脚本、175个html页面和29个css样式文件为主体,配合png/svg图…

2026/9/10 0:00:55

MATLAB读取Rinex 3.02观测文件:多系统GNSS数据解析实战

简介:基于MATLAB开发的Rinex3.02版观测文件(o文件)读取代码包,面向卫星定位导航方向的学习者与研究人员,用于解决新版观测文件的数据解析、历元提取与时间转换问题。压缩包共4个文件,包含两个m脚本、一个19…

2026/9/10 12:32:02

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/10 15:19:50

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/10 15:49:53

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码