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/composioComposio 的 Python 示例仓库python/examples是理解官方 SDK 各核心 API 的最直接入口。本文以 python/examples/README.md 为主线系统讲解如何运行这些示例、如何通过一次性配置脚本准备认证资源并逐一对工具执行、认证配置、连接账户、触发器、MCP 与工具路由器等示例做源码级拆解。读完本文你将掌握 Composio Python SDK 的典型调用模式以及如何在自己的项目中搭建可重复、可清理的示例运行环境。示例目录概览示例脚本大部分直接位于python/examples/目录下按功能覆盖 SDK 的几大核心能力脚本主题tools.py工具查询按 toolkit / 搜索与直接执行、代理调用proxytoolkits.py工具包toolkit列举、分类、按 slug 查询与授权auth_configs.py认证配置managed / custom auth的增删改查connected_accounts.py连接账户的发起、等待授权、启停与删除triggers.py触发器列举、创建、订阅与 Webhook 验签mcp_example.py通过 MCP 将 Composio 工具接入 LangChain Agentmodifiers.py工具执行前后、文件上传与 schema 的修饰器机制fastapi_app.py用 FastAPI 暴露 OAuth 授权跳转端点custom_tools_agent_test.py、experimental_tool_router_example.py、experimental_tool_router_advanced_example.py自定义工具与实验性工具路由器用法工具路由器Tool Router相关脚本则集中放在python/examples/tool_router/子目录中包括 tools.py、preload.py、claude_agent.py、crewai_agent.py、langchain_agent.py、openai_agents.py、tool_router_mcp.py、session_update.py、authorize.py、files.py 等。运行单个示例标准运行流程仓库使用uv管理 Python 工作区README 给出的标准三步流程如下cd python uv sync out$(node ../scripts/examples-provision.mjs) eval $out uv run python examples/tools.pyuv sync同步工作区虚拟环境安装python/composio及所有 provider 依赖node ../scripts/examples-provision.mjs对 Composio 项目做一次性供给检查provisioning check在 stdout 打印一批export COMPOSIO_EXAMPLES_*...环境变量eval $out把它们加载进当前 shelluv run python examples/file.py在虚拟环境中直接运行脚本无需先激活环境。uv run对子目录同样适用例如uv run python examples/tool_router/tools.py。两种 eval 写法为何不同README 特别强调必须先捕获再 evalout$(...) eval $out不要写成eval $(...)。原因在于eval的退出状态反映的是被求值文本的执行结果而不是供给脚本本身的结果——如果供给运行失败eval $(...)仍会看起来成功从而掩盖失败。先捕获到变量、再 eval供给脚本的退出码非零即失败会被正确传递。供给脚本的核心逻辑见 scripts/examples-provision.mjs它会依次调用GET /api/v3.1/auth_configs与GET /api/v3.1/connected_accounts按用户过滤将报告打印到 stderr将可 eval 的export行打印到 stdout。该脚本是幂等的——已有资源会被验证通过只有缺失的资源才会被创建且永远不会打印任何凭据值。供给脚本依赖的环境变量供给脚本本身需要两个输入见 scripts/examples-provision.mjsCOMPOSIO_API_KEY——必需缺失时脚本直接报错退出COMPOSIO_EXAMPLES_USER_ID——可选默认值为examples。后端地址通过COMPOSIO_BASE_URL选择默认指向 staging 环境解析逻辑在 harness/backend-url.mjs。需要人工参与的 OAuth 授权示例所依赖的 OAuth 类工具包gmail、googledrive、github、slack需要一次性浏览器授权。当某工具包尚无活跃连接时可加--initiate-missing让供给脚本代为发起连接请求node ../scripts/examples-provision.mjs --initiate-missing脚本会为每个缺失连接调用POST /api/v3.1/connected_accounts并把授权 URL 打印出来只需在浏览器中访问一次即可。serpapi 属于 API-Key 认证供给脚本会自动创建其认证配置无需浏览器步骤。供给脚本会为 OAuth 工具包创建名为examples-slug的use_composio_managed_auth认证配置为 serpapi 创建use_custom_auth/API_KEY方案配置演示键值为刻意伪造的占位符examples-demo-key见 scripts/examples-provision.mjs并非真实密钥。示例的环境变量约定示例脚本统一从环境变量读取配置缺失时抛出KeyError并指明缺失变量名。完整约定如下环境变量用途何时必需COMPOSIO_API_KEYComposio API 密钥总是必需COMPOSIO_EXAMPLES_USER_ID示例所代表的用户 id需要以用户身份操作时COMPOSIO_EXAMPLES_{GMAIL,GITHUB,SLACK}_AUTH_CONFIG_ID各工具包的认证配置 id使用对应工具包时COMPOSIO_EXAMPLES_{GMAIL,GITHUB,SLACK}_CONNECTED_ACCOUNT_ID各工具包的常驻连接账户 id直接调用连接时COMPOSIO_EXAMPLES_APIKEY_AUTH_CONFIG_IDserpapi 的 API-Key 认证配置 id演示 API-Key 连接时COMPOSIO_EXAMPLES_APIKEY_PLACEHOLDERserpapi 的占位键值同上OPENAI_API_KEY/ANTHROPIC_API_KEYLLM 提供方密钥仅调用对应 LLM 的示例需要例如 tools.py 通过os.environ[COMPOSIO_EXAMPLES_GITHUB_CONNECTED_ACCOUNT_ID]读取 GitHub 连接账户 idconnected_accounts.py 读取 Gmail 认证配置 id 与用户 idfastapi_app.py 在启动时校验两个必需变量并提前调用composio.auth_configs.get(...)做快速失败避免带着失效的认证配置对外服务。供给脚本的清理模式--gc示例运行会在项目中遗留资源可用--gc清理node ../scripts/examples-provision.mjs --gc --dry-run # 先预览 node ../scripts/examples-provision.mjs --gc # 真正删除--gc会删除三类由示例创建的资源从未达到ACTIVE状态的连接账户OAuth 发起后未完成授权的死连接多余的 serpapi 演示账户保留每个工具包最新一个活跃账户之前运行遗留的 MCP 配置——MCP 配置统一命名为examples-label-unix-seconds格式如examples-lc-slack-1754923456脚本用正则^examples-[a-z0-9-]-\d{10}$精确匹配见 scripts/examples-provision.mjs既靠examples-前缀证明是示例创建又靠 10 位秒级时间戳避免误伤手工创建的examples-scratch之类配置API 对 MCP 名称有 30 字符上限所以标签必须保持简短。清理有几道安全防线只删除 24 小时前创建的资源避免误删并发运行中的资源、只触碰示例自己创建的资源连接账户必须绑定到examples-slug认证配置任何项目自有的 gmail 配置都不会被误认为示例所有、created_at缺失或不可解析时按不够旧处理fail closed。脚本文件头注释明确警告这是破坏性操作应先在专用的一次性示例项目上配合--dry-run预览。工具与工具包示例工具查询与直接执行tools.py 演示了工具发现与执行的核心调用from composio import Composio composio Composio() # 按工具包获取全部工具 tools composio.tools.get(user_iddefault, toolkits[GITHUB]) # 按关键字搜索工具 tools composio.tools.get(user_iddefault, searchuser) # 组合工具包 搜索 tools composio.tools.get(user_iddefault, toolkits[GITHUB], searchstar) # 直接执行工具 response composio.tools.execute( user_iddefault, slugHACKERNEWS_GET_USER, arguments{username: pg}, version20251023_00, ) print(response)其中composio.tools.execute是同步直接执行传入工具 slug、参数与可选的version工具版本号示例中为20251023_00。工具支持按工具包、按搜索词、或两者组合三种方式获取user_id决定工具以哪个用户的上下文执行。代理调用Proxy同一文件中还演示了composio.tools.proxy——直接向第三方 API 发起代理请求并借用已连接的账户身份proxy_response composio.tools.proxy( endpoint/repos/composiohq/composio/issues/1, methodGET, connected_account_idgithub_connected_account_id, # 借用 GitHub 连接 parameters[ {name: Accept, value: application/vnd.github.v3json, type: header}, ], ) print(proxy_response)这里connected_account_id来自环境变量COMPOSIO_EXAMPLES_GITHUB_CONNECTED_ACCOUNT_ID代理调用会把请求以该账户的 GitHub 身份发出parameters可附加自定义请求头。工具包查询与授权toolkits.py 展示工具包 APItoolkits composio.toolkits.get() # 列出全部工具包 toolkit composio.toolkits.get(sluggithub) # 按 slug 查询 categories composio.toolkits.list_categories() # 列出工具包分类 connection_request composio.toolkits.authorize(user_id123, toolkitgithub)composio.toolkits.authorize是面向用户发起授权的一行式封装返回的连接请求对象可进一步用于获取授权 URL 或等待连接建立。认证配置示例auth_configs.pyauth_configs.py 覆盖认证配置的完整生命周期包括 Composio 托管认证managed auth与自定义认证custom auth两种模式from composio import Composio composio Composio() # 列出全部认证配置 auth_configs composio.auth_configs.list() # 托管认证由 Composio 代为管理凭据 auth_config composio.auth_configs.create( toolkitgithub, options{type: use_composio_managed_auth}, ) # 自定义认证自带 OAuth2 应用凭据 auth_config composio.auth_configs.create( toolkitnotion, options{ name: Notion Auth, type: use_custom_auth, auth_scheme: OAUTH2, credentials: { client_id: 1234567890, client_secret: 1234567890, oauth_redirect_uri: https://backend.composio.dev/api/v1/auth-apps/add, }, }, ) # 创建前查询必填字段 required_fields composio.toolkits.get_auth_config_creation_fields( toolkitNOTION, auth_schemeOAUTH2, ) # 按 id 获取 auth_config_retrieved composio.auth_configs.get(auth_config.id) # 从工具包元数据读取认证输入字段 toolkit composio.toolkits.get(slugnotion) required_input_fields [ field.name for field in toolkit.auth_config_details or [] if field.mode ] # 更新认证配置可修改凭据与工具访问策略 auth_config_updated composio.auth_configs.update( auth_config.id, options{ type: custom, credentials: {client_id: 1234567890, client_secret: 1234567890}, tool_access_config: { tools_for_connected_account_creation: [NOTION_ADD_PAGE_CONTENT], }, }, ) # 启用 / 禁用 / 删除 composio.auth_configs.enable(auth_config.id) composio.auth_configs.disable(auth_config.id) composio.auth_configs.delete(auth_config.id)几点值得注意的细节auth_scheme在 Python 端以小写 snake_case 传递OAUTH2、API_KEY供给脚本调用 API 时则以authScheme形式出现见 scripts/examples-provision.mjstool_access_config.tools_for_connected_account_creation可限定哪些工具允许在创建连接账户时使用用于按需暴露工具面示例中的client_id/client_secret均为演示占位值实际使用需替换为真实应用凭据。连接账户示例connected_accounts.pyconnected_accounts.py 演示连接的创建与全生命周期管理区分OAuth 连接与API-Key 连接两种路径from composio import Composio from composio.types import auth_scheme composio Composio() gmail_auth_config_id os.environ[COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID] user_id os.environ[COMPOSIO_EXAMPLES_USER_ID] # 列出全部连接 connected_accounts composio.connected_accounts.list() # OAuth 连接发起请求 - 用户浏览器授权 - 等待激活 connection_request composio.connected_accounts.initiate( user_iduser_id, auth_config_idgmail_auth_config_id, allow_multipleTrue, # 允许同一认证配置下存在多个连接 ) print(fVisit this URL to authorize: {connection_request.redirect_url}) connected_account connection_request.wait_for_connection() print(fConnected account {connected_account.id} is {connected_account.status}) # API-Key 连接无需浏览器直接携带 key 发起 connection_request composio.connected_accounts.initiate( user_iduser_id, auth_config_idos.environ[COMPOSIO_EXAMPLES_APIKEY_AUTH_CONFIG_ID], allow_multipleTrue, configauth_scheme.api_key( options{generic_api_key: os.environ[COMPOSIO_EXAMPLES_APIKEY_PLACEHOLDER]}, ), ) # 发起前查询必填字段 required_fields composio.toolkits.get_connected_account_initiation_fields( toolkitNOTION, auth_schemeAPI_KEY, ) # 获取 / 禁用 / 启用 / 删除 connected_account_retrieved composio.connected_accounts.get(connected_account.id) composio.connected_accounts.disable(connected_account.id) composio.connected_accounts.enable(connected_account.id) composio.connected_accounts.delete(connected_account.id)连接示例为何不能自动跑完README 特别说明了连接示例的特殊性connected_accounts.py演示的是创建连接的完整过程——调用initiate()打印授权 URL、调用wait_for_connection()等待账户激活或超时放弃。这个等待必须有真人打开 URL 完成授权因此该示例无法独立跑完自动化运行会跳过它。相比之下直接使用连接通过 Gmail/GitHub/Slack 调用工具的示例依赖的是供给脚本已验证为活跃的常驻连接账户可以全自动运行。这种创建连接需要人工、使用连接可自动化的区分是设计示例时对交互成本与可重复性的平衡也解释了为什么供给脚本要维护一组常驻 ACTIVE 连接。触发器示例triggers.pytriggers.py 覆盖触发器trigger与 Webhook 验签两大能力triggers composio.triggers.list() # 全部触发器 active_triggers composio.triggers.list_active() trigger_enums composio.triggers.list_enum() trigger composio.triggers.get_type(slugGMAIL_NEW_GMAIL_MESSAGE) # 创建触发器实例绑定连接账户 instance composio.triggers.create( slugGMAIL_NEW_GMAIL_MESSAGE, connected_account_idgmail_connected_account_id, trigger_config{}, ) # 或只传 user_id由后端解析活跃连接 instance composio.triggers.create( slugGMAIL_NEW_GMAIL_MESSAGE, user_iduser_id, trigger_config{}, ) # 禁用 / 启用 / 删除实例 composio.triggers.disable(trigger_idinstance.trigger_id) composio.triggers.enable(trigger_idinstance.trigger_id) composio.triggers.delete(trigger_idinstance.trigger_id)Webhook 验签Flask 示例示例文件内还以注释形式给出 Webhook 验签的 Flask 实现从请求头读取webhook-id、webhook-signature、webhook-timestamp调用composio.triggers.verify_webhook(...)校验签名校验通过后可从结果中读取versionWebhookVersionV1/V2/V3、payload归一化的 TriggerEvent与raw_payload原始负载签名不合法时抛WebhookSignatureVerificationError对应返回 401。验签密钥来自环境变量COMPOSIO_WEBHOOK_SECRET。订阅式触发示例最后演示订阅模式subscription composio.triggers.subscribe()用subscription.handle(toolkitGITHUB)、subscription.handle(toolkitSLACK)注册按工具包分发的回调函数最后subscription.wait_forever()阻塞等待事件。这是轮询之外的另一种事件消费方式适合长时间运行的常驻进程。MCP 集成示例mcp_example.pymcp_example.py 展示如何把 Composio 工具通过 MCPModel Context Protocol接入 LangChain Agentimport asyncio, os, time from langchain_mcp_adapters.client import MultiServerMCPClient from langgraph.prebuilt import create_react_agent from composio import Composio composio Composio() mcp_config composio.mcp.create( # 命名遵循 examples-label-unix-seconds供 --gc 识别 namefexamples-lc-slack-{int(time.time())}, toolkits[{toolkit: slack, auth_config_id: slack_auth_config_id}], # 控制暴露的工具数量LLM 提供方对单请求工具数有上限 allowed_tools[SLACK_LIST_ALL_CHANNELS, SLACK_SEARCH_MESSAGES], ) mcp_server mcp_config.generate(user_iduser_id) client MultiServerMCPClient( { composio: { url: mcp_server[url], transport: streamable_http, headers: {x-api-key: os.environ[COMPOSIO_API_KEY]}, } } ) async def langchain_mcp(message: str): tools await client.get_tools() agent create_react_agent(openai:gpt-4.1, tools) response await agent.ainvoke({messages: message}) return response mcp_response asyncio.run(langchain_mcp(Show me 20 most used slack channels))关键点MCP 配置名采用examples-label-unix-seconds规范命名这正是--gc清理 MCP 配置的匹配依据见 scripts/examples-provision.mjsallowed_tools用于收窄暴露给 LLM 的工具集合规避提供方单请求工具数量上限MCP 端点通过x-api-key请求头用 Composio API 密钥认证传输采用streamable_http传输层。修饰器示例modifiers.pymodifiers.py 演示 Composio 的修饰器modifier机制——在工具执行链路中插入自定义逻辑的钩子from composio import ( Composio, after_execute, before_execute, before_file_upload, schema_modifier, ) from composio.types import Tool, ToolExecuteParams, ToolExecutionResponse composio Composio() before_execute(tools[HACKERNEWS_GET_USER]) def before_execute_modifier(tool, toolkit, params): # 执行前改写请求参数 print(before_execute_modifier, tool, toolkit) return params before_file_upload(tools[HACKERNEWS_GET_USER]) def rewrite_upload_path(path, tool, toolkit): 每工具的文件路径策略钩子。 return path after_execute(tools[HACKERNEWS_GET_USER]) def after_execute_modifier(tool, toolkit, response): # 执行后改写响应例如只保留指定字段 return {**response, data: {karama: response[data][karama]}} # 执行时挂载修饰器 response composio.tools.execute( user_iddefault, slugHACKERNEWS_GET_USER, arguments{username: pg}, modifiers[before_execute_modifier, rewrite_upload_path, after_execute_modifier], ) schema_modifier(tools[HACKERNEWS_GET_USER]) def modify_schema(tool, toolkit, schema): return schema tools composio.tools.get( user_iddefault, slugHACKERNEWS_GET_USER, modifiers[modify_schema], )修饰器四类职责清晰before_execute改写请求参数、after_execute改写响应、before_file_upload实施文件上传路径策略、schema_modifier调整暴露给 LLM 的工具 schema。修饰器可同时作用于单个工具或整个工具包——示例后半部分用before_execute(toolkits[NOTION])展示了如何为 Notion 工具包动态注入自定义认证头从NOTION_API_KEY环境变量读取写入custom_auth_params。修饰器列表也可用于tools.get在工具暴露前改写其 schema。FastAPI 授权端点示例fastapi_app.pyfastapi_app.py 展示把 OAuth 授权流程嵌入 Web 应用的标准做法from fastapi import FastAPI from fastapi.responses import RedirectResponse from composio import Composio app FastAPI() composio Composio() app.get(/authorize/{toolkit}) def authorize_app(toolkit: str): user_id os.environ.get(COMPOSIO_EXAMPLES_USER_ID, ) auth_config_id os.environ.get(COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID, ) connection_request composio.connected_accounts.initiate( user_iduser_id, auth_config_idauth_config_id, ) return RedirectResponse(urlconnection_request.redirect_url) if __name__ __main__: import uvicorn for var in (COMPOSIO_EXAMPLES_USER_ID, COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID): if not os.environ.get(var): raise SystemExit(f{var} is required) # 启动前校验凭据与认证配置有效性 composio.auth_configs.get(os.environ[COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID]) uvicorn.run(app, host127.0.0.1, port8000)该示例的模式可直接迁移到真实产品从自有用户体系取user_id从配置取auth_config_idinitiate()拿到授权 URL 后 302 跳转。启动时的两个细节值得借鉴一是缺失环境变量时SystemExit快速失败二是在服务请求前先auth_configs.get()验证凭据与认证配置仍然有效避免带着坏配置对外服务。工具路由器示例tool_router/ 子目录工具路由器Tool Router是示例集中较新的一组能力核心思路是为指定用户创建一个隔离的会话session会话内按需暴露工具并可直接与各 LLM 框架对接。与 OpenAI Agents 集成tool_router/tools.py 演示基础用法from agents import Agent, Runner from composio_openai_agents import OpenAIAgentsProvider from composio import Composio, after_execute, before_execute composio Composio(providerOpenAIAgentsProvider()) # 为指定用户创建工具路由器会话只暴露 gmail 工具包 session composio.create(user_iduser_123, toolkits[gmail]) # 全局日志修饰器空列表 作用于所有工具 before_execute(tools[]) def log_before_execute(tool, toolkit, params): print(f Executing tool: {toolkit}.{tool}) return params after_execute(tools[]) def log_after_execute(tool, toolkit, response): print(f✅ Completed tool: {toolkit}.{tool}) return response tools session.tools(modifiers[log_before_execute, log_after_execute]) agent Agent( nameGmail Assistant, instructionsYou are a helpful assistant that helps users manage their Gmail accounts..., toolstools, ) result await Runner.run(starting_agentagent, inputFetch my last email from gmail and summarize it) print(result.final_output)composio.create()返回的 session 提供session.tools()产出已适配 OpenAI Agents 框架的工具对象tools[]的修饰器作用于会话内全部工具适合统一打日志、审计或注入上下文。预加载机制preloadtool_router/preload.py 演示三种直接暴露preload模式通过preload{tools: [...]}直接暴露 Composio 工具通过composio.experimental.tool(..., preloadTrue)暴露 SDK 自定义工具以及带preloadFalse的嵌套自定义工具覆盖在 preloaded 工具包内保持仅可搜索。示例通过断言验证最终暴露的工具集合session composio.create( user_idpreload-example-user, toolkits[hackernews], tools{hackernews: {enable: [HACKERNEWS_GET_USER]}}, preload{tools: [HACKERNEWS_GET_USER]}, manage_connectionsFalse, experimental{ custom_tools: [lookup_internal_user, search_internal_users], custom_toolkits: [internal_admin], }, ) tools session.tools() tool_names [tool.name for tool in tools] assert HACKERNEWS_GET_USER in tool_names assert LOCAL_LOOKUP_INTERNAL_USER in tool_names assert LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_HEALTH in tool_names assert LOCAL_SEARCH_INTERNAL_USERS not in tool_names # 未 preload保持搜索态 assert LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_AUDIT_LOG not in tool_names # preloadFalse 覆盖自定义工具名会带LOCAL_前缀以区分来源。示例运行方式COMPOSIO_API_KEY... OPENAI_API_KEY... python examples/tool_router/preload.py。与 Claude Agent SDK 集成tool_router/claude_agent.py 展示通过 MCP 把会话工具接入 Claudefrom claude_agent_sdk import ClaudeAgentOptions, query from composio_claude_agent_sdk import ClaudeAgentSDKProvider from composio import Composio composio Composio(providerClaudeAgentSDKProvider()) session composio.create( user_idos.environ[COMPOSIO_EXAMPLES_USER_ID], mcpTrue, # 让 session.mcp 可用 ) options ClaudeAgentOptions( system_promptYou are an expert Python developer, permission_modebypassPermissions, mcp_servers{ composio: { type: session.mcp.type, url: session.mcp.url, headers: session.mcp.headers, } }, ) async for message in query(promptFetch my last email and summarize it., optionsoptions): print(message)session.mcp直接提供 MCP 服务端三元组type/url/headers无需手工构造。工具路由器子目录中还包含 crewai_agent.py、langchain_agent.py、openai_agents.py 等框架适配示例以及 session_update.py、files.py、authorize.py、tool_router_mcp.py 等专题示例模式与上述一致composio.create()建会话 →session.tools()/session.mcp取工具 → 交给对应 Agent 框架执行。进阶阅读与验证示例入口与运行约定python/examples/README.md供给/清理脚本源码scripts/examples-provision.mjs幂等检查、--initiate-missing、--gc/--dry-run的完整实现Python SDK 核心客户端python/composio/sdk.py 与 python/composio/client类型与辅助构造python/composio/types.py含auth_scheme.api_key等辅助函数SDK 单元测试验证示例所用 API 行为python/tests/test_auth_configs.py、python/tests/test_connected_accounts.py、python/tests/test_triggers.py、python/tests/test_tool_router.py、python/tests/test_files.py这些测试文件与示例脚本相互印证示例展示的是面向用户的典型调用测试则覆盖了参数序列化、认证方案、schema 语义等边界行为两者结合可以更完整地理解 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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/composioComposio 的 Python 示例仓库python/examples是理解官方 SDK 各核心 API 的最直接入口。本文以 python/examples/README.md 为主线系统讲解如何运行这些示例、如何通过一次性配置脚本准备认证资源并逐一对工具执行、认证配置、连接账户、触发器、MCP 与工具路由器等示例做源码级拆解。读完本文你将掌握 Composio Python SDK 的典型调用模式以及如何在自己的项目中搭建可重复、可清理的示例运行环境。示例目录概览示例脚本大部分直接位于python/examples/目录下按功能覆盖 SDK 的几大核心能力脚本主题tools.py工具查询按 toolkit / 搜索与直接执行、代理调用proxytoolkits.py工具包toolkit列举、分类、按 slug 查询与授权auth_configs.py认证配置managed / custom auth的增删改查connected_accounts.py连接账户的发起、等待授权、启停与删除triggers.py触发器列举、创建、订阅与 Webhook 验签mcp_example.py通过 MCP 将 Composio 工具接入 LangChain Agentmodifiers.py工具执行前后、文件上传与 schema 的修饰器机制fastapi_app.py用 FastAPI 暴露 OAuth 授权跳转端点custom_tools_agent_test.py、experimental_tool_router_example.py、experimental_tool_router_advanced_example.py自定义工具与实验性工具路由器用法工具路由器Tool Router相关脚本则集中放在python/examples/tool_router/子目录中包括 tools.py、preload.py、claude_agent.py、crewai_agent.py、langchain_agent.py、openai_agents.py、tool_router_mcp.py、session_update.py、authorize.py、files.py 等。运行单个示例标准运行流程仓库使用uv管理 Python 工作区README 给出的标准三步流程如下cd python uv sync out$(node ../scripts/examples-provision.mjs) eval $out uv run python examples/tools.pyuv sync同步工作区虚拟环境安装python/composio及所有 provider 依赖node ../scripts/examples-provision.mjs对 Composio 项目做一次性供给检查provisioning check在 stdout 打印一批export COMPOSIO_EXAMPLES_*...环境变量eval $out把它们加载进当前 shelluv run python examples/file.py在虚拟环境中直接运行脚本无需先激活环境。uv run对子目录同样适用例如uv run python examples/tool_router/tools.py。两种 eval 写法为何不同README 特别强调必须先捕获再 evalout$(...) eval $out不要写成eval $(...)。原因在于eval的退出状态反映的是被求值文本的执行结果而不是供给脚本本身的结果——如果供给运行失败eval $(...)仍会看起来成功从而掩盖失败。先捕获到变量、再 eval供给脚本的退出码非零即失败会被正确传递。供给脚本的核心逻辑见 scripts/examples-provision.mjs它会依次调用GET /api/v3.1/auth_configs与GET /api/v3.1/connected_accounts按用户过滤将报告打印到 stderr将可 eval 的export行打印到 stdout。该脚本是幂等的——已有资源会被验证通过只有缺失的资源才会被创建且永远不会打印任何凭据值。供给脚本依赖的环境变量供给脚本本身需要两个输入见 scripts/examples-provision.mjsCOMPOSIO_API_KEY——必需缺失时脚本直接报错退出COMPOSIO_EXAMPLES_USER_ID——可选默认值为examples。后端地址通过COMPOSIO_BASE_URL选择默认指向 staging 环境解析逻辑在 harness/backend-url.mjs。需要人工参与的 OAuth 授权示例所依赖的 OAuth 类工具包gmail、googledrive、github、slack需要一次性浏览器授权。当某工具包尚无活跃连接时可加--initiate-missing让供给脚本代为发起连接请求node ../scripts/examples-provision.mjs --initiate-missing脚本会为每个缺失连接调用POST /api/v3.1/connected_accounts并把授权 URL 打印出来只需在浏览器中访问一次即可。serpapi 属于 API-Key 认证供给脚本会自动创建其认证配置无需浏览器步骤。供给脚本会为 OAuth 工具包创建名为examples-slug的use_composio_managed_auth认证配置为 serpapi 创建use_custom_auth/API_KEY方案配置演示键值为刻意伪造的占位符examples-demo-key见 scripts/examples-provision.mjs并非真实密钥。示例的环境变量约定示例脚本统一从环境变量读取配置缺失时抛出KeyError并指明缺失变量名。完整约定如下环境变量用途何时必需COMPOSIO_API_KEYComposio API 密钥总是必需COMPOSIO_EXAMPLES_USER_ID示例所代表的用户 id需要以用户身份操作时COMPOSIO_EXAMPLES_{GMAIL,GITHUB,SLACK}_AUTH_CONFIG_ID各工具包的认证配置 id使用对应工具包时COMPOSIO_EXAMPLES_{GMAIL,GITHUB,SLACK}_CONNECTED_ACCOUNT_ID各工具包的常驻连接账户 id直接调用连接时COMPOSIO_EXAMPLES_APIKEY_AUTH_CONFIG_IDserpapi 的 API-Key 认证配置 id演示 API-Key 连接时COMPOSIO_EXAMPLES_APIKEY_PLACEHOLDERserpapi 的占位键值同上OPENAI_API_KEY/ANTHROPIC_API_KEYLLM 提供方密钥仅调用对应 LLM 的示例需要例如 tools.py 通过os.environ[COMPOSIO_EXAMPLES_GITHUB_CONNECTED_ACCOUNT_ID]读取 GitHub 连接账户 idconnected_accounts.py 读取 Gmail 认证配置 id 与用户 idfastapi_app.py 在启动时校验两个必需变量并提前调用composio.auth_configs.get(...)做快速失败避免带着失效的认证配置对外服务。供给脚本的清理模式--gc示例运行会在项目中遗留资源可用--gc清理node ../scripts/examples-provision.mjs --gc --dry-run # 先预览 node ../scripts/examples-provision.mjs --gc # 真正删除--gc会删除三类由示例创建的资源从未达到ACTIVE状态的连接账户OAuth 发起后未完成授权的死连接多余的 serpapi 演示账户保留每个工具包最新一个活跃账户之前运行遗留的 MCP 配置——MCP 配置统一命名为examples-label-unix-seconds格式如examples-lc-slack-1754923456脚本用正则^examples-[a-z0-9-]-\d{10}$精确匹配见 scripts/examples-provision.mjs既靠examples-前缀证明是示例创建又靠 10 位秒级时间戳避免误伤手工创建的examples-scratch之类配置API 对 MCP 名称有 30 字符上限所以标签必须保持简短。清理有几道安全防线只删除 24 小时前创建的资源避免误删并发运行中的资源、只触碰示例自己创建的资源连接账户必须绑定到examples-slug认证配置任何项目自有的 gmail 配置都不会被误认为示例所有、created_at缺失或不可解析时按不够旧处理fail closed。脚本文件头注释明确警告这是破坏性操作应先在专用的一次性示例项目上配合--dry-run预览。工具与工具包示例工具查询与直接执行tools.py 演示了工具发现与执行的核心调用from composio import Composio composio Composio() # 按工具包获取全部工具 tools composio.tools.get(user_iddefault, toolkits[GITHUB]) # 按关键字搜索工具 tools composio.tools.get(user_iddefault, searchuser) # 组合工具包 搜索 tools composio.tools.get(user_iddefault, toolkits[GITHUB], searchstar) # 直接执行工具 response composio.tools.execute( user_iddefault, slugHACKERNEWS_GET_USER, arguments{username: pg}, version20251023_00, ) print(response)其中composio.tools.execute是同步直接执行传入工具 slug、参数与可选的version工具版本号示例中为20251023_00。工具支持按工具包、按搜索词、或两者组合三种方式获取user_id决定工具以哪个用户的上下文执行。代理调用Proxy同一文件中还演示了composio.tools.proxy——直接向第三方 API 发起代理请求并借用已连接的账户身份proxy_response composio.tools.proxy( endpoint/repos/composiohq/composio/issues/1, methodGET, connected_account_idgithub_connected_account_id, # 借用 GitHub 连接 parameters[ {name: Accept, value: application/vnd.github.v3json, type: header}, ], ) print(proxy_response)这里connected_account_id来自环境变量COMPOSIO_EXAMPLES_GITHUB_CONNECTED_ACCOUNT_ID代理调用会把请求以该账户的 GitHub 身份发出parameters可附加自定义请求头。工具包查询与授权toolkits.py 展示工具包 APItoolkits composio.toolkits.get() # 列出全部工具包 toolkit composio.toolkits.get(sluggithub) # 按 slug 查询 categories composio.toolkits.list_categories() # 列出工具包分类 connection_request composio.toolkits.authorize(user_id123, toolkitgithub)composio.toolkits.authorize是面向用户发起授权的一行式封装返回的连接请求对象可进一步用于获取授权 URL 或等待连接建立。认证配置示例auth_configs.pyauth_configs.py 覆盖认证配置的完整生命周期包括 Composio 托管认证managed auth与自定义认证custom auth两种模式from composio import Composio composio Composio() # 列出全部认证配置 auth_configs composio.auth_configs.list() # 托管认证由 Composio 代为管理凭据 auth_config composio.auth_configs.create( toolkitgithub, options{type: use_composio_managed_auth}, ) # 自定义认证自带 OAuth2 应用凭据 auth_config composio.auth_configs.create( toolkitnotion, options{ name: Notion Auth, type: use_custom_auth, auth_scheme: OAUTH2, credentials: { client_id: 1234567890, client_secret: 1234567890, oauth_redirect_uri: https://backend.composio.dev/api/v1/auth-apps/add, }, }, ) # 创建前查询必填字段 required_fields composio.toolkits.get_auth_config_creation_fields( toolkitNOTION, auth_schemeOAUTH2, ) # 按 id 获取 auth_config_retrieved composio.auth_configs.get(auth_config.id) # 从工具包元数据读取认证输入字段 toolkit composio.toolkits.get(slugnotion) required_input_fields [ field.name for field in toolkit.auth_config_details or [] if field.mode ] # 更新认证配置可修改凭据与工具访问策略 auth_config_updated composio.auth_configs.update( auth_config.id, options{ type: custom, credentials: {client_id: 1234567890, client_secret: 1234567890}, tool_access_config: { tools_for_connected_account_creation: [NOTION_ADD_PAGE_CONTENT], }, }, ) # 启用 / 禁用 / 删除 composio.auth_configs.enable(auth_config.id) composio.auth_configs.disable(auth_config.id) composio.auth_configs.delete(auth_config.id)几点值得注意的细节auth_scheme在 Python 端以小写 snake_case 传递OAUTH2、API_KEY供给脚本调用 API 时则以authScheme形式出现见 scripts/examples-provision.mjstool_access_config.tools_for_connected_account_creation可限定哪些工具允许在创建连接账户时使用用于按需暴露工具面示例中的client_id/client_secret均为演示占位值实际使用需替换为真实应用凭据。连接账户示例connected_accounts.pyconnected_accounts.py 演示连接的创建与全生命周期管理区分OAuth 连接与API-Key 连接两种路径from composio import Composio from composio.types import auth_scheme composio Composio() gmail_auth_config_id os.environ[COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID] user_id os.environ[COMPOSIO_EXAMPLES_USER_ID] # 列出全部连接 connected_accounts composio.connected_accounts.list() # OAuth 连接发起请求 - 用户浏览器授权 - 等待激活 connection_request composio.connected_accounts.initiate( user_iduser_id, auth_config_idgmail_auth_config_id, allow_multipleTrue, # 允许同一认证配置下存在多个连接 ) print(fVisit this URL to authorize: {connection_request.redirect_url}) connected_account connection_request.wait_for_connection() print(fConnected account {connected_account.id} is {connected_account.status}) # API-Key 连接无需浏览器直接携带 key 发起 connection_request composio.connected_accounts.initiate( user_iduser_id, auth_config_idos.environ[COMPOSIO_EXAMPLES_APIKEY_AUTH_CONFIG_ID], allow_multipleTrue, configauth_scheme.api_key( options{generic_api_key: os.environ[COMPOSIO_EXAMPLES_APIKEY_PLACEHOLDER]}, ), ) # 发起前查询必填字段 required_fields composio.toolkits.get_connected_account_initiation_fields( toolkitNOTION, auth_schemeAPI_KEY, ) # 获取 / 禁用 / 启用 / 删除 connected_account_retrieved composio.connected_accounts.get(connected_account.id) composio.connected_accounts.disable(connected_account.id) composio.connected_accounts.enable(connected_account.id) composio.connected_accounts.delete(connected_account.id)连接示例为何不能自动跑完README 特别说明了连接示例的特殊性connected_accounts.py演示的是创建连接的完整过程——调用initiate()打印授权 URL、调用wait_for_connection()等待账户激活或超时放弃。这个等待必须有真人打开 URL 完成授权因此该示例无法独立跑完自动化运行会跳过它。相比之下直接使用连接通过 Gmail/GitHub/Slack 调用工具的示例依赖的是供给脚本已验证为活跃的常驻连接账户可以全自动运行。这种创建连接需要人工、使用连接可自动化的区分是设计示例时对交互成本与可重复性的平衡也解释了为什么供给脚本要维护一组常驻 ACTIVE 连接。触发器示例triggers.pytriggers.py 覆盖触发器trigger与 Webhook 验签两大能力triggers composio.triggers.list() # 全部触发器 active_triggers composio.triggers.list_active() trigger_enums composio.triggers.list_enum() trigger composio.triggers.get_type(slugGMAIL_NEW_GMAIL_MESSAGE) # 创建触发器实例绑定连接账户 instance composio.triggers.create( slugGMAIL_NEW_GMAIL_MESSAGE, connected_account_idgmail_connected_account_id, trigger_config{}, ) # 或只传 user_id由后端解析活跃连接 instance composio.triggers.create( slugGMAIL_NEW_GMAIL_MESSAGE, user_iduser_id, trigger_config{}, ) # 禁用 / 启用 / 删除实例 composio.triggers.disable(trigger_idinstance.trigger_id) composio.triggers.enable(trigger_idinstance.trigger_id) composio.triggers.delete(trigger_idinstance.trigger_id)Webhook 验签Flask 示例示例文件内还以注释形式给出 Webhook 验签的 Flask 实现从请求头读取webhook-id、webhook-signature、webhook-timestamp调用composio.triggers.verify_webhook(...)校验签名校验通过后可从结果中读取versionWebhookVersionV1/V2/V3、payload归一化的 TriggerEvent与raw_payload原始负载签名不合法时抛WebhookSignatureVerificationError对应返回 401。验签密钥来自环境变量COMPOSIO_WEBHOOK_SECRET。订阅式触发示例最后演示订阅模式subscription composio.triggers.subscribe()用subscription.handle(toolkitGITHUB)、subscription.handle(toolkitSLACK)注册按工具包分发的回调函数最后subscription.wait_forever()阻塞等待事件。这是轮询之外的另一种事件消费方式适合长时间运行的常驻进程。MCP 集成示例mcp_example.pymcp_example.py 展示如何把 Composio 工具通过 MCPModel Context Protocol接入 LangChain Agentimport asyncio, os, time from langchain_mcp_adapters.client import MultiServerMCPClient from langgraph.prebuilt import create_react_agent from composio import Composio composio Composio() mcp_config composio.mcp.create( # 命名遵循 examples-label-unix-seconds供 --gc 识别 namefexamples-lc-slack-{int(time.time())}, toolkits[{toolkit: slack, auth_config_id: slack_auth_config_id}], # 控制暴露的工具数量LLM 提供方对单请求工具数有上限 allowed_tools[SLACK_LIST_ALL_CHANNELS, SLACK_SEARCH_MESSAGES], ) mcp_server mcp_config.generate(user_iduser_id) client MultiServerMCPClient( { composio: { url: mcp_server[url], transport: streamable_http, headers: {x-api-key: os.environ[COMPOSIO_API_KEY]}, } } ) async def langchain_mcp(message: str): tools await client.get_tools() agent create_react_agent(openai:gpt-4.1, tools) response await agent.ainvoke({messages: message}) return response mcp_response asyncio.run(langchain_mcp(Show me 20 most used slack channels))关键点MCP 配置名采用examples-label-unix-seconds规范命名这正是--gc清理 MCP 配置的匹配依据见 scripts/examples-provision.mjsallowed_tools用于收窄暴露给 LLM 的工具集合规避提供方单请求工具数量上限MCP 端点通过x-api-key请求头用 Composio API 密钥认证传输采用streamable_http传输层。修饰器示例modifiers.pymodifiers.py 演示 Composio 的修饰器modifier机制——在工具执行链路中插入自定义逻辑的钩子from composio import ( Composio, after_execute, before_execute, before_file_upload, schema_modifier, ) from composio.types import Tool, ToolExecuteParams, ToolExecutionResponse composio Composio() before_execute(tools[HACKERNEWS_GET_USER]) def before_execute_modifier(tool, toolkit, params): # 执行前改写请求参数 print(before_execute_modifier, tool, toolkit) return params before_file_upload(tools[HACKERNEWS_GET_USER]) def rewrite_upload_path(path, tool, toolkit): 每工具的文件路径策略钩子。 return path after_execute(tools[HACKERNEWS_GET_USER]) def after_execute_modifier(tool, toolkit, response): # 执行后改写响应例如只保留指定字段 return {**response, data: {karama: response[data][karama]}} # 执行时挂载修饰器 response composio.tools.execute( user_iddefault, slugHACKERNEWS_GET_USER, arguments{username: pg}, modifiers[before_execute_modifier, rewrite_upload_path, after_execute_modifier], ) schema_modifier(tools[HACKERNEWS_GET_USER]) def modify_schema(tool, toolkit, schema): return schema tools composio.tools.get( user_iddefault, slugHACKERNEWS_GET_USER, modifiers[modify_schema], )修饰器四类职责清晰before_execute改写请求参数、after_execute改写响应、before_file_upload实施文件上传路径策略、schema_modifier调整暴露给 LLM 的工具 schema。修饰器可同时作用于单个工具或整个工具包——示例后半部分用before_execute(toolkits[NOTION])展示了如何为 Notion 工具包动态注入自定义认证头从NOTION_API_KEY环境变量读取写入custom_auth_params。修饰器列表也可用于tools.get在工具暴露前改写其 schema。FastAPI 授权端点示例fastapi_app.pyfastapi_app.py 展示把 OAuth 授权流程嵌入 Web 应用的标准做法from fastapi import FastAPI from fastapi.responses import RedirectResponse from composio import Composio app FastAPI() composio Composio() app.get(/authorize/{toolkit}) def authorize_app(toolkit: str): user_id os.environ.get(COMPOSIO_EXAMPLES_USER_ID, ) auth_config_id os.environ.get(COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID, ) connection_request composio.connected_accounts.initiate( user_iduser_id, auth_config_idauth_config_id, ) return RedirectResponse(urlconnection_request.redirect_url) if __name__ __main__: import uvicorn for var in (COMPOSIO_EXAMPLES_USER_ID, COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID): if not os.environ.get(var): raise SystemExit(f{var} is required) # 启动前校验凭据与认证配置有效性 composio.auth_configs.get(os.environ[COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID]) uvicorn.run(app, host127.0.0.1, port8000)该示例的模式可直接迁移到真实产品从自有用户体系取user_id从配置取auth_config_idinitiate()拿到授权 URL 后 302 跳转。启动时的两个细节值得借鉴一是缺失环境变量时SystemExit快速失败二是在服务请求前先auth_configs.get()验证凭据与认证配置仍然有效避免带着坏配置对外服务。工具路由器示例tool_router/ 子目录工具路由器Tool Router是示例集中较新的一组能力核心思路是为指定用户创建一个隔离的会话session会话内按需暴露工具并可直接与各 LLM 框架对接。与 OpenAI Agents 集成tool_router/tools.py 演示基础用法from agents import Agent, Runner from composio_openai_agents import OpenAIAgentsProvider from composio import Composio, after_execute, before_execute composio Composio(providerOpenAIAgentsProvider()) # 为指定用户创建工具路由器会话只暴露 gmail 工具包 session composio.create(user_iduser_123, toolkits[gmail]) # 全局日志修饰器空列表 作用于所有工具 before_execute(tools[]) def log_before_execute(tool, toolkit, params): print(f Executing tool: {toolkit}.{tool}) return params after_execute(tools[]) def log_after_execute(tool, toolkit, response): print(f✅ Completed tool: {toolkit}.{tool}) return response tools session.tools(modifiers[log_before_execute, log_after_execute]) agent Agent( nameGmail Assistant, instructionsYou are a helpful assistant that helps users manage their Gmail accounts..., toolstools, ) result await Runner.run(starting_agentagent, inputFetch my last email from gmail and summarize it) print(result.final_output)composio.create()返回的 session 提供session.tools()产出已适配 OpenAI Agents 框架的工具对象tools[]的修饰器作用于会话内全部工具适合统一打日志、审计或注入上下文。预加载机制preloadtool_router/preload.py 演示三种直接暴露preload模式通过preload{tools: [...]}直接暴露 Composio 工具通过composio.experimental.tool(..., preloadTrue)暴露 SDK 自定义工具以及带preloadFalse的嵌套自定义工具覆盖在 preloaded 工具包内保持仅可搜索。示例通过断言验证最终暴露的工具集合session composio.create( user_idpreload-example-user, toolkits[hackernews], tools{hackernews: {enable: [HACKERNEWS_GET_USER]}}, preload{tools: [HACKERNEWS_GET_USER]}, manage_connectionsFalse, experimental{ custom_tools: [lookup_internal_user, search_internal_users], custom_toolkits: [internal_admin], }, ) tools session.tools() tool_names [tool.name for tool in tools] assert HACKERNEWS_GET_USER in tool_names assert LOCAL_LOOKUP_INTERNAL_USER in tool_names assert LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_HEALTH in tool_names assert LOCAL_SEARCH_INTERNAL_USERS not in tool_names # 未 preload保持搜索态 assert LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_AUDIT_LOG not in tool_names # preloadFalse 覆盖自定义工具名会带LOCAL_前缀以区分来源。示例运行方式COMPOSIO_API_KEY... OPENAI_API_KEY... python examples/tool_router/preload.py。与 Claude Agent SDK 集成tool_router/claude_agent.py 展示通过 MCP 把会话工具接入 Claudefrom claude_agent_sdk import ClaudeAgentOptions, query from composio_claude_agent_sdk import ClaudeAgentSDKProvider from composio import Composio composio Composio(providerClaudeAgentSDKProvider()) session composio.create( user_idos.environ[COMPOSIO_EXAMPLES_USER_ID], mcpTrue, # 让 session.mcp 可用 ) options ClaudeAgentOptions( system_promptYou are an expert Python developer, permission_modebypassPermissions, mcp_servers{ composio: { type: session.mcp.type, url: session.mcp.url, headers: session.mcp.headers, } }, ) async for message in query(promptFetch my last email and summarize it., optionsoptions): print(message)session.mcp直接提供 MCP 服务端三元组type/url/headers无需手工构造。工具路由器子目录中还包含 crewai_agent.py、langchain_agent.py、openai_agents.py 等框架适配示例以及 session_update.py、files.py、authorize.py、tool_router_mcp.py 等专题示例模式与上述一致composio.create()建会话 →session.tools()/session.mcp取工具 → 交给对应 Agent 框架执行。进阶阅读与验证示例入口与运行约定python/examples/README.md供给/清理脚本源码scripts/examples-provision.mjs幂等检查、--initiate-missing、--gc/--dry-run的完整实现Python SDK 核心客户端python/composio/sdk.py 与 python/composio/client类型与辅助构造python/composio/types.py含auth_scheme.api_key等辅助函数SDK 单元测试验证示例所用 API 行为python/tests/test_auth_configs.py、python/tests/test_connected_accounts.py、python/tests/test_triggers.py、python/tests/test_tool_router.py、python/tests/test_files.py这些测试文件与示例脚本相互印证示例展示的是面向用户的典型调用测试则覆盖了参数序列化、认证方案、schema 语义等边界行为两者结合可以更完整地理解 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考