Composio 会话工具策略完全指南用标签、精确白名单与 OAuth 作用域实现最小权限【免费下载链接】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 的 Session会话工具过滤机制为核心系统讲解如何通过行为标签behavior tags、精确工具白名单allowlist、OAuth 作用域叠加以及沙箱开关为 AI Agent 构建最小权限least privilege的受限会话。读完本文你将掌握 Python 与 TypeScript 两种 SDK 下composio.sessions.create()/composio.create()的全部过滤参数、它们之间的优先级关系以及如何在部署前用源码级手段验证会话实际暴露的工具面。本文对应的原始知识库文章位于 docs/kb/articles/platform-session-tool-policies.md其完整配置参考见 docs/content/docs/configuring-sessions.mdx。为什么需要会话级工具策略Composio 会话Session默认拥有整个工具目录的访问能力docs/content/docs/configuring-sessions.mdx明确说明默认情况下一个会话可以访问 Composio 目录中的每一个 toolkitAgent 可以随时通过COMPOSIO_SEARCH_TOOLS元工具发现并使用其中任意工具。这种全量可发现的默认行为在面向真实用户数据邮件、仓库、日历、支付的生产环境中风险极高。会话级工具策略的目标就是在发现阶段和执行阶段同时收紧权限——行为标签、工具白名单这些过滤器不仅在 Agent 搜索工具时生效在会话执行工具时同样强制执行The same filters are enforced when the session executes tools。这意味着即使 Agent 拿到了某个工具的名称只要它不在会话允许范围内执行时依然会被拒绝。从源码实现看会话创建入口ToolRouter.create()的核心参数在 python/composio/core/models/tool_router.py 中有完整定义支持toolkits、tools、tags、manage_connections、auth_configs、connected_accounts、sandbox、multi_account、preload、session_preset等十余个维度。本文聚焦其中与工具权限收紧最相关的五个策略。策略一用行为标签过滤宽泛的只读会话当 Agent 可能跨多个 toolkit 发现工具但你只希望它拿到标记为只读的工具时使用会话级行为标签session-level behavior tags。行为标签描述的是工具本身的语义特性与它属于哪个 toolkit 无关因此特别适合放开目录、收紧行为的场景。Pythonsession composio.sessions.create( user_iduser_123, tags{ enable: [readOnlyHint], disable: [destructiveHint], }, )TypeScriptconst session await composio.create(user_123, { tags: { enable: [readOnlyHint], disable: [destructiveHint], }, });可用的行为标签全集docs/content/docs/configuring-sessions.mdx的 Filtering tools by tags 一节给出了完整的标签定义标签含义readOnlyHint只读取数据的工具destructiveHint修改或删除数据的工具idempotentHint可以安全重试的工具openWorldHint在开放世界上下文中操作的工具其中tags参数支持两种写法数组简写等价于enabletags[readOnlyHint, idempotentHint]表示只保留同时满足只读与可安全重试的工具对象写法可同时表达启用与禁用tags{enable: [readOnlyHint], disable: [destructiveHint]}表示只读的工具可用、破坏性的工具不可用。从 SDK 实现看Python 侧create()的tags参数在 python/composio/core/models/tool_router.py 中会做归一化从{enable: [...], disable: [...]}中分别取出非空列表仅构造包含非空字段的结果字典空列表会被剔除。TypeScript 侧 ts/packages/core/src/lib/toolRouterParams.ts 也有对应的归一化逻辑数组自动转换为{ enable: [...] }形式已经是enable/disable结构的对象则原样保留。上线前的必要检查行为标签描述的是工具的行为因此文档特别强调在正式上线rollout前务必检查会话实际暴露的工具列表尤其是工作流涉及敏感数据时。检查手段有两种调用session.tools()直接枚举会话暴露给 AI 框架的工具默认返回元工具集使用composio.tools.get_raw_composio_tool_by_slug(GMAIL_SEND_EMAIL)查看单个工具的input_parameters/output_parameters与描述确认其语义与标签一致示例见 docs/content/docs/configuring-sessions.mdx 的 Browsing the catalog 一节。策略二用精确工具白名单实现最窄策略行为标签按语义维度过滤粒度仍然偏粗——一个只读标签下可能有上百个工具。当工作流所需操作集合完全已知时应当只允许它精确需要的工具 slug这就是最窄的策略。Pythonsession composio.sessions.create( user_iduser_123, tools{ gmail: {enable: [GMAIL_FETCH_EMAILS]}, github: {enable: [GITHUB_GET_AN_ISSUE]}, }, )TypeScriptconst session await composio.create(user_123, { tools: { gmail: { enable: [GMAIL_FETCH_EMAILS] }, github: { enable: [GITHUB_GET_AN_ISSUE] }, }, });白名单的核心价值在于它避免了新加入的工具只因与某个 toolkit 或行为标签共享属性就被自动接纳。例如 GitHub toolkit 未来新增一个删除仓库的工具如果会话只按toolkits[github]或tags[readOnlyHint]过滤新工具可能自动进入可发现范围而按精确 slug 白名单新工具不会出现在允许列表中除非你显式加入。tools 参数的完整语法tools参数以 toolkit slug 为键支持三种值形态依据 python/composio/core/models/tool_router.py 的create()文档与configuring-sessions.mdx形态含义示例数组简写等价于enablegmail: [GMAIL_SEND_EMAIL, GMAIL_FETCH_EMAILS]{enable: [...]}只启用列出的工具gmail: {enable: [GMAIL_SEND_EMAIL]}{disable: [...]}保留该 toolkit 其余全部工具、仅排除列出的slack: {disable: [SLACK_DELETE_MESSAGE]}disable形态适合基本信任某个 toolkit、但剔除几个危险操作的场景例如github: {disable: [GITHUB_DELETE_REPO, GITHUB_DELETE_BRANCH]}。注意它与白名单的哲学不同disable仍然会接纳 toolkit 后续新增的工具因此只有当你能容忍该 toolkit 的新工具自动可用时才使用disable。组合示例可同时出现在一个会话配置中session composio.sessions.create( user_iduser_123, tools{ gmail: [GMAIL_SEND_EMAIL, GMAIL_FETCH_EMAILS], # 数组简写 enable github: {enable: [GITHUB_CREATE_ISSUE]}, # 精确白名单 slack: {disable: [SLACK_DELETE_MESSAGE]}, # 排除式 }, )策略三叠加 OAuth 作用域双层次最小权限工具过滤只解决Agent 能调用哪些 Composio 工具的问题而OAuth 作用域scopes控制的是 provider 授予连接账号的权限。两者必须叠加使用才能构成完整的最小权限第一层provider 层只请求用例真正需要的 OAuth scopes从源头限制连接账号的权限面第二层Composio 层将会话限制到预期的工具集合防止 Agent 越权调用。设置 OAuth scopes 的示例详见 docs/content/docs/authentication/controlling-scopes.mdxfrom composio import Composio composio Composio() # 使用 Composio 托管 OAuth 应用覆盖默认 scopes auth_config composio.auth_configs.create( toolkithubspot, options{ type: use_composio_managed_auth, name: HubSpot, credentials: {scopes: sales-email-read,tickets}, }, )TypeScript 对应写法import { Composio } from composio/core; const composio new Composio(); const authConfig await composio.authConfigs.create(hubspot, { type: use_composio_managed_auth, name: HubSpot, credentials: { scopes: sales-email-read,tickets }, });使用自定义 OAuth 应用时将scopes与client_id、client_secret一起放在credentials中例如scopes: repo,read:org并确保你的 OAuth 应用在 provider 后台已审批这些 scopes。两个关键约束作用域变更只影响新连接修改 auth config 的 scopes 后已存在的用户会保留之前的授权直到他们重新连接reconnect为止必须把 auth config 显式传给会话需要按 toolkit 传入意图使用的 auth config ID否则会话不会请求这些 scopes。传递方式session composio.sessions.create( user_iduser_123, auth_configs{ github: ac_your_github_config, slack: ac_your_slack_config, }, )TypeScript 中对应键名为authConfigs如authConfigs: { github: ac_your_github_config }。完整说明见 docs/content/docs/configuring-sessions.mdx 的 Custom auth configs 一节。值得注意的是scopes 仅适用于 OAuth toolkit使用 API Key 或 bearer token 认证的 toolkit 没有 scopes 可设置。策略四仅对指定 toolkit 放行例外而不放宽全局策略前面三种策略都是全局收紧。但实践中常常出现整体只读、唯独某个 toolkit 需要放行写操作的需求。此时应当设置全局标签策略并仅对具名 toolkit 覆盖——这比把整个会话的全局策略放宽要安全得多。Pythonsession composio.sessions.create( user_iduser_123, tags[readOnlyHint], # 全局只允许只读工具 tools{ github: {tags: {disable: [destructiveHint]}}, # GitHub 例外禁用破坏性工具即可 gmail: {tags: [readOnlyHint]}, # Gmail 显式声明只读 }, )TypeScriptconst session await composio.create(user_123, { tags: [readOnlyHint], // 全局只允许只读工具 tools: { github: { tags: { disable: [destructiveHint] } }, // GitHub 例外 gmail: { tags: [readOnlyHint] }, }, });语义解读全局tags[readOnlyHint]意味着会话内所有工具默认必须满足只读GitHub 的 toolkit 级覆盖tags{disable: [destructiveHint]}表示GitHub 工具不再要求只读只需排除破坏性工具即允许 GitHub 的写操作非破坏性Gmail 的tags[readOnlyHint]是显式重申只读与全局一致也可以省略。从 SDK 源码确认toolkit 级标签覆盖override全局标签设置Toolkit-level tags override this global setting见 python/composio/core/models/tool_router.py。这种全局默认 局部例外的模式比将整个会话的全局策略放宽更可控例外被限定在具名 toolkit 范围内不会波及其他所有 toolkit。策略五不需要代码执行时关闭会话沙箱会话工具过滤器管辖的是应用工具app tools而会话默认还会附带一组远程沙箱工具COMPOSIO_REMOTE_WORKBENCH远程工作台和COMPOSIO_REMOTE_BASH_TOOL远程 shell它们提供了一个持久化计算环境。如果工作流不需要 Python、shell、文件处理或远程工作台执行应当关闭沙箱进一步压缩攻击面。Pythonsession composio.sessions.create( user_iduser_123, tags[readOnlyHint], sandbox{enable: False}, )TypeScriptconst session await composio.create(user_123, { tags: [readOnlyHint], sandbox: { enable: false }, });关闭沙箱后的具体行为依据 docs/content/docs/configuring-sessions.mdx 的 Disabling the sandbox 一节sandbox{enable: False}会触发三个连锁效果COMPOSIO_REMOTE_WORKBENCH和COMPOSIO_REMOTE_BASH_TOOL从会话中排除与沙箱相关的 system prompt 行被剥离避免引导 Agent 尝试调用代码执行工具直接调用沙箱会被后端以400 错误拒绝。另有两点使用注意sandbox是首选配置键workbench仍是完全受支持的别名且未被弃用存量代码无需改动。Python SDK 的session.update()中同时传sandbox与workbench会抛出InvalidParams异常见 python/composio/core/models/tool_router_session.py若保留沙箱但需要更大计算资源可配置sandbox{sandbox_size: large}可选档位standard1 vCPU / 1 GB默认、medium2 vCPU / 2 GB、large4 vCPU / 4 GB、xlarge8 vCPU / 8 GB。策略组合与优先级速查五个策略可以自由组合形成纵深防御。一个只读 精确白名单 最小作用域 无沙箱的完整配置示例Pythonsession composio.sessions.create( user_iduser_123, tags{enable: [readOnlyHint], disable: [destructiveHint]}, tools{ gmail: {enable: [GMAIL_FETCH_EMAILS, GMAIL_SEARCH]}, github: {enable: [GITHUB_GET_AN_ISSUE]}, }, auth_configs{gmail: ac_low_scope_gmail}, sandbox{enable: False}, )TypeScriptconst session await composio.create(user_123, { tags: { enable: [readOnlyHint], disable: [destructiveHint] }, tools: { gmail: { enable: [GMAIL_FETCH_EMAILS, GMAIL_SEARCH] }, github: { enable: [GITHUB_GET_AN_ISSUE] }, }, authConfigs: { gmail: ac_low_scope_gmail }, sandbox: { enable: false }, });各过滤维度的作用范围与关系维度作用层级覆盖关系tags全局全部 toolkit可被 toolkit 级tags覆盖tools.toolkit.tags单个 toolkit覆盖全局tagstools.toolkit.enable/disable单个 toolkit 内单个工具精确到 slugauth_configs认证层决定 scopes 与连接作用于连接创建不影响工具过滤sandbox.enable代码执行层独立开关与应用工具过滤正交从 python/composio/core/models/tool_router.py 的create()签名可以看到tags、tools、sandbox、auth_configs全部是可选独立参数可以按需组合Python SDK 还额外提供了session.update()TypeScript 同理用于对已创建的会话做部分更新patch只修改传入字段、保留其余字段方便在运行期动态收紧或放宽策略。上线前的验证清单最后结合文档与源码给出部署前建议执行的验证步骤枚举会话暴露的工具调用session.tools()确认工具集合与预期完全一致——这是文档明确强调的 rollout 前必做项尤其是工作流涉及敏感数据时核对标签语义对每个允许的工具调用composio.tools.get_raw_composio_tool_by_slug(slug)检查其描述与 schema确认行为标签描述与实际行为相符工具输入输出 schema 无用户上下文即可获取示例见 docs/content/docs/configuring-sessions.mdx 的 Browsing the catalog 一节确认作用域已生效验证新连接使用的 auth config ID 与会话中auth_configs指定的一致并提醒存量用户重新连接以获得新 scopes验证沙箱关闭确认会话工具列表中不含COMPOSIO_REMOTE_WORKBENCH/COMPOSIO_REMOTE_BASH_TOOL且直接调用沙箱返回 400执行路径验证由于标签与白名单过滤器在执行阶段同样强制可实际执行一次允许与拒绝边界上的工具调用确认行为符合预期。上述策略对应的完整会话配置文档位于 docs/content/docs/configuring-sessions.mdx会话对象的运行时实现tools()、execute()、update()、delete()等可在 python/composio/core/models/tool_router_session.py 与 ts/packages/core/src/models/Sessions.ts 中继续深入阅读。【免费下载链接】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 会话工具策略完全指南：用标签、精确白名单与 OAuth 作用域实现最小权限
Composio 会话工具策略完全指南用标签、精确白名单与 OAuth 作用域实现最小权限【免费下载链接】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 的 Session会话工具过滤机制为核心系统讲解如何通过行为标签behavior tags、精确工具白名单allowlist、OAuth 作用域叠加以及沙箱开关为 AI Agent 构建最小权限least privilege的受限会话。读完本文你将掌握 Python 与 TypeScript 两种 SDK 下composio.sessions.create()/composio.create()的全部过滤参数、它们之间的优先级关系以及如何在部署前用源码级手段验证会话实际暴露的工具面。本文对应的原始知识库文章位于 docs/kb/articles/platform-session-tool-policies.md其完整配置参考见 docs/content/docs/configuring-sessions.mdx。为什么需要会话级工具策略Composio 会话Session默认拥有整个工具目录的访问能力docs/content/docs/configuring-sessions.mdx明确说明默认情况下一个会话可以访问 Composio 目录中的每一个 toolkitAgent 可以随时通过COMPOSIO_SEARCH_TOOLS元工具发现并使用其中任意工具。这种全量可发现的默认行为在面向真实用户数据邮件、仓库、日历、支付的生产环境中风险极高。会话级工具策略的目标就是在发现阶段和执行阶段同时收紧权限——行为标签、工具白名单这些过滤器不仅在 Agent 搜索工具时生效在会话执行工具时同样强制执行The same filters are enforced when the session executes tools。这意味着即使 Agent 拿到了某个工具的名称只要它不在会话允许范围内执行时依然会被拒绝。从源码实现看会话创建入口ToolRouter.create()的核心参数在 python/composio/core/models/tool_router.py 中有完整定义支持toolkits、tools、tags、manage_connections、auth_configs、connected_accounts、sandbox、multi_account、preload、session_preset等十余个维度。本文聚焦其中与工具权限收紧最相关的五个策略。策略一用行为标签过滤宽泛的只读会话当 Agent 可能跨多个 toolkit 发现工具但你只希望它拿到标记为只读的工具时使用会话级行为标签session-level behavior tags。行为标签描述的是工具本身的语义特性与它属于哪个 toolkit 无关因此特别适合放开目录、收紧行为的场景。Pythonsession composio.sessions.create( user_iduser_123, tags{ enable: [readOnlyHint], disable: [destructiveHint], }, )TypeScriptconst session await composio.create(user_123, { tags: { enable: [readOnlyHint], disable: [destructiveHint], }, });可用的行为标签全集docs/content/docs/configuring-sessions.mdx的 Filtering tools by tags 一节给出了完整的标签定义标签含义readOnlyHint只读取数据的工具destructiveHint修改或删除数据的工具idempotentHint可以安全重试的工具openWorldHint在开放世界上下文中操作的工具其中tags参数支持两种写法数组简写等价于enabletags[readOnlyHint, idempotentHint]表示只保留同时满足只读与可安全重试的工具对象写法可同时表达启用与禁用tags{enable: [readOnlyHint], disable: [destructiveHint]}表示只读的工具可用、破坏性的工具不可用。从 SDK 实现看Python 侧create()的tags参数在 python/composio/core/models/tool_router.py 中会做归一化从{enable: [...], disable: [...]}中分别取出非空列表仅构造包含非空字段的结果字典空列表会被剔除。TypeScript 侧 ts/packages/core/src/lib/toolRouterParams.ts 也有对应的归一化逻辑数组自动转换为{ enable: [...] }形式已经是enable/disable结构的对象则原样保留。上线前的必要检查行为标签描述的是工具的行为因此文档特别强调在正式上线rollout前务必检查会话实际暴露的工具列表尤其是工作流涉及敏感数据时。检查手段有两种调用session.tools()直接枚举会话暴露给 AI 框架的工具默认返回元工具集使用composio.tools.get_raw_composio_tool_by_slug(GMAIL_SEND_EMAIL)查看单个工具的input_parameters/output_parameters与描述确认其语义与标签一致示例见 docs/content/docs/configuring-sessions.mdx 的 Browsing the catalog 一节。策略二用精确工具白名单实现最窄策略行为标签按语义维度过滤粒度仍然偏粗——一个只读标签下可能有上百个工具。当工作流所需操作集合完全已知时应当只允许它精确需要的工具 slug这就是最窄的策略。Pythonsession composio.sessions.create( user_iduser_123, tools{ gmail: {enable: [GMAIL_FETCH_EMAILS]}, github: {enable: [GITHUB_GET_AN_ISSUE]}, }, )TypeScriptconst session await composio.create(user_123, { tools: { gmail: { enable: [GMAIL_FETCH_EMAILS] }, github: { enable: [GITHUB_GET_AN_ISSUE] }, }, });白名单的核心价值在于它避免了新加入的工具只因与某个 toolkit 或行为标签共享属性就被自动接纳。例如 GitHub toolkit 未来新增一个删除仓库的工具如果会话只按toolkits[github]或tags[readOnlyHint]过滤新工具可能自动进入可发现范围而按精确 slug 白名单新工具不会出现在允许列表中除非你显式加入。tools 参数的完整语法tools参数以 toolkit slug 为键支持三种值形态依据 python/composio/core/models/tool_router.py 的create()文档与configuring-sessions.mdx形态含义示例数组简写等价于enablegmail: [GMAIL_SEND_EMAIL, GMAIL_FETCH_EMAILS]{enable: [...]}只启用列出的工具gmail: {enable: [GMAIL_SEND_EMAIL]}{disable: [...]}保留该 toolkit 其余全部工具、仅排除列出的slack: {disable: [SLACK_DELETE_MESSAGE]}disable形态适合基本信任某个 toolkit、但剔除几个危险操作的场景例如github: {disable: [GITHUB_DELETE_REPO, GITHUB_DELETE_BRANCH]}。注意它与白名单的哲学不同disable仍然会接纳 toolkit 后续新增的工具因此只有当你能容忍该 toolkit 的新工具自动可用时才使用disable。组合示例可同时出现在一个会话配置中session composio.sessions.create( user_iduser_123, tools{ gmail: [GMAIL_SEND_EMAIL, GMAIL_FETCH_EMAILS], # 数组简写 enable github: {enable: [GITHUB_CREATE_ISSUE]}, # 精确白名单 slack: {disable: [SLACK_DELETE_MESSAGE]}, # 排除式 }, )策略三叠加 OAuth 作用域双层次最小权限工具过滤只解决Agent 能调用哪些 Composio 工具的问题而OAuth 作用域scopes控制的是 provider 授予连接账号的权限。两者必须叠加使用才能构成完整的最小权限第一层provider 层只请求用例真正需要的 OAuth scopes从源头限制连接账号的权限面第二层Composio 层将会话限制到预期的工具集合防止 Agent 越权调用。设置 OAuth scopes 的示例详见 docs/content/docs/authentication/controlling-scopes.mdxfrom composio import Composio composio Composio() # 使用 Composio 托管 OAuth 应用覆盖默认 scopes auth_config composio.auth_configs.create( toolkithubspot, options{ type: use_composio_managed_auth, name: HubSpot, credentials: {scopes: sales-email-read,tickets}, }, )TypeScript 对应写法import { Composio } from composio/core; const composio new Composio(); const authConfig await composio.authConfigs.create(hubspot, { type: use_composio_managed_auth, name: HubSpot, credentials: { scopes: sales-email-read,tickets }, });使用自定义 OAuth 应用时将scopes与client_id、client_secret一起放在credentials中例如scopes: repo,read:org并确保你的 OAuth 应用在 provider 后台已审批这些 scopes。两个关键约束作用域变更只影响新连接修改 auth config 的 scopes 后已存在的用户会保留之前的授权直到他们重新连接reconnect为止必须把 auth config 显式传给会话需要按 toolkit 传入意图使用的 auth config ID否则会话不会请求这些 scopes。传递方式session composio.sessions.create( user_iduser_123, auth_configs{ github: ac_your_github_config, slack: ac_your_slack_config, }, )TypeScript 中对应键名为authConfigs如authConfigs: { github: ac_your_github_config }。完整说明见 docs/content/docs/configuring-sessions.mdx 的 Custom auth configs 一节。值得注意的是scopes 仅适用于 OAuth toolkit使用 API Key 或 bearer token 认证的 toolkit 没有 scopes 可设置。策略四仅对指定 toolkit 放行例外而不放宽全局策略前面三种策略都是全局收紧。但实践中常常出现整体只读、唯独某个 toolkit 需要放行写操作的需求。此时应当设置全局标签策略并仅对具名 toolkit 覆盖——这比把整个会话的全局策略放宽要安全得多。Pythonsession composio.sessions.create( user_iduser_123, tags[readOnlyHint], # 全局只允许只读工具 tools{ github: {tags: {disable: [destructiveHint]}}, # GitHub 例外禁用破坏性工具即可 gmail: {tags: [readOnlyHint]}, # Gmail 显式声明只读 }, )TypeScriptconst session await composio.create(user_123, { tags: [readOnlyHint], // 全局只允许只读工具 tools: { github: { tags: { disable: [destructiveHint] } }, // GitHub 例外 gmail: { tags: [readOnlyHint] }, }, });语义解读全局tags[readOnlyHint]意味着会话内所有工具默认必须满足只读GitHub 的 toolkit 级覆盖tags{disable: [destructiveHint]}表示GitHub 工具不再要求只读只需排除破坏性工具即允许 GitHub 的写操作非破坏性Gmail 的tags[readOnlyHint]是显式重申只读与全局一致也可以省略。从 SDK 源码确认toolkit 级标签覆盖override全局标签设置Toolkit-level tags override this global setting见 python/composio/core/models/tool_router.py。这种全局默认 局部例外的模式比将整个会话的全局策略放宽更可控例外被限定在具名 toolkit 范围内不会波及其他所有 toolkit。策略五不需要代码执行时关闭会话沙箱会话工具过滤器管辖的是应用工具app tools而会话默认还会附带一组远程沙箱工具COMPOSIO_REMOTE_WORKBENCH远程工作台和COMPOSIO_REMOTE_BASH_TOOL远程 shell它们提供了一个持久化计算环境。如果工作流不需要 Python、shell、文件处理或远程工作台执行应当关闭沙箱进一步压缩攻击面。Pythonsession composio.sessions.create( user_iduser_123, tags[readOnlyHint], sandbox{enable: False}, )TypeScriptconst session await composio.create(user_123, { tags: [readOnlyHint], sandbox: { enable: false }, });关闭沙箱后的具体行为依据 docs/content/docs/configuring-sessions.mdx 的 Disabling the sandbox 一节sandbox{enable: False}会触发三个连锁效果COMPOSIO_REMOTE_WORKBENCH和COMPOSIO_REMOTE_BASH_TOOL从会话中排除与沙箱相关的 system prompt 行被剥离避免引导 Agent 尝试调用代码执行工具直接调用沙箱会被后端以400 错误拒绝。另有两点使用注意sandbox是首选配置键workbench仍是完全受支持的别名且未被弃用存量代码无需改动。Python SDK 的session.update()中同时传sandbox与workbench会抛出InvalidParams异常见 python/composio/core/models/tool_router_session.py若保留沙箱但需要更大计算资源可配置sandbox{sandbox_size: large}可选档位standard1 vCPU / 1 GB默认、medium2 vCPU / 2 GB、large4 vCPU / 4 GB、xlarge8 vCPU / 8 GB。策略组合与优先级速查五个策略可以自由组合形成纵深防御。一个只读 精确白名单 最小作用域 无沙箱的完整配置示例Pythonsession composio.sessions.create( user_iduser_123, tags{enable: [readOnlyHint], disable: [destructiveHint]}, tools{ gmail: {enable: [GMAIL_FETCH_EMAILS, GMAIL_SEARCH]}, github: {enable: [GITHUB_GET_AN_ISSUE]}, }, auth_configs{gmail: ac_low_scope_gmail}, sandbox{enable: False}, )TypeScriptconst session await composio.create(user_123, { tags: { enable: [readOnlyHint], disable: [destructiveHint] }, tools: { gmail: { enable: [GMAIL_FETCH_EMAILS, GMAIL_SEARCH] }, github: { enable: [GITHUB_GET_AN_ISSUE] }, }, authConfigs: { gmail: ac_low_scope_gmail }, sandbox: { enable: false }, });各过滤维度的作用范围与关系维度作用层级覆盖关系tags全局全部 toolkit可被 toolkit 级tags覆盖tools.toolkit.tags单个 toolkit覆盖全局tagstools.toolkit.enable/disable单个 toolkit 内单个工具精确到 slugauth_configs认证层决定 scopes 与连接作用于连接创建不影响工具过滤sandbox.enable代码执行层独立开关与应用工具过滤正交从 python/composio/core/models/tool_router.py 的create()签名可以看到tags、tools、sandbox、auth_configs全部是可选独立参数可以按需组合Python SDK 还额外提供了session.update()TypeScript 同理用于对已创建的会话做部分更新patch只修改传入字段、保留其余字段方便在运行期动态收紧或放宽策略。上线前的验证清单最后结合文档与源码给出部署前建议执行的验证步骤枚举会话暴露的工具调用session.tools()确认工具集合与预期完全一致——这是文档明确强调的 rollout 前必做项尤其是工作流涉及敏感数据时核对标签语义对每个允许的工具调用composio.tools.get_raw_composio_tool_by_slug(slug)检查其描述与 schema确认行为标签描述与实际行为相符工具输入输出 schema 无用户上下文即可获取示例见 docs/content/docs/configuring-sessions.mdx 的 Browsing the catalog 一节确认作用域已生效验证新连接使用的 auth config ID 与会话中auth_configs指定的一致并提醒存量用户重新连接以获得新 scopes验证沙箱关闭确认会话工具列表中不含COMPOSIO_REMOTE_WORKBENCH/COMPOSIO_REMOTE_BASH_TOOL且直接调用沙箱返回 400执行路径验证由于标签与白名单过滤器在执行阶段同样强制可实际执行一次允许与拒绝边界上的工具调用确认行为符合预期。上述策略对应的完整会话配置文档位于 docs/content/docs/configuring-sessions.mdx会话对象的运行时实现tools()、execute()、update()、delete()等可在 python/composio/core/models/tool_router_session.py 与 ts/packages/core/src/models/Sessions.ts 中继续深入阅读。【免费下载链接】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），仅供参考