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），仅供参考