如何解析 COMPOSIO_SEARCH_TOOLS 返回的 skill 执行计划与已知陷阱字段【免费下载链接】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 上的 agent 时COMPOSIO_SEARCH_TOOLS这个 meta tool 除了返回匹配的工具 slug 和 schema还会在同一个响应里带回一个覆盖该任务的 skill执行剧本其中包含recommended_plan_steps建议执行步骤和known_pitfalls已知陷阱。这篇讲如何发起这次搜索、如何判断响应里是否带 skill、以及带 skill 时每个字段该怎么用。适用前提是你通过 SDK 或 API 创建了 sessionagent 拿到的是默认的 session meta tools没有用 direct tools preset 关掉 meta tools。skill 是随搜索响应返回的没有独立接口在 Skills 文档中skill 被定义为「针对一个具体任务的执行剧本」记录了任务需要的工具、调用顺序和会弄坏任务的做法。关键事实有四点直接决定解析逻辑怎么写skill 不需要安装、也没有 ID 引用agent 调COMPOSIO_SEARCH_TOOLS找到工具时覆盖该任务的 skill 随同一次响应返回skill 是只读的搜索按 use case 匹配没有安装、启用、配置动作目前也没有 opt-out没有列出或读取 skill 的 API所以不存在 cURL 方式单独获取 skillagent 只能在运行时通过搜索拿到搜索匹配的是 use case 描述而不是工具名Start a DM with someone in Slack and send them a message这类完整任务描述能命中 skill而slack tools这种说法命不中。另外注意skill 从平台真实使用中派生一个任务可以跨多个 toolkit比如 Slack Gmail跨 toolkit 的 skill 会挂在每个相关 toolkit 下。发起能带回 skill 的搜索先创建 session详见 Configuring Sessionssession 默认暴露 meta toolsagent 就能调COMPOSIO_SEARCH_TOOLS。按 What is a session? 给出的示例meta tool 必须通过session.execute()执行session composio.sessions.create(user_iduser_123) result session.execute( COMPOSIO_SEARCH_TOOLS, arguments{queries: [{use_case: send an email}]}, )import { Composio } from composio/core; const composio new Composio({ apiKey: your_api_key }); const session await composio.create(user_123); // ---cut--- const result await session.execute(COMPOSIO_SEARCH_TOOLS, { queries: [{ use_case: send an email }] });入参按 meta-tools.json 中的COMPOSIO_SEARCH_TOOLS输入 schema与解析 skill 直接相关的有queries必填数组minItems: 1一次可并行多个独立子查询每个 query 返回 4-6 个工具。每个 query 里use_case必填归一化后的英文任务描述maxLength: 1024known_fields可选逗号分隔的key:value提示串如channel_name:pod-sdk用于帮搜索解析缺失的 ID 等细节session新工作流首次搜索传{generate_id: true}之后所有 meta tool 调用都复用返回的session_id用户切换到不同 use case 时要用新的 use case 再调一次并生成新的 session idsearch_strategy枚举auto默认/tool_search。工具描述里明确写了当返回的计划与当前请求不匹配、或预期的工具缺失时用同样的 queries 以tool_search重试绕过缓存计划直接走工具搜索。这是后文「计划不匹配怎么办」的文档依据model可选客户端 LLM 模型名用于优化规划/搜索行为省略或无效则忽略。工具描述还要求use_case写成归一化后的问题描述、不要把人名/邮箱/ID 写进use_case放known_fields。对 skill 解析来说这条尤其重要use case 写得越接近真实任务越可能命中一个带执行计划的 skill。响应字段哪些总出现哪些只在命中 skill 时出现完整响应 schema 同样在 meta-tools.jsonresponseSchema字段该数据由 generate-meta-tools.ts 从 Tool Router API 拉取生成。结构上顶层是data、error、successful三个必填字段skill 相关字段在data.results[]每个请求 query 一个条目按请求顺序里每个 query 条目中总是出现的字段schema 的requiredindex请求中该 query 的 1 起始下标、use_case、primary_tool_slugs主要工具 slug 数组、related_tool_slugs辅助工具 slug 数组、toolkits本 query 涉及的工具集 slug、reasoning、task_difficulty。skills.mdx 的说法与此一致primary_tool_slugs和related_tool_slugs每次搜索都返回而recommended_plan_steps、known_pitfalls以及 skill 的 difficulty 信息只在某个 skill 覆盖该 use case 时出现所以代码里必须把它们当可选字段处理。只在缓存计划可用时出现的可选字段schema 描述原文为 only present when cached plan is availablerecommended_plan_steps字符串数组按顺序完成该任务的步骤可包含可选步骤和主路径不可用时的 fallbackknown_pitfalls字符串数组该任务的已知失败模式例如错误的标识符用法、缺失的查询步骤、不成立的假设reference_workbench_snippets对象数组descriptioncode供 workbench 处理工具响应的参考 Python 片段error该 query 搜索失败时的错误信息否则为 null。skills 文档给出的响应片段文档示例非固定输出{ primary_tool_slugs: [SLACK_FIND_CHANNELS, SLACK_SEND_MESSAGE], related_tool_slugs: [SLACK_FIND_USERS], difficulty: easy - Simple single-tool operation with known parameters, recommended_plan_steps: [ Resolve the channel ID with SLACK_FIND_CHANNELS before posting., Send the message with SLACK_SEND_MESSAGE using the resolved ID. ], known_pitfalls: [ Passing a channel name where the API expects an ID returns channel_not_found. ] }两处需要对齐的文档差异解析代码要覆盖难度字段名skills.mdx 的示例写作difficulty而 API 响应 schema 中的字段名是task_difficulty且列为每个 query 条目的必填项。以 schema 为准解析时读task_difficulty示例中的difficulty视为文档示意。字段存在性判断判断「是否命中 skill」应以recommended_plan_steps/known_pitfalls/reference_workbench_snippets是否出现为准两份文档在这点上口径一致而不是去探测难度字段。query 之外、与 skill 配合使用的顶层字段均在data下全部必填tool_schemas以tool_slug为 key 的去重工具定义含toolkit、description、input_schema可能为 nullschema 说带schemaRef的工具需要先调COMPOSIO_GET_TOOL_SCHEMAS加载完整 input_schema、usage_guidelinestoolkit_connection_statuses每个 toolkit 的has_active_connection、connection_details、current_user_info、status_message等。工具描述明确要求没有 active connection 就不要执行该 toolkit 的工具先通过COMPOSIO_MANAGE_CONNECTIONS建立连接time_info当前 UTC 时间ISO 字符串 epoch 秒与时区提示session返回id、generate_id、instructions后续 meta tool 调用复用session.idnext_steps_guidance组合了连接、规划器、记忆使用的步骤指引。顶层successful为布尔值任一 query 失败即falseerror的格式是X out of Y searches failed, reasons: details。单个 query 级别失败看results[].error。解析之后计划审阅与不匹配时的重试工具描述里有一段「Plan review checklist」是给 agent 的硬性要求也是你判断 skill 字段该不该直接照抄的依据响应包含详细执行计划和常见陷阱时必须仔细审阅、适配当前上下文再生成自己最终的分步计划按顺序执行跳过必要步骤会导致意外失败执行任何工具前先对照计划与陷阱检查入参的细节必填字段、ID、格式、限制并审阅该工具完整的 input schema严格给出 schema 合规的参数判断是否需要分页响应带分页 token 且任务隐含「取全」时要翻页到耗尽不要返回部分结果。也就是说recommended_plan_steps的可靠用法是「按序执行 逐步核对known_pitfalls」而不是逐字照搬known_pitfalls是执行时主动检查的失败模式清单例如示例中的「API 要 ID 却传了 channel name 会返回channel_not_found」。如果search_strategy: auto返回的计划与当前请求不符、或预期工具没出现按工具描述的重试方式是同样的 queries 改用search_strategy: tool_search再调一次绕过缓存计划直接走工具搜索。这时响应里很可能就没有recommended_plan_steps/known_pitfalls处理逻辑要能接受它们缺席。限制与边界Meta Tools 参考页的警告meta tool 的参数名和响应结构不保证向后兼容不要把 schema 当结构化类型定义写死在代码里——对 skill 字段尤其如此字段增删时解析逻辑要能降级。没有列出/读取 skill 的 API无法离线枚举平台上有覆盖的 use case命中与否只能靠运行时响应判断。meta tool 只能在 session 内执行用tools.execute()或给 provider 的handle_tool_calls传 user ID不带 session会走直连执行路径失败报can only be called inside a tool-router session。命中 skill 的前提是 use case 写得像真实任务命中与否没有独立的判定接口唯一的核对方式就是检查data.results[]中对应条目里可选字段是否出现。落地路径收敛为创建 session → 用规范 use case 调COMPOSIO_SEARCH_TOOLS→ 按results[].recommended_plan_steps/known_pitfalls是否存在分支处理 → 审阅计划并核对连接状态后按序执行计划不符时用tool_search重试。更多 session 侧配置见 Configuring Sessionssession 机制见 What is a session?。【免费下载链接】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_SEARCH_TOOLS 返回的 skill 执行计划与已知陷阱字段
如何解析 COMPOSIO_SEARCH_TOOLS 返回的 skill 执行计划与已知陷阱字段【免费下载链接】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 上的 agent 时COMPOSIO_SEARCH_TOOLS这个 meta tool 除了返回匹配的工具 slug 和 schema还会在同一个响应里带回一个覆盖该任务的 skill执行剧本其中包含recommended_plan_steps建议执行步骤和known_pitfalls已知陷阱。这篇讲如何发起这次搜索、如何判断响应里是否带 skill、以及带 skill 时每个字段该怎么用。适用前提是你通过 SDK 或 API 创建了 sessionagent 拿到的是默认的 session meta tools没有用 direct tools preset 关掉 meta tools。skill 是随搜索响应返回的没有独立接口在 Skills 文档中skill 被定义为「针对一个具体任务的执行剧本」记录了任务需要的工具、调用顺序和会弄坏任务的做法。关键事实有四点直接决定解析逻辑怎么写skill 不需要安装、也没有 ID 引用agent 调COMPOSIO_SEARCH_TOOLS找到工具时覆盖该任务的 skill 随同一次响应返回skill 是只读的搜索按 use case 匹配没有安装、启用、配置动作目前也没有 opt-out没有列出或读取 skill 的 API所以不存在 cURL 方式单独获取 skillagent 只能在运行时通过搜索拿到搜索匹配的是 use case 描述而不是工具名Start a DM with someone in Slack and send them a message这类完整任务描述能命中 skill而slack tools这种说法命不中。另外注意skill 从平台真实使用中派生一个任务可以跨多个 toolkit比如 Slack Gmail跨 toolkit 的 skill 会挂在每个相关 toolkit 下。发起能带回 skill 的搜索先创建 session详见 Configuring Sessionssession 默认暴露 meta toolsagent 就能调COMPOSIO_SEARCH_TOOLS。按 What is a session? 给出的示例meta tool 必须通过session.execute()执行session composio.sessions.create(user_iduser_123) result session.execute( COMPOSIO_SEARCH_TOOLS, arguments{queries: [{use_case: send an email}]}, )import { Composio } from composio/core; const composio new Composio({ apiKey: your_api_key }); const session await composio.create(user_123); // ---cut--- const result await session.execute(COMPOSIO_SEARCH_TOOLS, { queries: [{ use_case: send an email }] });入参按 meta-tools.json 中的COMPOSIO_SEARCH_TOOLS输入 schema与解析 skill 直接相关的有queries必填数组minItems: 1一次可并行多个独立子查询每个 query 返回 4-6 个工具。每个 query 里use_case必填归一化后的英文任务描述maxLength: 1024known_fields可选逗号分隔的key:value提示串如channel_name:pod-sdk用于帮搜索解析缺失的 ID 等细节session新工作流首次搜索传{generate_id: true}之后所有 meta tool 调用都复用返回的session_id用户切换到不同 use case 时要用新的 use case 再调一次并生成新的 session idsearch_strategy枚举auto默认/tool_search。工具描述里明确写了当返回的计划与当前请求不匹配、或预期的工具缺失时用同样的 queries 以tool_search重试绕过缓存计划直接走工具搜索。这是后文「计划不匹配怎么办」的文档依据model可选客户端 LLM 模型名用于优化规划/搜索行为省略或无效则忽略。工具描述还要求use_case写成归一化后的问题描述、不要把人名/邮箱/ID 写进use_case放known_fields。对 skill 解析来说这条尤其重要use case 写得越接近真实任务越可能命中一个带执行计划的 skill。响应字段哪些总出现哪些只在命中 skill 时出现完整响应 schema 同样在 meta-tools.jsonresponseSchema字段该数据由 generate-meta-tools.ts 从 Tool Router API 拉取生成。结构上顶层是data、error、successful三个必填字段skill 相关字段在data.results[]每个请求 query 一个条目按请求顺序里每个 query 条目中总是出现的字段schema 的requiredindex请求中该 query 的 1 起始下标、use_case、primary_tool_slugs主要工具 slug 数组、related_tool_slugs辅助工具 slug 数组、toolkits本 query 涉及的工具集 slug、reasoning、task_difficulty。skills.mdx 的说法与此一致primary_tool_slugs和related_tool_slugs每次搜索都返回而recommended_plan_steps、known_pitfalls以及 skill 的 difficulty 信息只在某个 skill 覆盖该 use case 时出现所以代码里必须把它们当可选字段处理。只在缓存计划可用时出现的可选字段schema 描述原文为 only present when cached plan is availablerecommended_plan_steps字符串数组按顺序完成该任务的步骤可包含可选步骤和主路径不可用时的 fallbackknown_pitfalls字符串数组该任务的已知失败模式例如错误的标识符用法、缺失的查询步骤、不成立的假设reference_workbench_snippets对象数组descriptioncode供 workbench 处理工具响应的参考 Python 片段error该 query 搜索失败时的错误信息否则为 null。skills 文档给出的响应片段文档示例非固定输出{ primary_tool_slugs: [SLACK_FIND_CHANNELS, SLACK_SEND_MESSAGE], related_tool_slugs: [SLACK_FIND_USERS], difficulty: easy - Simple single-tool operation with known parameters, recommended_plan_steps: [ Resolve the channel ID with SLACK_FIND_CHANNELS before posting., Send the message with SLACK_SEND_MESSAGE using the resolved ID. ], known_pitfalls: [ Passing a channel name where the API expects an ID returns channel_not_found. ] }两处需要对齐的文档差异解析代码要覆盖难度字段名skills.mdx 的示例写作difficulty而 API 响应 schema 中的字段名是task_difficulty且列为每个 query 条目的必填项。以 schema 为准解析时读task_difficulty示例中的difficulty视为文档示意。字段存在性判断判断「是否命中 skill」应以recommended_plan_steps/known_pitfalls/reference_workbench_snippets是否出现为准两份文档在这点上口径一致而不是去探测难度字段。query 之外、与 skill 配合使用的顶层字段均在data下全部必填tool_schemas以tool_slug为 key 的去重工具定义含toolkit、description、input_schema可能为 nullschema 说带schemaRef的工具需要先调COMPOSIO_GET_TOOL_SCHEMAS加载完整 input_schema、usage_guidelinestoolkit_connection_statuses每个 toolkit 的has_active_connection、connection_details、current_user_info、status_message等。工具描述明确要求没有 active connection 就不要执行该 toolkit 的工具先通过COMPOSIO_MANAGE_CONNECTIONS建立连接time_info当前 UTC 时间ISO 字符串 epoch 秒与时区提示session返回id、generate_id、instructions后续 meta tool 调用复用session.idnext_steps_guidance组合了连接、规划器、记忆使用的步骤指引。顶层successful为布尔值任一 query 失败即falseerror的格式是X out of Y searches failed, reasons: details。单个 query 级别失败看results[].error。解析之后计划审阅与不匹配时的重试工具描述里有一段「Plan review checklist」是给 agent 的硬性要求也是你判断 skill 字段该不该直接照抄的依据响应包含详细执行计划和常见陷阱时必须仔细审阅、适配当前上下文再生成自己最终的分步计划按顺序执行跳过必要步骤会导致意外失败执行任何工具前先对照计划与陷阱检查入参的细节必填字段、ID、格式、限制并审阅该工具完整的 input schema严格给出 schema 合规的参数判断是否需要分页响应带分页 token 且任务隐含「取全」时要翻页到耗尽不要返回部分结果。也就是说recommended_plan_steps的可靠用法是「按序执行 逐步核对known_pitfalls」而不是逐字照搬known_pitfalls是执行时主动检查的失败模式清单例如示例中的「API 要 ID 却传了 channel name 会返回channel_not_found」。如果search_strategy: auto返回的计划与当前请求不符、或预期工具没出现按工具描述的重试方式是同样的 queries 改用search_strategy: tool_search再调一次绕过缓存计划直接走工具搜索。这时响应里很可能就没有recommended_plan_steps/known_pitfalls处理逻辑要能接受它们缺席。限制与边界Meta Tools 参考页的警告meta tool 的参数名和响应结构不保证向后兼容不要把 schema 当结构化类型定义写死在代码里——对 skill 字段尤其如此字段增删时解析逻辑要能降级。没有列出/读取 skill 的 API无法离线枚举平台上有覆盖的 use case命中与否只能靠运行时响应判断。meta tool 只能在 session 内执行用tools.execute()或给 provider 的handle_tool_calls传 user ID不带 session会走直连执行路径失败报can only be called inside a tool-router session。命中 skill 的前提是 use case 写得像真实任务命中与否没有独立的判定接口唯一的核对方式就是检查data.results[]中对应条目里可选字段是否出现。落地路径收敛为创建 session → 用规范 use case 调COMPOSIO_SEARCH_TOOLS→ 按results[].recommended_plan_steps/known_pitfalls是否存在分支处理 → 审阅计划并核对连接状态后按序执行计划不符时用tool_search重试。更多 session 侧配置见 Configuring Sessionssession 机制见 What is a session?。【免费下载链接】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），仅供参考