{ "canonical_name": "ComposioHQ/composio", "compilation_id": "pack_5b952a0391ee494a87cc17ef8ada7413", "created_at": "2026-05-15T11:39:46.064412+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npm install @composio/core` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npm install @composio/core", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_d7ee9b99347d487c9e8b646e72da440b" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_f77074cf4e636cdd607aea06cb3dbb8c", "canonical_name": "ComposioHQ/composio", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/ComposioHQ/composio", "slug": "composio", "source_packet_id": "phit_a4d5553a7462485785ddeba6695885a1", "source_validation_id": "dval_2338278d08fa4b36b2924d1ece43ba6f" }, "merchandising": { "best_for": "需要工具连接与集成能力，并使用 local_cli的用户", "github_forks": 4554, "github_stars": 28209, "one_liner_en": "Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.", "one_liner_zh": "Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.", "primary_category": { "category_id": "tool-integrations", "confidence": "high", "name_en": "Tool Integrations", "name_zh": "工具连接与集成", "reason": "curated popular coverage category matched project identity" }, "target_user": "使用 local_cli 等宿主 AI 的用户", "title_en": "composio", "title_zh": "composio 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Structured Data Extraction", "label_zh": "结构化数据提取", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-structured-data-extraction", "type": "core_capability" }, { "label_en": "Multi-role Workflow", "label_zh": "多角色协作流程", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-multi-role-workflow", "type": "workflow_pattern" }, { "label_en": "Open Source Tool", "label_zh": "开源工具", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-open-source-tool", "type": "selection_signal" } ] }, "packet_id": "phit_a4d5553a7462485785ddeba6695885a1", "page_model": { "artifacts": { "artifact_slug": "composio", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npm install @composio/core", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/ComposioHQ/composio#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "结构化数据提取", "多角色协作流程", "开源工具" ], "eyebrow": "工具连接与集成", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要工具连接与集成能力，并使用 local_cli的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "local_cli", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_54d53b3e2a6e4cf4a3e4783f824ed87b | https://github.com/ComposioHQ/composio/issues/3269 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shares:{})", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_1b88beb594aa433eb998eac3b16a20e0 | https://github.com/ComposioHQ/composio/issues/3422 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shar…", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] Custom auth configs shouldn't require a dev project to use", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_1d62ba62e77b47ff88b50d2db41a8cf7 | https://github.com/ComposioHQ/composio/issues/3271 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[Feature] Custom auth configs shouldn't require a dev project to use", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "仓库名 `composio` 与安装入口 `@composio/core` 不完全一致。", "category": "身份坑", "evidence": [ "identity.distribution | github_repo:762304524 | https://github.com/ComposioHQ/composio | repo=composio; install=@composio/core" ], "severity": "medium", "suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。", "title": "仓库名和安装名不一致", "user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:762304524 | https://github.com/ComposioHQ/composio | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | github_repo:762304524 | https://github.com/ComposioHQ/composio | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：@composio/core@0.10.0", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_66f9d5fd557f41c7845ca5dd7d93ae6f | https://github.com/ComposioHQ/composio/releases/tag/%40composio/core%400.10.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：@composio/core@0.10.0", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 12 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops。", "title": "踩坑日志" }, "snapshot": { "contributors": 54, "forks": 4554, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 28209 }, "source_url": "https://github.com/ComposioHQ/composio", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.", "title": "composio 能力包", "trial_prompt": "# composio - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 composio 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Introduction to Composio。围绕“Introduction to Composio”模拟一次用户任务，不展示安装或运行结果。\n2. getting-started：Getting Started。围绕“Getting Started”模拟一次用户任务，不展示安装或运行结果。\n3. architecture-overview：System Architecture。围绕“System Architecture”模拟一次用户任务，不展示安装或运行结果。\n4. core-concepts：Core Concepts。围绕“Core Concepts”模拟一次用户任务，不展示安装或运行结果。\n5. typescript-sdk：TypeScript SDK。围绕“TypeScript SDK”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Introduction to Composio”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. getting-started\n输入：用户提供的“Getting Started”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture-overview\n输入：用户提供的“System Architecture”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. core-concepts\n输入：用户提供的“Core Concepts”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. typescript-sdk\n输入：用户提供的“TypeScript SDK”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Introduction to Composio”形成一个小中间产物，并等待用户确认。\n- Step 2 / getting-started：Step 2 必须围绕“Getting Started”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture-overview：Step 3 必须围绕“System Architecture”形成一个小中间产物，并等待用户确认。\n- Step 4 / core-concepts：Step 4 必须围绕“Core Concepts”形成一个小中间产物，并等待用户确认。\n- Step 5 / typescript-sdk：Step 5 必须围绕“TypeScript SDK”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/ComposioHQ/composio\n- https://github.com/ComposioHQ/composio#readme\n- .agents/skills/bug-fixing-guide/SKILL.md\n- .agents/skills/building-agents/SKILL.md\n- .agents/skills/building-agents-using-anthropic/SKILL.md\n- .agents/skills/building-agents-using-autogen/SKILL.md\n- .agents/skills/building-agents-using-cloudflare/SKILL.md\n- .agents/skills/building-agents-using-crewai/SKILL.md\n- .agents/skills/building-agents-using-google/SKILL.md\n- .agents/skills/building-agents-using-langchain/SKILL.md\n- .agents/skills/building-agents-using-langgraph/SKILL.md\n- .agents/skills/building-agents-using-llamaindex/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 composio 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github, x。github/github_issue: [Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but fil（https://github.com/ComposioHQ/composio/issues/3422）；github/github_issue: [Feature] Custom auth configs shouldn't require a dev project to use（https://github.com/ComposioHQ/composio/issues/3271）；github/github_issue: [Bug]: CLI - v0.2.25 release missing binary assets — upgrade command sil（https://github.com/ComposioHQ/composio/issues/3269）；github/github_release: @composio/core@0.10.0（https://github.com/ComposioHQ/composio/releases/tag/%40composio/core%400.10.0）；x: Open Claude Cowork: AI Agent Automation Across Desktop & Apps ...（https://x.com/VivekIntel/status/2047603619235779012）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but fil", "url": "https://github.com/ComposioHQ/composio/issues/3422" }, { "kind": "github_issue", "source": "github", "title": "[Feature] Custom auth configs shouldn't require a dev project to use", "url": "https://github.com/ComposioHQ/composio/issues/3271" }, { "kind": "github_issue", "source": "github", "title": "[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command sil", "url": "https://github.com/ComposioHQ/composio/issues/3269" }, { "kind": "github_release", "source": "github", "title": "@composio/core@0.10.0", "url": "https://github.com/ComposioHQ/composio/releases/tag/%40composio/core%400.10.0" }, { "kind": "searxng_indexed", "source": "x", "title": "Open Claude Cowork: AI Agent Automation Across Desktop & Apps ...", "url": "https://x.com/VivekIntel/status/2047603619235779012" } ], "status": "已收录 5 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "工具连接与集成", "desc": "Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.", "effort": "安装已验证", "forks": 4554, "icon": "link", "name": "composio 能力包", "risk": "可发布", "slug": "composio", "stars": 28209, "tags": [ "浏览器 Agent", "网页任务自动化", "结构化数据提取", "多角色协作流程", "开源工具" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/ComposioHQ/composio 项目说明书\n\n生成时间：2026-05-15 11:24:53 UTC\n\n## 目录\n\n- [Introduction to Composio](#introduction)\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture-overview)\n- [Core Concepts](#core-concepts)\n- [TypeScript SDK](#typescript-sdk)\n- [Python SDK](#python-sdk)\n- [AI Framework Providers](#providers-integration)\n- [Toolkits Management](#toolkits-management)\n- [Custom Tools and Toolkits](#custom-tools)\n- [Connected Accounts](#connected-accounts)\n\n\n\n## Introduction to Composio\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#architecture-overview), [Core Concepts](#core-concepts)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/ComposioHQ/composio/blob/main/README.md)\n- [ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n- [ts/packages/cli/src/commands/root-help.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts)\n- [ts/packages/cli/src/commands/$default.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/$default.cmd.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [python/providers/claude_agent_sdk/README.md](https://github.com/ComposioHQ/composio/blob/main/python/providers/claude_agent_sdk/README.md)\n
\n\n# Introduction to Composio\n\n## Overview\n\nComposio is a comprehensive platform for managing Python and TypeScript projects that enables AI agents to interact with external tools and services. It provides a unified interface for tool execution, toolkit management, and agent integration across multiple AI frameworks.\n\n**资料来源：[ts/packages/cli/src/commands/$default.cmd.ts:7]()\n\n```typescript\nexport const $defaultCmd = Command.make('composio', { logLevel }).pipe(\n Command.withDescription(\n `Composio CLI - A tool for managing Python and TypeScript composio.dev projects.`\n )\n);\n```\n\n## Core Architecture\n\nComposio operates through a layered architecture that separates concerns between the CLI interface, core SDK, provider system, and tool execution layer.\n\n```mermaid\ngraph TD\n A[User/Agent] --> B[Composio CLI]\n B --> C[Core SDK]\n C --> D[Providers]\n D --> E[Tool Execution Layer]\n E --> F[External Services]\n \n G[Python SDK] --> C\n H[TypeScript SDK] --> C\n```\n\n### SDK Components\n\n| Component | Language | Purpose |\n|-----------|----------|---------|\n| Core SDK | TypeScript | Central tool management and execution |\n| Python SDK | Python | Python-native integration |\n| CLI | TypeScript | Command-line interface for tool management |\n| Providers | TypeScript/Python | Framework-specific integrations |\n\n**资料来源：[ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n\n## Composio CLI\n\nThe Composio CLI is the primary interface for managing tools, executing actions, and administering projects. It provides commands for both runtime operations and development workflows.\n\n**资料来源：[ts/packages/cli/src/commands/root-help.ts:1-50](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts)\n\n### Primary Commands\n\n| Command | Description |\n|---------|-------------|\n| `composio execute` | Execute a tool with specified parameters |\n| `composio link` | Link a toolkit to the current project |\n| `composio tools list` | List available tools from a toolkit |\n| `composio tools info` | Get detailed information about a specific tool |\n| `composio triggers list` | List available triggers |\n| `composio triggers info` | Get detailed information about a trigger |\n| `composio orgs switch` | Switch between organizations |\n\n**资料来源：[ts/packages/cli/src/services/command-hints.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts)\n\n### Development Commands\n\nThe CLI includes a dedicated `dev` namespace for development workflows:\n\n| Command | Description |\n|---------|-------------|\n| `composio dev init` | Initialize a new Composio project |\n| `composio dev playground-execute` | Execute tools in playground mode |\n| `composio dev logs tools` | View tool execution logs |\n| `composio dev logs triggers` | View trigger execution logs |\n| `composio dev toolkits list` | List available toolkits |\n| `composio dev toolkits info` | Get toolkit information |\n| `composio dev toolkits search` | Search for toolkits |\n| `composio dev toolkits version` | Manage toolkit versions |\n\n**资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n\n## Tool Execution Flow\n\nTools in Composio follow a structured execution pipeline that handles permission requests, parameter validation, and result processing.\n\n```mermaid\ngraph TD\n A[User Request] --> B[CLI Command]\n B --> C{Auth Required?}\n C -->|Yes| D[Permission Request]\n C -->|No| E[Execute Tool]\n D --> F{Permission Granted?}\n F -->|Session| E\n F -->|Once| E\n F -->|Deny| G[Abort]\n E --> H[Tool Execution]\n H --> I[Return Result]\n I --> J[Log Execution]\n```\n\n**资料来源：[ts/packages/cli/src/services/tool-permissions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/tool-permissions.ts)\n\n## Provider System\n\nComposio uses a provider-based architecture to support different AI frameworks and agent implementations. Providers wrap tools with framework-specific logic and execution handlers.\n\n**资料来源：[ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n\n### Provider Types\n\n#### Non-Agentic Providers\n\nNon-agentic providers provide basic tool wrapping without autonomous decision-making:\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise;\n async getTools(modifiers?: SchemaModifiersParams): Promise;\n async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise;\n}\n```\n\n#### Agentic Providers\n\nAgentic providers support autonomous agent behavior with extended capabilities:\n\n```typescript\nclass AgenticProvider extends BaseAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise;\n async getTools(modifiers?: ModifiersParams): Promise;\n // Additional execution handlers for autonomous behavior\n}\n```\n\n**资料来源：[ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n\n### Creating New Providers\n\nTo create a new provider, use the CLI scripts:\n\n```bash\n# Create a non-agentic provider (default)\npnpm run create-provider \n\n# Create an agentic provider\npnpm run create-provider --agentic\n```\n\nThe script creates a new provider with the following structure:\n\n```\n/\n├── src/\n│ └── index.ts # Provider implementation\n├── package.json # Package configuration\n├── tsconfig.json # TypeScript configuration\n├── tsup.config.ts # Build configuration\n└── README.md # Provider documentation\n```\n\n**资料来源：[ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n\n## Session Management\n\nEach CLI session operates within an isolated environment, providing secure and organized execution contexts.\n\n```mermaid\ngraph TD\n A[CLI Session Start] --> B[Create Session Directory]\n B --> C[Initialize Session State]\n C --> D[Execute Commands]\n D --> E[Store Artifacts]\n E --> F[Log History]\n D --> G{Command Type}\n G -->|run| H[Create Artifacts in cwd]\n G -->|execute| I[Download Attachments]\n```\n\n**资料来源：[ts/packages/cli/src/commands/root-help.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts)\n\n### Session Artifacts\n\nEach CLI session gets a unique subdirectory, scoped to your working directory, which stores:\n\n- Session history\n- Files created during `run` and `execute` commands\n- Downloaded attachments\n- Generated outputs\n\nUse `composio artifacts cwd` to print the path for the current directory's session.\n\n## SDK Integration\n\nComposio provides SDKs for both Python and TypeScript, enabling integration with various AI frameworks.\n\n**资料来源：[python/providers/claude_agent_sdk/README.md](https://github.com/ComposioHQ/composio/blob/main/python/providers/claude_agent_sdk/README.md)\n\n### Python SDK Example\n\n```python\nimport asyncio\nfrom composio import Composio\nfrom composio_claude_agent_sdk import ClaudeAgentSDKProvider\nfrom claude_agent_sdk import query, ClaudeAgentOptions\n\n# Initialize Composio with the Claude Code Agents provider\ncomposio = Composio(provider=ClaudeAgentSDKProvider())\n\nasync def main():\n # Get tools from Composio\n tools = composio.tools.get(\n user_id=\"default\",\n toolkits=[\"gmail\"],\n )\n \n # Create an MCP server configuration with the tools\n mcp_server = composio.provider.create_mcp_server(tools)\n```\n\n**资料来源：[python/providers/claude_agent_sdk/README.md](https://github.com/ComposioHQ/composio/blob/main/python/providers/claude_agent_sdk/README.md)\n\n## Environment Configuration\n\nComposio supports various environment variables for configuration:\n\n| Variable | Description |\n|----------|-------------|\n| `COMPOSIO_API_KEY` | Your Composio API key |\n| `COMPOSIO_BASE_URL` | Custom API base URL (optional) |\n| `COMPOSIO_LOG_LEVEL` | Logging level: silent, error, warn, info, debug |\n| `COMPOSIO_DISABLE_TELEMETRY` | Disable telemetry when set to \"true\" |\n| `COMPOSIO_TOOLKIT_VERSION_` | Specific version for a toolkit |\n| `DEVELOPMENT` | Development mode flag |\n| `CI` | CI environment flag |\n\n**资料来源：[ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n\n## Project Initialization\n\nTo initialize a new Composio project:\n\n```bash\ncd \ncomposio dev init\n```\n\nThe initialization process:\n\n1. Creates a `.env.local` file in the project directory\n2. Sets up the project API key by fetching session information\n3. Validates the connection to Composio services\n\n**资料来源：[ts/packages/cli/src/commands/init.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/init.cmd.ts)\n\n## Error Handling\n\nComposio uses a structured error handling system based on the Effect framework:\n\n```typescript\nexport const captureErrorsFrom = (cause: Cause): readonly PrettyError[] =>\n reduceWithContext(cause, undefined, {\n emptyCase: (): readonly PrettyError[] => [],\n dieCase: (_, unknownError) => [parseError(unknownError)],\n failCase: (_, error) => [parseError(error)],\n interruptCase: () => [],\n parallelCase: (_, l, r) => [...l, ...r],\n sequentialCase: (_, l, r) => [...l, ...r],\n });\n```\n\n**资料来源：[ts/packages/cli/src/effect-errors/logic/errors/capture-errors-from-cause.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effect-errors/logic/errors/capture-errors-from-cause.ts)\n\n## Local Tools\n\nComposio supports local tool execution through the `cli-local-tools` package, which provides a registry of locally available tools independent of remote API calls.\n\n```typescript\nexport const isLocalToolSlug = (\n toolSlug: string,\n options: { readonly declarations?: ReadonlyArray } = {}\n): boolean => {\n const upper = toolSlug.toUpperCase();\n if (!upper.startsWith(LOCAL_TOOL_PREFIX)) return false;\n return (\n resolveLocalTool(toolSlug, { includeUnsupported: true, declarations: options.declarations }) !==\n null\n );\n};\n```\n\n**资料来源：[ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n\n## Documentation Generation\n\nThe Python SDK includes automated documentation generation using Griffe:\n\n```bash\ncd python\nuv run --with griffe python scripts/generate-docs.py\n```\n\nThis process:\n1. Extracts docstrings from `composio/**/*.py` → structured data\n2. Transforms data → MDX files\n3. Outputs written to `docs/content/reference/sdk-reference/python/`\n\n**资料来源：[python/scripts/README.md](https://github.com/ComposioHQ/composio/blob/main/python/scripts/README.md)\n\n## Further Reading\n\n- [SDK Documentation Generator](https://github.com/ComposioHQ/composio/blob/main/python/scripts/README.md)\n- [Release Process Documentation](https://github.com/ComposioHQ/composio/blob/main/ts/docs/internal/release.md)\n- [Contributing Guide](https://github.com/ComposioHQ/composio/blob/main/CONTRIBUTING.md)\n- [Official Documentation](https://docs.composio.dev)\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Introduction to Composio](#introduction), [TypeScript SDK](#typescript-sdk), [Python SDK](#python-sdk)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/docs/getting-started.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/getting-started.md)\n- [ts/packages/core/src/composio.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/composio.ts)\n- [python/composio/sdk.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/sdk.py)\n- [ts/examples/tool-router/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/examples/tool-router/src/index.ts)\n- [python/examples/tool_router/tools.py](https://github.com/ComposioHQ/composio/blob/main/python/examples/tool_router/tools.py)\n- [ts/packages/cli/src/commands/init.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/init.cmd.ts)\n- [ts/packages/cli/src/services/terminal-ui.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/terminal-ui.ts)\n
\n\n# Getting Started\n\n## Overview\n\nComposio is a platform that provides a unified interface for managing and executing tools across multiple agent frameworks. The Getting Started guide provides developers with the essential steps to install, configure, and begin using Composio SDK in their projects. Whether you're using TypeScript/JavaScript or Python, this guide covers the complete setup process from installation through your first tool execution.\n\n## Installation\n\n### TypeScript/JavaScript SDK\n\nInstall the Composio SDK using your preferred package manager:\n\n```bash\n# Using npm\nnpm install @composio/core\n\n# Using pnpm\npnpm add @composio/core\n\n# Using yarn\nyarn add @composio/core\n```\n\n### Python SDK\n\nInstall the Python SDK using pip:\n\n```bash\npip install composio-core\n```\n\n### CLI Installation\n\nThe Composio CLI provides tools for managing toolkits, executing tools locally, and inspecting execution logs. Install globally for command-line access:\n\n```bash\n# Using npm\nnpm install -g @composio/cli\n\n# Using bun (recommended)\nbun install -g @composio/cli\n```\n\n## Environment Configuration\n\n### API Key Setup\n\nComposio requires API key authentication. Set up your environment variables before using the SDK:\n\n```bash\n# Required\nexport COMPOSIO_API_KEY=\"your-api-key-here\"\n\n# Optional: Custom API base URL\nexport COMPOSIO_BASE_URL=\"https://api.composio.dev\"\n\n# Optional: Logging level (silent, error, warn, info, debug)\nexport COMPOSIO_LOG_LEVEL=\"info\"\n\n# Optional: Disable telemetry\nexport COMPOSIO_DISABLE_TELEMETRY=\"true\"\n```\n\n### Project Initialization\n\nFor TypeScript projects, initialize Composio in your working directory:\n\n```bash\ncomposio init\n```\n\nThe initialization process:\n\n1. Creates a `.composio` directory in your project\n2. Generates a `.env.local` file with your project API key\n3. Sets up local tool configurations\n4. Validates your API credentials\n\n```typescript\n// Example: composio.ts initialization\nimport { Composio } from \"@composio/core\";\n\nconst client = new Composio({\n apiKey: process.env.COMPOSIO_API_KEY,\n baseURL: process.env.COMPOSIO_BASE_URL,\n});\n```\n\n资料来源：[ts/packages/core/src/composio.ts:1-50]()\n\n## SDK Initialization\n\n### TypeScript SDK\n\nInitialize the Composio client with configuration options:\n\n```typescript\nimport { Composio } from \"@composio/core\";\n\n// Basic initialization\nconst client = new Composio();\n\n// With explicit configuration\nconst client = new Composio({\n apiKey: \"your-api-key\",\n baseURL: \"https://api.composio.dev\",\n logLevel: \"info\",\n timeout: 30000,\n});\n```\n\n资料来源：[ts/packages/core/src/composio.ts:50-80]()\n\n### Python SDK\n\nInitialize the Python client:\n\n```python\nfrom composio import Composio\n\n# Basic initialization\nclient = Composio()\n\n# With explicit configuration\nclient = Composio(\n api_key=\"your-api-key\",\n base_url=\"https://api.composio.dev\",\n log_level=\"info\",\n timeout=30\n)\n```\n\n资料来源：[python/composio/sdk.py:1-100]()\n\n## Core Concepts\n\n### Tools\n\nTools are the fundamental building blocks in Composio. Each tool represents a specific action that can be executed through the platform.\n\n```typescript\n// Get available tools\nconst tools = await client.tools.list();\n\n// Get a specific tool by slug\nconst tool = await client.tools.get(\"github_create_issue\");\n```\n\n### Toolkits\n\nToolkits are collections of related tools organized by service or functionality:\n\n```typescript\n// List available toolkits\nconst toolkits = await client.toolkits.list();\n\n// Get tools within a toolkit\nconst githubTools = await client.toolkits.get(\"github\");\n```\n\n### Actions\n\nActions are specific operations that can be performed using tools:\n\n```typescript\n// Execute a tool action\nconst result = await client.execute(\"github_create_issue\", {\n title: \"Bug report\",\n body: \"Description of the issue\",\n repository: \"owner/repo\"\n});\n```\n\n## Working with Tools\n\n### Listing Available Tools\n\n```typescript\n// List all available tools\nconst allTools = await client.getTools();\n\n// Filter tools by toolkit\nconst slackTools = await client.getTools({ toolkit: \"slack\" });\n\n// Filter tools by search query\nconst searchResults = await client.getTools({ query: \"message\" });\n```\n\n### Executing Tools\n\n```typescript\n// Execute a single tool\nconst result = await client.execute(\"slack_send_message\", {\n channel: \"#general\",\n text: \"Hello from Composio!\"\n});\n```\n\n资料来源：[ts/examples/tool-router/src/index.ts:1-50]()\n\n### Tool Execution Parameters\n\n| Parameter | Type | Description | Required |\n|-----------|------|-------------|----------|\n| `toolSlug` | string | Unique identifier for the tool | Yes |\n| `params` | object | Tool-specific input parameters | Yes |\n| `accountId` | string | Connected account identifier | No |\n| `sessionId` | string | Execution session identifier | No |\n\n## Local Tools (CLI)\n\nThe Composio CLI enables local tool execution for development and testing.\n\n### Local Toolkit Registry\n\n```typescript\nimport { getLocalToolkitDeclarations, getAllLocalToolkitSlugs } from \"@composio/cli\";\n\n// Get all available local toolkits\nconst slugs = getAllLocalToolkitSlugs();\n\n// Check if a toolkit is local\nconst isLocal = isLocalToolkitSlug(\"local_filesystem\");\n```\n\n### Local Tool Execution\n\n```bash\n# Execute a local tool\ncomposio execute local_filesystem_read --path ./README.md\n\n# Get tool schema\ncomposio execute --get-schema\n```\n\n## CLI Commands Reference\n\n### Development Commands\n\n| Command | Description |\n|---------|-------------|\n| `composio dev init` | Initialize a new Composio project |\n| `composio dev playground-execute` | Test tool execution in playground mode |\n| `composio dev logs tools` | View tool execution logs |\n| `composio dev logs triggers` | View trigger execution logs |\n\n### Tool Commands\n\n| Command | Description |\n|---------|-------------|\n| `composio tools list` | List available tools |\n| `composio tools info` | Get detailed tool information |\n| `composio execute` | Execute a specific tool |\n\n### Toolkit Commands\n\n| Command | Description |\n|---------|-------------|\n| `composio toolkits list` | List available toolkits |\n| `composio toolkits info` | Get toolkit details |\n| `composio toolkits search` | Search toolkits |\n| `composio toolkits version` | Manage toolkit versions |\n\n资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts:1-30]()\n\n## Tool Router Pattern\n\nThe tool router enables intelligent routing of agent requests to appropriate tools:\n\n```typescript\nimport { Composio } from \"@composio/core\";\nimport { OpenAI } from \"openai\";\n\nconst client = new Composio();\nconst openai = new OpenAI();\n\nasync function handleAgentRequest(userMessage: string) {\n // Get available tools from Composio\n const tools = await client.getTools({\n filtered_tools: [\"github\", \"slack\", \"jira\"]\n });\n\n // Create a system prompt with tool schemas\n const systemPrompt = `\n You have access to the following tools:\n ${tools.map(t => `- ${t.name}: ${t.description}`).join('\\n')}\n `;\n\n // Process with OpenAI\n const response = await openai.chat.completions.create({\n model: \"gpt-4\",\n messages: [\n { role: \"system\", content: systemPrompt },\n { role: \"user\", content: userMessage }\n ],\n tools: tools.map(tool => tool.schema),\n });\n\n // Execute the selected tool\n if (response.choices[0].message.tool_calls) {\n for (const call of response.choices[0].message.tool_calls) {\n const result = await client.execute(call.function.name, \n JSON.parse(call.function.arguments)\n );\n console.log(\"Tool result:\", result);\n }\n }\n}\n```\n\n资料来源：[ts/examples/tool-router/src/index.ts:50-100]()\n\n## Permission Management\n\nWhen executing tools that require user authentication, Composio provides a permission flow:\n\n```typescript\n// Request permission for tool execution\nconst permission = await client.requestPermission({\n toolSlug: \"github_create_issue\",\n params: {\n title: \"New Issue\",\n body: \"Issue description\"\n }\n});\n\n// Permission states:\n// - pending: Waiting for user approval\n// - approved: Permission granted\n// - denied: Permission rejected\n```\n\n资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-50]()\n\n## Logging and Debugging\n\n### CLI Logging\n\nThe CLI provides structured logging for debugging:\n\n```bash\n# View tool execution logs\ncomposio dev logs tools \n\n# View trigger logs\ncomposio dev logs triggers \n```\n\n### SDK Logging\n\n```typescript\nconst client = new Composio({\n logLevel: \"debug\",\n // Custom logger\n logger: {\n info: (msg) => console.log(`[INFO] ${msg}`),\n error: (msg) => console.error(`[ERROR] ${msg}`),\n debug: (msg) => console.debug(`[DEBUG] ${msg}`),\n }\n});\n```\n\n## Workflow Diagram\n\n```mermaid\ngraph TD\n A[Install SDK] --> B[Set API Key]\n B --> C[Initialize Client]\n C --> D[Get Available Tools]\n D --> E{Choose Toolkit}\n E -->|GitHub| F[GitHub Tools]\n E -->|Slack| G[Slack Tools]\n E -->|Jira| H[Jira Tools]\n F --> I[Execute Tool]\n G --> I\n H --> I\n I --> J[Check Permission]\n J -->|Approved| K[Return Result]\n J -->|Denied| L[Raise Error]\n```\n\n## Next Steps\n\n- **Explore Toolkits**: Browse the available [toolkits documentation](./docs/toolkits.md)\n- **API Reference**: View the complete [SDK API reference](./docs/reference/sdk-reference.md)\n- **Examples**: Check out [example projects](./examples/) for real-world implementations\n- **CLI Commands**: Review the [CLI command reference](./docs/cli-commands.md)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `API key not found` | Set `COMPOSIO_API_KEY` environment variable |\n| `Tool not found` | Verify the toolkit is installed: `composio toolkits list` |\n| `Permission denied` | Run `composio link ` to connect your account |\n| `Timeout error` | Increase timeout in client config or check network connectivity |\n\n### Getting Help\n\n- Documentation: https://docs.composio.dev\n- Discord Community: https://discord.gg/composio\n- GitHub Issues: https://github.com/ComposioHQ/composio/issues\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Introduction to Composio](#introduction), [Core Concepts](#core-concepts), [TypeScript SDK](#typescript-sdk), [Python SDK](#python-sdk)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/core/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/index.ts)\n- [python/composio/__init__.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/__init__.py)\n- [ts/packages/core/src/platform/node.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/platform/node.ts)\n- [ts/packages/core/src/platform/workerd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/platform/workerd.ts)\n- [python/composio/core/models/toolkits.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/toolkits.py)\n
\n\n# System Architecture\n\nComposio is a multi-platform tool integration framework that enables AI agents to interact with external tools and services. The system is architected as a cross-language SDK with TypeScript/JavaScript as the primary implementation and Python bindings, supporting multiple runtime environments including Node.js, Deno, Bun, and Cloudflare Workers (workerd).\n\n## Core Components Overview\n\n```mermaid\ngraph TD\n subgraph \"TypeScript SDK\"\n A[composio-core] --> B[Platform Abstraction]\n B --> C[Node.js Runtime]\n B --> D[workerd Runtime]\n B --> E[Bun Runtime]\n end\n \n subgraph \"Tool Integration\"\n F[Tool Registry] --> G[Toolkits]\n G --> H[Individual Tools]\n end\n \n subgraph \"Providers\"\n I[BaseNonAgenticProvider]\n J[BaseAgenticProvider]\n K[MCP Server]\n end\n \n A --> F\n A --> I\n A --> J\n A --> K\n```\n\nThe system consists of three primary layers:\n\n| Layer | Purpose | Key Files |\n|-------|---------|-----------|\n| **Core SDK** | Platform initialization, API client management | `ts/packages/core/src/index.ts` |\n| **Tool Layer** | Tool registration, toolkit management | `python/composio/core/models/toolkits.py` |\n| **Provider Layer** | External SDK integration (Claude, OpenAI, etc.) | `ts/packages/providers/*/src/index.ts` |\n\n## Platform Abstraction Architecture\n\nComposio implements a platform-agnostic design through a platform abstraction layer that detects and adapts to different JavaScript runtimes.\n\n### Platform Detection\n\nThe platform system uses conditional imports to provide runtime-specific implementations:\n\n```typescript\n// ts/packages/core/src/platform/node.ts\nimport { NodeRuntime } from './implementations/node';\n\nexport const platform = NodeRuntime;\n```\n\n### Supported Platforms\n\n| Platform | Module | Use Case |\n|----------|--------|----------|\n| Node.js | `platform/node.ts` | Server-side applications, CLI tools |\n| workerd | `platform/workerd.ts` | Cloudflare Workers, edge computing |\n| Bun | Bundled with core | High-performance runtime |\n| Deno | Native fetch/http | Deno Deploy, standalone execution |\n\n### Platform Interface Contract\n\nAll platform implementations must provide:\n\n1. **HTTP Client** - Request/response handling\n2. **File System Access** - Local artifact storage\n3. **Environment Variables** - Configuration management\n4. **Console/Logging** - Output handling\n\n## Tool System Architecture\n\n### Tool Classification\n\nTools in Composio are organized hierarchically:\n\n```mermaid\ngraph TD\n A[Toolkit] --> B[Gmail Toolkit]\n A --> C[Slack Toolkit]\n A --> D[GitHub Toolkit]\n \n B --> E[send_email]\n B --> F[read_emails]\n C --> G[send_message]\n D --> H[create_issue]\n```\n\n### Tool Data Model\n\nThe Python toolkit model (`python/composio/core/models/toolkits.py`) defines:\n\n```python\nclass Toolkit:\n slug: str # Unique identifier\n name: str # Display name\n description: str # Human-readable description\n tools: List[Tool] # Contained tools\n triggers: List[Trigger] # Event triggers\n version: str # Version string\n```\n\n### Local vs Remote Tools\n\nComposio distinguishes between local and remote tool execution:\n\n| Type | Execution Location | Registry |\n|------|-------------------|----------|\n| Remote Tools | Composio Cloud API | `composio-tools` |\n| Local Tools | Client-side execution | `cli-local-tools` |\n\nLocal tools are registered via `LocalToolkitDeclaration` and execute directly on the client, supporting multiple platforms (Node.js, workerd, Bun).\n\n## Provider System Architecture\n\n### Provider Types\n\n```mermaid\ngraph TD\n A[BaseComposioProvider] --> B[BaseNonAgenticProvider]\n A --> C[BaseAgenticProvider]\n \n B --> D[Custom Non-Agentic Providers]\n C --> E[Claude Agent SDK Provider]\n C --> F[OpenAI Provider]\n C --> G[Custom Agentic Providers]\n```\n\n### Provider Interface\n\nNon-agentic providers implement:\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise;\n async getTools(modifiers?: SchemaModifiersParams): Promise;\n async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise;\n}\n```\n\nAgentic providers extend with execution handling:\n\n```typescript\nclass AgenticProvider extends BaseAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise;\n async getTools(modifiers?: ModifiersParams): Promise;\n async execute(toolSlug: string, params: any): Promise;\n}\n```\n\n### MCP Server Integration\n\nProviders can create MCP (Model Context Protocol) server configurations:\n\n```python\nmcp_server = composio.provider.create_mcp_server(tools)\n```\n\nThis enables interoperability with any MCP-compatible client.\n\n## SDK Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Composio\n participant Platform\n participant API\n \n User->>Composio: Composio(config)\n Composio->>Platform: detectRuntime()\n Platform-->>Composio: RuntimeType\n Composio->>API: initializeClient(apiKey, baseURL)\n API-->>Composio: Authenticated client\n Composio-->>User: SDK instance ready\n```\n\n### TypeScript Initialization\n\n```typescript\n// ts/packages/core/src/index.ts\nimport { Composio } from \"@composio/core\";\n\nconst client = new Composio({\n apiKey: process.env.COMPOSIO_API_KEY,\n baseURL: \"https://api.composio.dev\"\n});\n```\n\n### Python Initialization\n\n```python\n# python/composio/__init__.py\nfrom composio import Composio\n\nclient = Composio(\n api_key=os.getenv(\"COMPOSIO_API_KEY\")\n)\n```\n\n## CLI Architecture\n\nThe Composio CLI is built using the Effect framework for functional command handling:\n\n### Command Structure\n\n| Command | Purpose |\n|---------|---------|\n| `composio execute` | Execute a tool directly |\n| `composio tools list` | List available tools |\n| `composio tools info` | Get tool details |\n| `composio generate ts` | Generate TypeScript types |\n| `composio dev init` | Initialize development environment |\n| `composio dev playground-execute` | Test tool execution |\n\n### Core Dependency Management\n\nThe CLI detects project environments and suggests appropriate installation commands:\n\n```mermaid\ngraph TD\n A[Project Detection] --> B{Python vs JS?}\n B -->|Python| C[Detect Package Manager]\n B -->|JS| D[Detect Package Manager]\n C --> E[uv pip install composio]\n D --> F[npm install @composio/core]\n```\n\n## Toolkit Index Generation\n\nThe TypeScript SDK generates type-safe toolkit indices for compile-time safety:\n\n```mermaid\ngraph LR\n A[Toolkit Definitions] --> B[createToolkitIndex]\n B --> C[Type-safe Enum]\n C --> D[Tool Wrappers]\n```\n\nThe `createToolkitIndex` function transforms raw toolkit data into structured indices with version overrides and type-safe tool accessors.\n\n## Configuration and Environment\n\n### Environment Variables\n\n| Variable | Purpose | Default |\n|----------|---------|---------|\n| `COMPOSIO_API_KEY` | Authentication key | Required |\n| `COMPOSIO_BASE_URL` | API endpoint | `api.composio.dev` |\n| `COMPOSIO_LOG_LEVEL` | Logging verbosity | `info` |\n| `COMPOSIO_DISABLE_TELEMETRY` | Opt-out of telemetry | `false` |\n| `COMPOSIO_TOOLKIT_VERSION_` | Toolkit version override | `latest` |\n\n### Project-Scoped Configuration\n\nThe CLI creates `.env.local` files scoped to working directories for session management and project-specific API keys.\n\n## Error Handling Architecture\n\nComposio uses the Effect library for typed error handling:\n\n```typescript\nconst captureErrorsFrom = (cause: Cause): readonly PrettyError[] =>\n reduceWithContext(cause, undefined, {\n emptyCase: () => [],\n failCase: (_, error) => [parseError(error)],\n interruptCase: () => [],\n // ...\n });\n```\n\nThis provides structured error reporting with context preservation across asynchronous operations.\n\n## Data Flow: Tool Execution\n\n```mermaid\ngraph TD\n A[User Code] --> B[Composio Client]\n B --> C[Tool Request]\n C --> D{Local or Remote?}\n D -->|Local| E[Local Toolkit Registry]\n D -->|Remote| F[Composio API]\n E --> G[Direct Execution]\n F --> H[API Validation]\n H --> I[Remote Execution]\n I --> J[Result Return]\n G --> J\n J --> K[Response Processing]\n K --> A\n```\n\n## Extension Points\n\n### Creating Custom Providers\n\nDevelopers can create new providers using the provided scaffolding:\n\n```bash\n# Non-agentic provider\npnpm create:provider my-provider\n\n# Agentic provider with execution handlers\npnpm create:provider my-provider --agentic\n```\n\nThis generates the standard provider structure with required methods pre-scaffolded.\n\n### Local Tool Development\n\nLocal tools can be registered in `cli-local-tools/src/registry.ts` with platform-specific execution logic.\n\n## Security Model\n\n### Tool Permissions\n\nTool execution requires user consent, managed through a browser-based permission flow:\n\n1. Tool execution request triggers permission check\n2. Browser UI presents allow/deny options\n3. Decision is cached for session or one-time use\n4. Token-based verification prevents CSRF attacks\n\n### API Key Management\n\n- **User API Keys**: Global authentication tokens\n- **Project API Keys**: Scoped to specific projects\n- **Environment Variables**: `.env.local` for development\n\n## Summary\n\nComposio's architecture provides:\n\n1. **Cross-platform support** through runtime detection and abstraction\n2. **Type-safe tool access** via generated TypeScript indices\n3. **Provider flexibility** with extensible provider interfaces\n4. **Local execution** for tools that don't require cloud API calls\n5. **Permission management** with session-scoped authorization\n6. **CLI tooling** for development and tool management\n\nThe system balances convenience (automatic platform detection) with flexibility (custom providers and local tools), making it suitable for both production deployments and development workflows.\n\n---\n\n\n\n## Core Concepts\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture-overview), [Toolkits Management](#toolkits-management), [Connected Accounts](#connected-accounts)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n- [ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [ts/packages/cli/src/effects/toolkit-version-overrides.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts)\n- [ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n
\n\n# Core Concepts\n\nComposio is a platform that provides a collection of tools and toolkits for AI agents. Understanding the core concepts is essential for effectively using and extending Composio. This page covers the fundamental building blocks: Tools, Toolkits, Connected Accounts, and the Provider system.\n\n## Toolkits\n\nToolkits are collections of related tools that enable AI agents to perform actions within specific domains. Each toolkit focuses on a particular service or functionality area, such as Gmail, Slack, GitHub, or Google Calendar.\n\n### Toolkit Structure\n\nA toolkit consists of:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `slug` | `string` | Unique identifier for the toolkit |\n| `name` | `string` | Human-readable name |\n| `description` | `string` | Description of the toolkit's functionality |\n| `tools` | `Tool[]` | Array of tools included in the toolkit |\n| `platforms` | `LocalCliPlatform[]` | Supported platforms (e.g., linux, darwin, windows) |\n| `source` | `string` | Source of the toolkit |\n| `setup` | `SetupConfig` | Configuration for setting up the toolkit |\n\n### Toolkit Version Management\n\nComposio supports version overrides for toolkits. The version system allows specifying different versions for different toolkits:\n\n```typescript\n// From toolkit-version-overrides.ts\nexport interface ToolkitVersionSpec {\n toolkitSlug: string;\n toolkitVersion: string; // e.g., '20250901_00' or 'latest'\n}\n\nexport type ToolkitVersionOverrides = Map, string>;\n```\n\nThe system groups toolkits by version and builds version maps from specifications:\n\n```mermaid\ngraph TD\n A[ToolkitVersionSpec Array] --> B[groupByVersion]\n B --> C[Map: version -> toolkitSlug[]]\n \n A --> D[buildVersionMapFromSpecs]\n D --> E[ToolkitVersionOverrides Map]\n E --> F[ toolkitSlug -> version]\n```\n\n### Toolkit Discovery Commands\n\nThe CLI provides commands for discovering and inspecting toolkits:\n\n| Command | Description |\n|---------|-------------|\n| `composio toolkits list` | List all available toolkits |\n| `composio toolkits info` | Get detailed information about a specific toolkit |\n| `composio toolkits search` | Search toolkits by keyword |\n| `composio toolkits version` | View and manage toolkit versions |\n\n## Tools\n\nTools are the fundamental execution units in Composio. Each tool represents a specific action that can be performed by an AI agent.\n\n### Tool Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `slug` | `string` | Unique identifier for the tool |\n| `name` | `string` | Human-readable name |\n| `description` | `string` | Description of what the tool does |\n| `inputParams` | `Parameter[]` | Required and optional input parameters |\n| `outputParams` | `Parameter[]` | Output parameters (optional) |\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Composio as Composio Core\n participant Tool as Tool Executor\n participant API as External API\n \n Agent->>Composio: Execute tool(slug, params)\n Composio->>Tool: Create execution context\n Tool->>API: Make API request\n API-->>Tool: API response\n Tool-->>Composio: Formatted result\n Composio-->>Agent: Return result\n```\n\n### Toolkits Index\n\nThe toolkit index organizes all tools by their parent toolkit:\n\n```typescript\n// From create-toolkit-index.ts\nexport interface CreateToolkitIndexInput {\n slug: string;\n version?: string;\n typeableTools:\n | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> }\n | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> };\n triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>;\n}\n\nexport type ToolkitIndex = Record;\n```\n\n## Connected Accounts\n\nConnected Accounts represent authenticated access to external services. They enable tools to interact with user-specific data and perform authorized actions.\n\n### Account Model\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | `string` | Unique identifier for the connection |\n| `toolkit` | `string` | The toolkit this account belongs to |\n| `accountId` | `string` | User account ID on the external service |\n| `accountName` | `string` | Display name for the account |\n| `authConfig` | `AuthConfig` | Authentication configuration |\n| `status` | `ConnectionStatus` | Active, inactive, or error state |\n\n### Authentication Flow\n\n```mermaid\ngraph LR\n A[User] -->|Link Account| B[CLI Command]\n B --> C{Auth Required?}\n C -->|Yes| D[OAuth/Browser Auth]\n D --> E[Token Exchange]\n E --> F[Store Credentials]\n C -->|No| F\n F --> G[Connected Account Created]\n```\n\n## Local CLI Tools\n\nLocal CLI tools are tools that execute locally on the user's machine rather than through the Composio cloud API. They provide additional capabilities for local development and execution.\n\n### Local Toolkit Declaration\n\n```typescript\ninterface LocalToolkitDeclaration {\n slug: string;\n name: string;\n description: string;\n platforms: LocalCliPlatform[];\n tools: LocalToolDeclaration[];\n source: string;\n setup?: SetupConfig;\n}\n```\n\n### Local Tool Registry\n\nThe registry manages local tools and provides functions for toolkit discovery:\n\n```typescript\n// From registry.ts\nexport const getAllLocalToolkitSlugs = (\n options: { readonly declarations?: ReadonlyArray } = {}\n): ReadonlyArray;\n\nexport const isLocalToolkitSlug = (\n toolkitSlug: string | undefined,\n options: { readonly declarations?: ReadonlyArray } = {}\n): boolean;\n\nexport const getLocalCustomToolkits = (\n options: {\n readonly currentPlatform?: LocalCliPlatform;\n readonly toolkits?: ReadonlyArray;\n readonly declarations?: ReadonlyArray;\n } = {}\n): ReadonlyArray;\n```\n\n### Platform Support\n\nLocal tools can specify which platforms they support:\n\n```typescript\ntype LocalCliPlatform = 'linux' | 'darwin' | 'windows';\n```\n\n## Provider System\n\nComposio uses a provider system to wrap and manage tools. Providers add functionality like schema modification and parameter handling.\n\n### Provider Types\n\n```typescript\n// From modifiers.types.ts\nexport type ProviderOptions =\n TProvider extends BaseComposioProvider\n ? TProvider extends BaseAgenticProvider\n ? AgenticToolOptions\n : ToolOptions\n : never;\n```\n\n### Provider Interface\n\nNon-agentic providers must implement:\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n // Wrap a tool with schema modifiers\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise;\n\n // Get all available tools\n async getTools(modifiers?: SchemaModifiersParams): Promise;\n\n // Get a specific tool by slug\n async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise;\n}\n```\n\nAgentic providers extend the interface with additional agentic-specific options.\n\n## Schema Modifiers\n\nSchema modifiers allow providers to transform tool schemas before execution:\n\n```typescript\ninterface SchemaModifiersParams {\n modifySchema?: (context: { schema: z.ZodSchema }) => z.ZodSchema;\n beforeExecute?: (context: { params: Record }) => Record;\n afterExecute?: (context: { result: unknown }) => unknown;\n}\n```\n\n### Modifier Execution Flow\n\n```mermaid\ngraph TD\n A[Raw Tool Schema] --> B[modifySchema]\n B --> C[Modified Schema]\n C --> D[User Params]\n D --> E[beforeExecute]\n E --> F[Processed Params]\n F --> G[Tool Execution]\n G --> H[Raw Result]\n H --> I[afterExecute]\n I --> J[Final Result]\n```\n\n## Tool Permissions\n\nComposio implements a permission system for tool execution, especially for local tools that may have access to sensitive local resources.\n\n### Permission Flow\n\n```mermaid\ngraph TD\n A[Tool Execution Request] --> B{Permission Check}\n B -->|Session Allowed| C[Execute Tool]\n B -->|One-time| D[Prompt User]\n D -->|Allow| C\n D -->|Deny| E[Access Denied]\n B -->|Denied| E\n```\n\n### Permission Options\n\n| Option | Description |\n|--------|-------------|\n| `Allow for this session` | Grants permission for the current session |\n| `Allow once` | Grants permission for a single execution |\n| `Deny` | Denies the execution |\n\n## Error Handling\n\nComposio uses Effect-based error handling for predictable error management:\n\n```typescript\n// From capture-errors-from-cause.ts\nexport const captureErrorsFrom = (cause: Cause): readonly PrettyError[] =>\n reduceWithContext(cause, undefined, {\n emptyCase: (): readonly PrettyError[] => [],\n dieCase: (_, unknownError) => [parseError(unknownError)],\n failCase: (_, error) => [parseError(error)],\n interruptCase: () => [],\n parallelCase: (_, l, r) => [...l, ...r],\n sequentialCase: (_, l, r) => [...l, ...r],\n });\n```\n\n## Summary\n\nThe Composio architecture is built on several interconnected concepts:\n\n| Concept | Role |\n|---------|------|\n| **Toolkits** | Organize related tools by domain |\n| **Tools** | Individual executable units with defined inputs/outputs |\n| **Connected Accounts** | Authenticated access to external services |\n| **Local CLI Tools** | Locally executed tools that extend cloud capabilities |\n| **Providers** | Wrap and enhance tools with additional functionality |\n| **Schema Modifiers** | Transform tool schemas and execution contexts |\n| **Permissions** | Control access to tool execution |\n\nTogether, these concepts provide a flexible and extensible system for AI agent tool integration.\n\n---\n\n\n\n## TypeScript SDK\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [AI Framework Providers](#providers-integration), [Getting Started](#getting-started)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts)\n- [ts/packages/core/scripts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/scripts/README.md)\n- [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [ts/packages/ts-builders/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/ts-builders/README.md)\n- [ts/packages/cli/src/commands/generate/generate.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/generate/generate.cmd.ts)\n- [ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n- [ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n- [ts/packages/cli/src/effects/validate-toolkit-versions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/validate-toolkit-versions.ts)\n- [ts/packages/core/src/models/Tools.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/Tools.ts)\n
\n\n# TypeScript SDK\n\nThe Composio TypeScript SDK provides a comprehensive toolkit for integrating third-party services and tools into AI agent applications. It enables developers to programmatically interact with tools, manage toolkits, execute actions, and handle file operations across multiple platforms.\n\n## Overview\n\nThe SDK is organized as a monorepo under `ts/` containing multiple packages that work together to provide a complete development experience:\n\n| Package | Purpose |\n|---------|---------|\n| `@composio/core` | Core SDK functionality, API clients, and tool management |\n| `@composio/cli` | Command-line interface for project management and generation |\n| `@composio/cli-local-tools` | Local tool execution and toolkit registry |\n| `@composio/ts-builders` | TypeScript AST generation utilities |\n| `@composio/providers` | Base provider implementations |\n\n资料来源：[ts/README.md]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Developer Application] --> B[@composio/core]\n B --> C[ComposioToolkitsRepository]\n B --> D[ToolRouter]\n B --> E[Files Module]\n \n C --> F[Composio API]\n \n G[@composio/cli] --> H[generate command]\n H --> I[TypeScript Type Stubs]\n H --> J[transpiled JS]\n \n G --> K[execute command]\n K --> L[LocalToolRegistry]\n L --> M[Tool Execution]\n \n N[Providers] --> B\n N --> O[BaseNonAgenticProvider]\n N --> P[BaseAgenticProvider]\n```\n\nThe SDK follows a layered architecture where the core package handles all API interactions while the CLI provides tooling support for project setup and execution.\n\n资料来源：[ts/packages/ts-builders/README.md]()\n资料来源：[ts/packages/cli/src/commands/generate/generate.cmd.ts]()\n\n## Core Components\n\n### Composio Client\n\nThe main entry point for interacting with the Composio platform:\n\n```typescript\nimport { Composio } from '@composio/core';\n\nconst client = new Composio({\n apiKey: process.env.COMPOSIO_API_KEY,\n baseUrl: process.env.COMPOSIO_BASE_URL, // optional\n});\n```\n\nThe client provides access to:\n- `tools` - Tool listing and retrieval\n- `toolkits` - Toolkit management\n- `execute` - Direct tool execution\n- `files` - File upload and management\n\n### Tool Management\n\nTools are fetched and wrapped using providers that modify their schemas and execution behavior:\n\n```typescript\n// Get all tools\nconst tools = await client.tools.list();\n\n// Get tools with type safety\nconst typedTools = await client.tools.list({\n type: 'typed',\n filterParams: { tags: ['github'] }\n});\n\n// Get a specific tool\nconst tool = await client.tools.get('default', 'GITHUB_GET_REPOS');\n```\n\n资料来源：[ts/packages/core/src/models/Tools.ts]()\n资料来源：[ts/packages/core/src/types/modifiers.types.ts]()\n\n### Provider System\n\nProviders enable integration with different AI frameworks and modify tool behavior:\n\n#### Non-Agentic Providers\n\nFor frameworks that handle tool execution externally:\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\n\nclass CustomProvider extends BaseNonAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise {\n if (modifiers?.schema) {\n return modifiers.schema(toolSlug, tool);\n }\n return tool;\n }\n\n async getTools(modifiers?: SchemaModifiersParams): Promise {\n const response = await this.client.getTools();\n return Promise.all(response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers)));\n }\n}\n```\n\n#### Agentic Providers\n\nFor frameworks requiring full control over execution:\n\n```typescript\nimport { BaseAgenticProvider } from '@composio/core';\n\nclass AgenticProvider extends BaseAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise;\n async getTools(modifiers?: ModifiersParams): Promise;\n}\n```\n\n资料来源：[ts/packages/providers/README.md]()\n\n### Modifiers System\n\nSchema and execution modifiers allow runtime customization of tool behavior:\n\n```typescript\nconst tools = await composio.tools.list('default', {\n modifySchema: (toolSlug, toolkitSlug, schema) => {\n return { ...schema, description: 'Custom description' };\n },\n beforeExecute: (toolSlug, toolkitSlug, params) => params,\n afterExecute: (toolSlug, toolkitSlug, result) => result\n});\n```\n\n资料来源：[ts/packages/core/src/types/modifiers.types.ts]()\n资料来源：[ts/packages/core/src/models/Tools.ts]()\n\n## CLI Commands\n\n### Type Stub Generation\n\nThe `composio generate ts` command generates TypeScript type definitions:\n\n```bash\n# Generate with transpiled JS (default when no --output-dir)\ncomposio generate ts\n\n# Specify output directory\ncomposio generate ts --output-dir ./types\n\n# Compact single module output\ncomposio generate ts --compact\n\n# Filter by specific toolkits\ncomposio generate ts --toolkits github --toolkits slack\n```\n\n#### Command Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--compact` | Emit a single module file | `false` |\n| `--transpiled` | Also emit ESM JavaScript files | `true` (if no `--output-dir`) |\n| `--output-dir` | Output directory path | `node_modules/@composio/core` |\n| `--toolkits` | Filter to specific toolkits | All toolkits |\n\n**Invariants:**\n- `--output-dir` cannot refer to a path inside `node_modules`\n- Without `--output-dir`, files are written to `@composio/core` in `node_modules`\n- If `--transpiled` is `true`, sources are transpiled to ESM JavaScript alongside TypeScript files (CJS not supported)\n\n资料来源：[ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts]()\n\n### Tool Execution\n\n```bash\n# Execute a tool\ncomposio execute \"GITHUB_GET_REPOS\" -d '{}'\n\n# Get tool schema\ncomposio execute \"GITHUB_GET_REPOS\" --get-schema\n\n# Dry run\ncomposio execute \"GITHUB_GET_REPOS\" -d '{}' --dry-run\n```\n\n### Tool Information\n\n```bash\n# View tool details\ncomposio tools info \"GITHUB_GET_REPOS\"\n\n# List tools in a toolkit\ncomposio tools list \"github\"\n```\n\n资料来源：[ts/packages/cli/src/commands/tools/commands/tools.info.cmd.ts]()\n资料来源：[ts/packages/cli/src/services/command-hints.ts]()\n\n## Local Tools\n\nThe CLI supports local tool execution through the `cli-local-tools` package:\n\n```typescript\nimport { getLocalCustomToolkits, isLocalToolSlug } from '@composio/cli-local-tools';\n\n// Check if a slug is a local tool\nif (isLocalToolSlug('LOCAL_MY_TOOL')) {\n // Handle local tool\n}\n\n// Get all local toolkits\nconst toolkits = getLocalCustomToolkits({\n currentPlatform: 'linux',\n toolkits: ['my-toolkit']\n});\n```\n\n### Toolkit Readiness\n\nCheck platform compatibility and readiness status:\n\n```typescript\nimport { getReadinessReport } from '@composio/cli-local-tools';\n\nconst report = await getReadinessReport({\n currentPlatform: detectCliPlatform(),\n toolkits: ['github', 'slack']\n});\n```\n\nStatus values:\n- `ready` - Toolkit and tools fully supported\n- `disabled` - Disabled via `~/composio/local_tools.json`\n- `unsupported` - Platform not supported by toolkit\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts]()\n资料来源：[ts/packages/cli-local-tools/src/readiness.ts]()\n\n## Toolkit Index\n\nThe SDK creates a toolkit index for efficient tool and trigger type lookup:\n\n```typescript\nimport { createToolkitIndex } from '@composio/cli/src/generation/create-toolkit-index';\n\ntype ToolkitIndex = Record;\n```\n\nThe index maps toolkit names to their tools and trigger types, enabling fast lookups by slug prefix matching.\n\n资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts]()\n\n## Environment Configuration\n\n| Variable | Description |\n|----------|-------------|\n| `COMPOSIO_API_KEY` | API key for Composio services |\n| `COMPOSIO_BASE_URL` | Custom API base URL (optional) |\n| `COMPOSIO_LOG_LEVEL` | Logging level: `silent`, `error`, `warn`, `info`, `debug` |\n| `COMPOSIO_DISABLE_TELEMETRY` | Set to `\"true\"` to disable telemetry |\n| `COMPOSIO_TOOLKIT_VERSION_` | Specific version for a toolkit (e.g., `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`) |\n| `DEVELOPMENT` | Development mode flag |\n| `CI` | CI environment flag |\n\n资料来源：[ts/README.md]()\n\n## Version Validation\n\nThe CLI validates toolkit version overrides against the API:\n\n```typescript\nimport { validateToolkitVersionOverrides } from '@composio/cli/src/effects/validate-toolkit-versions';\n\nconst { validatedOverrides, warnings } = yield* client\n .validateToolkitVersions(versionOverrides, toolkitSlugsFilter);\n```\n\nInvalid versions are caught and reported with helpful error messages including correct toolkit slug format guidance.\n\n资料来源：[ts/packages/cli/src/effects/validate-toolkit-versions.ts]()\n\n## SDK Documentation Generation\n\nDocumentation is auto-generated from TypeScript source using TypeDoc:\n\n```bash\npnpm generate:docs\n```\n\n**Process:**\n1. TypeDoc extracts JSDoc from `src/models/*.ts` → JSON AST\n2. `generate-docs.ts` transforms AST → MDX files\n3. Output written to `docs/content/reference/sdk-reference/typescript/`\n\n**Configuration:**\n- Entry points: Auto-discovered from `src/models/*.ts`\n- Excluded classes: `INTERNAL_CLASSES` set in script\n- User-instantiated classes: `USER_INSTANTIATED_CLASSES` (shows constructor)\n\n资料来源：[ts/packages/core/scripts/README.md]()\n\n## Provider Creation\n\nCreate new providers using the provided script:\n\n```bash\n# Non-agentic provider (default)\npnpm run create-provider my-provider\n\n# Agentic provider\npnpm run create-provider my-provider --agentic\n```\n\nThe script creates a new provider with structure:\n```\n/\n├── src/index.ts # Provider implementation\n├── package.json # Package configuration\n├── tsconfig.json # TypeScript configuration\n├── tsup.config.ts # Build configuration\n└── README.md # Provider documentation\n```\n\n资料来源：[ts/packages/providers/README.md]()\n\n## Error Handling\n\nThe SDK provides structured error handling through the errors module:\n\n```typescript\nimport { ComposioError, InvalidToolkitVersionsError } from '@composio/core/errors';\n\n// Errors include:\n// - ComposioError: Base error class\n// - InvalidToolkitVersionsError: Version validation failures\n// - InvalidToolkitsError: Invalid toolkit slugs\n// - HttpServerError: API communication errors\n```\n\n资料来源：[ts/packages/core/src/errors/index.ts]()\n\n## Framework Integrations\n\nThe SDK includes pre-built providers for common AI frameworks:\n\n| Provider | Package | Description |\n|----------|---------|-------------|\n| LangChain | `@composio/langchain` | Integration with LangChain agents |\n| Vercel AI | `@composio/vercel` | Integration with Vercel AI SDK |\n\nProvider dependencies:\n```json\n{\n \"@composio/core\": \">=0.10.0 <1.0.0\",\n \"ai\": \"^5.0.0 || ^6.0.0\"\n}\n```\n\n资料来源：[ts/packages/providers/langchain/package.json]()\n资料来源：[ts/packages/providers/vercel/package.json]()\n\n---\n\n\n\n## Python SDK\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#typescript-sdk), [AI Framework Providers](#providers-integration), [Getting Started](#getting-started)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/composio/sdk.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/sdk.py)\n- [python/composio/client/__init__.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/client/__init__.py)\n- [python/composio/client/types.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/client/types.py)\n- [python/composio/core/models/tool_router.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/tool_router.py)\n- [python/composio/core/models/tool_router_session.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/tool_router_session.py)\n- [python/composio/exceptions.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/exceptions.py)\n- [python/examples/tool_router/tools.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/examples/tool_router/tools.py)\n- [python/docs/development.md](https://github.com/ComposioHQ/composio/blob/main/python/docs/development.md)\n
\n\n# Python SDK\n\nThe Composio Python SDK provides a comprehensive interface for integrating external tools and services into AI applications. It enables developers to fetch, configure, and execute tools from the Composio platform while supporting advanced features like schema modification, execution hooks, and MCP (Model Context Protocol) server creation.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Application Code] --> B[Composio SDK]\n B --> C[Tool Client]\n B --> D[Tool Router]\n B --> E[MCP Server]\n C --> F[Composio API]\n D --> F\n E --> F\n G[Schema Modifiers] --> B\n H[Execution Modifiers] --> B\n I[Providers] --> B\n```\n\nThe SDK is structured around several core components that work together to provide a seamless integration experience. The primary entry point is the `Composio` class, which orchestrates all tool-related operations including fetching tools from the API, managing local tool configurations, and handling execution with modifiers. 资料来源：[python/composio/sdk.py:1-100]()\n\n## Core Components\n\n### Composio Main Class\n\nThe `Composio` class serves as the central interface for SDK operations. It handles initialization, tool retrieval, and configuration management through a fluent API design.\n\n```python\nfrom composio import Composio\n\ncomposio = Composio(\n api_key=\"your-api-key\",\n base_url=\"https://api.composio.dev\",\n timeout=60,\n max_retries=3,\n allow_tracking=True,\n file_download_dir=\"./downloads\",\n provider=OpenAIProvider(),\n toolkit_versions={\"github\": \"12202025_01\"}\n)\n```\n\n资料来源：[python/README.md:1-50]()\n\n### Tool Client\n\nThe tool client module (`composio/client/__init__.py`) manages all interactions with tools, including retrieval, filtering, and execution. It provides a typed interface for working with tools and toolkits through the types defined in `client/types.py`. 资料来源：[python/composio/client/__init__.py:1-50]()\n\n### Type System\n\nThe SDK uses Pydantic models for type safety and validation. All tool schemas, parameters, and return types are strongly typed through the `Tool` and related classes in `client/types.py`. 资料来源：[python/composio/client/types.py:1-100]()\n\n## Configuration\n\n### Initialization Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `api_key` | `str` | Environment `COMPOSIO_API_KEY` | Your Composio API key |\n| `base_url` | `str` | `\"https://api.composio.dev\"` | Custom API base URL |\n| `timeout` | `int` | `60` | Request timeout in seconds |\n| `max_retries` | `int` | `3` | Maximum retry attempts |\n| `allow_tracking` | `bool` | `True` | Enable/disable telemetry |\n| `file_download_dir` | `str` | `\"./downloads\"` | Directory for file downloads |\n| `provider` | `Provider` | `OpenAIProvider()` | Custom provider instance |\n| `toolkit_versions` | `dict` | `{}` | Specific toolkit versions |\n\n资料来源：[python/composio/sdk.py:50-100]()\n\n### Environment Variables\n\nThe SDK automatically reads several environment variables for configuration:\n\n| Variable | Description |\n|----------|-------------|\n| `COMPOSIO_API_KEY` | Primary API authentication key |\n| `COMPOSIO_BASE_URL` | Override default API endpoint |\n| `COMPOSIO_WORKING_DIR` | Session working directory |\n| `COMPOSIO_LOG_LEVEL` | Logging level (silent, error, warn, info, debug) |\n| `COMPOSIO_TOOLKIT_VERSION_` | Version for specific toolkit |\n| `DEVELOPMENT` | Development mode flag |\n| `CI` | CI environment flag |\n\n资料来源：[python/README.md:100-150]()\n\n## Tool Management\n\n### Retrieving Tools\n\n```python\n# Get all tools from a specific toolkit\ntools = composio.tools.get(\n user_id=\"default\",\n toolkits=[\"gmail\", \"github\"]\n)\n\n# Get a specific tool by slug\ntool = composio.tools.get(\n user_id=\"default\",\n slug=\"GITHUB_CREATE_ISSUE\"\n)\n```\n\n资料来源：[python/README.md:50-80]()\n\n### Tool Structure\n\nTools in the Composio SDK follow a standardized structure that includes:\n\n- **Slug**: Unique identifier for the tool\n- **Name**: Human-readable display name\n- **Description**: Detailed explanation of tool functionality\n- **Parameters**: JSON schema for input validation\n- **Toolkit**: Parent toolkit grouping\n- **Triggers**: Associated trigger configurations\n\n资料来源：[python/composio/client/types.py:50-100]()\n\n## Schema Modifiers\n\nSchema modifiers allow transformation of tool schemas before they are used by AI models. This enables customization of parameter descriptions, adding defaults, or restructuring schemas.\n\n```mermaid\ngraph LR\n A[Raw Tool Schema] --> B[Schema Modifier Function]\n B --> C[Modified Schema]\n C --> D[AI Model / Tool Execution]\n```\n\n### Usage Example\n\n```python\nfrom composio import schema_modifier\nfrom composio.types import Tool\n\n@schema_modifier(tools=[\"HACKERNEWS_GET_USER\"])\ndef modify_schema(tool: str, toolkit: str, schema: Tool) -> Tool:\n schema[\"description\"] = \"Enhanced HackerNews user lookup with additional features\"\n schema[\"parameters\"][\"properties\"][\"include_karma\"] = {\n \"type\": \"boolean\",\n \"description\": \"Include user karma in response\",\n \"default\": True\n }\n return schema\n\n# Apply modifier when retrieving tools\ntools = composio.tools.get(\n user_id=\"default\",\n slug=\"HACKERNEWS_GET_USER\",\n modifiers=[modify_schema]\n)\n```\n\n资料来源：[python/README.md:80-120]()\n\n## Execution Modifiers\n\nExecution modifiers provide hooks for transforming tool execution behavior. They come in two flavors: `before_execute` and `after_execute`.\n\n```mermaid\ngraph TD\n A[Tool Call Request] --> B[Before Execute Hook]\n B --> C{Continue?}\n C -->|Yes| D[Execute Tool]\n C -->|No| E[Return Modified Response]\n D --> F[After Execute Hook]\n F --> G[Final Response]\n```\n\n### Before Execute Hook\n\n```python\nfrom composio import before_execute\n\n@before_execute(tools=[\"GITHUB_CREATE_ISSUE\"])\ndef validate_issue_input(tool: str, toolkit: str, params: dict) -> dict:\n # Validate or transform parameters before execution\n if \"title\" in params and len(params[\"title\"]) > 100:\n params[\"title\"] = params[\"title\"][:97] + \"...\"\n return params\n```\n\n### After Execute Hook\n\n```python\nfrom composio import after_execute\n\n@after_execute(tools=[\"GITHUB_CREATE_ISSUE\"])\ndef log_issue_creation(tool: str, toolkit: str, params: dict, response: dict) -> dict:\n # Post-process the response\n print(f\"Issue created: {response.get('html_url')}\")\n return response\n```\n\n资料来源：[python/README.md:120-180]()\n\n## Tool Router (Experimental)\n\nThe Tool Router is an experimental feature that enables intelligent tool routing and session management. It provides capabilities for dynamic tool selection, retry logic, and stateful interactions.\n\n```mermaid\ngraph TD\n A[User Request] --> B[Tool Router]\n B --> C[Session Manager]\n C --> D{Route Decision}\n D -->|Tool A| E[Execute Tool A]\n D -->|Tool B| F[Execute Tool B]\n E --> G[Response Handler]\n F --> G\n G --> H[User Response]\n```\n\n### Tool Router Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `base_url` | `str` | Composio API base URL |\n| `api_key` | `str` | API authentication key |\n| `tool_calls_max_concurrency` | `int` | Maximum concurrent tool calls |\n| `default_language` | `str` | Default language for responses |\n\n资料来源：[python/composio/core/models/tool_router.py:1-100]()\n\n### Tool Router Session\n\nThe session management system (`tool_router_session.py`) maintains state across multiple tool interactions, enabling complex multi-step workflows:\n\n```python\nfrom composio.core.models.tool_router_session import ToolRouterSession\n\nsession = ToolRouterSession(\n user_id=\"user123\",\n session_id=\"session456\",\n tool_calls=[]\n)\n```\n\n资料来源：[python/composio/core/models/tool_router_session.py:1-50]()\n\n### Tool Definitions\n\nCustom tool definitions can be provided to the Tool Router for specialized behavior:\n\n```python\nfrom composio.core.models.tool_router import ToolDefinition\n\ntools = [\n ToolDefinition(\n name=\"custom_tool\",\n description=\"A custom tool implementation\",\n parameters={\"type\": \"object\", \"properties\": {}}\n )\n]\n```\n\n资料来源：[python/examples/tool_router/tools.py:1-50]()\n\n## MCP (Model Context Protocol) Support\n\nThe SDK provides native MCP server creation for seamless integration with Claude, Cursor, and other MCP-compatible tools.\n\n```mermaid\ngraph LR\n A[Composio SDK] --> B[MCP Server]\n B --> C[Claude Desktop]\n B --> D[Cursor]\n B --> E[Other MCP Clients]\n```\n\n### Creating an MCP Server\n\n```python\nfrom composio import Composio\n\ncomposio = Composio()\n\n# Create MCP server with specified toolkits\nmcp_server = composio.mcp.create(\n \"my-mcp-server\",\n toolkits=[\"github\", \"gmail\"],\n manually_manage_connections=False\n)\n\n# Generate server instance for a user\nserver_instance = mcp_server.generate(\"user123\")\nprint(f\"MCP Server URL: {server_instance['url']}\")\n```\n\n资料来源：[python/README.md:200-230]()\n\n## Error Handling\n\nThe SDK defines specific exception types for different error scenarios, enabling precise error handling in application code.\n\n```python\nfrom composio import Composio\nfrom composio.exceptions import ComposioError, ApiKeyNotProvidedError\n\ntry:\n composio = Composio() # Will raise ApiKeyNotProvidedError if no API key\n tools = composio.tools.get(user_id=\"default\", toolkits=[\"github\"])\nexcept ApiKeyNotProvidedError:\n print(\"Please provide your COMPOSIO_API_KEY\")\nexcept ComposioError as e:\n print(f\"Composio error: {e}\")\n```\n\n### Exception Hierarchy\n\n| Exception | Base Class | Description |\n|-----------|------------|-------------|\n| `ComposioError` | `Exception` | Base exception for all SDK errors |\n| `ApiKeyNotProvidedError` | `ComposioError` | API key missing or invalid |\n| `ToolNotFoundError` | `ComposioError` | Requested tool does not exist |\n| `ToolkitNotFoundError` | `ComposioError` | Requested toolkit not available |\n| `ConnectionError` | `ComposioError` | Network connectivity issues |\n| `TimeoutError` | `ComposioError` | Request exceeded timeout |\n\n资料来源：[python/composio/exceptions.py:1-50]()\n\n## Supported AI Frameworks\n\nThe SDK provides dedicated integrations for popular AI frameworks:\n\n| Framework | Description | Provider Class |\n|-----------|-------------|----------------|\n| OpenAI | Direct integration with OpenAI's API | `OpenAIProvider()` |\n| LangChain | Tools and agents for LangChain workflows | `LangChainProvider()` |\n| LangGraph | State machine workflows | `LangGraphProvider()` |\n| CrewAI | Multi-agent systems | `CrewAIProvider()` |\n| AutoGen | Microsoft's AutoGen framework | `AutoGenProvider()` |\n| Anthropic | Claude integration | `AnthropicProvider()` |\n| Google AI | Gemini and Google AI services | `GoogleAIProvider()` |\n| LlamaIndex | RAG and data framework | `LlamaIndexProvider()` |\n\n```python\nfrom composio import Composio\nfrom composio_providers import OpenAIProvider\n\ncomposio = Composio(provider=OpenAIProvider())\n```\n\n资料来源：[python/README.md:180-200]()\n\n## Development and Testing\n\n### Development Setup\n\nFor local development, ensure you have the required dependencies installed:\n\n```bash\ncd python\nuv sync\n```\n\n### Integration Testing\n\nIntegration tests are located in `python/composio/integration_test/` and require a valid Composio API key:\n\n```bash\nexport COMPOSIO_API_KEY=\"your_api_key_here\"\npytest python/composio/integration_test/ -v\n```\n\n资料来源：[python/composio/integration_test/README.md:1-30]()\n\n### Available Test Modules\n\n| Test File | Coverage |\n|-----------|----------|\n| `test_mcp.py` | MCP functionality and server creation |\n| `test_tool_router.py` | Tool Router experimental features |\n\n## Quick Start Example\n\n```python\nfrom composio import Composio\nfrom composio_claude_agent_sdk import ClaudeAgentSDKProvider\n\n# Initialize with a provider\ncomposio = Composio(provider=ClaudeAgentSDKProvider())\n\n# Get tools from specific toolkits\ntools = composio.tools.get(\n user_id=\"default\",\n toolkits=[\"gmail\", \"github\"]\n)\n\n# Create MCP server configuration\nmcp_server = composio.provider.create_mcp_server(tools)\n\n# Tools are now available to your AI agent\n```\n\n资料来源：[python/providers/claude_agent_sdk/README.md:1-50]()\n\n## Best Practices\n\n1. **API Key Management**: Store your API key in environment variables rather than hardcoding\n2. **Timeout Configuration**: Adjust timeout based on expected tool execution times\n3. **Error Handling**: Always wrap SDK calls in try-except blocks for graceful degradation\n4. **Modifier Usage**: Apply schema and execution modifiers at initialization for consistent behavior\n5. **Tool Filtering**: Use specific toolkits rather than fetching all tools to reduce latency\n\n---\n\n\n\n## AI Framework Providers\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#typescript-sdk), [Python SDK](#python-sdk), [Core Concepts](#core-concepts)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/providers/openai/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/openai/src/index.ts)\n- [ts/packages/providers/anthropic/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/anthropic/src/index.ts)\n- [ts/packages/providers/langchain/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/langchain/src/index.ts)\n- [ts/packages/providers/llamaindex/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/llamaindex/src/index.ts)\n- [python/providers/openai/composio_openai/provider.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/openai/composio_openai/provider.py)\n- [python/providers/langchain/composio_langchain/provider.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/langchain/composio_langchain/provider.py)\n- [python/providers/crewai/composio_crewai/providers.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/crewai/composio_crewai/providers.py)\n- [ts/docs/providers/custom.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/providers/custom.md)\n- [ts/docs/api/providers.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/api/providers.md)\n
\n\n# AI Framework Providers\n\n## Overview\n\nAI Framework Providers are adapter layers that integrate Composio's tool ecosystem with various AI agent frameworks. They act as bridges between Composio's standardized tool definitions and the specific formats expected by different AI SDKs and frameworks such as OpenAI, Anthropic Claude Code, LangChain, LlamaIndex, and CrewAI.\n\nProviders enable agents to:\n- Access Composio tools in their native format\n- Transform tool schemas for framework-specific requirements\n- Handle tool execution with custom modifiers\n- Create MCP (Model Context Protocol) servers from Composio tool definitions\n\n资料来源：[ts/docs/api/providers.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/api/providers.md)\n\n## Architecture\n\n### Provider Hierarchy\n\n```mermaid\ngraph TD\n A[BaseComposioProvider] --> B[BaseNonAgenticProvider]\n A --> C[BaseAgenticProvider]\n B --> D[OpenAIProvider]\n B --> E[AnthropicProvider]\n B --> F[LangChainProvider]\n B --> G[LlamaIndexProvider]\n C --> H[ClaudeAgentSDKProvider]\n C --> I[VercelProvider]\n```\n\n### Data Flow\n\n```mermaid\ngraph LR\n A[Composio SDK] -->|Tool Requests| B[Provider]\n B -->|Schema Transform| C[Framework-Specific Format]\n C --> D[AI Agent/Framework]\n D -->|Execution| E[Modifier Chain]\n E -->|Result| F[Response Transform]\n F -->|ToolExecuteResponse| A\n```\n\n## Provider Types\n\n### Non-Agentic Providers\n\nNon-agentic providers wrap tools for frameworks that handle tool execution externally. They focus on schema transformation without managing execution flow.\n\n**Available Non-Agentic Providers:**\n\n| Provider | Package | Framework |\n|----------|---------|-----------|\n| OpenAIProvider | `@composio/openai` | OpenAI SDK |\n| AnthropicProvider | `@composio/anthropic` | Anthropic SDK |\n| LangChainProvider | `@composio/langchain` | LangChain |\n| LlamaIndexProvider | `@composio/llamaindex` | LlamaIndex |\n\n资料来源：[ts/packages/providers/openai/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/openai/src/index.ts)\n\n**Core Interface:**\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: SchemaModifiersParams\n ): Promise;\n\n async getTools(\n modifiers?: SchemaModifiersParams\n ): Promise;\n\n async getToolBySlug(\n slug: string,\n modifiers?: SchemaModifiersParams\n ): Promise;\n}\n```\n\n资料来源：[ts/docs/providers/custom.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/providers/custom.md)\n\n### Agentic Providers\n\nAgentic providers manage both schema transformation and execution flow. They support before/after execute modifiers for full control over tool behavior.\n\n**Core Interface:**\n\n```typescript\nclass AgenticProvider extends BaseAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: ModifiersParams\n ): Promise;\n\n async getTools(\n modifiers?: ModifiersParams\n ): Promise;\n\n async getToolBySlug(\n slug: string,\n modifiers?: ModifiersParams\n ): Promise;\n}\n```\n\n资料来源：[ts/docs/providers/custom.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/providers/custom.md)\n\n**Available Agentic Providers:**\n\n| Provider | Package | Framework |\n|----------|---------|-----------|\n| ClaudeAgentSDKProvider | `@composio/claude-agent-sdk` | Claude Code Agents SDK |\n| VercelProvider | `@composio/vercel` | Vercel AI SDK |\n\n## Core Methods\n\n### wrapTool\n\nTransforms a single tool with optional modifiers for framework-specific formatting.\n\n```typescript\nasync wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: SchemaModifiersParams\n): Promise\n```\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| toolSlug | `string` | Unique identifier for the tool |\n| tool | `Tool` | The tool definition to wrap |\n| modifiers | `SchemaModifiersParams` | Optional schema transformation functions |\n\n**Returns:** `Promise` - The transformed tool\n\n### getTools\n\nRetrieves all available tools, optionally filtered by toolkit and transformed with modifiers.\n\n```typescript\nasync getTools(\n modifiers?: SchemaModifiersParams\n): Promise\n```\n\n### getToolBySlug\n\nRetrieves a specific tool by its slug identifier.\n\n```typescript\nasync getToolBySlug(\n slug: string,\n modifiers?: SchemaModifiersParams\n): Promise\n```\n\n资料来源：[ts/packages/providers/openai/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/openai/src/index.ts)\n\n## Modifiers System\n\nModifiers enable runtime transformation of tool schemas and execution behavior.\n\n### Schema Modifiers\n\nTransform tool schemas before they are used by the agent:\n\n```typescript\ntype schemaModifier = (\n toolSlug: string,\n tool: Tool\n) => Tool;\n```\n\n### Execution Modifiers\n\nControl tool execution flow:\n\n```typescript\ntype beforeExecuteModifier = (\n toolSlug: string,\n params: Record\n) => Record;\n\ntype afterExecuteModifier = (\n toolSlug: string,\n response: ToolExecuteResponse\n) => ToolExecuteResponse;\n```\n\n### Modifier Application Flow\n\n```mermaid\ngraph TD\n A[Request Tool] --> B{Modifier Chain}\n B --> C[Schema Modifier]\n C --> D[Before Execute Modifier]\n D --> E[Tool Execution]\n E --> F[After Execute Modifier]\n F --> G[Return Response]\n```\n\n资料来源：[ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n\n## Python Providers\n\n### OpenAI Provider\n\n```python\nfrom composio_openai import ComposioOpenAI\n\nclient = ComposioOpenAI(api_key=\"your-api-key\")\n\n# Get tools\ntools = client.tools.get()\n\n# Execute a tool\nresult = client.tools.execute(\n action=\"HACKERNEWS_GET_USER\",\n params={\"username\": \"user123\"}\n)\n```\n\n资料来源：[python/providers/openai/composio_openai/provider.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/openai/composio_openai/provider.py)\n\n### LangChain Provider\n\n```python\nfrom composio_langchain import ComposioToolkit, Action\n\n# Initialize with LangChain adapter\ntoolkit = ComposioToolkit(\n actions=[Action.HACKERNEWS_GET_USER]\n)\n\n# Get LangChain tools\nlangchain_tools = toolkit.get_tools()\n```\n\n资料来源：[python/providers/langchain/composio_langchain/provider.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/langchain/composio_langchain/provider.py)\n\n### CrewAI Provider\n\n```python\nfrom composio_crewai import ComposioTool, Action\nfrom crewai import Agent\n\n# Create Composio tool for CrewAI\ncomposio_tool = ComposioTool(\n action=Action.HACKERNEWS_GET_USER\n)\n\n# Attach to CrewAI agent\nagent = Agent(\n role=\"Researcher\",\n goal=\"Fetch user data\",\n tools=[composio_tool]\n)\n```\n\n资料来源：[python/providers/crewai/composio_crewai/providers.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/crewai/composio_crewai/providers.py)\n\n## TypeScript Provider Implementation\n\n### OpenAI Provider\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\nimport type { Tool, SchemaModifiersParams } from '@composio/core';\n\nexport class OpenAIProvider extends BaseNonAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: SchemaModifiersParams\n ): Promise {\n if (modifiers?.schema) {\n return modifiers.schema(toolSlug, tool);\n }\n return tool;\n }\n\n async getTools(modifiers?: SchemaModifiersParams): Promise {\n const response = await this.client.getTools();\n return Promise.all(\n response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers))\n );\n }\n\n async getToolBySlug(\n slug: string,\n modifiers?: SchemaModifiersParams\n ): Promise {\n const response = await this.client.getToolBySlug(slug);\n return this.wrapTool(slug, response.data, modifiers);\n }\n}\n```\n\n资料来源：[ts/packages/providers/openai/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/openai/src/index.ts)\n\n### Anthropic Provider\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\nimport type { Tool, SchemaModifiersParams } from '@composio/core';\n\nexport class AnthropicProvider extends BaseNonAgenticProvider {\n // Similar implementation to OpenAIProvider\n // Framework-specific adaptations applied in wrapTool\n}\n```\n\n资料来源：[ts/packages/providers/anthropic/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/anthropic/src/index.ts)\n\n### LlamaIndex Provider\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\nimport type { Tool, SchemaModifiersParams } from '@composio/core';\n\nexport class LlamaIndexProvider extends BaseNonAgenticProvider {\n // LlamaIndex-specific implementation\n}\n```\n\n资料来源：[ts/packages/providers/llamaindex/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/llamaindex/src/index.ts)\n\n## Creating Custom Providers\n\n### Project Structure\n\n```\nmy-provider/\n├── src/\n│ └── index.ts # Provider implementation\n├── package.json # Package configuration\n├── tsconfig.json # TypeScript configuration\n├── tsup.config.ts # Build configuration\n└── README.md # Provider documentation\n```\n\n### Generation Command\n\n```bash\n# Non-agentic provider (default)\npnpm create:provider my-provider\n\n# Agentic provider\npnpm create:provider my-provider --agentic\n```\n\n### Required Methods\n\n#### For Non-Agentic Providers\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\nimport type { Tool, SchemaModifiersParams } from '@composio/core';\n\nexport class MyProvider extends BaseNonAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: SchemaModifiersParams\n ): Promise {\n // Apply schema modifiers if provided\n if (modifiers?.schema) {\n return modifiers.schema(toolSlug, tool);\n }\n return tool;\n }\n\n async getTools(\n modifiers?: SchemaModifiersParams\n ): Promise {\n const response = await this.client.getTools();\n return Promise.all(\n response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers))\n );\n }\n\n async getToolBySlug(\n slug: string,\n modifiers?: SchemaModifiersParams\n ): Promise {\n const response = await this.client.getToolBySlug(slug);\n return this.wrapTool(slug, response.data, modifiers);\n }\n}\n```\n\n#### For Agentic Providers\n\n```typescript\nimport { BaseAgenticProvider } from '@composio/core';\nimport type { Tool, ModifiersParams, ToolExecuteResponse } from '@composio/core';\n\nexport class MyAgenticProvider extends BaseAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: ModifiersParams\n ): Promise {\n if (modifiers?.schema) {\n return modifiers.schema(toolSlug, tool);\n }\n return tool;\n }\n\n async getTools(\n modifiers?: ModifiersParams\n ): Promise {\n const response = await this.client.getTools();\n return Promise.all(\n response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers))\n );\n }\n\n async getToolBySlug(\n slug: string,\n modifiers?: ModifiersParams\n ): Promise {\n const response = await this.client.getToolBySlug(slug);\n return this.wrapTool(slug, response.data, modifiers);\n }\n}\n```\n\n## Best Practices\n\n### Type Safety\n\nAlways use TypeScript and ensure proper type definitions for all methods and parameters. Leverage the existing type definitions from `@composio/core`:\n\n```typescript\nimport type { \n Tool, \n SchemaModifiersParams, \n ModifiersParams,\n ToolExecuteResponse \n} from '@composio/core';\n```\n\n### Error Handling\n\nImplement proper error handling for API calls and tool execution:\n\n```typescript\nasync getTools(modifiers?: SchemaModifiersParams): Promise {\n try {\n const response = await this.client.getTools();\n return response.data;\n } catch (error) {\n throw new ComposioProviderError(\n `Failed to fetch tools: ${error.message}`,\n { cause: error }\n );\n }\n}\n```\n\n### Modifier Support\n\n- **Non-agentic providers**: Implement schema modifiers to transform tool schemas\n- **Agentic providers**: Implement both schema and execution modifiers for full control\n\n### Testing\n\nWrite comprehensive tests covering:\n- Tool wrapping with and without modifiers\n- Error scenarios for API failures\n- Edge cases in modifier application\n- Framework-specific format compliance\n\n## Provider Options\n\nProvider behavior can be configured through `ProviderOptions`:\n\n```typescript\ntype ProviderOptions =\n TProvider extends BaseComposioProvider\n ? TProvider extends BaseAgenticProvider\n ? AgenticToolOptions\n : ToolOptions\n : never;\n```\n\n| Option Type | Use Case |\n|------------|----------|\n| `ToolOptions` | Non-agentic providers |\n| `AgenticToolOptions` | Agentic providers with execution control |\n\n资料来源：[ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n\n## Summary\n\nAI Framework Providers are essential integration layers that enable Composio tools to work seamlessly with various AI agent frameworks. They provide:\n\n- **Abstraction**: Unified interface for diverse AI frameworks\n- **Transformation**: Schema adaptation for framework-specific formats\n- **Extensibility**: Custom provider creation for unsupported frameworks\n- **Control**: Modifier system for runtime behavior customization\n\nThe provider architecture supports both simple schema wrapping (non-agentic) and full execution control (agentic), making it adaptable to a wide range of AI framework requirements.\n\n---\n\n\n\n## Toolkits Management\n\n### 相关页面\n\n相关主题：[Custom Tools and Toolkits](#custom-tools), [Core Concepts](#core-concepts), [AI Framework Providers](#providers-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/core/src/models/Toolkits.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/Toolkits.ts)\n- [ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n- [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/cli-local-tools/src/readiness.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/readiness.ts)\n- [ts/packages/cli/src/effects/toolkit-version-overrides.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts)\n- [ts/packages/cli/src/effects/validate-toolkit-versions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/validate-toolkit-versions.ts)\n- [ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts)\n
\n\n# Toolkits Management\n\n## Overview\n\nToolkits Management is the system responsible for organizing, discovering, and configuring collections of tools and triggers within Composio. Toolkits serve as the fundamental unit of organization for functionality, grouping related tools under a common namespace with shared metadata, versioning, and configuration options.\n\nThe management system encompasses both **remote toolkits** (hosted and managed by Composio) and **local toolkits** (user-defined or third-party tools executed locally via the CLI). This dual approach provides flexibility for different use cases while maintaining a consistent interface for tool execution and configuration.\n\n资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts:1-16]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Toolkits Management] --> B[Remote Toolkits]\n A --> C[Local Toolkits]\n \n B --> B1[Toolkit Index]\n B --> B2[Version Overrides]\n B --> B3[Validation]\n \n C --> C1[Registry]\n C --> C2[Readiness Check]\n C --> C3[Configuration]\n \n B1 --> D[createToolkitIndex]\n B2 --> E[buildVersionMapFromSpecs]\n B3 --> F[validateToolkitVersions]\n \n C1 --> G[getLocalCustomToolkits]\n C2 --> H[LocalToolkitReadiness]\n C3 --> I[localToolsCmd$Configure]\n```\n\n### Core Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| Toolkit Index | Groups tools/triggers by toolkit name | `ts/packages/cli/src/generation/create-toolkit-index.ts` |\n| Version Overrides | Manages toolkit version specifications | `ts/packages/cli/src/effects/toolkit-version-overrides.ts` |\n| Version Validation | Validates toolkit versions against API | `ts/packages/cli/src/effects/validate-toolkit-versions.ts` |\n| Local Registry | Manages local toolkit declarations | `ts/packages/cli-local-tools/src/registry.ts` |\n| Readiness Check | Determines toolkit availability status | `ts/packages/cli-local-tools/src/readiness.ts` |\n| Configuration | Handles toolkit/tool configuration | `ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts` |\n\n## Toolkit Discovery (CLI Commands)\n\nThe Composio CLI provides a comprehensive set of commands for toolkit discovery under the `toolkits` command group.\n\n资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts:14-23]()\n\n### Available Commands\n\n```bash\ncomposio toolkits \n```\n\n| Command | Description |\n|---------|-------------|\n| `list` | List available toolkits |\n| `info` | Display detailed information about a specific toolkit |\n| `search` | Search for toolkits by name or keywords |\n| `version` | Manage toolkit version information |\n\n### Command Examples\n\n```bash\n# List all available toolkits\ncomposio toolkits list\n\n# Get info about a specific toolkit\ncomposio toolkits info gmail\n\n# Search for toolkits\ncomposio toolkits search \"email\"\n\n# Check toolkit versions\ncomposio toolkits version\n```\n\n## Toolkit Index System\n\nThe toolkit index is a structured mapping that organizes tools and trigger types by their corresponding toolkit name.\n\n资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:1-30]()\n\n### Data Model\n\n```typescript\ninterface CreateToolkitIndexInput {\n readonly slug: string;\n readonly version?: string;\n readonly typeableTools:\n | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> }\n | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> };\n readonly triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>;\n}\n\ntype ToolkitIndex = Record;\n```\n\n### Index Creation Process\n\n```mermaid\ngraph LR\n A[Input Data] --> B[groupByToolkits]\n B --> C[Record.fromEntries]\n C --> D[stripPrefix]\n D --> E[ToolkitIndex]\n```\n\nThe `createToolkitIndex` function performs the following operations:\n\n1. Groups tools and trigger types by their toolkit prefix\n2. Converts the grouped data to a Record\n3. Strips the toolkit prefix from individual tool/trigger identifiers\n4. Applies version overrides when specified\n\n资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:23-45]()\n\n## Local Toolkit Registry\n\nThe local toolkit registry manages toolkits that are executed locally through the CLI rather than through the Composio API.\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:1-50]()\n\n### Registry Functions\n\n| Function | Purpose |\n|----------|---------|\n| `getAllLocalToolkitSlugs` | Returns all registered local toolkit slugs |\n| `isLocalToolkitSlug` | Checks if a slug corresponds to a local toolkit |\n| `isLocalToolSlug` | Checks if a tool slug is a local tool |\n| `getLocalToolkitDeclarations` | Gets declarations filtered by platform/toolkits |\n| `getLocalCustomToolkits` | Returns CustomToolkit objects for local toolkits |\n\n### Filtering Logic\n\n```typescript\nconst toolkitMatchesFilter = (\n toolkit: LocalToolkitDeclaration,\n requestedToolkits?: ReadonlyArray\n): boolean => {\n if (!requestedToolkits || requestedToolkits.length === 0) return true;\n const requested = new Set(requestedToolkits.map(slug => slug.toLowerCase()));\n return requested.has(toolkit.slug.toLowerCase());\n};\n```\n\nThe filtering is case-insensitive, supporting flexible user input while maintaining consistent internal representation.\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:15-23]()\n\n### Toolkit Declaration Structure\n\nLocal toolkit declarations follow this structure:\n\n```typescript\ninterface LocalToolkitDeclaration {\n slug: string;\n name: string;\n description: string;\n platforms: ReadonlyArray;\n tools: ReadonlyArray;\n source: string;\n setup?: ToolkitSetup;\n}\n```\n\n## Toolkit Readiness Assessment\n\nThe readiness system evaluates whether local toolkits and their tools are available for use based on platform support and configuration state.\n\n资料来源：[ts/packages/cli-local-tools/src/readiness.ts:1-50]()\n\n### Readiness States\n\n| Status | Description |\n|--------|-------------|\n| `ready` | Toolkit and all tools are available |\n| `disabled` | Toolkit is disabled via local_tools.json metadata |\n| `unsupported` | Toolkit platforms do not include current platform |\n\n### Readiness Report Structure\n\n```typescript\ninterface LocalToolkitReadiness {\n slug: string;\n name: string;\n description: string;\n platforms: ReadonlyArray;\n supported: boolean;\n status: 'ready' | 'disabled' | 'unsupported';\n source: string;\n setup?: ToolkitSetup;\n tools: LocalToolReadiness[];\n messages: string[];\n hints: SetupHint[];\n}\n```\n\n### Platform Support Check\n\nThe system detects the current platform and filters toolkits based on platform compatibility:\n\n```typescript\nconst currentPlatform = options.currentPlatform ?? detectCliPlatform();\nreturn declarationsFor(options.declarations)\n .filter(toolkit => supportsCliPlatform(toolkit.platforms, currentPlatform))\n .filter(toolkit => toolkit.tools.length > 0);\n```\n\n## Toolkit Version Management\n\nComposio supports version pinning for toolkits to ensure consistent behavior across environments.\n\n资料来源：[ts/packages/cli/src/effects/toolkit-version-overrides.ts:1-60]()\n\n### Version Specification\n\n```typescript\ninterface ToolkitVersionSpec {\n toolkitSlug: string;\n toolkitVersion: string; // e.g., '20250901_00' or 'latest'\n}\n```\n\n### Grouping by Version\n\n```typescript\nexport const groupByVersion = (\n specs: ReadonlyArray\n): Map[]> => {\n const grouped = new Map[]>();\n for (const spec of specs) {\n const existing = grouped.get(spec.toolkitVersion);\n if (existing) {\n existing.push(spec.toolkitSlug);\n } else {\n grouped.set(spec.toolkitVersion, [spec.toolkitSlug]);\n }\n }\n return grouped;\n};\n```\n\nThis produces a mapping like:\n```\n\"20250901_00\" => [\"gmail\"]\n\"latest\" => [\"slack\", \"github\"]\n```\n\n### Version Map Building\n\n```typescript\nexport const buildVersionMapFromSpecs = (\n specs: ReadonlyArray\n): ToolkitVersionOverrides => {\n const versionMap = new Map, string>();\n for (const spec of specs) {\n if (spec.toolkitVersion !== 'latest') {\n versionMap.set(spec.toolkitSlug, spec.toolkitVersion);\n }\n }\n return versionMap;\n};\n```\n\nNote: 'latest' versions are excluded from the version map since they represent the default behavior.\n\n## Toolkit Version Validation\n\nBefore applying version overrides, the system validates them against the Composio API.\n\n资料来源：[ts/packages/cli/src/effects/validate-toolkit-versions.ts:1-60]()\n\n### Validation Process\n\n```mermaid\ngraph TD\n A[Version Overrides] --> B{validateToolkitVersions}\n B --> C[Check toolkit existence]\n B --> D[Verify version availability]\n C -->|Invalid| E[InvalidToolkitsError]\n D -->|Invalid| F[InvalidToolkitVersionsError]\n C -->|Valid| G[Return validated overrides]\n D -->|Valid| G\n```\n\n### Error Handling\n\n| Error Type | Cause | User Message |\n|------------|-------|--------------|\n| `InvalidToolkitsError` | Toolkit slug doesn't exist | Invalid toolkit(s) specified |\n| `InvalidToolkitVersionsError` | Version doesn't exist for toolkit | Invalid version for specific toolkit |\n| `HttpServerError` | API communication failure | Network or server error |\n\n## Toolkit Configuration\n\nLocal toolkits can be configured through the CLI, allowing users to customize installation commands, enable/disable tools, and manage authentication.\n\n资料来源：[ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts:1-50]()\n\n### Configuration Options\n\n```bash\ncomposio local-tools configure --selector [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `--command` | Override installation command |\n| `--disable` | Disable the toolkit or tool |\n| `--enable` | Enable the toolkit or tool |\n| `--authenticated` | Mark as authenticated |\n| `--unauthenticated` | Mark as not authenticated |\n\n### Metadata Storage\n\nConfiguration is stored in `~/composio/local_tools.json` with the following structure:\n\n```typescript\ninterface LocalToolMetadata {\n disabled?: boolean;\n authenticated?: boolean;\n installation?: {\n command?: string;\n };\n}\n```\n\n### Display Configuration Info\n\nWhen configuring a toolkit or tool, the CLI displays:\n\n```\nName: \nKind: \nPath: \nCommand: \nDisabled: \nAuthenticated: \n```\n\n## Tool Permission System\n\nComposio implements a permission system for tool execution to ensure security and user control.\n\n资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-60]()\n\n### Permission Flow\n\n```mermaid\ngraph TD\n A[Tool Execution Request] --> B{Permission Check}\n B -->|First time| C[Browser Prompt]\n B -->|Previously allowed| D[Execute Tool]\n C --> E[Allow for session]\n C --> F[Allow once]\n C --> G[Deny]\n E --> D\n F --> H[Execute once]\n H --> D\n```\n\n### Permission Decision Types\n\n| Decision | Scope | Persistence |\n|----------|-------|-------------|\n| `ALLOW_SESSION` | All executions in current session | Session-scoped |\n| `ALLOW_ONCE` | Single execution | Single use |\n| `DENY` | Block execution | Single use |\n\n### Browser-based Permission Request\n\nWhen permission is required, a local HTTP server is started on port 127.0.0.1 (configurable) with an HTML interface presenting the three options.\n\n## Integration with TypeScript Generation\n\nThe toolkit system integrates with Composio's TypeScript type generation to provide type-safe tool access.\n\n资料来源：[ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts:1-30]()\n\n### Generation Options\n\n```bash\ncomposio generate ts [options]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--compact` | Emit single module file | false |\n| `--transpiled` | Include transpiled JS | true (if no --output-dir) |\n| `--output-dir` | Output directory | node_modules/@composio/core |\n| `--toolkits` | Filter by toolkit(s) | All toolkits |\n\n### Invariants\n\n- `--output-dir` cannot refer to a path inside `node_modules`\n- If `--output-dir` is not specified, `--transpiled` defaults to true\n- If `--output-dir` is specified, `--transpiled` defaults to false\n\n## Summary\n\nToolkits Management in Composio provides a comprehensive system for organizing and managing tools with the following key capabilities:\n\n1. **Discovery**: CLI commands for listing, searching, and inspecting available toolkits\n2. **Indexing**: Automatic organization of tools and triggers by toolkit prefix\n3. **Local Support**: Registry and execution system for locally-defined toolkits\n4. **Version Control**: Version pinning with validation against the Composio API\n5. **Configuration**: Flexible configuration of toolkit behavior including installation commands and enable/disable states\n6. **Permissions**: Security layer for tool execution with session and one-time permission grants\n7. **Type Safety**: Integration with TypeScript generation for type-safe tool usage\n\nThe architecture separates concerns between remote toolkits (API-managed) and local toolkits (CLI-managed), while providing a unified interface for tool execution and configuration.\n\n---\n\n\n\n## Custom Tools and Toolkits\n\n### 相关页面\n\n相关主题：[Toolkits Management](#toolkits-management), [Core Concepts](#core-concepts)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n- [ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n- [ts/packages/cli/src/services/command-hints.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n- [ts/packages/cli/src/effects/toolkit-version-overrides.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts)\n- [ts/packages/cli-local-tools/src/readiness.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/readiness.ts)\n- [ts/packages/cli/src/services/tool-permissions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/tool-permissions.ts)\n- [ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts)\n- [ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts)\n- [ts/packages/cli/src/effects/validate-toolkit-versions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/validate-toolkit-versions.ts)\n- [ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts)\n
\n\n# Custom Tools and Toolkits\n\n## Overview\n\nCustom Tools and Toolkits are the fundamental building blocks in Composio that enable agents to interact with external services and perform specific actions. A **Custom Tool** represents a single executable action with defined input parameters and output schemas, while a **Custom Toolkit** is a collection of related tools grouped under a common namespace.\n\nThe Composio framework provides both TypeScript (`@composio/core`) and Python (`composio-core`) SDKs for defining, creating, and managing custom tools and toolkits. This architecture allows developers to extend Composio's capabilities by creating specialized tools for their specific use cases.\n\n资料来源：[ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n\n## Architecture\n\n### High-Level Architecture\n\n```mermaid\ngraph TD\n A[Developer] --> B[Custom Tool Definition]\n B --> C[CustomTool Instance]\n C --> D[CustomToolkit Container]\n D --> E[Composio Client]\n E --> F[Tool Execution Engine]\n \n G[Agent] --> E\n E --> H[Tool Response]\n H --> G\n```\n\n### Component Hierarchy\n\n```mermaid\ngraph TD\n A[CustomToolkit] --> B[Tool 1]\n A --> C[Tool 2]\n A --> D[Tool N]\n \n B --> E[Name]\n B --> F[Description]\n B --> G[InputParams]\n B --> H[OutputParams]\n B --> I[Execute Function]\n \n E --> J[slug]\n J --> K[displayName]\n```\n\n## Custom Tool Structure\n\n### TypeScript Implementation\n\nCustom tools in TypeScript are created using the `createCustomTool` factory function, which accepts a tool slug and a configuration object.\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:65-79](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n\n```typescript\nconst toCustomTool = (\n toolkit: LocalToolkitDeclaration,\n tool: LocalToolDeclaration,\n currentPlatform: LocalCliPlatform\n) =>\n createCustomTool(tool.slug, {\n name: tool.name,\n description: descriptionWithPlatform(tool.description, tool.platforms),\n inputParams: tool.inputParams,\n ...(tool.outputParams ? { outputParams: tool.outputParams } : {}),\n execute: async input =>\n executeLocalTool(tool.execution, input as Record, {\n toolkit,\n tool,\n finalSlug: normalizeLocalToolSlug(tool.slug, toolkit.slug),\n platform: currentPlatform,\n }),\n });\n```\n\n### Tool Properties\n\n| Property | Type | Required | Description |\n|----------|------|----------|-------------|\n| `slug` | `string` | Yes | Unique identifier for the tool |\n| `name` | `string` | Yes | Human-readable display name |\n| `description` | `string` | Yes | Detailed explanation of tool functionality |\n| `inputParams` | `Parameter[]` | No | Array of input parameter definitions |\n| `outputParams` | `Parameter[]` | No | Array of output parameter definitions |\n| `execute` | `Function` | Yes | Async function that performs the tool action |\n| `triggers` | `Trigger[]` | No | Event triggers associated with the tool |\n\n### Input/Output Parameters\n\nParameters define the schema for tool inputs and outputs using a structured format:\n\n```typescript\ninterface Parameter {\n name: string; // Parameter identifier\n type: 'string' | 'number' | 'boolean' | 'object' | 'array';\n description: string; // Human-readable explanation\n required: boolean; // Whether the parameter is mandatory\n default?: any; // Optional default value\n enum?: string[]; // For restricted value sets\n}\n```\n\n## Custom Toolkit Structure\n\n### Creating a Toolkit\n\nToolkits group related tools under a common namespace and platform context.\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:81-88](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n\n```typescript\nconst toCustomToolkit = (\n toolkit: LocalToolkitDeclaration,\n currentPlatform: LocalCliPlatform\n): CustomToolkit =>\n createCustomToolkit(toolkit.slug, {\n name: toolkit.name,\n description: descriptionWithPlatform(toolkit.description, toolkit.platforms),\n tools: toolkit.tools.map(tool => toCustomTool(toolkit, tool, currentPlatform)),\n });\n```\n\n### Toolkit Properties\n\n| Property | Type | Required | Description |\n|----------|------|----------|-------------|\n| `slug` | `string` | Yes | Unique toolkit identifier |\n| `name` | `string` | Yes | Display name for the toolkit |\n| `description` | `string` | Yes | Toolkit documentation |\n| `tools` | `CustomTool[]` | Yes | Collection of tools in this toolkit |\n| `platforms` | `LocalCliPlatform[]` | Yes | Supported platforms (e.g., linux, darwin, windows) |\n\n## Toolkit Discovery and Filtering\n\n### Filtering by Platform\n\nComposio provides functions to filter toolkits and tools based on the current platform:\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:55-63](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n\n```typescript\nconst toolkitMatchesFilter = (\n toolkit: LocalToolkitDeclaration,\n requestedToolkits?: ReadonlyArray\n): boolean => {\n if (!requestedToolkits || requestedToolkits.length === 0) return true;\n const requested = new Set(requestedToolkits.map(slug => slug.toLowerCase()));\n return requested.has(toolkit.slug.toLowerCase());\n};\n```\n\n### Getting Local Toolkit Declarations\n\n```typescript\nexport const getLocalToolkitDeclarations = (\n options: {\n readonly currentPlatform?: LocalCliPlatform;\n readonly toolkits?: ReadonlyArray;\n readonly declarations?: ReadonlyArray;\n } = {}\n): ReadonlyArray => {\n const currentPlatform = options.currentPlatform ?? detectCliPlatform();\n return declarationsFor(options.declarations)\n .filter(toolkit => toolkitMatchesFilter(toolkit, options.toolkits))\n .filter(toolkit => supportsCliPlatform(toolkit.platforms, currentPlatform))\n .map(toolkit => ({\n ...toolkit,\n tools: toolkit.tools.filter(tool => supportsCliPlatform(tool.platforms, currentPlatform)),\n }))\n .filter(toolkit => toolkit.tools.length > 0);\n};\n```\n\n### Toolkit Index Generation\n\nThe toolkit index creates a structured mapping of all tools organized by their parent toolkit.\n\n资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:22-45](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n\n```typescript\nexport function createToolkitIndex(input: CreateToolkitIndexInput): Simplify {\n const { versionMap } = input;\n\n return pipe(\n input,\n groupByToolkits,\n Record.fromEntries,\n Record.mapEntries((value, key) => {\n const stripPrefix = String.slice(key.length + 1);\n\n const { slug } = value.toolkit;\n\n // Look up version override for this toolkit (lowercase key lookup)\n const version = versionMap?.get(String.toLowerCase(slug));\n // ... further processing\n })\n );\n}\n```\n\n## CLI Commands for Toolkits\n\nComposio CLI provides comprehensive commands for toolkit management:\n\n资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n\n| Command | Description |\n|---------|-------------|\n| `composio toolkits list` | List all available toolkits |\n| `composio toolkits info ` | Display detailed toolkit information |\n| `composio toolkits search ` | Search toolkits by name or description |\n| `composio toolkits version` | Manage toolkit version overrides |\n\n### Command Examples\n\n```bash\n# List toolkits\ncomposio toolkits list\n\n# Get toolkit information\ncomposio toolkits info \"gmail\"\n\n# Search for toolkits\ncomposio toolkits search \"email\"\n```\n\n资料来源：[ts/packages/cli/src/services/command-hints.ts:15-30](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts)\n\n## Version Management\n\n### Toolkit Version Overrides\n\nComposio supports version pinning for toolkits, allowing specific versions to be used instead of the latest release.\n\n资料来源：[ts/packages/cli/src/effects/toolkit-version-overrides.ts:16-35](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts)\n\n```typescript\nexport const buildVersionMapFromSpecs = (\n specs: ReadonlyArray\n): ToolkitVersionOverrides => {\n const versionMap = new Map, string>();\n for (const spec of specs) {\n if (spec.toolkitVersion !== 'latest') {\n versionMap.set(spec.toolkitSlug, spec.toolkitVersion);\n }\n }\n return versionMap;\n};\n```\n\n### Version Grouping\n\nToolkits can be grouped by their version specification:\n\n```typescript\nexport const groupByVersion = (\n specs: ReadonlyArray\n): Map[]> => {\n const grouped = new Map[]>();\n // Groups toolkits by version string\n return grouped;\n};\n```\n\n### Version Validation\n\nBefore applying version overrides, Composio validates that all specified versions and toolkit slugs are valid:\n\n资料来源：[ts/packages/cli/src/effects/validate-toolkit-versions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/validate-toolkit-versions.ts)\n\n```typescript\nexport const validateToolkitVersionOverrides = ({\n versionOverrides,\n toolkitSlugsFilter,\n client,\n}): Effect.Effect =>\n Effect.gen(function* () {\n const ui = yield* TerminalUI;\n\n // Skip if no overrides\n if (versionOverrides.size === 0) {\n return { validatedOverrides: versionOverrides };\n }\n // ... validation logic\n });\n```\n\n## Local Tools Configuration\n\n### Configuration File\n\nLocal tools can be configured via `~/composio/local_tools.json`:\n\n资料来源：[ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts)\n\n```bash\n# Configure a toolkit\ncomposio local-tools configure --selector --command \"\"\n\n# Disable a tool\ncomposio local-tools configure --selector --disable\n\n# Enable authentication\ncomposio local-tools configure --selector --authenticated\n```\n\n### Configuration Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `disabled` | `boolean` | Whether the tool/kit is disabled |\n| `authenticated` | `boolean` | Whether authentication is required |\n| `installation.command` | `string` | Custom installation command |\n| `metadataPath` | `string` | Path to local metadata file |\n\n## Tool Readiness and Status\n\n### Readiness Checks\n\nComposio performs readiness checks on local tools to determine their operational status:\n\n资料来源：[ts/packages/cli-local-tools/src/readiness.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/readiness.ts)\n\n```typescript\nconst status = toolkitSupported\n ? toolkitDisabled\n ? 'disabled'\n : aggregateStatus(tools.map(tool => tool.status))\n : 'unsupported';\n```\n\n### Status Values\n\n| Status | Description |\n|--------|-------------|\n| `ready` | Tool is fully operational |\n| `disabled` | Tool is explicitly disabled in configuration |\n| `unsupported` | Tool not supported on current platform |\n| `needs_setup` | Tool requires additional configuration |\n\n## Permission System\n\n### Tool Permission Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant ComposioCLI\n participant HTTPServer\n participant User\n \n Agent->>ComposioCLI: Execute tool request\n ComposioCLI->>HTTPServer: Start permission server\n HTTPServer->>User: Show permission dialog\n User->>HTTPServer: Allow/Deny decision\n HTTPServer->>ComposioCLI: Return decision\n ComposioCLI->>Agent: Execute or reject\n```\n\n### Permission Decision Types\n\n| Decision | Scope | Persistence |\n|----------|-------|-------------|\n| `allow_session` | Current session | Temporary |\n| `allow_once` | Single execution | Single use |\n| `deny` | Rejected | Permanent for request |\n\n资料来源：[ts/packages/cli/src/services/tool-permissions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/tool-permissions.ts)\n\n## Logs and Monitoring\n\n### Log Commands\n\nComposio provides commands to monitor tool and trigger execution:\n\n资料来源：[ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts)\n\n```bash\n# View tool execution logs\ncomposio dev logs tools \n\n# View trigger execution logs\ncomposio dev logs triggers \n```\n\n## Provider Integration\n\n### Schema Modifiers\n\nCustom tools support schema modification through provider options, enabling dynamic schema transformation:\n\n资料来源：[ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n\n```typescript\nexport type ProviderOptions =\n TProvider extends BaseComposioProvider\n ? TProvider extends BaseAgenticProvider\n ? AgenticToolOptions\n : ToolOptions\n : never;\n```\n\n### Modifier Functions\n\n| Function | Purpose |\n|----------|---------|\n| `modifySchema` | Transform input/output schemas |\n| `beforeExecute` | Pre-execution hook for parameter manipulation |\n| `afterExecute` | Post-execution hook for result processing |\n\n## Usage Example\n\n### TypeScript\n\n```typescript\nimport { createCustomTool, createCustomToolkit } from '@composio/core';\n\nconst myTool = createCustomTool('fetch_data', {\n name: 'Fetch Data',\n description: 'Retrieves data from the specified endpoint',\n inputParams: [\n {\n name: 'url',\n type: 'string',\n description: 'The URL to fetch data from',\n required: true,\n },\n ],\n execute: async (input) => {\n const response = await fetch(input.url);\n return await response.json();\n },\n});\n\nconst myToolkit = createCustomToolkit('data_fetchers', {\n name: 'Data Fetchers',\n description: 'Tools for fetching various data sources',\n tools: [myTool],\n});\n```\n\n### Python\n\n```python\nfrom composio.core.models.custom_tool import CustomTool\nfrom composio.core.models.custom_tool_types import Parameter\n\nmy_tool = CustomTool(\n name=\"fetch_data\",\n description=\"Retrieves data from the specified endpoint\",\n input_params=[\n Parameter(\n name=\"url\",\n type=\"string\",\n description=\"The URL to fetch data from\",\n required=True\n )\n ]\n)\n```\n\n## Summary\n\nCustom Tools and Toolkits in Composio provide a flexible, extensible system for defining and managing agent capabilities:\n\n1. **Custom Tools** are atomic units of work with defined inputs, outputs, and execution logic\n2. **Custom Toolkits** organize related tools under common namespaces and platform contexts\n3. **Version Management** enables pinning toolkits to specific versions\n4. **Permission System** controls tool execution with browser-based approval flows\n5. **CLI Integration** provides comprehensive commands for toolkit discovery and management\n6. **Provider Integration** supports schema modification and transformation through modifier functions\n\nThis architecture allows developers to extend Composio's functionality while maintaining consistency with the framework's patterns for tool definition, execution, and monitoring.\n\n---\n\n\n\n## Connected Accounts\n\n### 相关页面\n\n相关主题：[Core Concepts](#core-concepts)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/core/src/models/ConnectedAccounts.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/ConnectedAccounts.ts)\n- [ts/packages/core/src/types/connectedAccounts.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/connectedAccounts.types.ts)\n- [python/composio/core/models/connected_accounts.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/connected_accounts.py)\n- [ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts)\n- [ts/examples/connected-accounts/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/examples/connected-accounts/src/index.ts)\n- [python/examples/connected_accounts.py](https://github.com/ComposioHQ/composio/blob/main/python/examples/connected_accounts.py)\n- [docs/content/docs/auth-configuration/connected-accounts.mdx](https://github.com/ComposioHQ/composio/blob/main/docs/content/docs/auth-configuration/connected-accounts.mdx)\n
\n\n# Connected Accounts\n\n## Overview\n\nConnected Accounts in Composio represent the integration layer between external third-party services (such as Gmail, Slack, GitHub) and the Composio platform. They manage authentication credentials, authorization scopes, and access control for tools that require external service authentication.\n\nA **Connected Account** is essentially a stored authentication configuration that links a user's external service account to Composio's tool ecosystem. This abstraction allows Composio to handle OAuth flows, token refresh, and permission management across multiple integrations while providing a unified interface for tool execution.\n\nThe Connected Accounts system serves as the foundation for:\n\n- OAuth-based authentication with external services\n- Access control and permission management at the account level\n- Caching and optimization of authentication data\n- Cross-toolkit credential sharing\n- Consumer-level account routing\n\n## Architecture\n\n### Core Components\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CMD[connected-accounts.cmd.ts
CLI Commands]\n HINTS[command-hints.ts
Command Hints]\n end\n \n subgraph \"Effects Layer\"\n CTRS[create-tool-router-session.ts
Tool Router Session]\n PERMS[tool-permissions.ts
Permission Handler]\n end\n \n subgraph \"Core Models\"\n CA[ConnectedAccounts.ts
Python Model]\n CAC[connectedAccounts.types.ts
Type Definitions]\n end\n \n subgraph \"Services\"\n CACHE[consumer-short-term-cache.ts
Cache Service]\n LINK[Link Command
OAuth Flow]\n end\n \n CMD --> CTRS\n CTRS --> CACHE\n CTRS --> CAC\n PERMS --> CAC\n LINK --> CA\n CA --> CAC\n```\n\n### Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Cache as Cache Service\n participant API as Composio API\n participant External as External Service\n \n User->>CLI: composio connected-accounts link gmail\n \n CLI->>API: Initiate OAuth Flow\n API->>External: Redirect to OAuth Provider\n External-->>API: OAuth Callback + Auth Code\n API->>External: Exchange Code for Tokens\n External-->>API: Access Token + Refresh Token\n \n API->>API: Store Connected Account\n API-->>CLI: Connected Account Created\n \n Note over CLI,Cache: Subsequent Requests\n \n CLI->>Cache: Check Cache\n alt Cache Hit\n Cache-->>CLI: Return Cached Accounts\n else Cache Miss\n Cache->>API: Fetch Fresh Data\n API-->>Cache: Connected Account Data\n Cache-->>CLI: Return Data\n end\n \n CLI->>API: Execute Tool with Account\n API->>External: Use Account Credentials\n External-->>API: Service Response\n API-->>CLI: Tool Result\n```\n\n## CLI Commands\n\nThe Composio CLI provides a dedicated command group for managing connected accounts:\n\n### Command Structure\n\n| Command | Description | Entry Point |\n|---------|-------------|-------------|\n| `link` | Connect a new external account | `connected-accounts.link.cmd.ts` |\n| `list` | List all connected accounts | `connected-accounts.list.cmd.ts` |\n| `info` | Get details of a specific account | `connected-accounts.info.cmd.ts` |\n| `whoami` | Show currently authenticated identity | `connected-accounts.whoami.cmd.ts` |\n\n资料来源：[ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts:14-18]()\n\n### Link Command\n\nThe `link` command initiates the OAuth flow to connect an external service:\n\n```bash\ncomposio link \n```\n\nThis command:\n1. Retrieves the OAuth configuration for the specified toolkit\n2. Opens a browser window for user authentication\n3. Handles the OAuth callback\n4. Stores the resulting connected account\n\n### List Command\n\nDisplay all connected accounts with their status:\n\n```bash\ncomposio connected-accounts list\n```\n\nThe output includes:\n- Account ID\n- Associated toolkit\n- Authentication status\n- Last used timestamp\n\n## Access Control (ACL)\n\nConnected Accounts support fine-grained access control through ACL (Access Control List) configurations.\n\n### ACL Parameters\n\n```typescript\nexport const UpdateConnectedAccountAclParamsSchema = ConnectedAccountAclConfigSchema.refine(\n acl =>\n acl.allowAllUsers !== undefined ||\n acl.allowedUserIds !== undefined ||\n acl.notAllowedUserIds !== undefined,\n {\n message: 'At least one of allowAllUsers, allowedUserIds, or notAllowedUserIds must be provided',\n }\n);\n```\n\n资料来源：[ts/packages/core/src/types/connectedAccounts.types.ts:1-10]()\n\n### ACL Configuration Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `allowAllUsers` | `boolean` | Grant access to all users in the organization |\n| `allowedUserIds` | `string[]` | Explicit list of user IDs granted access |\n| `notAllowedUserIds` | `string[]` | Explicit list of user IDs denied access |\n\n**Validation Rule:** At least one of these fields must be provided when updating ACL.\n\n## Tool Router Integration\n\nConnected Accounts are integrated into the Tool Router system, which manages tool execution and authentication routing.\n\n### Session Creation Flow\n\n```mermaid\ngraph TD\n Start([Create Tool Router Session]) --> CheckCache{Cache Scope
Provided?}\n \n CheckCache -->|Yes| FetchAuth[Fetch Auth Configs
from Cache]\n CheckCache -->|No| SkipCache[Skip Cache]\n \n FetchAuth --> CacheExists{Cached Data
Available?}\n CacheExists -->|Yes| UseCache[Use Cached Auth Configs]\n CacheExists -->|No| FetchLive[Fetch Live from API]\n \n SkipCache --> BuildContext[Build Connection Context]\n UseCache --> BuildContext\n FetchLive --> BuildContext\n \n BuildContext --> MergeAccounts[Merge Connected Accounts]\n MergeAccounts --> FilterAccounts[Filter Available Accounts]\n FilterAccounts --> ReturnContext[Return Connection Context]\n \n ReturnContext --> End([Session Ready])\n```\n\n### Connection Context Structure\n\nThe connection context aggregates authentication data for tool execution:\n\n```typescript\ninterface ConnectionContext {\n connectedToolkits: string[];\n authConfigs: Record;\n connectedAccounts: ConnectedAccount[];\n availableConnectedAccounts: AvailableConnectedAccount[];\n}\n```\n\n资料来源：[ts/packages/cli/src/effects/create-tool-router-session.ts:1-30]()\n\n### Connected Account Mapping\n\nConnected accounts are mapped to word IDs for efficient lookup:\n\n```typescript\nconst wordIds = Object.fromEntries(\n Object.entries(selected).flatMap(([toolkit, connectedAccountId]) => {\n const account = available[toolkit.toLowerCase()]?.find(\n item => item.id === connectedAccountId\n );\n return account?.wordId ? [[toolkit, account.wordId]] : [];\n })\n);\n```\n\n资料来源：[ts/packages/cli/src/effects/create-tool-router-session.ts:8-15]()\n\n## Caching System\n\nThe Connected Accounts system includes a sophisticated caching layer to optimize API calls and improve performance.\n\n### Cache Key Normalization\n\n| Normalization | Description |\n|--------------|-------------|\n| Toolkit slugs | Converted to lowercase |\n| Auth config IDs | Validated as non-empty strings |\n| Connected account IDs | Validated as non-empty strings |\n\n资料来源：[ts/packages/cli/src/services/consumer-short-term-cache.ts:1-30]()\n\n### Cache Merge Strategy\n\nWhen multiple sources provide connected account mappings, they are merged with the following precedence:\n\n1. **Later declarations override earlier ones**\n2. **Auth configs are merged object-wise**\n3. **Empty configurations are filtered out**\n\n```typescript\nconst mergeAuthConfigMappings = (params) => {\n const current = normalizeAuthConfigMappings(params.current);\n const next = normalizeAuthConfigMappings(params.next);\n if (!current) return next;\n if (!next) return current;\n\n return normalizeAuthConfigMappings({\n authConfigs: {\n ...(current.authConfigs ?? {}),\n ...(next.authConfigs ?? {}),\n },\n });\n};\n```\n\n资料来源：[ts/packages/cli/src/services/consumer-short-term-cache.ts:50-70]()\n\n## Tool Permission System\n\nWhen executing tools that require connected account authentication, Composio provides a permission confirmation flow.\n\n### Permission Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant CLI\n participant Browser\n participant Server\n \n Agent->>CLI: Execute Tool with Account\n CLI->>Server: Start Permission Server\n \n CLI->>Browser: Open Permission Dialog\n Note over Browser: \"Allow gmail?\"\n \n Browser->>Server: User Decision\n \n alt Allow for Session\n Server-->>CLI: Allow with Token\n CLI->>Agent: Execute Tool\n else Allow Once\n Server-->>CLI: Allow Once Token\n CLI->>Agent: Execute Tool\n else Deny\n Server-->>CLI: Deny\n CLI-->>Agent: Permission Denied\n end\n```\n\n### Permission Dialog\n\nThe permission dialog is rendered as an HTML page served on localhost:\n\n```html\n

Allow ${toolSlug}?

\n

Composio CLI is requesting permission to execute this tool${accountLabel ? ` for ${accountLabel}` : ''}.

\n```\n\n提供三个选项：\n- **Allow for this session** - 持续授权直到会话结束\n- **Allow once** - 仅本次执行授权\n- **Deny** - 拒绝执行\n\n资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-50]()\n\n## Python SDK Integration\n\n### Model Definition\n\n```python\nclass ConnectedAccount(BaseModel):\n id: str\n name: str\n integration_id: str\n connected_account_type: str\n connection_metadata: dict\n enabled: bool\n active: bool\n auth_scheme: str\n auth_expiry: Optional[datetime] = None\n redirect_uri: Optional[str] = None\n entity_id: Optional[str] = None\n user_id: Optional[str] = None\n scopes: list[str] = []\n account_id: Optional[str] = None\n```\n\n资料来源：[python/composio/core/models/connected_accounts.py:1-20]()\n\n### Usage Example\n\n```python\nfrom composio import Composio\nfrom composio.client.components import ConnectedAcocunts\n\ncomposio_client = Composio()\n\n# List all connected accounts\naccounts = composio_client.connected_accounts.list()\n\n# Get info for a specific account\naccount = composio_client.connected_accounts.get(account_id=\"acc_xxx\")\n\n# Link a new account\nnew_account = composio_client.connected_accounts.link(\n integration_id=\"int_xxx\",\n entity_id=\"entity_xxx\"\n)\n```\n\n## Common Use Cases\n\n### 1. Multi-Account Management\n\nUsers can connect multiple accounts from the same service provider:\n\n```bash\n# Connect personal Gmail\ncomposio link gmail --account personal\n\n# Connect work Gmail\ncomposio link gmail --account work\n```\n\n### 2. Cross-Toolkit Sharing\n\nOne connected account can provide authentication for multiple toolkits if they share the same OAuth provider.\n\n### 3. Organization-Level Accounts\n\nEnterprise users can share connected accounts across team members using ACL configurations:\n\n```python\n# Share account with entire organization\ncomposio_client.connected_accounts.update_acl(\n account_id=\"acc_xxx\",\n allow_all_users=True\n)\n\n# Share with specific users only\ncomposio_client.connected_accounts.update_acl(\n account_id=\"acc_xxx\",\n allowed_user_ids=[\"user_1\", \"user_2\"]\n)\n```\n\n## Related Commands Reference\n\n| Command | Description |\n|---------|-------------|\n| `composio connected-accounts link ` | Connect a new account |\n| `composio connected-accounts list` | List all connected accounts |\n| `composio connected-accounts info ` | Show account details |\n| `composio connected-accounts whoami` | Show current identity |\n| `composio dev playground-execute ` | Test tool with connected account |\n| `composio link ` | Quick link command (alias) |\n\n资料来源：[ts/packages/cli/src/services/command-hints.ts:1-50]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| Account not found | Toolkit not connected | Run `composio link ` |\n| Permission denied | ACL restricts access | Check with account owner to update ACL |\n| Token expired | OAuth token needs refresh | Re-link the account |\n| Cache stale | Old cached data | Use `--no-cache` flag or update cache settings |\n\n### Debug Mode\n\nEnable verbose logging to debug connected account issues:\n\n```bash\nCOMPOSIO_LOG_LEVEL=debug composio connected-accounts list\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：ComposioHQ/composio\n\n摘要：发现 12 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops。\n\n## 1. 安装坑 · 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_54d53b3e2a6e4cf4a3e4783f824ed87b | https://github.com/ComposioHQ/composio/issues/3269 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shar…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shares:{})\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1b88beb594aa433eb998eac3b16a20e0 | https://github.com/ComposioHQ/composio/issues/3422 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：[Feature] Custom auth configs shouldn't require a dev project to use\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] Custom auth configs shouldn't require a dev project to use\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1d62ba62e77b47ff88b50d2db41a8cf7 | https://github.com/ComposioHQ/composio/issues/3271 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 4. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `composio` 与安装入口 `@composio/core` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @composio/core`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:762304524 | https://github.com/ComposioHQ/composio | repo=composio; install=@composio/core\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:762304524 | https://github.com/ComposioHQ/composio | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:762304524 | https://github.com/ComposioHQ/composio | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：@composio/core@0.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：@composio/core@0.10.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66f9d5fd557f41c7845ca5dd7d93ae6f | https://github.com/ComposioHQ/composio/releases/tag/%40composio/core%400.10.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | issue_or_pr_quality=unknown\n\n## 12. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | release_recency=unknown\n\n\n", "markdown_key": "composio", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:762304524", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/ComposioHQ/composio" }, { "evidence_id": "art_e7d12cd559424cc4b20cfcebc1b34d30", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/ComposioHQ/composio#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "composio 说明书", "toc": [ "https://github.com/ComposioHQ/composio 项目说明书", "目录", "Introduction to Composio", "Overview", "Core Architecture", "Composio CLI", "Tool Execution Flow", "Provider System", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "dc052f5c0e91bd425e2167a1eecc741335a2bf18", "repo_inspection_error": null, "repo_inspection_files": [ "pyproject.toml", "pnpm-lock.yaml", "Dockerfile", "package.json", "README.md", "uv.lock", "docs/vercel.json", "docs/source.config.ts", "docs/CLAUDE.md", "docs/package.json", "docs/proxy.ts", "docs/README.md", "docs/tsconfig.json", "docs/components.json", "docs/bunfig.toml", "docs/scripts/generate-meta-tools.ts", "docs/scripts/generate-toolkits.ts", "docs/scripts/generate-api-index.ts", "docs/scripts/preload.ts", "docs/scripts/README.md", "docs/scripts/validate-links.ts", "docs/public/openapi.json", "docs/public/openapi-v3.json", "docs/.claude/plan.md", "docs/lib/utils.ts", "docs/lib/use-api-version.ts", "docs/lib/toolkit-data.ts", "docs/lib/meta-tools-data.ts", "docs/lib/openapi.ts", "docs/lib/toolkit-schema.ts", "docs/lib/api-version.ts", "docs/lib/source.ts", "docs/lib/filter-api-version.ts", "docs/app/sitemap.ts", "docs/types/toolkit.ts", "docs/public/data/toolkits-list.json", "docs/public/data/toolkits.json", "docs/public/data/meta-tools.json", "docs/content/docs/meta.json", "docs/content/docs/managing-multiple-connected-accounts.mdx" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# composio - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 composio 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.agents/skills/bug-fixing-guide/SKILL.md`, `.agents/skills/building-agents/SKILL.md`, `.agents/skills/building-agents-using-anthropic/SKILL.md`, `.agents/skills/building-agents-using-autogen/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.agents/skills/bug-fixing-guide/SKILL.md`, `.agents/skills/building-agents/SKILL.md`, `.agents/skills/building-agents-using-anthropic/SKILL.md`, `.agents/skills/building-agents-using-autogen/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`INSTALL.md`, `README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `curl -fsSL https://raw.githubusercontent.com/ComposioHQ/composio/main/install.sh | bash` 证据：`INSTALL.md` Claim：`clm_0005` unverified 0.25, `clm_0006` unverified 0.25\n- `curl -fsSL https://raw.githubusercontent.com/ComposioHQ/composio/main/install.sh | bash -s -- v0.1.24` 证据：`INSTALL.md` Claim：`clm_0006` unverified 0.25\n- `npm install -g @composio/cli` 证据：`INSTALL.md` Claim：`clm_0007` unverified 0.25\n- `pnpm add -g @composio/cli` 证据：`INSTALL.md` Claim：`clm_0008` unverified 0.25\n- `curl -v -fsSL https://raw.githubusercontent.com/ComposioHQ/composio/main/install.sh | bash` 证据：`INSTALL.md` Claim：`clm_0009` unverified 0.25\n- `curl -O https://raw.githubusercontent.com/ComposioHQ/composio/main/install.sh` 证据：`INSTALL.md` Claim：`clm_0010` unverified 0.25\n- `npm install @composio/core` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `yarn add @composio/core` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `pnpm add @composio/core` 证据：`README.md` Claim：`clm_0013` supported 0.86\n- `npm install @composio/openai-agents @openai/agents` 证据：`README.md` Claim：`clm_0014` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.agents/skills/bug-fixing-guide/SKILL.md`, `.agents/skills/building-agents/SKILL.md`, `.agents/skills/building-agents-using-anthropic/SKILL.md`, `.agents/skills/building-agents-using-autogen/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/skills/bug-fixing-guide/SKILL.md`, `.agents/skills/building-agents/SKILL.md`, `.agents/skills/building-agents-using-anthropic/SKILL.md`, `.agents/skills/building-agents-using-autogen/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`INSTALL.md`, `README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0011` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.agents/skills/bug-fixing-guide/SKILL.md`, `.agents/skills/building-agents-using-anthropic/SKILL.md`, `.agents/skills/building-agents-using-autogen/SKILL.md`, `.agents/skills/building-agents-using-cloudflare/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`INSTALL.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`INSTALL.md`, `README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/skills/bug-fixing-guide/SKILL.md`, `.agents/skills/building-agents-using-anthropic/SKILL.md`, `.agents/skills/building-agents-using-autogen/SKILL.md`, `.agents/skills/building-agents-using-cloudflare/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`INSTALL.md`, `README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0017` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`INSTALL.md`, `README.md` Claim：`clm_0018` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.agents/skills/bug-fixing-guide/SKILL.md`, `.agents/skills/building-agents/SKILL.md`, `.agents/skills/building-agents-using-anthropic/SKILL.md`, `.agents/skills/building-agents-using-autogen/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`INSTALL.md`, `README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2153\n- 重要文件覆盖：40/2153\n- 证据索引条目：121\n- 角色 / Skill 条目：41\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 composio 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 composio 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 composio 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 41 个角色 / Skill / 项目文档条目。\n\n- **Bug Fixing Guide**（skill）：Standard practices for fixing bugs in Composio SDK. Always add regression tests for major bugs. 激活提示：当用户任务与“Bug Fixing Guide”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/bug-fixing-guide/SKILL.md`\n- **Building Agents using Anthropic with Composio**（skill）：Building Agents using Anthropic with Composio 激活提示：当用户任务与“Building Agents using Anthropic with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-anthropic/SKILL.md`\n- **Building Agents using Microsoft AutoGen with Composio**（skill）：Building Agents using Microsoft AutoGen with Composio 激活提示：当用户任务与“Building Agents using Microsoft AutoGen with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-autogen/SKILL.md`\n- **Building Agents using Cloudflare with Composio**（skill）：Building Agents using Cloudflare with Composio 激活提示：当用户任务与“Building Agents using Cloudflare with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-cloudflare/SKILL.md`\n- **Building Agents using CrewAI with Composio**（skill）：Building Agents using CrewAI with Composio 激活提示：当用户任务与“Building Agents using CrewAI with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-crewai/SKILL.md`\n- **Building Agents using Google Gemini with Composio**（skill）：Building Agents using Google Gemini with Composio 激活提示：当用户任务与“Building Agents using Google Gemini with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-google/SKILL.md`\n- **Building Agents using LangChain with Composio**（skill）：Building Agents using LangChain with Composio 激活提示：当用户任务与“Building Agents using LangChain with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-langchain/SKILL.md`\n- **Building Agents using LangGraph with Composio**（skill）：Building Agents using LangGraph with Composio 激活提示：当用户任务与“Building Agents using LangGraph with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-langgraph/SKILL.md`\n- **Building Agents using LlamaIndex with Composio**（skill）：Building Agents using LlamaIndex with Composio 激活提示：当用户任务与“Building Agents using LlamaIndex with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-llamaindex/SKILL.md`\n- **Building Agents using Mastra with Composio**（skill）：Building Agents using Mastra with Composio 激活提示：当用户任务与“Building Agents using Mastra with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-mastra/SKILL.md`\n- **Building Agents using OpenAI with Composio**（skill）：Building Agents using OpenAI with Composio 激活提示：当用户任务与“Building Agents using OpenAI with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-openai/SKILL.md`\n- **Building Agents using Vercel AI SDK with Composio**（skill）：Building Agents using Vercel AI SDK with Composio 激活提示：当用户任务与“Building Agents using Vercel AI SDK with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents-using-vercel/SKILL.md`\n- **Building AI Agents with Composio SDK**（skill）：Building AI Agents with Composio SDK 激活提示：当用户任务与“Building AI Agents with Composio SDK”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/building-agents/SKILL.md`\n- **CLI Release Promotion**（skill）：Validate a Composio CLI beta release and promote it to a stable release by dispatching the CLI binary workflow with an existing beta tag. 激活提示：当用户任务与“CLI Release Promotion”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/cli-release-promotion/SKILL.md`\n- **CLI E2E Test Development**（skill）：Write end-to-end tests for CLI commands using the Docker-based test framework in ts/e2e-tests/cli/. 激活提示：当用户任务与“CLI E2E Test Development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/create-cli-e2e/SKILL.md`\n- **CLI Design Guidelines**（skill）：CLI design guidelines — arguments, flags, subcommands, help, output, errors, interactivity, config precedence. Apply when designing new commands or reviewing CLI UX. 激活提示：当用户任务与“CLI Design Guidelines”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/create-cli/SKILL.md`\n- **Ephemeral E2E SDK Tests**（skill）：Quick ephemeral verification tests for Composio SDK with AI frameworks. Never commit these tests. 激活提示：当用户任务与“Ephemeral E2E SDK Tests”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/ephemeral-e2e-sdk-tests/SKILL.md`\n- **Implement CLI Command**（skill）：Implement new CLI commands in ts/packages/cli/ using Effect.ts patterns, service wiring, and @effect/cli declarations. 激活提示：当用户任务与“Implement CLI Command”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/implement-cli-command/SKILL.md`\n- **Testing Composio SDK in Real-World Scenarios**（skill）：Testing Composio SDK in Real-World Scenarios 激活提示：当用户任务与“Testing Composio SDK in Real-World Scenarios”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/test-sdk-in-realworld/SKILL.md`\n- **Bug Fixing Guide**（skill）：Standard practices for fixing bugs in Composio SDK. Always add regression tests for major bugs. 激活提示：当用户任务与“Bug Fixing Guide”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/bug-fixing-guide/SKILL.md`\n- **Building Agents using Anthropic with Composio**（skill）：Building Agents using Anthropic with Composio 激活提示：当用户任务与“Building Agents using Anthropic with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-anthropic/SKILL.md`\n- **Building Agents using Microsoft AutoGen with Composio**（skill）：Building Agents using Microsoft AutoGen with Composio 激活提示：当用户任务与“Building Agents using Microsoft AutoGen with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-autogen/SKILL.md`\n- **Building Agents using Cloudflare with Composio**（skill）：Building Agents using Cloudflare with Composio 激活提示：当用户任务与“Building Agents using Cloudflare with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-cloudflare/SKILL.md`\n- **Building Agents using CrewAI with Composio**（skill）：Building Agents using CrewAI with Composio 激活提示：当用户任务与“Building Agents using CrewAI with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-crewai/SKILL.md`\n- **Building Agents using Google Gemini with Composio**（skill）：Building Agents using Google Gemini with Composio 激活提示：当用户任务与“Building Agents using Google Gemini with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-google/SKILL.md`\n- **Building Agents using LangChain with Composio**（skill）：Building Agents using LangChain with Composio 激活提示：当用户任务与“Building Agents using LangChain with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-langchain/SKILL.md`\n- **Building Agents using LangGraph with Composio**（skill）：Building Agents using LangGraph with Composio 激活提示：当用户任务与“Building Agents using LangGraph with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-langgraph/SKILL.md`\n- **Building Agents using LlamaIndex with Composio**（skill）：Building Agents using LlamaIndex with Composio 激活提示：当用户任务与“Building Agents using LlamaIndex with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-llamaindex/SKILL.md`\n- **Building Agents using Mastra with Composio**（skill）：Building Agents using Mastra with Composio 激活提示：当用户任务与“Building Agents using Mastra with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-mastra/SKILL.md`\n- **Building Agents using OpenAI with Composio**（skill）：Building Agents using OpenAI with Composio 激活提示：当用户任务与“Building Agents using OpenAI with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-openai/SKILL.md`\n- **Building Agents using Vercel AI SDK with Composio**（skill）：Building Agents using Vercel AI SDK with Composio 激活提示：当用户任务与“Building Agents using Vercel AI SDK with Composio”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents-using-vercel/SKILL.md`\n- **Building AI Agents with Composio SDK**（skill）：Building AI Agents with Composio SDK 激活提示：当用户任务与“Building AI Agents with Composio SDK”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/building-agents/SKILL.md`\n- **CLI Release**（skill）：Release the CLI — diff features since last release, run /full-cli-test on them, and create a changeset PR with patch bump and test results. 激活提示：当用户任务与“CLI Release”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/cli-release/SKILL.md`\n- **CLI Test with Bundling CI**（skill）：Trigger a CI binary build via workflow dispatch, monitor it, download the artifact, and test the CLI binary locally. 激活提示：当用户任务与“CLI Test with Bundling CI”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/cli-test-with-bundling/SKILL.md`\n- **CLI Test**（skill）：Build the CLI binary from source and test it locally by running commands against the built binary. 激活提示：当用户任务与“CLI Test”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/cli-test/SKILL.md`\n- **CLI E2E Test Development**（skill）：Write end-to-end tests for CLI commands using the Docker-based test framework in ts/e2e-tests/cli/. 激活提示：当用户任务与“CLI E2E Test Development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/create-cli-e2e/SKILL.md`\n- **CLI Design Guidelines**（skill）：CLI design guidelines — arguments, flags, subcommands, help, output, errors, interactivity, config precedence. Apply when designing new commands or reviewing CLI UX. 激活提示：当用户任务与“CLI Design Guidelines”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/create-cli/SKILL.md`\n- **Ephemeral E2E SDK Tests**（skill）：Quick ephemeral verification tests for Composio SDK with AI frameworks. Never commit these tests. 激活提示：当用户任务与“Ephemeral E2E SDK Tests”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/ephemeral-e2e-sdk-tests/SKILL.md`\n- **Full CLI Test**（skill）：Full CLI test pipeline — monitor CI for types/lint, then run local binary test, then run bundled binary test via CI. 激活提示：当用户任务与“Full CLI Test”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/full-cli-test/SKILL.md`\n- **Implement CLI Command**（skill）：Implement new CLI commands in ts/packages/cli/ using Effect.ts patterns, service wiring, and @effect/cli declarations. 激活提示：当用户任务与“Implement CLI Command”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/implement-cli-command/SKILL.md`\n- **Testing Composio SDK in Real-World Scenarios**（skill）：Testing Composio SDK in Real-World Scenarios 激活提示：当用户任务与“Testing Composio SDK in Real-World Scenarios”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/test-sdk-in-realworld/SKILL.md`\n\n## 证据索引\n\n- 共索引 121 条证据。\n\n- **Composio Documentation**（documentation）：Documentation site for Composio, built with Fumadocs https://fumadocs.dev/ . 证据：`docs/CLAUDE.md`\n- **Composio Docs**（documentation）：Documentation site for Composio, built with Fumadocs https://fumadocs.dev/ . 证据：`docs/README.md`\n- **OpenAPI Scripts**（documentation）：Fetches the Composio OpenAPI spec and filters it for use in Fumadocs API reference documentation. 证据：`docs/scripts/README.md`\n- **Composio SDK v3 Documentation**（documentation）：Composio SDK is a powerful toolkit that enables you to integrate third-party tools and services into your applications. This SDK helps you connect to various services toolkits , execute tools, and manage user connections seamlessly. 证据：`ts/docs/README.md`\n- **Changesets**（documentation）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 证据：`.changeset/README.md`\n- **AGENTS.md**（documentation）：This file provides guidance to AI coding agents Codex, Claude Code, etc. when working with code in this repository. 证据：`AGENTS.md`\n- **CLAUDE.md**（documentation）：Guidance for Claude Code when working in this repository. For Codex / generic-agent guidance see AGENTS.md . 证据：`CLAUDE.md`\n- **Composio SDK**（documentation）：🌐 Website https://composio.dev • 📚 Documentation https://docs.composio.dev 证据：`README.md`\n- **Composio**（documentation）：! Composio Banner https://github.com/user-attachments/assets/9ba0e9c1-85a4-4b51-ae60-f9fe7992e819 证据：`python/README.md`\n- **Composio SDK v3**（documentation）：The Composio SDK is a powerful toolkit that enables you to integrate third-party tools and services into your applications. It helps you connect to various services toolkits , execute tools, and manage user connections seamlessly. 证据：`ts/README.md`\n- **Integration Tests**（documentation）：Integration tests for Composio SDK functionality. 证据：`python/composio/integration_test/README.md`\n- **🚀🔗 Leveraging Claude with Composio**（documentation）：Facilitate the integration of Claude with Composio to empower Claude models to directly interact with external applications, broadening their capabilities and application scope. 证据：`python/providers/anthropic/README.md`\n- **🚀🔗 Integrating Composio with Autogen SDK**（documentation）：🚀🔗 Integrating Composio with Autogen SDK 证据：`python/providers/autogen/README.md`\n- **Composio Claude Code Agents Provider**（documentation）：Composio Claude Code Agents Provider 证据：`python/providers/claude_agent_sdk/README.md`\n- **CrewAI plugin**（documentation）：CrewAI plugin 证据：`python/providers/crewai/README.md`\n- **🚀🔗 Integrating Composio with Google's Gemini SDK**（documentation）：🚀🔗 Integrating Composio with Google's Gemini SDK 证据：`python/providers/gemini/README.md`\n- **🚀🔗 Integrating Composio with Google AI Python**（documentation）：🚀🔗 Integrating Composio with Google AI Python 证据：`python/providers/google/README.md`\n- **Composio Provider For Google ADK**（documentation）：Composio Provider For Google ADK 证据：`python/providers/google_adk/README.md`\n- **Langchain provider for composio SDK**（documentation）：Langchain provider for composio SDK 证据：`python/providers/langchain/README.md`\n- **🦜🕸️ Using Composio With LangGraph**（documentation）：Integrate Composio with LangGraph Agentic workflows & enable them to interact seamlessly with external apps, enhancing their functionality and reach. 证据：`python/providers/langgraph/README.md`\n- **Using Composio With LLamaIndex**（documentation）：Integrate Composio with LLamaIndex Agentic workflows & enable them to interact seamlessly with external apps, enhancing their functionality and reach. 证据：`python/providers/llamaindex/README.md`\n- **🚀🔗 Leveraging OpenAI with Composio**（documentation）：Facilitate the integration of OpenAI with Composio to empower OpenAI models to directly interact with external applications, broadening their capabilities and application scope. 证据：`python/providers/openai/README.md`\n- **Composio Integration for OpenAI Agents**（documentation）：Composio Integration for OpenAI Agents 证据：`python/providers/openai_agents/README.md`\n- **SDK Documentation Generator**（documentation）：Generates MDX reference docs from Python source using griffe. 证据：`python/scripts/README.md`\n- **E2E Tests**（documentation）：End-to-end tests for @composio/core and the CLI across different runtimes. 证据：`ts/e2e-tests/README.md`\n- **E2E Test Utilities**（documentation）：Shared infrastructure for running @composio/core and CLI end-to-end tests in isolated Docker environments. 证据：`ts/e2e-tests/_utils/README.md`\n- **CLI E2E Tests**（documentation）：End-to-end tests for the compiled composio CLI binary. 证据：`ts/e2e-tests/cli/README.md`\n- **CLI composio dev toolkits info Test**（documentation）：CLI composio dev toolkits info Test 证据：`ts/e2e-tests/cli/toolkits/info/README.md`\n- **CLI composio dev toolkits list Test**（documentation）：CLI composio dev toolkits list Test 证据：`ts/e2e-tests/cli/toolkits/list/README.md`\n- **CLI composio dev toolkits search Test**（documentation）：CLI composio dev toolkits search Test 证据：`ts/e2e-tests/cli/toolkits/search/README.md`\n- **CLI composio version Test**（documentation）：Verifies that composio version prints the correct version string and respects stdout piping. 证据：`ts/e2e-tests/cli/version/README.md`\n- **CLI composio whoami Test**（documentation）：Verifies that composio whoami prints the authenticated API key and respects stdout piping. 证据：`ts/e2e-tests/cli/whoami/README.md`\n- **Cloudflare Workers Compatibility Tests**（documentation）：Cloudflare Workers Compatibility Tests 证据：`ts/e2e-tests/runtimes/cloudflare/cf-workers-basic/README.md`\n- **Composio Core Files - Cloudflare Workers E2E Test**（documentation）：Composio Core Files - Cloudflare Workers E2E Test 证据：`ts/e2e-tests/runtimes/cloudflare/cf-workers-files/README.md`\n- **Tool Router AI - Cloudflare Workers E2E Test**（documentation）：Tool Router AI - Cloudflare Workers E2E Test 证据：`ts/e2e-tests/runtimes/cloudflare/cf-workers-tool-router-ai/README.md`\n- **Deno ESM Compatibility Test**（documentation）：Verifies that @composio/core works correctly when imported via npm: specifier in Deno. 证据：`ts/e2e-tests/runtimes/deno/esm-basic/README.md`\n- **Node.js CommonJS Compatibility Test**（documentation）：Node.js CommonJS Compatibility Test 证据：`ts/e2e-tests/runtimes/node/cjs-basic/README.md`\n- **Node.js ESM Compatibility Test**（documentation）：Verifies that @composio/core works correctly when imported via import in ES Module environments. 证据：`ts/e2e-tests/runtimes/node/esm-basic/README.md`\n- **Node.js File Upload Round-Trip Integrity Test**（documentation）：Node.js File Upload Round-Trip Integrity Test 证据：`ts/e2e-tests/runtimes/node/file-roundtrip/README.md`\n- **json-schema-to-zod + Zod v3 Compatibility Test**（documentation）：json-schema-to-zod + Zod v3 Compatibility Test 证据：`ts/e2e-tests/runtimes/node/json-schema-to-zod-v3/README.md`\n- **json-schema-to-zod + Zod v4 Compatibility Test**（documentation）：json-schema-to-zod + Zod v4 Compatibility Test 证据：`ts/e2e-tests/runtimes/node/json-schema-to-zod-v4/README.md`\n- **@composio/mastra + Zod v3 Tool Router Test**（documentation）：@composio/mastra + Zod v3 Tool Router Test 证据：`ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/README.md`\n- **@composio/mastra + Zod v4 Tool Router Test**（documentation）：@composio/mastra + Zod v4 Tool Router Test 证据：`ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/README.md`\n- **OpenAI + Zod v4 Compatibility Test**（documentation）：Verifies that @composio/core works correctly with openai and zod@4 . 证据：`ts/e2e-tests/runtimes/node/openai-zod4-compat/README.md`\n- **Tool Router Session Files E2E Test**（documentation）：End-to-end test for the Tool Router session files mount API list, upload, download, delete . 证据：`ts/e2e-tests/runtimes/node/tool-router-files/README.md`\n- **Tool Router Pagination E2E Test**（documentation）：End-to-end regression test for session.toolkits cursor pagination. 证据：`ts/e2e-tests/runtimes/node/tool-router-pagination/README.md`\n- **TypeScript .mjs Import Resolution Test**（documentation）：TypeScript .mjs Import Resolution Test 证据：`ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext/README.md`\n- **CJS Example**（documentation）：This example demonstrates how to use Composio SDK with CommonJS. 证据：`ts/examples/cjs/README.md`\n- **Connected Accounts Example**（documentation）：This example demonstrates how to work with connected accounts in the Composio SDK, including authorization flows and waiting for connections to become active. 证据：`ts/examples/connected-accounts/README.md`\n- **Custom Tools Examples**（documentation）：This directory contains examples demonstrating how to create and use custom tools with Composio SDK. 证据：`ts/examples/custom-tools/README.md`\n- **File-handling Example**（documentation）：This example demonstrates how to use Composio SDK for file-handling. 证据：`ts/examples/file-handling/README.md`\n- **Google Example**（documentation）：This example demonstrates how to use Composio SDK with Google's GenAI Gemini . 证据：`ts/examples/google/README.md`\n- **Json-schema-to-zod Example**（documentation）：This example demonstrates how to use Composio SDK for json-schema-to-zod. 证据：`ts/examples/json-schema-to-zod/README.md`\n- **Llamaindex Example**（documentation）：This example demonstrates how to use Composio SDK for llamaindex. 证据：`ts/examples/llamaindex/README.md`\n- **Mastra Example**（documentation）：This example demonstrates how to use Composio SDK for mastra. 证据：`ts/examples/mastra/README.md`\n- **Mcp Example**（documentation）：This example demonstrates how to use Composio SDK for mcp. 证据：`ts/examples/mcp/README.md`\n- **Vercel Example with Composio SDK**（documentation）：This example demonstrates how to use the Composio SDK with Vercel's AI SDK to create an AI-powered application that can interact with HackerNews data. 证据：`ts/examples/modifiers/README.md`\n- **Session-management Example**（documentation）：This example demonstrates how to use Composio SDK for session-management. 证据：`ts/examples/session-management/README.md`\n- **Tool-router Example**（documentation）：This example demonstrates how to use Composio SDK for tool-router. 证据：`ts/examples/tool-router/README.md`\n- **Vercel Example with Composio SDK**（documentation）：This example demonstrates how to use the Composio SDK with Vercel's AI SDK to create an AI-powered application that can interact with HackerNews data. 证据：`ts/examples/toolkits/README.md`\n- 其余 61 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/CLAUDE.md`, `docs/README.md`, `docs/scripts/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/CLAUDE.md`, `docs/README.md`, `docs/scripts/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction to Composio**：importance `high`\n - source_paths: README.md, ts/README.md, python/README.md\n- **Getting Started**：importance `high`\n - source_paths: ts/docs/getting-started.md, ts/packages/core/src/composio.ts, python/composio/sdk.py, ts/examples/tool-router/src/index.ts, python/examples/tool_router/tools.py\n- **System Architecture**：importance `high`\n - source_paths: ts/packages/core/src/index.ts, python/composio/__init__.py, ts/packages/core/src/platform/node.ts, ts/packages/core/src/platform/workerd.ts, python/composio/core/models/toolkits.py\n- **Core Concepts**：importance `high`\n - source_paths: ts/docs/core-concepts.md, ts/packages/core/src/models/Toolkits.ts, ts/packages/core/src/models/Tools.ts, ts/packages/core/src/models/ConnectedAccounts.ts, python/composio/core/models/tools.py\n- **TypeScript SDK**：importance `high`\n - source_paths: ts/packages/core/src/composio.ts, ts/packages/core/src/models/ToolRouter.ts, ts/packages/core/src/models/Files.node.ts, ts/packages/core/src/errors/index.ts, ts/docs/api/composio.md\n- **Python SDK**：importance `high`\n - source_paths: python/composio/sdk.py, python/composio/client/__init__.py, python/composio/client/types.py, python/composio/core/models/tool_router.py, python/composio/core/models/tool_router_session.py\n- **AI Framework Providers**：importance `high`\n - source_paths: ts/packages/providers/openai/src/index.ts, ts/packages/providers/anthropic/src/index.ts, ts/packages/providers/langchain/src/index.ts, ts/packages/providers/llamaindex/src/index.ts, python/providers/openai/composio_openai/provider.py\n- **Toolkits Management**：importance `high`\n - source_paths: ts/packages/core/src/models/Toolkits.ts, python/composio/core/models/toolkits.py, ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts, docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx, docs/content/docs/toolkits/enable-and-disable-toolkits.mdx\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `dc052f5c0e91bd425e2167a1eecc741335a2bf18`\n- inspected_files: `pyproject.toml`, `pnpm-lock.yaml`, `Dockerfile`, `package.json`, `README.md`, `uv.lock`, `docs/vercel.json`, `docs/source.config.ts`, `docs/CLAUDE.md`, `docs/package.json`, `docs/proxy.ts`, `docs/README.md`, `docs/tsconfig.json`, `docs/components.json`, `docs/bunfig.toml`, `docs/scripts/generate-meta-tools.ts`, `docs/scripts/generate-toolkits.ts`, `docs/scripts/generate-api-index.ts`, `docs/scripts/preload.ts`, `docs/scripts/README.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_54d53b3e2a6e4cf4a3e4783f824ed87b | https://github.com/ComposioHQ/composio/issues/3269 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shar…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shares:{})\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_1b88beb594aa433eb998eac3b16a20e0 | https://github.com/ComposioHQ/composio/issues/3422 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Feature] Custom auth configs shouldn't require a dev project to use\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] Custom auth configs shouldn't require a dev project to use\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_1d62ba62e77b47ff88b50d2db41a8cf7 | https://github.com/ComposioHQ/composio/issues/3271 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `composio` 与安装入口 `@composio/core` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:762304524 | https://github.com/ComposioHQ/composio | repo=composio; install=@composio/core\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:762304524 | https://github.com/ComposioHQ/composio | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:762304524 | https://github.com/ComposioHQ/composio | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：@composio/core@0.10.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：@composio/core@0.10.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_66f9d5fd557f41c7845ca5dd7d93ae6f | https://github.com/ComposioHQ/composio/releases/tag/%40composio/core%400.10.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：ComposioHQ/composio\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shar…（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Feature] Custom auth configs shouldn't require a dev project to use（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/ComposioHQ/composio 项目说明书\n\n生成时间：2026-05-15 11:24:53 UTC\n\n## 目录\n\n- [Introduction to Composio](#introduction)\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture-overview)\n- [Core Concepts](#core-concepts)\n- [TypeScript SDK](#typescript-sdk)\n- [Python SDK](#python-sdk)\n- [AI Framework Providers](#providers-integration)\n- [Toolkits Management](#toolkits-management)\n- [Custom Tools and Toolkits](#custom-tools)\n- [Connected Accounts](#connected-accounts)\n\n\n\n## Introduction to Composio\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#architecture-overview), [Core Concepts](#core-concepts)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/ComposioHQ/composio/blob/main/README.md)\n- [ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n- [ts/packages/cli/src/commands/root-help.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts)\n- [ts/packages/cli/src/commands/$default.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/$default.cmd.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [python/providers/claude_agent_sdk/README.md](https://github.com/ComposioHQ/composio/blob/main/python/providers/claude_agent_sdk/README.md)\n
\n\n# Introduction to Composio\n\n## Overview\n\nComposio is a comprehensive platform for managing Python and TypeScript projects that enables AI agents to interact with external tools and services. It provides a unified interface for tool execution, toolkit management, and agent integration across multiple AI frameworks.\n\n**资料来源：[ts/packages/cli/src/commands/$default.cmd.ts:7]()\n\n```typescript\nexport const $defaultCmd = Command.make('composio', { logLevel }).pipe(\n Command.withDescription(\n `Composio CLI - A tool for managing Python and TypeScript composio.dev projects.`\n )\n);\n```\n\n## Core Architecture\n\nComposio operates through a layered architecture that separates concerns between the CLI interface, core SDK, provider system, and tool execution layer.\n\n```mermaid\ngraph TD\n A[User/Agent] --> B[Composio CLI]\n B --> C[Core SDK]\n C --> D[Providers]\n D --> E[Tool Execution Layer]\n E --> F[External Services]\n \n G[Python SDK] --> C\n H[TypeScript SDK] --> C\n```\n\n### SDK Components\n\n| Component | Language | Purpose |\n|-----------|----------|---------|\n| Core SDK | TypeScript | Central tool management and execution |\n| Python SDK | Python | Python-native integration |\n| CLI | TypeScript | Command-line interface for tool management |\n| Providers | TypeScript/Python | Framework-specific integrations |\n\n**资料来源：[ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n\n## Composio CLI\n\nThe Composio CLI is the primary interface for managing tools, executing actions, and administering projects. It provides commands for both runtime operations and development workflows.\n\n**资料来源：[ts/packages/cli/src/commands/root-help.ts:1-50](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts)\n\n### Primary Commands\n\n| Command | Description |\n|---------|-------------|\n| `composio execute` | Execute a tool with specified parameters |\n| `composio link` | Link a toolkit to the current project |\n| `composio tools list` | List available tools from a toolkit |\n| `composio tools info` | Get detailed information about a specific tool |\n| `composio triggers list` | List available triggers |\n| `composio triggers info` | Get detailed information about a trigger |\n| `composio orgs switch` | Switch between organizations |\n\n**资料来源：[ts/packages/cli/src/services/command-hints.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts)\n\n### Development Commands\n\nThe CLI includes a dedicated `dev` namespace for development workflows:\n\n| Command | Description |\n|---------|-------------|\n| `composio dev init` | Initialize a new Composio project |\n| `composio dev playground-execute` | Execute tools in playground mode |\n| `composio dev logs tools` | View tool execution logs |\n| `composio dev logs triggers` | View trigger execution logs |\n| `composio dev toolkits list` | List available toolkits |\n| `composio dev toolkits info` | Get toolkit information |\n| `composio dev toolkits search` | Search for toolkits |\n| `composio dev toolkits version` | Manage toolkit versions |\n\n**资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n\n## Tool Execution Flow\n\nTools in Composio follow a structured execution pipeline that handles permission requests, parameter validation, and result processing.\n\n```mermaid\ngraph TD\n A[User Request] --> B[CLI Command]\n B --> C{Auth Required?}\n C -->|Yes| D[Permission Request]\n C -->|No| E[Execute Tool]\n D --> F{Permission Granted?}\n F -->|Session| E\n F -->|Once| E\n F -->|Deny| G[Abort]\n E --> H[Tool Execution]\n H --> I[Return Result]\n I --> J[Log Execution]\n```\n\n**资料来源：[ts/packages/cli/src/services/tool-permissions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/tool-permissions.ts)\n\n## Provider System\n\nComposio uses a provider-based architecture to support different AI frameworks and agent implementations. Providers wrap tools with framework-specific logic and execution handlers.\n\n**资料来源：[ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n\n### Provider Types\n\n#### Non-Agentic Providers\n\nNon-agentic providers provide basic tool wrapping without autonomous decision-making:\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise;\n async getTools(modifiers?: SchemaModifiersParams): Promise;\n async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise;\n}\n```\n\n#### Agentic Providers\n\nAgentic providers support autonomous agent behavior with extended capabilities:\n\n```typescript\nclass AgenticProvider extends BaseAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise;\n async getTools(modifiers?: ModifiersParams): Promise;\n // Additional execution handlers for autonomous behavior\n}\n```\n\n**资料来源：[ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n\n### Creating New Providers\n\nTo create a new provider, use the CLI scripts:\n\n```bash\n# Create a non-agentic provider (default)\npnpm run create-provider \n\n# Create an agentic provider\npnpm run create-provider --agentic\n```\n\nThe script creates a new provider with the following structure:\n\n```\n/\n├── src/\n│ └── index.ts # Provider implementation\n├── package.json # Package configuration\n├── tsconfig.json # TypeScript configuration\n├── tsup.config.ts # Build configuration\n└── README.md # Provider documentation\n```\n\n**资料来源：[ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n\n## Session Management\n\nEach CLI session operates within an isolated environment, providing secure and organized execution contexts.\n\n```mermaid\ngraph TD\n A[CLI Session Start] --> B[Create Session Directory]\n B --> C[Initialize Session State]\n C --> D[Execute Commands]\n D --> E[Store Artifacts]\n E --> F[Log History]\n D --> G{Command Type}\n G -->|run| H[Create Artifacts in cwd]\n G -->|execute| I[Download Attachments]\n```\n\n**资料来源：[ts/packages/cli/src/commands/root-help.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts)\n\n### Session Artifacts\n\nEach CLI session gets a unique subdirectory, scoped to your working directory, which stores:\n\n- Session history\n- Files created during `run` and `execute` commands\n- Downloaded attachments\n- Generated outputs\n\nUse `composio artifacts cwd` to print the path for the current directory's session.\n\n## SDK Integration\n\nComposio provides SDKs for both Python and TypeScript, enabling integration with various AI frameworks.\n\n**资料来源：[python/providers/claude_agent_sdk/README.md](https://github.com/ComposioHQ/composio/blob/main/python/providers/claude_agent_sdk/README.md)\n\n### Python SDK Example\n\n```python\nimport asyncio\nfrom composio import Composio\nfrom composio_claude_agent_sdk import ClaudeAgentSDKProvider\nfrom claude_agent_sdk import query, ClaudeAgentOptions\n\n# Initialize Composio with the Claude Code Agents provider\ncomposio = Composio(provider=ClaudeAgentSDKProvider())\n\nasync def main():\n # Get tools from Composio\n tools = composio.tools.get(\n user_id=\"default\",\n toolkits=[\"gmail\"],\n )\n \n # Create an MCP server configuration with the tools\n mcp_server = composio.provider.create_mcp_server(tools)\n```\n\n**资料来源：[python/providers/claude_agent_sdk/README.md](https://github.com/ComposioHQ/composio/blob/main/python/providers/claude_agent_sdk/README.md)\n\n## Environment Configuration\n\nComposio supports various environment variables for configuration:\n\n| Variable | Description |\n|----------|-------------|\n| `COMPOSIO_API_KEY` | Your Composio API key |\n| `COMPOSIO_BASE_URL` | Custom API base URL (optional) |\n| `COMPOSIO_LOG_LEVEL` | Logging level: silent, error, warn, info, debug |\n| `COMPOSIO_DISABLE_TELEMETRY` | Disable telemetry when set to \"true\" |\n| `COMPOSIO_TOOLKIT_VERSION_` | Specific version for a toolkit |\n| `DEVELOPMENT` | Development mode flag |\n| `CI` | CI environment flag |\n\n**资料来源：[ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n\n## Project Initialization\n\nTo initialize a new Composio project:\n\n```bash\ncd \ncomposio dev init\n```\n\nThe initialization process:\n\n1. Creates a `.env.local` file in the project directory\n2. Sets up the project API key by fetching session information\n3. Validates the connection to Composio services\n\n**资料来源：[ts/packages/cli/src/commands/init.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/init.cmd.ts)\n\n## Error Handling\n\nComposio uses a structured error handling system based on the Effect framework:\n\n```typescript\nexport const captureErrorsFrom = (cause: Cause): readonly PrettyError[] =>\n reduceWithContext(cause, undefined, {\n emptyCase: (): readonly PrettyError[] => [],\n dieCase: (_, unknownError) => [parseError(unknownError)],\n failCase: (_, error) => [parseError(error)],\n interruptCase: () => [],\n parallelCase: (_, l, r) => [...l, ...r],\n sequentialCase: (_, l, r) => [...l, ...r],\n });\n```\n\n**资料来源：[ts/packages/cli/src/effect-errors/logic/errors/capture-errors-from-cause.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effect-errors/logic/errors/capture-errors-from-cause.ts)\n\n## Local Tools\n\nComposio supports local tool execution through the `cli-local-tools` package, which provides a registry of locally available tools independent of remote API calls.\n\n```typescript\nexport const isLocalToolSlug = (\n toolSlug: string,\n options: { readonly declarations?: ReadonlyArray } = {}\n): boolean => {\n const upper = toolSlug.toUpperCase();\n if (!upper.startsWith(LOCAL_TOOL_PREFIX)) return false;\n return (\n resolveLocalTool(toolSlug, { includeUnsupported: true, declarations: options.declarations }) !==\n null\n );\n};\n```\n\n**资料来源：[ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n\n## Documentation Generation\n\nThe Python SDK includes automated documentation generation using Griffe:\n\n```bash\ncd python\nuv run --with griffe python scripts/generate-docs.py\n```\n\nThis process:\n1. Extracts docstrings from `composio/**/*.py` → structured data\n2. Transforms data → MDX files\n3. Outputs written to `docs/content/reference/sdk-reference/python/`\n\n**资料来源：[python/scripts/README.md](https://github.com/ComposioHQ/composio/blob/main/python/scripts/README.md)\n\n## Further Reading\n\n- [SDK Documentation Generator](https://github.com/ComposioHQ/composio/blob/main/python/scripts/README.md)\n- [Release Process Documentation](https://github.com/ComposioHQ/composio/blob/main/ts/docs/internal/release.md)\n- [Contributing Guide](https://github.com/ComposioHQ/composio/blob/main/CONTRIBUTING.md)\n- [Official Documentation](https://docs.composio.dev)\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Introduction to Composio](#introduction), [TypeScript SDK](#typescript-sdk), [Python SDK](#python-sdk)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/docs/getting-started.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/getting-started.md)\n- [ts/packages/core/src/composio.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/composio.ts)\n- [python/composio/sdk.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/sdk.py)\n- [ts/examples/tool-router/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/examples/tool-router/src/index.ts)\n- [python/examples/tool_router/tools.py](https://github.com/ComposioHQ/composio/blob/main/python/examples/tool_router/tools.py)\n- [ts/packages/cli/src/commands/init.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/init.cmd.ts)\n- [ts/packages/cli/src/services/terminal-ui.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/terminal-ui.ts)\n
\n\n# Getting Started\n\n## Overview\n\nComposio is a platform that provides a unified interface for managing and executing tools across multiple agent frameworks. The Getting Started guide provides developers with the essential steps to install, configure, and begin using Composio SDK in their projects. Whether you're using TypeScript/JavaScript or Python, this guide covers the complete setup process from installation through your first tool execution.\n\n## Installation\n\n### TypeScript/JavaScript SDK\n\nInstall the Composio SDK using your preferred package manager:\n\n```bash\n# Using npm\nnpm install @composio/core\n\n# Using pnpm\npnpm add @composio/core\n\n# Using yarn\nyarn add @composio/core\n```\n\n### Python SDK\n\nInstall the Python SDK using pip:\n\n```bash\npip install composio-core\n```\n\n### CLI Installation\n\nThe Composio CLI provides tools for managing toolkits, executing tools locally, and inspecting execution logs. Install globally for command-line access:\n\n```bash\n# Using npm\nnpm install -g @composio/cli\n\n# Using bun (recommended)\nbun install -g @composio/cli\n```\n\n## Environment Configuration\n\n### API Key Setup\n\nComposio requires API key authentication. Set up your environment variables before using the SDK:\n\n```bash\n# Required\nexport COMPOSIO_API_KEY=\"your-api-key-here\"\n\n# Optional: Custom API base URL\nexport COMPOSIO_BASE_URL=\"https://api.composio.dev\"\n\n# Optional: Logging level (silent, error, warn, info, debug)\nexport COMPOSIO_LOG_LEVEL=\"info\"\n\n# Optional: Disable telemetry\nexport COMPOSIO_DISABLE_TELEMETRY=\"true\"\n```\n\n### Project Initialization\n\nFor TypeScript projects, initialize Composio in your working directory:\n\n```bash\ncomposio init\n```\n\nThe initialization process:\n\n1. Creates a `.composio` directory in your project\n2. Generates a `.env.local` file with your project API key\n3. Sets up local tool configurations\n4. Validates your API credentials\n\n```typescript\n// Example: composio.ts initialization\nimport { Composio } from \"@composio/core\";\n\nconst client = new Composio({\n apiKey: process.env.COMPOSIO_API_KEY,\n baseURL: process.env.COMPOSIO_BASE_URL,\n});\n```\n\n资料来源：[ts/packages/core/src/composio.ts:1-50]()\n\n## SDK Initialization\n\n### TypeScript SDK\n\nInitialize the Composio client with configuration options:\n\n```typescript\nimport { Composio } from \"@composio/core\";\n\n// Basic initialization\nconst client = new Composio();\n\n// With explicit configuration\nconst client = new Composio({\n apiKey: \"your-api-key\",\n baseURL: \"https://api.composio.dev\",\n logLevel: \"info\",\n timeout: 30000,\n});\n```\n\n资料来源：[ts/packages/core/src/composio.ts:50-80]()\n\n### Python SDK\n\nInitialize the Python client:\n\n```python\nfrom composio import Composio\n\n# Basic initialization\nclient = Composio()\n\n# With explicit configuration\nclient = Composio(\n api_key=\"your-api-key\",\n base_url=\"https://api.composio.dev\",\n log_level=\"info\",\n timeout=30\n)\n```\n\n资料来源：[python/composio/sdk.py:1-100]()\n\n## Core Concepts\n\n### Tools\n\nTools are the fundamental building blocks in Composio. Each tool represents a specific action that can be executed through the platform.\n\n```typescript\n// Get available tools\nconst tools = await client.tools.list();\n\n// Get a specific tool by slug\nconst tool = await client.tools.get(\"github_create_issue\");\n```\n\n### Toolkits\n\nToolkits are collections of related tools organized by service or functionality:\n\n```typescript\n// List available toolkits\nconst toolkits = await client.toolkits.list();\n\n// Get tools within a toolkit\nconst githubTools = await client.toolkits.get(\"github\");\n```\n\n### Actions\n\nActions are specific operations that can be performed using tools:\n\n```typescript\n// Execute a tool action\nconst result = await client.execute(\"github_create_issue\", {\n title: \"Bug report\",\n body: \"Description of the issue\",\n repository: \"owner/repo\"\n});\n```\n\n## Working with Tools\n\n### Listing Available Tools\n\n```typescript\n// List all available tools\nconst allTools = await client.getTools();\n\n// Filter tools by toolkit\nconst slackTools = await client.getTools({ toolkit: \"slack\" });\n\n// Filter tools by search query\nconst searchResults = await client.getTools({ query: \"message\" });\n```\n\n### Executing Tools\n\n```typescript\n// Execute a single tool\nconst result = await client.execute(\"slack_send_message\", {\n channel: \"#general\",\n text: \"Hello from Composio!\"\n});\n```\n\n资料来源：[ts/examples/tool-router/src/index.ts:1-50]()\n\n### Tool Execution Parameters\n\n| Parameter | Type | Description | Required |\n|-----------|------|-------------|----------|\n| `toolSlug` | string | Unique identifier for the tool | Yes |\n| `params` | object | Tool-specific input parameters | Yes |\n| `accountId` | string | Connected account identifier | No |\n| `sessionId` | string | Execution session identifier | No |\n\n## Local Tools (CLI)\n\nThe Composio CLI enables local tool execution for development and testing.\n\n### Local Toolkit Registry\n\n```typescript\nimport { getLocalToolkitDeclarations, getAllLocalToolkitSlugs } from \"@composio/cli\";\n\n// Get all available local toolkits\nconst slugs = getAllLocalToolkitSlugs();\n\n// Check if a toolkit is local\nconst isLocal = isLocalToolkitSlug(\"local_filesystem\");\n```\n\n### Local Tool Execution\n\n```bash\n# Execute a local tool\ncomposio execute local_filesystem_read --path ./README.md\n\n# Get tool schema\ncomposio execute --get-schema\n```\n\n## CLI Commands Reference\n\n### Development Commands\n\n| Command | Description |\n|---------|-------------|\n| `composio dev init` | Initialize a new Composio project |\n| `composio dev playground-execute` | Test tool execution in playground mode |\n| `composio dev logs tools` | View tool execution logs |\n| `composio dev logs triggers` | View trigger execution logs |\n\n### Tool Commands\n\n| Command | Description |\n|---------|-------------|\n| `composio tools list` | List available tools |\n| `composio tools info` | Get detailed tool information |\n| `composio execute` | Execute a specific tool |\n\n### Toolkit Commands\n\n| Command | Description |\n|---------|-------------|\n| `composio toolkits list` | List available toolkits |\n| `composio toolkits info` | Get toolkit details |\n| `composio toolkits search` | Search toolkits |\n| `composio toolkits version` | Manage toolkit versions |\n\n资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts:1-30]()\n\n## Tool Router Pattern\n\nThe tool router enables intelligent routing of agent requests to appropriate tools:\n\n```typescript\nimport { Composio } from \"@composio/core\";\nimport { OpenAI } from \"openai\";\n\nconst client = new Composio();\nconst openai = new OpenAI();\n\nasync function handleAgentRequest(userMessage: string) {\n // Get available tools from Composio\n const tools = await client.getTools({\n filtered_tools: [\"github\", \"slack\", \"jira\"]\n });\n\n // Create a system prompt with tool schemas\n const systemPrompt = `\n You have access to the following tools:\n ${tools.map(t => `- ${t.name}: ${t.description}`).join('\\n')}\n `;\n\n // Process with OpenAI\n const response = await openai.chat.completions.create({\n model: \"gpt-4\",\n messages: [\n { role: \"system\", content: systemPrompt },\n { role: \"user\", content: userMessage }\n ],\n tools: tools.map(tool => tool.schema),\n });\n\n // Execute the selected tool\n if (response.choices[0].message.tool_calls) {\n for (const call of response.choices[0].message.tool_calls) {\n const result = await client.execute(call.function.name, \n JSON.parse(call.function.arguments)\n );\n console.log(\"Tool result:\", result);\n }\n }\n}\n```\n\n资料来源：[ts/examples/tool-router/src/index.ts:50-100]()\n\n## Permission Management\n\nWhen executing tools that require user authentication, Composio provides a permission flow:\n\n```typescript\n// Request permission for tool execution\nconst permission = await client.requestPermission({\n toolSlug: \"github_create_issue\",\n params: {\n title: \"New Issue\",\n body: \"Issue description\"\n }\n});\n\n// Permission states:\n// - pending: Waiting for user approval\n// - approved: Permission granted\n// - denied: Permission rejected\n```\n\n资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-50]()\n\n## Logging and Debugging\n\n### CLI Logging\n\nThe CLI provides structured logging for debugging:\n\n```bash\n# View tool execution logs\ncomposio dev logs tools \n\n# View trigger logs\ncomposio dev logs triggers \n```\n\n### SDK Logging\n\n```typescript\nconst client = new Composio({\n logLevel: \"debug\",\n // Custom logger\n logger: {\n info: (msg) => console.log(`[INFO] ${msg}`),\n error: (msg) => console.error(`[ERROR] ${msg}`),\n debug: (msg) => console.debug(`[DEBUG] ${msg}`),\n }\n});\n```\n\n## Workflow Diagram\n\n```mermaid\ngraph TD\n A[Install SDK] --> B[Set API Key]\n B --> C[Initialize Client]\n C --> D[Get Available Tools]\n D --> E{Choose Toolkit}\n E -->|GitHub| F[GitHub Tools]\n E -->|Slack| G[Slack Tools]\n E -->|Jira| H[Jira Tools]\n F --> I[Execute Tool]\n G --> I\n H --> I\n I --> J[Check Permission]\n J -->|Approved| K[Return Result]\n J -->|Denied| L[Raise Error]\n```\n\n## Next Steps\n\n- **Explore Toolkits**: Browse the available [toolkits documentation](./docs/toolkits.md)\n- **API Reference**: View the complete [SDK API reference](./docs/reference/sdk-reference.md)\n- **Examples**: Check out [example projects](./examples/) for real-world implementations\n- **CLI Commands**: Review the [CLI command reference](./docs/cli-commands.md)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `API key not found` | Set `COMPOSIO_API_KEY` environment variable |\n| `Tool not found` | Verify the toolkit is installed: `composio toolkits list` |\n| `Permission denied` | Run `composio link ` to connect your account |\n| `Timeout error` | Increase timeout in client config or check network connectivity |\n\n### Getting Help\n\n- Documentation: https://docs.composio.dev\n- Discord Community: https://discord.gg/composio\n- GitHub Issues: https://github.com/ComposioHQ/composio/issues\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Introduction to Composio](#introduction), [Core Concepts](#core-concepts), [TypeScript SDK](#typescript-sdk), [Python SDK](#python-sdk)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/core/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/index.ts)\n- [python/composio/__init__.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/__init__.py)\n- [ts/packages/core/src/platform/node.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/platform/node.ts)\n- [ts/packages/core/src/platform/workerd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/platform/workerd.ts)\n- [python/composio/core/models/toolkits.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/toolkits.py)\n
\n\n# System Architecture\n\nComposio is a multi-platform tool integration framework that enables AI agents to interact with external tools and services. The system is architected as a cross-language SDK with TypeScript/JavaScript as the primary implementation and Python bindings, supporting multiple runtime environments including Node.js, Deno, Bun, and Cloudflare Workers (workerd).\n\n## Core Components Overview\n\n```mermaid\ngraph TD\n subgraph \"TypeScript SDK\"\n A[composio-core] --> B[Platform Abstraction]\n B --> C[Node.js Runtime]\n B --> D[workerd Runtime]\n B --> E[Bun Runtime]\n end\n \n subgraph \"Tool Integration\"\n F[Tool Registry] --> G[Toolkits]\n G --> H[Individual Tools]\n end\n \n subgraph \"Providers\"\n I[BaseNonAgenticProvider]\n J[BaseAgenticProvider]\n K[MCP Server]\n end\n \n A --> F\n A --> I\n A --> J\n A --> K\n```\n\nThe system consists of three primary layers:\n\n| Layer | Purpose | Key Files |\n|-------|---------|-----------|\n| **Core SDK** | Platform initialization, API client management | `ts/packages/core/src/index.ts` |\n| **Tool Layer** | Tool registration, toolkit management | `python/composio/core/models/toolkits.py` |\n| **Provider Layer** | External SDK integration (Claude, OpenAI, etc.) | `ts/packages/providers/*/src/index.ts` |\n\n## Platform Abstraction Architecture\n\nComposio implements a platform-agnostic design through a platform abstraction layer that detects and adapts to different JavaScript runtimes.\n\n### Platform Detection\n\nThe platform system uses conditional imports to provide runtime-specific implementations:\n\n```typescript\n// ts/packages/core/src/platform/node.ts\nimport { NodeRuntime } from './implementations/node';\n\nexport const platform = NodeRuntime;\n```\n\n### Supported Platforms\n\n| Platform | Module | Use Case |\n|----------|--------|----------|\n| Node.js | `platform/node.ts` | Server-side applications, CLI tools |\n| workerd | `platform/workerd.ts` | Cloudflare Workers, edge computing |\n| Bun | Bundled with core | High-performance runtime |\n| Deno | Native fetch/http | Deno Deploy, standalone execution |\n\n### Platform Interface Contract\n\nAll platform implementations must provide:\n\n1. **HTTP Client** - Request/response handling\n2. **File System Access** - Local artifact storage\n3. **Environment Variables** - Configuration management\n4. **Console/Logging** - Output handling\n\n## Tool System Architecture\n\n### Tool Classification\n\nTools in Composio are organized hierarchically:\n\n```mermaid\ngraph TD\n A[Toolkit] --> B[Gmail Toolkit]\n A --> C[Slack Toolkit]\n A --> D[GitHub Toolkit]\n \n B --> E[send_email]\n B --> F[read_emails]\n C --> G[send_message]\n D --> H[create_issue]\n```\n\n### Tool Data Model\n\nThe Python toolkit model (`python/composio/core/models/toolkits.py`) defines:\n\n```python\nclass Toolkit:\n slug: str # Unique identifier\n name: str # Display name\n description: str # Human-readable description\n tools: List[Tool] # Contained tools\n triggers: List[Trigger] # Event triggers\n version: str # Version string\n```\n\n### Local vs Remote Tools\n\nComposio distinguishes between local and remote tool execution:\n\n| Type | Execution Location | Registry |\n|------|-------------------|----------|\n| Remote Tools | Composio Cloud API | `composio-tools` |\n| Local Tools | Client-side execution | `cli-local-tools` |\n\nLocal tools are registered via `LocalToolkitDeclaration` and execute directly on the client, supporting multiple platforms (Node.js, workerd, Bun).\n\n## Provider System Architecture\n\n### Provider Types\n\n```mermaid\ngraph TD\n A[BaseComposioProvider] --> B[BaseNonAgenticProvider]\n A --> C[BaseAgenticProvider]\n \n B --> D[Custom Non-Agentic Providers]\n C --> E[Claude Agent SDK Provider]\n C --> F[OpenAI Provider]\n C --> G[Custom Agentic Providers]\n```\n\n### Provider Interface\n\nNon-agentic providers implement:\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise;\n async getTools(modifiers?: SchemaModifiersParams): Promise;\n async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise;\n}\n```\n\nAgentic providers extend with execution handling:\n\n```typescript\nclass AgenticProvider extends BaseAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise;\n async getTools(modifiers?: ModifiersParams): Promise;\n async execute(toolSlug: string, params: any): Promise;\n}\n```\n\n### MCP Server Integration\n\nProviders can create MCP (Model Context Protocol) server configurations:\n\n```python\nmcp_server = composio.provider.create_mcp_server(tools)\n```\n\nThis enables interoperability with any MCP-compatible client.\n\n## SDK Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Composio\n participant Platform\n participant API\n \n User->>Composio: Composio(config)\n Composio->>Platform: detectRuntime()\n Platform-->>Composio: RuntimeType\n Composio->>API: initializeClient(apiKey, baseURL)\n API-->>Composio: Authenticated client\n Composio-->>User: SDK instance ready\n```\n\n### TypeScript Initialization\n\n```typescript\n// ts/packages/core/src/index.ts\nimport { Composio } from \"@composio/core\";\n\nconst client = new Composio({\n apiKey: process.env.COMPOSIO_API_KEY,\n baseURL: \"https://api.composio.dev\"\n});\n```\n\n### Python Initialization\n\n```python\n# python/composio/__init__.py\nfrom composio import Composio\n\nclient = Composio(\n api_key=os.getenv(\"COMPOSIO_API_KEY\")\n)\n```\n\n## CLI Architecture\n\nThe Composio CLI is built using the Effect framework for functional command handling:\n\n### Command Structure\n\n| Command | Purpose |\n|---------|---------|\n| `composio execute` | Execute a tool directly |\n| `composio tools list` | List available tools |\n| `composio tools info` | Get tool details |\n| `composio generate ts` | Generate TypeScript types |\n| `composio dev init` | Initialize development environment |\n| `composio dev playground-execute` | Test tool execution |\n\n### Core Dependency Management\n\nThe CLI detects project environments and suggests appropriate installation commands:\n\n```mermaid\ngraph TD\n A[Project Detection] --> B{Python vs JS?}\n B -->|Python| C[Detect Package Manager]\n B -->|JS| D[Detect Package Manager]\n C --> E[uv pip install composio]\n D --> F[npm install @composio/core]\n```\n\n## Toolkit Index Generation\n\nThe TypeScript SDK generates type-safe toolkit indices for compile-time safety:\n\n```mermaid\ngraph LR\n A[Toolkit Definitions] --> B[createToolkitIndex]\n B --> C[Type-safe Enum]\n C --> D[Tool Wrappers]\n```\n\nThe `createToolkitIndex` function transforms raw toolkit data into structured indices with version overrides and type-safe tool accessors.\n\n## Configuration and Environment\n\n### Environment Variables\n\n| Variable | Purpose | Default |\n|----------|---------|---------|\n| `COMPOSIO_API_KEY` | Authentication key | Required |\n| `COMPOSIO_BASE_URL` | API endpoint | `api.composio.dev` |\n| `COMPOSIO_LOG_LEVEL` | Logging verbosity | `info` |\n| `COMPOSIO_DISABLE_TELEMETRY` | Opt-out of telemetry | `false` |\n| `COMPOSIO_TOOLKIT_VERSION_` | Toolkit version override | `latest` |\n\n### Project-Scoped Configuration\n\nThe CLI creates `.env.local` files scoped to working directories for session management and project-specific API keys.\n\n## Error Handling Architecture\n\nComposio uses the Effect library for typed error handling:\n\n```typescript\nconst captureErrorsFrom = (cause: Cause): readonly PrettyError[] =>\n reduceWithContext(cause, undefined, {\n emptyCase: () => [],\n failCase: (_, error) => [parseError(error)],\n interruptCase: () => [],\n // ...\n });\n```\n\nThis provides structured error reporting with context preservation across asynchronous operations.\n\n## Data Flow: Tool Execution\n\n```mermaid\ngraph TD\n A[User Code] --> B[Composio Client]\n B --> C[Tool Request]\n C --> D{Local or Remote?}\n D -->|Local| E[Local Toolkit Registry]\n D -->|Remote| F[Composio API]\n E --> G[Direct Execution]\n F --> H[API Validation]\n H --> I[Remote Execution]\n I --> J[Result Return]\n G --> J\n J --> K[Response Processing]\n K --> A\n```\n\n## Extension Points\n\n### Creating Custom Providers\n\nDevelopers can create new providers using the provided scaffolding:\n\n```bash\n# Non-agentic provider\npnpm create:provider my-provider\n\n# Agentic provider with execution handlers\npnpm create:provider my-provider --agentic\n```\n\nThis generates the standard provider structure with required methods pre-scaffolded.\n\n### Local Tool Development\n\nLocal tools can be registered in `cli-local-tools/src/registry.ts` with platform-specific execution logic.\n\n## Security Model\n\n### Tool Permissions\n\nTool execution requires user consent, managed through a browser-based permission flow:\n\n1. Tool execution request triggers permission check\n2. Browser UI presents allow/deny options\n3. Decision is cached for session or one-time use\n4. Token-based verification prevents CSRF attacks\n\n### API Key Management\n\n- **User API Keys**: Global authentication tokens\n- **Project API Keys**: Scoped to specific projects\n- **Environment Variables**: `.env.local` for development\n\n## Summary\n\nComposio's architecture provides:\n\n1. **Cross-platform support** through runtime detection and abstraction\n2. **Type-safe tool access** via generated TypeScript indices\n3. **Provider flexibility** with extensible provider interfaces\n4. **Local execution** for tools that don't require cloud API calls\n5. **Permission management** with session-scoped authorization\n6. **CLI tooling** for development and tool management\n\nThe system balances convenience (automatic platform detection) with flexibility (custom providers and local tools), making it suitable for both production deployments and development workflows.\n\n---\n\n\n\n## Core Concepts\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture-overview), [Toolkits Management](#toolkits-management), [Connected Accounts](#connected-accounts)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n- [ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [ts/packages/cli/src/effects/toolkit-version-overrides.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts)\n- [ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n
\n\n# Core Concepts\n\nComposio is a platform that provides a collection of tools and toolkits for AI agents. Understanding the core concepts is essential for effectively using and extending Composio. This page covers the fundamental building blocks: Tools, Toolkits, Connected Accounts, and the Provider system.\n\n## Toolkits\n\nToolkits are collections of related tools that enable AI agents to perform actions within specific domains. Each toolkit focuses on a particular service or functionality area, such as Gmail, Slack, GitHub, or Google Calendar.\n\n### Toolkit Structure\n\nA toolkit consists of:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `slug` | `string` | Unique identifier for the toolkit |\n| `name` | `string` | Human-readable name |\n| `description` | `string` | Description of the toolkit's functionality |\n| `tools` | `Tool[]` | Array of tools included in the toolkit |\n| `platforms` | `LocalCliPlatform[]` | Supported platforms (e.g., linux, darwin, windows) |\n| `source` | `string` | Source of the toolkit |\n| `setup` | `SetupConfig` | Configuration for setting up the toolkit |\n\n### Toolkit Version Management\n\nComposio supports version overrides for toolkits. The version system allows specifying different versions for different toolkits:\n\n```typescript\n// From toolkit-version-overrides.ts\nexport interface ToolkitVersionSpec {\n toolkitSlug: string;\n toolkitVersion: string; // e.g., '20250901_00' or 'latest'\n}\n\nexport type ToolkitVersionOverrides = Map, string>;\n```\n\nThe system groups toolkits by version and builds version maps from specifications:\n\n```mermaid\ngraph TD\n A[ToolkitVersionSpec Array] --> B[groupByVersion]\n B --> C[Map: version -> toolkitSlug[]]\n \n A --> D[buildVersionMapFromSpecs]\n D --> E[ToolkitVersionOverrides Map]\n E --> F[ toolkitSlug -> version]\n```\n\n### Toolkit Discovery Commands\n\nThe CLI provides commands for discovering and inspecting toolkits:\n\n| Command | Description |\n|---------|-------------|\n| `composio toolkits list` | List all available toolkits |\n| `composio toolkits info` | Get detailed information about a specific toolkit |\n| `composio toolkits search` | Search toolkits by keyword |\n| `composio toolkits version` | View and manage toolkit versions |\n\n## Tools\n\nTools are the fundamental execution units in Composio. Each tool represents a specific action that can be performed by an AI agent.\n\n### Tool Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `slug` | `string` | Unique identifier for the tool |\n| `name` | `string` | Human-readable name |\n| `description` | `string` | Description of what the tool does |\n| `inputParams` | `Parameter[]` | Required and optional input parameters |\n| `outputParams` | `Parameter[]` | Output parameters (optional) |\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Composio as Composio Core\n participant Tool as Tool Executor\n participant API as External API\n \n Agent->>Composio: Execute tool(slug, params)\n Composio->>Tool: Create execution context\n Tool->>API: Make API request\n API-->>Tool: API response\n Tool-->>Composio: Formatted result\n Composio-->>Agent: Return result\n```\n\n### Toolkits Index\n\nThe toolkit index organizes all tools by their parent toolkit:\n\n```typescript\n// From create-toolkit-index.ts\nexport interface CreateToolkitIndexInput {\n slug: string;\n version?: string;\n typeableTools:\n | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> }\n | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> };\n triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>;\n}\n\nexport type ToolkitIndex = Record;\n```\n\n## Connected Accounts\n\nConnected Accounts represent authenticated access to external services. They enable tools to interact with user-specific data and perform authorized actions.\n\n### Account Model\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | `string` | Unique identifier for the connection |\n| `toolkit` | `string` | The toolkit this account belongs to |\n| `accountId` | `string` | User account ID on the external service |\n| `accountName` | `string` | Display name for the account |\n| `authConfig` | `AuthConfig` | Authentication configuration |\n| `status` | `ConnectionStatus` | Active, inactive, or error state |\n\n### Authentication Flow\n\n```mermaid\ngraph LR\n A[User] -->|Link Account| B[CLI Command]\n B --> C{Auth Required?}\n C -->|Yes| D[OAuth/Browser Auth]\n D --> E[Token Exchange]\n E --> F[Store Credentials]\n C -->|No| F\n F --> G[Connected Account Created]\n```\n\n## Local CLI Tools\n\nLocal CLI tools are tools that execute locally on the user's machine rather than through the Composio cloud API. They provide additional capabilities for local development and execution.\n\n### Local Toolkit Declaration\n\n```typescript\ninterface LocalToolkitDeclaration {\n slug: string;\n name: string;\n description: string;\n platforms: LocalCliPlatform[];\n tools: LocalToolDeclaration[];\n source: string;\n setup?: SetupConfig;\n}\n```\n\n### Local Tool Registry\n\nThe registry manages local tools and provides functions for toolkit discovery:\n\n```typescript\n// From registry.ts\nexport const getAllLocalToolkitSlugs = (\n options: { readonly declarations?: ReadonlyArray } = {}\n): ReadonlyArray;\n\nexport const isLocalToolkitSlug = (\n toolkitSlug: string | undefined,\n options: { readonly declarations?: ReadonlyArray } = {}\n): boolean;\n\nexport const getLocalCustomToolkits = (\n options: {\n readonly currentPlatform?: LocalCliPlatform;\n readonly toolkits?: ReadonlyArray;\n readonly declarations?: ReadonlyArray;\n } = {}\n): ReadonlyArray;\n```\n\n### Platform Support\n\nLocal tools can specify which platforms they support:\n\n```typescript\ntype LocalCliPlatform = 'linux' | 'darwin' | 'windows';\n```\n\n## Provider System\n\nComposio uses a provider system to wrap and manage tools. Providers add functionality like schema modification and parameter handling.\n\n### Provider Types\n\n```typescript\n// From modifiers.types.ts\nexport type ProviderOptions =\n TProvider extends BaseComposioProvider\n ? TProvider extends BaseAgenticProvider\n ? AgenticToolOptions\n : ToolOptions\n : never;\n```\n\n### Provider Interface\n\nNon-agentic providers must implement:\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n // Wrap a tool with schema modifiers\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise;\n\n // Get all available tools\n async getTools(modifiers?: SchemaModifiersParams): Promise;\n\n // Get a specific tool by slug\n async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise;\n}\n```\n\nAgentic providers extend the interface with additional agentic-specific options.\n\n## Schema Modifiers\n\nSchema modifiers allow providers to transform tool schemas before execution:\n\n```typescript\ninterface SchemaModifiersParams {\n modifySchema?: (context: { schema: z.ZodSchema }) => z.ZodSchema;\n beforeExecute?: (context: { params: Record }) => Record;\n afterExecute?: (context: { result: unknown }) => unknown;\n}\n```\n\n### Modifier Execution Flow\n\n```mermaid\ngraph TD\n A[Raw Tool Schema] --> B[modifySchema]\n B --> C[Modified Schema]\n C --> D[User Params]\n D --> E[beforeExecute]\n E --> F[Processed Params]\n F --> G[Tool Execution]\n G --> H[Raw Result]\n H --> I[afterExecute]\n I --> J[Final Result]\n```\n\n## Tool Permissions\n\nComposio implements a permission system for tool execution, especially for local tools that may have access to sensitive local resources.\n\n### Permission Flow\n\n```mermaid\ngraph TD\n A[Tool Execution Request] --> B{Permission Check}\n B -->|Session Allowed| C[Execute Tool]\n B -->|One-time| D[Prompt User]\n D -->|Allow| C\n D -->|Deny| E[Access Denied]\n B -->|Denied| E\n```\n\n### Permission Options\n\n| Option | Description |\n|--------|-------------|\n| `Allow for this session` | Grants permission for the current session |\n| `Allow once` | Grants permission for a single execution |\n| `Deny` | Denies the execution |\n\n## Error Handling\n\nComposio uses Effect-based error handling for predictable error management:\n\n```typescript\n// From capture-errors-from-cause.ts\nexport const captureErrorsFrom = (cause: Cause): readonly PrettyError[] =>\n reduceWithContext(cause, undefined, {\n emptyCase: (): readonly PrettyError[] => [],\n dieCase: (_, unknownError) => [parseError(unknownError)],\n failCase: (_, error) => [parseError(error)],\n interruptCase: () => [],\n parallelCase: (_, l, r) => [...l, ...r],\n sequentialCase: (_, l, r) => [...l, ...r],\n });\n```\n\n## Summary\n\nThe Composio architecture is built on several interconnected concepts:\n\n| Concept | Role |\n|---------|------|\n| **Toolkits** | Organize related tools by domain |\n| **Tools** | Individual executable units with defined inputs/outputs |\n| **Connected Accounts** | Authenticated access to external services |\n| **Local CLI Tools** | Locally executed tools that extend cloud capabilities |\n| **Providers** | Wrap and enhance tools with additional functionality |\n| **Schema Modifiers** | Transform tool schemas and execution contexts |\n| **Permissions** | Control access to tool execution |\n\nTogether, these concepts provide a flexible and extensible system for AI agent tool integration.\n\n---\n\n\n\n## TypeScript SDK\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [AI Framework Providers](#providers-integration), [Getting Started](#getting-started)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts)\n- [ts/packages/core/scripts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/scripts/README.md)\n- [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [ts/packages/ts-builders/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/ts-builders/README.md)\n- [ts/packages/cli/src/commands/generate/generate.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/generate/generate.cmd.ts)\n- [ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md)\n- [ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n- [ts/packages/cli/src/effects/validate-toolkit-versions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/validate-toolkit-versions.ts)\n- [ts/packages/core/src/models/Tools.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/Tools.ts)\n
\n\n# TypeScript SDK\n\nThe Composio TypeScript SDK provides a comprehensive toolkit for integrating third-party services and tools into AI agent applications. It enables developers to programmatically interact with tools, manage toolkits, execute actions, and handle file operations across multiple platforms.\n\n## Overview\n\nThe SDK is organized as a monorepo under `ts/` containing multiple packages that work together to provide a complete development experience:\n\n| Package | Purpose |\n|---------|---------|\n| `@composio/core` | Core SDK functionality, API clients, and tool management |\n| `@composio/cli` | Command-line interface for project management and generation |\n| `@composio/cli-local-tools` | Local tool execution and toolkit registry |\n| `@composio/ts-builders` | TypeScript AST generation utilities |\n| `@composio/providers` | Base provider implementations |\n\n资料来源：[ts/README.md]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Developer Application] --> B[@composio/core]\n B --> C[ComposioToolkitsRepository]\n B --> D[ToolRouter]\n B --> E[Files Module]\n \n C --> F[Composio API]\n \n G[@composio/cli] --> H[generate command]\n H --> I[TypeScript Type Stubs]\n H --> J[transpiled JS]\n \n G --> K[execute command]\n K --> L[LocalToolRegistry]\n L --> M[Tool Execution]\n \n N[Providers] --> B\n N --> O[BaseNonAgenticProvider]\n N --> P[BaseAgenticProvider]\n```\n\nThe SDK follows a layered architecture where the core package handles all API interactions while the CLI provides tooling support for project setup and execution.\n\n资料来源：[ts/packages/ts-builders/README.md]()\n资料来源：[ts/packages/cli/src/commands/generate/generate.cmd.ts]()\n\n## Core Components\n\n### Composio Client\n\nThe main entry point for interacting with the Composio platform:\n\n```typescript\nimport { Composio } from '@composio/core';\n\nconst client = new Composio({\n apiKey: process.env.COMPOSIO_API_KEY,\n baseUrl: process.env.COMPOSIO_BASE_URL, // optional\n});\n```\n\nThe client provides access to:\n- `tools` - Tool listing and retrieval\n- `toolkits` - Toolkit management\n- `execute` - Direct tool execution\n- `files` - File upload and management\n\n### Tool Management\n\nTools are fetched and wrapped using providers that modify their schemas and execution behavior:\n\n```typescript\n// Get all tools\nconst tools = await client.tools.list();\n\n// Get tools with type safety\nconst typedTools = await client.tools.list({\n type: 'typed',\n filterParams: { tags: ['github'] }\n});\n\n// Get a specific tool\nconst tool = await client.tools.get('default', 'GITHUB_GET_REPOS');\n```\n\n资料来源：[ts/packages/core/src/models/Tools.ts]()\n资料来源：[ts/packages/core/src/types/modifiers.types.ts]()\n\n### Provider System\n\nProviders enable integration with different AI frameworks and modify tool behavior:\n\n#### Non-Agentic Providers\n\nFor frameworks that handle tool execution externally:\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\n\nclass CustomProvider extends BaseNonAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise {\n if (modifiers?.schema) {\n return modifiers.schema(toolSlug, tool);\n }\n return tool;\n }\n\n async getTools(modifiers?: SchemaModifiersParams): Promise {\n const response = await this.client.getTools();\n return Promise.all(response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers)));\n }\n}\n```\n\n#### Agentic Providers\n\nFor frameworks requiring full control over execution:\n\n```typescript\nimport { BaseAgenticProvider } from '@composio/core';\n\nclass AgenticProvider extends BaseAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise;\n async getTools(modifiers?: ModifiersParams): Promise;\n}\n```\n\n资料来源：[ts/packages/providers/README.md]()\n\n### Modifiers System\n\nSchema and execution modifiers allow runtime customization of tool behavior:\n\n```typescript\nconst tools = await composio.tools.list('default', {\n modifySchema: (toolSlug, toolkitSlug, schema) => {\n return { ...schema, description: 'Custom description' };\n },\n beforeExecute: (toolSlug, toolkitSlug, params) => params,\n afterExecute: (toolSlug, toolkitSlug, result) => result\n});\n```\n\n资料来源：[ts/packages/core/src/types/modifiers.types.ts]()\n资料来源：[ts/packages/core/src/models/Tools.ts]()\n\n## CLI Commands\n\n### Type Stub Generation\n\nThe `composio generate ts` command generates TypeScript type definitions:\n\n```bash\n# Generate with transpiled JS (default when no --output-dir)\ncomposio generate ts\n\n# Specify output directory\ncomposio generate ts --output-dir ./types\n\n# Compact single module output\ncomposio generate ts --compact\n\n# Filter by specific toolkits\ncomposio generate ts --toolkits github --toolkits slack\n```\n\n#### Command Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--compact` | Emit a single module file | `false` |\n| `--transpiled` | Also emit ESM JavaScript files | `true` (if no `--output-dir`) |\n| `--output-dir` | Output directory path | `node_modules/@composio/core` |\n| `--toolkits` | Filter to specific toolkits | All toolkits |\n\n**Invariants:**\n- `--output-dir` cannot refer to a path inside `node_modules`\n- Without `--output-dir`, files are written to `@composio/core` in `node_modules`\n- If `--transpiled` is `true`, sources are transpiled to ESM JavaScript alongside TypeScript files (CJS not supported)\n\n资料来源：[ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts]()\n\n### Tool Execution\n\n```bash\n# Execute a tool\ncomposio execute \"GITHUB_GET_REPOS\" -d '{}'\n\n# Get tool schema\ncomposio execute \"GITHUB_GET_REPOS\" --get-schema\n\n# Dry run\ncomposio execute \"GITHUB_GET_REPOS\" -d '{}' --dry-run\n```\n\n### Tool Information\n\n```bash\n# View tool details\ncomposio tools info \"GITHUB_GET_REPOS\"\n\n# List tools in a toolkit\ncomposio tools list \"github\"\n```\n\n资料来源：[ts/packages/cli/src/commands/tools/commands/tools.info.cmd.ts]()\n资料来源：[ts/packages/cli/src/services/command-hints.ts]()\n\n## Local Tools\n\nThe CLI supports local tool execution through the `cli-local-tools` package:\n\n```typescript\nimport { getLocalCustomToolkits, isLocalToolSlug } from '@composio/cli-local-tools';\n\n// Check if a slug is a local tool\nif (isLocalToolSlug('LOCAL_MY_TOOL')) {\n // Handle local tool\n}\n\n// Get all local toolkits\nconst toolkits = getLocalCustomToolkits({\n currentPlatform: 'linux',\n toolkits: ['my-toolkit']\n});\n```\n\n### Toolkit Readiness\n\nCheck platform compatibility and readiness status:\n\n```typescript\nimport { getReadinessReport } from '@composio/cli-local-tools';\n\nconst report = await getReadinessReport({\n currentPlatform: detectCliPlatform(),\n toolkits: ['github', 'slack']\n});\n```\n\nStatus values:\n- `ready` - Toolkit and tools fully supported\n- `disabled` - Disabled via `~/composio/local_tools.json`\n- `unsupported` - Platform not supported by toolkit\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts]()\n资料来源：[ts/packages/cli-local-tools/src/readiness.ts]()\n\n## Toolkit Index\n\nThe SDK creates a toolkit index for efficient tool and trigger type lookup:\n\n```typescript\nimport { createToolkitIndex } from '@composio/cli/src/generation/create-toolkit-index';\n\ntype ToolkitIndex = Record;\n```\n\nThe index maps toolkit names to their tools and trigger types, enabling fast lookups by slug prefix matching.\n\n资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts]()\n\n## Environment Configuration\n\n| Variable | Description |\n|----------|-------------|\n| `COMPOSIO_API_KEY` | API key for Composio services |\n| `COMPOSIO_BASE_URL` | Custom API base URL (optional) |\n| `COMPOSIO_LOG_LEVEL` | Logging level: `silent`, `error`, `warn`, `info`, `debug` |\n| `COMPOSIO_DISABLE_TELEMETRY` | Set to `\"true\"` to disable telemetry |\n| `COMPOSIO_TOOLKIT_VERSION_` | Specific version for a toolkit (e.g., `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`) |\n| `DEVELOPMENT` | Development mode flag |\n| `CI` | CI environment flag |\n\n资料来源：[ts/README.md]()\n\n## Version Validation\n\nThe CLI validates toolkit version overrides against the API:\n\n```typescript\nimport { validateToolkitVersionOverrides } from '@composio/cli/src/effects/validate-toolkit-versions';\n\nconst { validatedOverrides, warnings } = yield* client\n .validateToolkitVersions(versionOverrides, toolkitSlugsFilter);\n```\n\nInvalid versions are caught and reported with helpful error messages including correct toolkit slug format guidance.\n\n资料来源：[ts/packages/cli/src/effects/validate-toolkit-versions.ts]()\n\n## SDK Documentation Generation\n\nDocumentation is auto-generated from TypeScript source using TypeDoc:\n\n```bash\npnpm generate:docs\n```\n\n**Process:**\n1. TypeDoc extracts JSDoc from `src/models/*.ts` → JSON AST\n2. `generate-docs.ts` transforms AST → MDX files\n3. Output written to `docs/content/reference/sdk-reference/typescript/`\n\n**Configuration:**\n- Entry points: Auto-discovered from `src/models/*.ts`\n- Excluded classes: `INTERNAL_CLASSES` set in script\n- User-instantiated classes: `USER_INSTANTIATED_CLASSES` (shows constructor)\n\n资料来源：[ts/packages/core/scripts/README.md]()\n\n## Provider Creation\n\nCreate new providers using the provided script:\n\n```bash\n# Non-agentic provider (default)\npnpm run create-provider my-provider\n\n# Agentic provider\npnpm run create-provider my-provider --agentic\n```\n\nThe script creates a new provider with structure:\n```\n/\n├── src/index.ts # Provider implementation\n├── package.json # Package configuration\n├── tsconfig.json # TypeScript configuration\n├── tsup.config.ts # Build configuration\n└── README.md # Provider documentation\n```\n\n资料来源：[ts/packages/providers/README.md]()\n\n## Error Handling\n\nThe SDK provides structured error handling through the errors module:\n\n```typescript\nimport { ComposioError, InvalidToolkitVersionsError } from '@composio/core/errors';\n\n// Errors include:\n// - ComposioError: Base error class\n// - InvalidToolkitVersionsError: Version validation failures\n// - InvalidToolkitsError: Invalid toolkit slugs\n// - HttpServerError: API communication errors\n```\n\n资料来源：[ts/packages/core/src/errors/index.ts]()\n\n## Framework Integrations\n\nThe SDK includes pre-built providers for common AI frameworks:\n\n| Provider | Package | Description |\n|----------|---------|-------------|\n| LangChain | `@composio/langchain` | Integration with LangChain agents |\n| Vercel AI | `@composio/vercel` | Integration with Vercel AI SDK |\n\nProvider dependencies:\n```json\n{\n \"@composio/core\": \">=0.10.0 <1.0.0\",\n \"ai\": \"^5.0.0 || ^6.0.0\"\n}\n```\n\n资料来源：[ts/packages/providers/langchain/package.json]()\n资料来源：[ts/packages/providers/vercel/package.json]()\n\n---\n\n\n\n## Python SDK\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#typescript-sdk), [AI Framework Providers](#providers-integration), [Getting Started](#getting-started)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/composio/sdk.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/sdk.py)\n- [python/composio/client/__init__.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/client/__init__.py)\n- [python/composio/client/types.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/client/types.py)\n- [python/composio/core/models/tool_router.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/tool_router.py)\n- [python/composio/core/models/tool_router_session.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/tool_router_session.py)\n- [python/composio/exceptions.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/exceptions.py)\n- [python/examples/tool_router/tools.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/examples/tool_router/tools.py)\n- [python/docs/development.md](https://github.com/ComposioHQ/composio/blob/main/python/docs/development.md)\n
\n\n# Python SDK\n\nThe Composio Python SDK provides a comprehensive interface for integrating external tools and services into AI applications. It enables developers to fetch, configure, and execute tools from the Composio platform while supporting advanced features like schema modification, execution hooks, and MCP (Model Context Protocol) server creation.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Application Code] --> B[Composio SDK]\n B --> C[Tool Client]\n B --> D[Tool Router]\n B --> E[MCP Server]\n C --> F[Composio API]\n D --> F\n E --> F\n G[Schema Modifiers] --> B\n H[Execution Modifiers] --> B\n I[Providers] --> B\n```\n\nThe SDK is structured around several core components that work together to provide a seamless integration experience. The primary entry point is the `Composio` class, which orchestrates all tool-related operations including fetching tools from the API, managing local tool configurations, and handling execution with modifiers. 资料来源：[python/composio/sdk.py:1-100]()\n\n## Core Components\n\n### Composio Main Class\n\nThe `Composio` class serves as the central interface for SDK operations. It handles initialization, tool retrieval, and configuration management through a fluent API design.\n\n```python\nfrom composio import Composio\n\ncomposio = Composio(\n api_key=\"your-api-key\",\n base_url=\"https://api.composio.dev\",\n timeout=60,\n max_retries=3,\n allow_tracking=True,\n file_download_dir=\"./downloads\",\n provider=OpenAIProvider(),\n toolkit_versions={\"github\": \"12202025_01\"}\n)\n```\n\n资料来源：[python/README.md:1-50]()\n\n### Tool Client\n\nThe tool client module (`composio/client/__init__.py`) manages all interactions with tools, including retrieval, filtering, and execution. It provides a typed interface for working with tools and toolkits through the types defined in `client/types.py`. 资料来源：[python/composio/client/__init__.py:1-50]()\n\n### Type System\n\nThe SDK uses Pydantic models for type safety and validation. All tool schemas, parameters, and return types are strongly typed through the `Tool` and related classes in `client/types.py`. 资料来源：[python/composio/client/types.py:1-100]()\n\n## Configuration\n\n### Initialization Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `api_key` | `str` | Environment `COMPOSIO_API_KEY` | Your Composio API key |\n| `base_url` | `str` | `\"https://api.composio.dev\"` | Custom API base URL |\n| `timeout` | `int` | `60` | Request timeout in seconds |\n| `max_retries` | `int` | `3` | Maximum retry attempts |\n| `allow_tracking` | `bool` | `True` | Enable/disable telemetry |\n| `file_download_dir` | `str` | `\"./downloads\"` | Directory for file downloads |\n| `provider` | `Provider` | `OpenAIProvider()` | Custom provider instance |\n| `toolkit_versions` | `dict` | `{}` | Specific toolkit versions |\n\n资料来源：[python/composio/sdk.py:50-100]()\n\n### Environment Variables\n\nThe SDK automatically reads several environment variables for configuration:\n\n| Variable | Description |\n|----------|-------------|\n| `COMPOSIO_API_KEY` | Primary API authentication key |\n| `COMPOSIO_BASE_URL` | Override default API endpoint |\n| `COMPOSIO_WORKING_DIR` | Session working directory |\n| `COMPOSIO_LOG_LEVEL` | Logging level (silent, error, warn, info, debug) |\n| `COMPOSIO_TOOLKIT_VERSION_` | Version for specific toolkit |\n| `DEVELOPMENT` | Development mode flag |\n| `CI` | CI environment flag |\n\n资料来源：[python/README.md:100-150]()\n\n## Tool Management\n\n### Retrieving Tools\n\n```python\n# Get all tools from a specific toolkit\ntools = composio.tools.get(\n user_id=\"default\",\n toolkits=[\"gmail\", \"github\"]\n)\n\n# Get a specific tool by slug\ntool = composio.tools.get(\n user_id=\"default\",\n slug=\"GITHUB_CREATE_ISSUE\"\n)\n```\n\n资料来源：[python/README.md:50-80]()\n\n### Tool Structure\n\nTools in the Composio SDK follow a standardized structure that includes:\n\n- **Slug**: Unique identifier for the tool\n- **Name**: Human-readable display name\n- **Description**: Detailed explanation of tool functionality\n- **Parameters**: JSON schema for input validation\n- **Toolkit**: Parent toolkit grouping\n- **Triggers**: Associated trigger configurations\n\n资料来源：[python/composio/client/types.py:50-100]()\n\n## Schema Modifiers\n\nSchema modifiers allow transformation of tool schemas before they are used by AI models. This enables customization of parameter descriptions, adding defaults, or restructuring schemas.\n\n```mermaid\ngraph LR\n A[Raw Tool Schema] --> B[Schema Modifier Function]\n B --> C[Modified Schema]\n C --> D[AI Model / Tool Execution]\n```\n\n### Usage Example\n\n```python\nfrom composio import schema_modifier\nfrom composio.types import Tool\n\n@schema_modifier(tools=[\"HACKERNEWS_GET_USER\"])\ndef modify_schema(tool: str, toolkit: str, schema: Tool) -> Tool:\n schema[\"description\"] = \"Enhanced HackerNews user lookup with additional features\"\n schema[\"parameters\"][\"properties\"][\"include_karma\"] = {\n \"type\": \"boolean\",\n \"description\": \"Include user karma in response\",\n \"default\": True\n }\n return schema\n\n# Apply modifier when retrieving tools\ntools = composio.tools.get(\n user_id=\"default\",\n slug=\"HACKERNEWS_GET_USER\",\n modifiers=[modify_schema]\n)\n```\n\n资料来源：[python/README.md:80-120]()\n\n## Execution Modifiers\n\nExecution modifiers provide hooks for transforming tool execution behavior. They come in two flavors: `before_execute` and `after_execute`.\n\n```mermaid\ngraph TD\n A[Tool Call Request] --> B[Before Execute Hook]\n B --> C{Continue?}\n C -->|Yes| D[Execute Tool]\n C -->|No| E[Return Modified Response]\n D --> F[After Execute Hook]\n F --> G[Final Response]\n```\n\n### Before Execute Hook\n\n```python\nfrom composio import before_execute\n\n@before_execute(tools=[\"GITHUB_CREATE_ISSUE\"])\ndef validate_issue_input(tool: str, toolkit: str, params: dict) -> dict:\n # Validate or transform parameters before execution\n if \"title\" in params and len(params[\"title\"]) > 100:\n params[\"title\"] = params[\"title\"][:97] + \"...\"\n return params\n```\n\n### After Execute Hook\n\n```python\nfrom composio import after_execute\n\n@after_execute(tools=[\"GITHUB_CREATE_ISSUE\"])\ndef log_issue_creation(tool: str, toolkit: str, params: dict, response: dict) -> dict:\n # Post-process the response\n print(f\"Issue created: {response.get('html_url')}\")\n return response\n```\n\n资料来源：[python/README.md:120-180]()\n\n## Tool Router (Experimental)\n\nThe Tool Router is an experimental feature that enables intelligent tool routing and session management. It provides capabilities for dynamic tool selection, retry logic, and stateful interactions.\n\n```mermaid\ngraph TD\n A[User Request] --> B[Tool Router]\n B --> C[Session Manager]\n C --> D{Route Decision}\n D -->|Tool A| E[Execute Tool A]\n D -->|Tool B| F[Execute Tool B]\n E --> G[Response Handler]\n F --> G\n G --> H[User Response]\n```\n\n### Tool Router Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `base_url` | `str` | Composio API base URL |\n| `api_key` | `str` | API authentication key |\n| `tool_calls_max_concurrency` | `int` | Maximum concurrent tool calls |\n| `default_language` | `str` | Default language for responses |\n\n资料来源：[python/composio/core/models/tool_router.py:1-100]()\n\n### Tool Router Session\n\nThe session management system (`tool_router_session.py`) maintains state across multiple tool interactions, enabling complex multi-step workflows:\n\n```python\nfrom composio.core.models.tool_router_session import ToolRouterSession\n\nsession = ToolRouterSession(\n user_id=\"user123\",\n session_id=\"session456\",\n tool_calls=[]\n)\n```\n\n资料来源：[python/composio/core/models/tool_router_session.py:1-50]()\n\n### Tool Definitions\n\nCustom tool definitions can be provided to the Tool Router for specialized behavior:\n\n```python\nfrom composio.core.models.tool_router import ToolDefinition\n\ntools = [\n ToolDefinition(\n name=\"custom_tool\",\n description=\"A custom tool implementation\",\n parameters={\"type\": \"object\", \"properties\": {}}\n )\n]\n```\n\n资料来源：[python/examples/tool_router/tools.py:1-50]()\n\n## MCP (Model Context Protocol) Support\n\nThe SDK provides native MCP server creation for seamless integration with Claude, Cursor, and other MCP-compatible tools.\n\n```mermaid\ngraph LR\n A[Composio SDK] --> B[MCP Server]\n B --> C[Claude Desktop]\n B --> D[Cursor]\n B --> E[Other MCP Clients]\n```\n\n### Creating an MCP Server\n\n```python\nfrom composio import Composio\n\ncomposio = Composio()\n\n# Create MCP server with specified toolkits\nmcp_server = composio.mcp.create(\n \"my-mcp-server\",\n toolkits=[\"github\", \"gmail\"],\n manually_manage_connections=False\n)\n\n# Generate server instance for a user\nserver_instance = mcp_server.generate(\"user123\")\nprint(f\"MCP Server URL: {server_instance['url']}\")\n```\n\n资料来源：[python/README.md:200-230]()\n\n## Error Handling\n\nThe SDK defines specific exception types for different error scenarios, enabling precise error handling in application code.\n\n```python\nfrom composio import Composio\nfrom composio.exceptions import ComposioError, ApiKeyNotProvidedError\n\ntry:\n composio = Composio() # Will raise ApiKeyNotProvidedError if no API key\n tools = composio.tools.get(user_id=\"default\", toolkits=[\"github\"])\nexcept ApiKeyNotProvidedError:\n print(\"Please provide your COMPOSIO_API_KEY\")\nexcept ComposioError as e:\n print(f\"Composio error: {e}\")\n```\n\n### Exception Hierarchy\n\n| Exception | Base Class | Description |\n|-----------|------------|-------------|\n| `ComposioError` | `Exception` | Base exception for all SDK errors |\n| `ApiKeyNotProvidedError` | `ComposioError` | API key missing or invalid |\n| `ToolNotFoundError` | `ComposioError` | Requested tool does not exist |\n| `ToolkitNotFoundError` | `ComposioError` | Requested toolkit not available |\n| `ConnectionError` | `ComposioError` | Network connectivity issues |\n| `TimeoutError` | `ComposioError` | Request exceeded timeout |\n\n资料来源：[python/composio/exceptions.py:1-50]()\n\n## Supported AI Frameworks\n\nThe SDK provides dedicated integrations for popular AI frameworks:\n\n| Framework | Description | Provider Class |\n|-----------|-------------|----------------|\n| OpenAI | Direct integration with OpenAI's API | `OpenAIProvider()` |\n| LangChain | Tools and agents for LangChain workflows | `LangChainProvider()` |\n| LangGraph | State machine workflows | `LangGraphProvider()` |\n| CrewAI | Multi-agent systems | `CrewAIProvider()` |\n| AutoGen | Microsoft's AutoGen framework | `AutoGenProvider()` |\n| Anthropic | Claude integration | `AnthropicProvider()` |\n| Google AI | Gemini and Google AI services | `GoogleAIProvider()` |\n| LlamaIndex | RAG and data framework | `LlamaIndexProvider()` |\n\n```python\nfrom composio import Composio\nfrom composio_providers import OpenAIProvider\n\ncomposio = Composio(provider=OpenAIProvider())\n```\n\n资料来源：[python/README.md:180-200]()\n\n## Development and Testing\n\n### Development Setup\n\nFor local development, ensure you have the required dependencies installed:\n\n```bash\ncd python\nuv sync\n```\n\n### Integration Testing\n\nIntegration tests are located in `python/composio/integration_test/` and require a valid Composio API key:\n\n```bash\nexport COMPOSIO_API_KEY=\"your_api_key_here\"\npytest python/composio/integration_test/ -v\n```\n\n资料来源：[python/composio/integration_test/README.md:1-30]()\n\n### Available Test Modules\n\n| Test File | Coverage |\n|-----------|----------|\n| `test_mcp.py` | MCP functionality and server creation |\n| `test_tool_router.py` | Tool Router experimental features |\n\n## Quick Start Example\n\n```python\nfrom composio import Composio\nfrom composio_claude_agent_sdk import ClaudeAgentSDKProvider\n\n# Initialize with a provider\ncomposio = Composio(provider=ClaudeAgentSDKProvider())\n\n# Get tools from specific toolkits\ntools = composio.tools.get(\n user_id=\"default\",\n toolkits=[\"gmail\", \"github\"]\n)\n\n# Create MCP server configuration\nmcp_server = composio.provider.create_mcp_server(tools)\n\n# Tools are now available to your AI agent\n```\n\n资料来源：[python/providers/claude_agent_sdk/README.md:1-50]()\n\n## Best Practices\n\n1. **API Key Management**: Store your API key in environment variables rather than hardcoding\n2. **Timeout Configuration**: Adjust timeout based on expected tool execution times\n3. **Error Handling**: Always wrap SDK calls in try-except blocks for graceful degradation\n4. **Modifier Usage**: Apply schema and execution modifiers at initialization for consistent behavior\n5. **Tool Filtering**: Use specific toolkits rather than fetching all tools to reduce latency\n\n---\n\n\n\n## AI Framework Providers\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#typescript-sdk), [Python SDK](#python-sdk), [Core Concepts](#core-concepts)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/providers/openai/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/openai/src/index.ts)\n- [ts/packages/providers/anthropic/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/anthropic/src/index.ts)\n- [ts/packages/providers/langchain/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/langchain/src/index.ts)\n- [ts/packages/providers/llamaindex/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/llamaindex/src/index.ts)\n- [python/providers/openai/composio_openai/provider.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/openai/composio_openai/provider.py)\n- [python/providers/langchain/composio_langchain/provider.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/langchain/composio_langchain/provider.py)\n- [python/providers/crewai/composio_crewai/providers.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/crewai/composio_crewai/providers.py)\n- [ts/docs/providers/custom.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/providers/custom.md)\n- [ts/docs/api/providers.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/api/providers.md)\n
\n\n# AI Framework Providers\n\n## Overview\n\nAI Framework Providers are adapter layers that integrate Composio's tool ecosystem with various AI agent frameworks. They act as bridges between Composio's standardized tool definitions and the specific formats expected by different AI SDKs and frameworks such as OpenAI, Anthropic Claude Code, LangChain, LlamaIndex, and CrewAI.\n\nProviders enable agents to:\n- Access Composio tools in their native format\n- Transform tool schemas for framework-specific requirements\n- Handle tool execution with custom modifiers\n- Create MCP (Model Context Protocol) servers from Composio tool definitions\n\n资料来源：[ts/docs/api/providers.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/api/providers.md)\n\n## Architecture\n\n### Provider Hierarchy\n\n```mermaid\ngraph TD\n A[BaseComposioProvider] --> B[BaseNonAgenticProvider]\n A --> C[BaseAgenticProvider]\n B --> D[OpenAIProvider]\n B --> E[AnthropicProvider]\n B --> F[LangChainProvider]\n B --> G[LlamaIndexProvider]\n C --> H[ClaudeAgentSDKProvider]\n C --> I[VercelProvider]\n```\n\n### Data Flow\n\n```mermaid\ngraph LR\n A[Composio SDK] -->|Tool Requests| B[Provider]\n B -->|Schema Transform| C[Framework-Specific Format]\n C --> D[AI Agent/Framework]\n D -->|Execution| E[Modifier Chain]\n E -->|Result| F[Response Transform]\n F -->|ToolExecuteResponse| A\n```\n\n## Provider Types\n\n### Non-Agentic Providers\n\nNon-agentic providers wrap tools for frameworks that handle tool execution externally. They focus on schema transformation without managing execution flow.\n\n**Available Non-Agentic Providers:**\n\n| Provider | Package | Framework |\n|----------|---------|-----------|\n| OpenAIProvider | `@composio/openai` | OpenAI SDK |\n| AnthropicProvider | `@composio/anthropic` | Anthropic SDK |\n| LangChainProvider | `@composio/langchain` | LangChain |\n| LlamaIndexProvider | `@composio/llamaindex` | LlamaIndex |\n\n资料来源：[ts/packages/providers/openai/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/openai/src/index.ts)\n\n**Core Interface:**\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: SchemaModifiersParams\n ): Promise;\n\n async getTools(\n modifiers?: SchemaModifiersParams\n ): Promise;\n\n async getToolBySlug(\n slug: string,\n modifiers?: SchemaModifiersParams\n ): Promise;\n}\n```\n\n资料来源：[ts/docs/providers/custom.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/providers/custom.md)\n\n### Agentic Providers\n\nAgentic providers manage both schema transformation and execution flow. They support before/after execute modifiers for full control over tool behavior.\n\n**Core Interface:**\n\n```typescript\nclass AgenticProvider extends BaseAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: ModifiersParams\n ): Promise;\n\n async getTools(\n modifiers?: ModifiersParams\n ): Promise;\n\n async getToolBySlug(\n slug: string,\n modifiers?: ModifiersParams\n ): Promise;\n}\n```\n\n资料来源：[ts/docs/providers/custom.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/providers/custom.md)\n\n**Available Agentic Providers:**\n\n| Provider | Package | Framework |\n|----------|---------|-----------|\n| ClaudeAgentSDKProvider | `@composio/claude-agent-sdk` | Claude Code Agents SDK |\n| VercelProvider | `@composio/vercel` | Vercel AI SDK |\n\n## Core Methods\n\n### wrapTool\n\nTransforms a single tool with optional modifiers for framework-specific formatting.\n\n```typescript\nasync wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: SchemaModifiersParams\n): Promise\n```\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| toolSlug | `string` | Unique identifier for the tool |\n| tool | `Tool` | The tool definition to wrap |\n| modifiers | `SchemaModifiersParams` | Optional schema transformation functions |\n\n**Returns:** `Promise` - The transformed tool\n\n### getTools\n\nRetrieves all available tools, optionally filtered by toolkit and transformed with modifiers.\n\n```typescript\nasync getTools(\n modifiers?: SchemaModifiersParams\n): Promise\n```\n\n### getToolBySlug\n\nRetrieves a specific tool by its slug identifier.\n\n```typescript\nasync getToolBySlug(\n slug: string,\n modifiers?: SchemaModifiersParams\n): Promise\n```\n\n资料来源：[ts/packages/providers/openai/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/openai/src/index.ts)\n\n## Modifiers System\n\nModifiers enable runtime transformation of tool schemas and execution behavior.\n\n### Schema Modifiers\n\nTransform tool schemas before they are used by the agent:\n\n```typescript\ntype schemaModifier = (\n toolSlug: string,\n tool: Tool\n) => Tool;\n```\n\n### Execution Modifiers\n\nControl tool execution flow:\n\n```typescript\ntype beforeExecuteModifier = (\n toolSlug: string,\n params: Record\n) => Record;\n\ntype afterExecuteModifier = (\n toolSlug: string,\n response: ToolExecuteResponse\n) => ToolExecuteResponse;\n```\n\n### Modifier Application Flow\n\n```mermaid\ngraph TD\n A[Request Tool] --> B{Modifier Chain}\n B --> C[Schema Modifier]\n C --> D[Before Execute Modifier]\n D --> E[Tool Execution]\n E --> F[After Execute Modifier]\n F --> G[Return Response]\n```\n\n资料来源：[ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n\n## Python Providers\n\n### OpenAI Provider\n\n```python\nfrom composio_openai import ComposioOpenAI\n\nclient = ComposioOpenAI(api_key=\"your-api-key\")\n\n# Get tools\ntools = client.tools.get()\n\n# Execute a tool\nresult = client.tools.execute(\n action=\"HACKERNEWS_GET_USER\",\n params={\"username\": \"user123\"}\n)\n```\n\n资料来源：[python/providers/openai/composio_openai/provider.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/openai/composio_openai/provider.py)\n\n### LangChain Provider\n\n```python\nfrom composio_langchain import ComposioToolkit, Action\n\n# Initialize with LangChain adapter\ntoolkit = ComposioToolkit(\n actions=[Action.HACKERNEWS_GET_USER]\n)\n\n# Get LangChain tools\nlangchain_tools = toolkit.get_tools()\n```\n\n资料来源：[python/providers/langchain/composio_langchain/provider.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/langchain/composio_langchain/provider.py)\n\n### CrewAI Provider\n\n```python\nfrom composio_crewai import ComposioTool, Action\nfrom crewai import Agent\n\n# Create Composio tool for CrewAI\ncomposio_tool = ComposioTool(\n action=Action.HACKERNEWS_GET_USER\n)\n\n# Attach to CrewAI agent\nagent = Agent(\n role=\"Researcher\",\n goal=\"Fetch user data\",\n tools=[composio_tool]\n)\n```\n\n资料来源：[python/providers/crewai/composio_crewai/providers.py](https://github.com/ComposioHQ/composio/blob/main/python/providers/crewai/composio_crewai/providers.py)\n\n## TypeScript Provider Implementation\n\n### OpenAI Provider\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\nimport type { Tool, SchemaModifiersParams } from '@composio/core';\n\nexport class OpenAIProvider extends BaseNonAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: SchemaModifiersParams\n ): Promise {\n if (modifiers?.schema) {\n return modifiers.schema(toolSlug, tool);\n }\n return tool;\n }\n\n async getTools(modifiers?: SchemaModifiersParams): Promise {\n const response = await this.client.getTools();\n return Promise.all(\n response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers))\n );\n }\n\n async getToolBySlug(\n slug: string,\n modifiers?: SchemaModifiersParams\n ): Promise {\n const response = await this.client.getToolBySlug(slug);\n return this.wrapTool(slug, response.data, modifiers);\n }\n}\n```\n\n资料来源：[ts/packages/providers/openai/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/openai/src/index.ts)\n\n### Anthropic Provider\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\nimport type { Tool, SchemaModifiersParams } from '@composio/core';\n\nexport class AnthropicProvider extends BaseNonAgenticProvider {\n // Similar implementation to OpenAIProvider\n // Framework-specific adaptations applied in wrapTool\n}\n```\n\n资料来源：[ts/packages/providers/anthropic/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/anthropic/src/index.ts)\n\n### LlamaIndex Provider\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\nimport type { Tool, SchemaModifiersParams } from '@composio/core';\n\nexport class LlamaIndexProvider extends BaseNonAgenticProvider {\n // LlamaIndex-specific implementation\n}\n```\n\n资料来源：[ts/packages/providers/llamaindex/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/llamaindex/src/index.ts)\n\n## Creating Custom Providers\n\n### Project Structure\n\n```\nmy-provider/\n├── src/\n│ └── index.ts # Provider implementation\n├── package.json # Package configuration\n├── tsconfig.json # TypeScript configuration\n├── tsup.config.ts # Build configuration\n└── README.md # Provider documentation\n```\n\n### Generation Command\n\n```bash\n# Non-agentic provider (default)\npnpm create:provider my-provider\n\n# Agentic provider\npnpm create:provider my-provider --agentic\n```\n\n### Required Methods\n\n#### For Non-Agentic Providers\n\n```typescript\nimport { BaseNonAgenticProvider } from '@composio/core';\nimport type { Tool, SchemaModifiersParams } from '@composio/core';\n\nexport class MyProvider extends BaseNonAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: SchemaModifiersParams\n ): Promise {\n // Apply schema modifiers if provided\n if (modifiers?.schema) {\n return modifiers.schema(toolSlug, tool);\n }\n return tool;\n }\n\n async getTools(\n modifiers?: SchemaModifiersParams\n ): Promise {\n const response = await this.client.getTools();\n return Promise.all(\n response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers))\n );\n }\n\n async getToolBySlug(\n slug: string,\n modifiers?: SchemaModifiersParams\n ): Promise {\n const response = await this.client.getToolBySlug(slug);\n return this.wrapTool(slug, response.data, modifiers);\n }\n}\n```\n\n#### For Agentic Providers\n\n```typescript\nimport { BaseAgenticProvider } from '@composio/core';\nimport type { Tool, ModifiersParams, ToolExecuteResponse } from '@composio/core';\n\nexport class MyAgenticProvider extends BaseAgenticProvider {\n async wrapTool(\n toolSlug: string,\n tool: Tool,\n modifiers?: ModifiersParams\n ): Promise {\n if (modifiers?.schema) {\n return modifiers.schema(toolSlug, tool);\n }\n return tool;\n }\n\n async getTools(\n modifiers?: ModifiersParams\n ): Promise {\n const response = await this.client.getTools();\n return Promise.all(\n response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers))\n );\n }\n\n async getToolBySlug(\n slug: string,\n modifiers?: ModifiersParams\n ): Promise {\n const response = await this.client.getToolBySlug(slug);\n return this.wrapTool(slug, response.data, modifiers);\n }\n}\n```\n\n## Best Practices\n\n### Type Safety\n\nAlways use TypeScript and ensure proper type definitions for all methods and parameters. Leverage the existing type definitions from `@composio/core`:\n\n```typescript\nimport type { \n Tool, \n SchemaModifiersParams, \n ModifiersParams,\n ToolExecuteResponse \n} from '@composio/core';\n```\n\n### Error Handling\n\nImplement proper error handling for API calls and tool execution:\n\n```typescript\nasync getTools(modifiers?: SchemaModifiersParams): Promise {\n try {\n const response = await this.client.getTools();\n return response.data;\n } catch (error) {\n throw new ComposioProviderError(\n `Failed to fetch tools: ${error.message}`,\n { cause: error }\n );\n }\n}\n```\n\n### Modifier Support\n\n- **Non-agentic providers**: Implement schema modifiers to transform tool schemas\n- **Agentic providers**: Implement both schema and execution modifiers for full control\n\n### Testing\n\nWrite comprehensive tests covering:\n- Tool wrapping with and without modifiers\n- Error scenarios for API failures\n- Edge cases in modifier application\n- Framework-specific format compliance\n\n## Provider Options\n\nProvider behavior can be configured through `ProviderOptions`:\n\n```typescript\ntype ProviderOptions =\n TProvider extends BaseComposioProvider\n ? TProvider extends BaseAgenticProvider\n ? AgenticToolOptions\n : ToolOptions\n : never;\n```\n\n| Option Type | Use Case |\n|------------|----------|\n| `ToolOptions` | Non-agentic providers |\n| `AgenticToolOptions` | Agentic providers with execution control |\n\n资料来源：[ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n\n## Summary\n\nAI Framework Providers are essential integration layers that enable Composio tools to work seamlessly with various AI agent frameworks. They provide:\n\n- **Abstraction**: Unified interface for diverse AI frameworks\n- **Transformation**: Schema adaptation for framework-specific formats\n- **Extensibility**: Custom provider creation for unsupported frameworks\n- **Control**: Modifier system for runtime behavior customization\n\nThe provider architecture supports both simple schema wrapping (non-agentic) and full execution control (agentic), making it adaptable to a wide range of AI framework requirements.\n\n---\n\n\n\n## Toolkits Management\n\n### 相关页面\n\n相关主题：[Custom Tools and Toolkits](#custom-tools), [Core Concepts](#core-concepts), [AI Framework Providers](#providers-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/core/src/models/Toolkits.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/Toolkits.ts)\n- [ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n- [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/cli-local-tools/src/readiness.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/readiness.ts)\n- [ts/packages/cli/src/effects/toolkit-version-overrides.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts)\n- [ts/packages/cli/src/effects/validate-toolkit-versions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/validate-toolkit-versions.ts)\n- [ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts)\n
\n\n# Toolkits Management\n\n## Overview\n\nToolkits Management is the system responsible for organizing, discovering, and configuring collections of tools and triggers within Composio. Toolkits serve as the fundamental unit of organization for functionality, grouping related tools under a common namespace with shared metadata, versioning, and configuration options.\n\nThe management system encompasses both **remote toolkits** (hosted and managed by Composio) and **local toolkits** (user-defined or third-party tools executed locally via the CLI). This dual approach provides flexibility for different use cases while maintaining a consistent interface for tool execution and configuration.\n\n资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts:1-16]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Toolkits Management] --> B[Remote Toolkits]\n A --> C[Local Toolkits]\n \n B --> B1[Toolkit Index]\n B --> B2[Version Overrides]\n B --> B3[Validation]\n \n C --> C1[Registry]\n C --> C2[Readiness Check]\n C --> C3[Configuration]\n \n B1 --> D[createToolkitIndex]\n B2 --> E[buildVersionMapFromSpecs]\n B3 --> F[validateToolkitVersions]\n \n C1 --> G[getLocalCustomToolkits]\n C2 --> H[LocalToolkitReadiness]\n C3 --> I[localToolsCmd$Configure]\n```\n\n### Core Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| Toolkit Index | Groups tools/triggers by toolkit name | `ts/packages/cli/src/generation/create-toolkit-index.ts` |\n| Version Overrides | Manages toolkit version specifications | `ts/packages/cli/src/effects/toolkit-version-overrides.ts` |\n| Version Validation | Validates toolkit versions against API | `ts/packages/cli/src/effects/validate-toolkit-versions.ts` |\n| Local Registry | Manages local toolkit declarations | `ts/packages/cli-local-tools/src/registry.ts` |\n| Readiness Check | Determines toolkit availability status | `ts/packages/cli-local-tools/src/readiness.ts` |\n| Configuration | Handles toolkit/tool configuration | `ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts` |\n\n## Toolkit Discovery (CLI Commands)\n\nThe Composio CLI provides a comprehensive set of commands for toolkit discovery under the `toolkits` command group.\n\n资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts:14-23]()\n\n### Available Commands\n\n```bash\ncomposio toolkits \n```\n\n| Command | Description |\n|---------|-------------|\n| `list` | List available toolkits |\n| `info` | Display detailed information about a specific toolkit |\n| `search` | Search for toolkits by name or keywords |\n| `version` | Manage toolkit version information |\n\n### Command Examples\n\n```bash\n# List all available toolkits\ncomposio toolkits list\n\n# Get info about a specific toolkit\ncomposio toolkits info gmail\n\n# Search for toolkits\ncomposio toolkits search \"email\"\n\n# Check toolkit versions\ncomposio toolkits version\n```\n\n## Toolkit Index System\n\nThe toolkit index is a structured mapping that organizes tools and trigger types by their corresponding toolkit name.\n\n资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:1-30]()\n\n### Data Model\n\n```typescript\ninterface CreateToolkitIndexInput {\n readonly slug: string;\n readonly version?: string;\n readonly typeableTools:\n | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> }\n | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> };\n readonly triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>;\n}\n\ntype ToolkitIndex = Record;\n```\n\n### Index Creation Process\n\n```mermaid\ngraph LR\n A[Input Data] --> B[groupByToolkits]\n B --> C[Record.fromEntries]\n C --> D[stripPrefix]\n D --> E[ToolkitIndex]\n```\n\nThe `createToolkitIndex` function performs the following operations:\n\n1. Groups tools and trigger types by their toolkit prefix\n2. Converts the grouped data to a Record\n3. Strips the toolkit prefix from individual tool/trigger identifiers\n4. Applies version overrides when specified\n\n资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:23-45]()\n\n## Local Toolkit Registry\n\nThe local toolkit registry manages toolkits that are executed locally through the CLI rather than through the Composio API.\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:1-50]()\n\n### Registry Functions\n\n| Function | Purpose |\n|----------|---------|\n| `getAllLocalToolkitSlugs` | Returns all registered local toolkit slugs |\n| `isLocalToolkitSlug` | Checks if a slug corresponds to a local toolkit |\n| `isLocalToolSlug` | Checks if a tool slug is a local tool |\n| `getLocalToolkitDeclarations` | Gets declarations filtered by platform/toolkits |\n| `getLocalCustomToolkits` | Returns CustomToolkit objects for local toolkits |\n\n### Filtering Logic\n\n```typescript\nconst toolkitMatchesFilter = (\n toolkit: LocalToolkitDeclaration,\n requestedToolkits?: ReadonlyArray\n): boolean => {\n if (!requestedToolkits || requestedToolkits.length === 0) return true;\n const requested = new Set(requestedToolkits.map(slug => slug.toLowerCase()));\n return requested.has(toolkit.slug.toLowerCase());\n};\n```\n\nThe filtering is case-insensitive, supporting flexible user input while maintaining consistent internal representation.\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:15-23]()\n\n### Toolkit Declaration Structure\n\nLocal toolkit declarations follow this structure:\n\n```typescript\ninterface LocalToolkitDeclaration {\n slug: string;\n name: string;\n description: string;\n platforms: ReadonlyArray;\n tools: ReadonlyArray;\n source: string;\n setup?: ToolkitSetup;\n}\n```\n\n## Toolkit Readiness Assessment\n\nThe readiness system evaluates whether local toolkits and their tools are available for use based on platform support and configuration state.\n\n资料来源：[ts/packages/cli-local-tools/src/readiness.ts:1-50]()\n\n### Readiness States\n\n| Status | Description |\n|--------|-------------|\n| `ready` | Toolkit and all tools are available |\n| `disabled` | Toolkit is disabled via local_tools.json metadata |\n| `unsupported` | Toolkit platforms do not include current platform |\n\n### Readiness Report Structure\n\n```typescript\ninterface LocalToolkitReadiness {\n slug: string;\n name: string;\n description: string;\n platforms: ReadonlyArray;\n supported: boolean;\n status: 'ready' | 'disabled' | 'unsupported';\n source: string;\n setup?: ToolkitSetup;\n tools: LocalToolReadiness[];\n messages: string[];\n hints: SetupHint[];\n}\n```\n\n### Platform Support Check\n\nThe system detects the current platform and filters toolkits based on platform compatibility:\n\n```typescript\nconst currentPlatform = options.currentPlatform ?? detectCliPlatform();\nreturn declarationsFor(options.declarations)\n .filter(toolkit => supportsCliPlatform(toolkit.platforms, currentPlatform))\n .filter(toolkit => toolkit.tools.length > 0);\n```\n\n## Toolkit Version Management\n\nComposio supports version pinning for toolkits to ensure consistent behavior across environments.\n\n资料来源：[ts/packages/cli/src/effects/toolkit-version-overrides.ts:1-60]()\n\n### Version Specification\n\n```typescript\ninterface ToolkitVersionSpec {\n toolkitSlug: string;\n toolkitVersion: string; // e.g., '20250901_00' or 'latest'\n}\n```\n\n### Grouping by Version\n\n```typescript\nexport const groupByVersion = (\n specs: ReadonlyArray\n): Map[]> => {\n const grouped = new Map[]>();\n for (const spec of specs) {\n const existing = grouped.get(spec.toolkitVersion);\n if (existing) {\n existing.push(spec.toolkitSlug);\n } else {\n grouped.set(spec.toolkitVersion, [spec.toolkitSlug]);\n }\n }\n return grouped;\n};\n```\n\nThis produces a mapping like:\n```\n\"20250901_00\" => [\"gmail\"]\n\"latest\" => [\"slack\", \"github\"]\n```\n\n### Version Map Building\n\n```typescript\nexport const buildVersionMapFromSpecs = (\n specs: ReadonlyArray\n): ToolkitVersionOverrides => {\n const versionMap = new Map, string>();\n for (const spec of specs) {\n if (spec.toolkitVersion !== 'latest') {\n versionMap.set(spec.toolkitSlug, spec.toolkitVersion);\n }\n }\n return versionMap;\n};\n```\n\nNote: 'latest' versions are excluded from the version map since they represent the default behavior.\n\n## Toolkit Version Validation\n\nBefore applying version overrides, the system validates them against the Composio API.\n\n资料来源：[ts/packages/cli/src/effects/validate-toolkit-versions.ts:1-60]()\n\n### Validation Process\n\n```mermaid\ngraph TD\n A[Version Overrides] --> B{validateToolkitVersions}\n B --> C[Check toolkit existence]\n B --> D[Verify version availability]\n C -->|Invalid| E[InvalidToolkitsError]\n D -->|Invalid| F[InvalidToolkitVersionsError]\n C -->|Valid| G[Return validated overrides]\n D -->|Valid| G\n```\n\n### Error Handling\n\n| Error Type | Cause | User Message |\n|------------|-------|--------------|\n| `InvalidToolkitsError` | Toolkit slug doesn't exist | Invalid toolkit(s) specified |\n| `InvalidToolkitVersionsError` | Version doesn't exist for toolkit | Invalid version for specific toolkit |\n| `HttpServerError` | API communication failure | Network or server error |\n\n## Toolkit Configuration\n\nLocal toolkits can be configured through the CLI, allowing users to customize installation commands, enable/disable tools, and manage authentication.\n\n资料来源：[ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts:1-50]()\n\n### Configuration Options\n\n```bash\ncomposio local-tools configure --selector [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `--command` | Override installation command |\n| `--disable` | Disable the toolkit or tool |\n| `--enable` | Enable the toolkit or tool |\n| `--authenticated` | Mark as authenticated |\n| `--unauthenticated` | Mark as not authenticated |\n\n### Metadata Storage\n\nConfiguration is stored in `~/composio/local_tools.json` with the following structure:\n\n```typescript\ninterface LocalToolMetadata {\n disabled?: boolean;\n authenticated?: boolean;\n installation?: {\n command?: string;\n };\n}\n```\n\n### Display Configuration Info\n\nWhen configuring a toolkit or tool, the CLI displays:\n\n```\nName: \nKind: \nPath: \nCommand: \nDisabled: \nAuthenticated: \n```\n\n## Tool Permission System\n\nComposio implements a permission system for tool execution to ensure security and user control.\n\n资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-60]()\n\n### Permission Flow\n\n```mermaid\ngraph TD\n A[Tool Execution Request] --> B{Permission Check}\n B -->|First time| C[Browser Prompt]\n B -->|Previously allowed| D[Execute Tool]\n C --> E[Allow for session]\n C --> F[Allow once]\n C --> G[Deny]\n E --> D\n F --> H[Execute once]\n H --> D\n```\n\n### Permission Decision Types\n\n| Decision | Scope | Persistence |\n|----------|-------|-------------|\n| `ALLOW_SESSION` | All executions in current session | Session-scoped |\n| `ALLOW_ONCE` | Single execution | Single use |\n| `DENY` | Block execution | Single use |\n\n### Browser-based Permission Request\n\nWhen permission is required, a local HTTP server is started on port 127.0.0.1 (configurable) with an HTML interface presenting the three options.\n\n## Integration with TypeScript Generation\n\nThe toolkit system integrates with Composio's TypeScript type generation to provide type-safe tool access.\n\n资料来源：[ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts:1-30]()\n\n### Generation Options\n\n```bash\ncomposio generate ts [options]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--compact` | Emit single module file | false |\n| `--transpiled` | Include transpiled JS | true (if no --output-dir) |\n| `--output-dir` | Output directory | node_modules/@composio/core |\n| `--toolkits` | Filter by toolkit(s) | All toolkits |\n\n### Invariants\n\n- `--output-dir` cannot refer to a path inside `node_modules`\n- If `--output-dir` is not specified, `--transpiled` defaults to true\n- If `--output-dir` is specified, `--transpiled` defaults to false\n\n## Summary\n\nToolkits Management in Composio provides a comprehensive system for organizing and managing tools with the following key capabilities:\n\n1. **Discovery**: CLI commands for listing, searching, and inspecting available toolkits\n2. **Indexing**: Automatic organization of tools and triggers by toolkit prefix\n3. **Local Support**: Registry and execution system for locally-defined toolkits\n4. **Version Control**: Version pinning with validation against the Composio API\n5. **Configuration**: Flexible configuration of toolkit behavior including installation commands and enable/disable states\n6. **Permissions**: Security layer for tool execution with session and one-time permission grants\n7. **Type Safety**: Integration with TypeScript generation for type-safe tool usage\n\nThe architecture separates concerns between remote toolkits (API-managed) and local toolkits (CLI-managed), while providing a unified interface for tool execution and configuration.\n\n---\n\n\n\n## Custom Tools and Toolkits\n\n### 相关页面\n\n相关主题：[Toolkits Management](#toolkits-management), [Core Concepts](#core-concepts)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n- [ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n- [ts/packages/cli/src/services/command-hints.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n- [ts/packages/cli/src/effects/toolkit-version-overrides.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts)\n- [ts/packages/cli-local-tools/src/readiness.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/readiness.ts)\n- [ts/packages/cli/src/services/tool-permissions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/tool-permissions.ts)\n- [ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts)\n- [ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts)\n- [ts/packages/cli/src/effects/validate-toolkit-versions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/validate-toolkit-versions.ts)\n- [ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts)\n
\n\n# Custom Tools and Toolkits\n\n## Overview\n\nCustom Tools and Toolkits are the fundamental building blocks in Composio that enable agents to interact with external services and perform specific actions. A **Custom Tool** represents a single executable action with defined input parameters and output schemas, while a **Custom Toolkit** is a collection of related tools grouped under a common namespace.\n\nThe Composio framework provides both TypeScript (`@composio/core`) and Python (`composio-core`) SDKs for defining, creating, and managing custom tools and toolkits. This architecture allows developers to extend Composio's capabilities by creating specialized tools for their specific use cases.\n\n资料来源：[ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n\n## Architecture\n\n### High-Level Architecture\n\n```mermaid\ngraph TD\n A[Developer] --> B[Custom Tool Definition]\n B --> C[CustomTool Instance]\n C --> D[CustomToolkit Container]\n D --> E[Composio Client]\n E --> F[Tool Execution Engine]\n \n G[Agent] --> E\n E --> H[Tool Response]\n H --> G\n```\n\n### Component Hierarchy\n\n```mermaid\ngraph TD\n A[CustomToolkit] --> B[Tool 1]\n A --> C[Tool 2]\n A --> D[Tool N]\n \n B --> E[Name]\n B --> F[Description]\n B --> G[InputParams]\n B --> H[OutputParams]\n B --> I[Execute Function]\n \n E --> J[slug]\n J --> K[displayName]\n```\n\n## Custom Tool Structure\n\n### TypeScript Implementation\n\nCustom tools in TypeScript are created using the `createCustomTool` factory function, which accepts a tool slug and a configuration object.\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:65-79](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n\n```typescript\nconst toCustomTool = (\n toolkit: LocalToolkitDeclaration,\n tool: LocalToolDeclaration,\n currentPlatform: LocalCliPlatform\n) =>\n createCustomTool(tool.slug, {\n name: tool.name,\n description: descriptionWithPlatform(tool.description, tool.platforms),\n inputParams: tool.inputParams,\n ...(tool.outputParams ? { outputParams: tool.outputParams } : {}),\n execute: async input =>\n executeLocalTool(tool.execution, input as Record, {\n toolkit,\n tool,\n finalSlug: normalizeLocalToolSlug(tool.slug, toolkit.slug),\n platform: currentPlatform,\n }),\n });\n```\n\n### Tool Properties\n\n| Property | Type | Required | Description |\n|----------|------|----------|-------------|\n| `slug` | `string` | Yes | Unique identifier for the tool |\n| `name` | `string` | Yes | Human-readable display name |\n| `description` | `string` | Yes | Detailed explanation of tool functionality |\n| `inputParams` | `Parameter[]` | No | Array of input parameter definitions |\n| `outputParams` | `Parameter[]` | No | Array of output parameter definitions |\n| `execute` | `Function` | Yes | Async function that performs the tool action |\n| `triggers` | `Trigger[]` | No | Event triggers associated with the tool |\n\n### Input/Output Parameters\n\nParameters define the schema for tool inputs and outputs using a structured format:\n\n```typescript\ninterface Parameter {\n name: string; // Parameter identifier\n type: 'string' | 'number' | 'boolean' | 'object' | 'array';\n description: string; // Human-readable explanation\n required: boolean; // Whether the parameter is mandatory\n default?: any; // Optional default value\n enum?: string[]; // For restricted value sets\n}\n```\n\n## Custom Toolkit Structure\n\n### Creating a Toolkit\n\nToolkits group related tools under a common namespace and platform context.\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:81-88](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n\n```typescript\nconst toCustomToolkit = (\n toolkit: LocalToolkitDeclaration,\n currentPlatform: LocalCliPlatform\n): CustomToolkit =>\n createCustomToolkit(toolkit.slug, {\n name: toolkit.name,\n description: descriptionWithPlatform(toolkit.description, toolkit.platforms),\n tools: toolkit.tools.map(tool => toCustomTool(toolkit, tool, currentPlatform)),\n });\n```\n\n### Toolkit Properties\n\n| Property | Type | Required | Description |\n|----------|------|----------|-------------|\n| `slug` | `string` | Yes | Unique toolkit identifier |\n| `name` | `string` | Yes | Display name for the toolkit |\n| `description` | `string` | Yes | Toolkit documentation |\n| `tools` | `CustomTool[]` | Yes | Collection of tools in this toolkit |\n| `platforms` | `LocalCliPlatform[]` | Yes | Supported platforms (e.g., linux, darwin, windows) |\n\n## Toolkit Discovery and Filtering\n\n### Filtering by Platform\n\nComposio provides functions to filter toolkits and tools based on the current platform:\n\n资料来源：[ts/packages/cli-local-tools/src/registry.ts:55-63](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n\n```typescript\nconst toolkitMatchesFilter = (\n toolkit: LocalToolkitDeclaration,\n requestedToolkits?: ReadonlyArray\n): boolean => {\n if (!requestedToolkits || requestedToolkits.length === 0) return true;\n const requested = new Set(requestedToolkits.map(slug => slug.toLowerCase()));\n return requested.has(toolkit.slug.toLowerCase());\n};\n```\n\n### Getting Local Toolkit Declarations\n\n```typescript\nexport const getLocalToolkitDeclarations = (\n options: {\n readonly currentPlatform?: LocalCliPlatform;\n readonly toolkits?: ReadonlyArray;\n readonly declarations?: ReadonlyArray;\n } = {}\n): ReadonlyArray => {\n const currentPlatform = options.currentPlatform ?? detectCliPlatform();\n return declarationsFor(options.declarations)\n .filter(toolkit => toolkitMatchesFilter(toolkit, options.toolkits))\n .filter(toolkit => supportsCliPlatform(toolkit.platforms, currentPlatform))\n .map(toolkit => ({\n ...toolkit,\n tools: toolkit.tools.filter(tool => supportsCliPlatform(tool.platforms, currentPlatform)),\n }))\n .filter(toolkit => toolkit.tools.length > 0);\n};\n```\n\n### Toolkit Index Generation\n\nThe toolkit index creates a structured mapping of all tools organized by their parent toolkit.\n\n资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:22-45](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)\n\n```typescript\nexport function createToolkitIndex(input: CreateToolkitIndexInput): Simplify {\n const { versionMap } = input;\n\n return pipe(\n input,\n groupByToolkits,\n Record.fromEntries,\n Record.mapEntries((value, key) => {\n const stripPrefix = String.slice(key.length + 1);\n\n const { slug } = value.toolkit;\n\n // Look up version override for this toolkit (lowercase key lookup)\n const version = versionMap?.get(String.toLowerCase(slug));\n // ... further processing\n })\n );\n}\n```\n\n## CLI Commands for Toolkits\n\nComposio CLI provides comprehensive commands for toolkit management:\n\n资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n\n| Command | Description |\n|---------|-------------|\n| `composio toolkits list` | List all available toolkits |\n| `composio toolkits info ` | Display detailed toolkit information |\n| `composio toolkits search ` | Search toolkits by name or description |\n| `composio toolkits version` | Manage toolkit version overrides |\n\n### Command Examples\n\n```bash\n# List toolkits\ncomposio toolkits list\n\n# Get toolkit information\ncomposio toolkits info \"gmail\"\n\n# Search for toolkits\ncomposio toolkits search \"email\"\n```\n\n资料来源：[ts/packages/cli/src/services/command-hints.ts:15-30](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts)\n\n## Version Management\n\n### Toolkit Version Overrides\n\nComposio supports version pinning for toolkits, allowing specific versions to be used instead of the latest release.\n\n资料来源：[ts/packages/cli/src/effects/toolkit-version-overrides.ts:16-35](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts)\n\n```typescript\nexport const buildVersionMapFromSpecs = (\n specs: ReadonlyArray\n): ToolkitVersionOverrides => {\n const versionMap = new Map, string>();\n for (const spec of specs) {\n if (spec.toolkitVersion !== 'latest') {\n versionMap.set(spec.toolkitSlug, spec.toolkitVersion);\n }\n }\n return versionMap;\n};\n```\n\n### Version Grouping\n\nToolkits can be grouped by their version specification:\n\n```typescript\nexport const groupByVersion = (\n specs: ReadonlyArray\n): Map[]> => {\n const grouped = new Map[]>();\n // Groups toolkits by version string\n return grouped;\n};\n```\n\n### Version Validation\n\nBefore applying version overrides, Composio validates that all specified versions and toolkit slugs are valid:\n\n资料来源：[ts/packages/cli/src/effects/validate-toolkit-versions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/validate-toolkit-versions.ts)\n\n```typescript\nexport const validateToolkitVersionOverrides = ({\n versionOverrides,\n toolkitSlugsFilter,\n client,\n}): Effect.Effect =>\n Effect.gen(function* () {\n const ui = yield* TerminalUI;\n\n // Skip if no overrides\n if (versionOverrides.size === 0) {\n return { validatedOverrides: versionOverrides };\n }\n // ... validation logic\n });\n```\n\n## Local Tools Configuration\n\n### Configuration File\n\nLocal tools can be configured via `~/composio/local_tools.json`:\n\n资料来源：[ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts)\n\n```bash\n# Configure a toolkit\ncomposio local-tools configure --selector --command \"\"\n\n# Disable a tool\ncomposio local-tools configure --selector --disable\n\n# Enable authentication\ncomposio local-tools configure --selector --authenticated\n```\n\n### Configuration Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `disabled` | `boolean` | Whether the tool/kit is disabled |\n| `authenticated` | `boolean` | Whether authentication is required |\n| `installation.command` | `string` | Custom installation command |\n| `metadataPath` | `string` | Path to local metadata file |\n\n## Tool Readiness and Status\n\n### Readiness Checks\n\nComposio performs readiness checks on local tools to determine their operational status:\n\n资料来源：[ts/packages/cli-local-tools/src/readiness.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/readiness.ts)\n\n```typescript\nconst status = toolkitSupported\n ? toolkitDisabled\n ? 'disabled'\n : aggregateStatus(tools.map(tool => tool.status))\n : 'unsupported';\n```\n\n### Status Values\n\n| Status | Description |\n|--------|-------------|\n| `ready` | Tool is fully operational |\n| `disabled` | Tool is explicitly disabled in configuration |\n| `unsupported` | Tool not supported on current platform |\n| `needs_setup` | Tool requires additional configuration |\n\n## Permission System\n\n### Tool Permission Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant ComposioCLI\n participant HTTPServer\n participant User\n \n Agent->>ComposioCLI: Execute tool request\n ComposioCLI->>HTTPServer: Start permission server\n HTTPServer->>User: Show permission dialog\n User->>HTTPServer: Allow/Deny decision\n HTTPServer->>ComposioCLI: Return decision\n ComposioCLI->>Agent: Execute or reject\n```\n\n### Permission Decision Types\n\n| Decision | Scope | Persistence |\n|----------|-------|-------------|\n| `allow_session` | Current session | Temporary |\n| `allow_once` | Single execution | Single use |\n| `deny` | Rejected | Permanent for request |\n\n资料来源：[ts/packages/cli/src/services/tool-permissions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/tool-permissions.ts)\n\n## Logs and Monitoring\n\n### Log Commands\n\nComposio provides commands to monitor tool and trigger execution:\n\n资料来源：[ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts)\n\n```bash\n# View tool execution logs\ncomposio dev logs tools \n\n# View trigger execution logs\ncomposio dev logs triggers \n```\n\n## Provider Integration\n\n### Schema Modifiers\n\nCustom tools support schema modification through provider options, enabling dynamic schema transformation:\n\n资料来源：[ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts)\n\n```typescript\nexport type ProviderOptions =\n TProvider extends BaseComposioProvider\n ? TProvider extends BaseAgenticProvider\n ? AgenticToolOptions\n : ToolOptions\n : never;\n```\n\n### Modifier Functions\n\n| Function | Purpose |\n|----------|---------|\n| `modifySchema` | Transform input/output schemas |\n| `beforeExecute` | Pre-execution hook for parameter manipulation |\n| `afterExecute` | Post-execution hook for result processing |\n\n## Usage Example\n\n### TypeScript\n\n```typescript\nimport { createCustomTool, createCustomToolkit } from '@composio/core';\n\nconst myTool = createCustomTool('fetch_data', {\n name: 'Fetch Data',\n description: 'Retrieves data from the specified endpoint',\n inputParams: [\n {\n name: 'url',\n type: 'string',\n description: 'The URL to fetch data from',\n required: true,\n },\n ],\n execute: async (input) => {\n const response = await fetch(input.url);\n return await response.json();\n },\n});\n\nconst myToolkit = createCustomToolkit('data_fetchers', {\n name: 'Data Fetchers',\n description: 'Tools for fetching various data sources',\n tools: [myTool],\n});\n```\n\n### Python\n\n```python\nfrom composio.core.models.custom_tool import CustomTool\nfrom composio.core.models.custom_tool_types import Parameter\n\nmy_tool = CustomTool(\n name=\"fetch_data\",\n description=\"Retrieves data from the specified endpoint\",\n input_params=[\n Parameter(\n name=\"url\",\n type=\"string\",\n description=\"The URL to fetch data from\",\n required=True\n )\n ]\n)\n```\n\n## Summary\n\nCustom Tools and Toolkits in Composio provide a flexible, extensible system for defining and managing agent capabilities:\n\n1. **Custom Tools** are atomic units of work with defined inputs, outputs, and execution logic\n2. **Custom Toolkits** organize related tools under common namespaces and platform contexts\n3. **Version Management** enables pinning toolkits to specific versions\n4. **Permission System** controls tool execution with browser-based approval flows\n5. **CLI Integration** provides comprehensive commands for toolkit discovery and management\n6. **Provider Integration** supports schema modification and transformation through modifier functions\n\nThis architecture allows developers to extend Composio's functionality while maintaining consistency with the framework's patterns for tool definition, execution, and monitoring.\n\n---\n\n\n\n## Connected Accounts\n\n### 相关页面\n\n相关主题：[Core Concepts](#core-concepts)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/core/src/models/ConnectedAccounts.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/ConnectedAccounts.ts)\n- [ts/packages/core/src/types/connectedAccounts.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/connectedAccounts.types.ts)\n- [python/composio/core/models/connected_accounts.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/connected_accounts.py)\n- [ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts)\n- [ts/examples/connected-accounts/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/examples/connected-accounts/src/index.ts)\n- [python/examples/connected_accounts.py](https://github.com/ComposioHQ/composio/blob/main/python/examples/connected_accounts.py)\n- [docs/content/docs/auth-configuration/connected-accounts.mdx](https://github.com/ComposioHQ/composio/blob/main/docs/content/docs/auth-configuration/connected-accounts.mdx)\n
\n\n# Connected Accounts\n\n## Overview\n\nConnected Accounts in Composio represent the integration layer between external third-party services (such as Gmail, Slack, GitHub) and the Composio platform. They manage authentication credentials, authorization scopes, and access control for tools that require external service authentication.\n\nA **Connected Account** is essentially a stored authentication configuration that links a user's external service account to Composio's tool ecosystem. This abstraction allows Composio to handle OAuth flows, token refresh, and permission management across multiple integrations while providing a unified interface for tool execution.\n\nThe Connected Accounts system serves as the foundation for:\n\n- OAuth-based authentication with external services\n- Access control and permission management at the account level\n- Caching and optimization of authentication data\n- Cross-toolkit credential sharing\n- Consumer-level account routing\n\n## Architecture\n\n### Core Components\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CMD[connected-accounts.cmd.ts
CLI Commands]\n HINTS[command-hints.ts
Command Hints]\n end\n \n subgraph \"Effects Layer\"\n CTRS[create-tool-router-session.ts
Tool Router Session]\n PERMS[tool-permissions.ts
Permission Handler]\n end\n \n subgraph \"Core Models\"\n CA[ConnectedAccounts.ts
Python Model]\n CAC[connectedAccounts.types.ts
Type Definitions]\n end\n \n subgraph \"Services\"\n CACHE[consumer-short-term-cache.ts
Cache Service]\n LINK[Link Command
OAuth Flow]\n end\n \n CMD --> CTRS\n CTRS --> CACHE\n CTRS --> CAC\n PERMS --> CAC\n LINK --> CA\n CA --> CAC\n```\n\n### Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Cache as Cache Service\n participant API as Composio API\n participant External as External Service\n \n User->>CLI: composio connected-accounts link gmail\n \n CLI->>API: Initiate OAuth Flow\n API->>External: Redirect to OAuth Provider\n External-->>API: OAuth Callback + Auth Code\n API->>External: Exchange Code for Tokens\n External-->>API: Access Token + Refresh Token\n \n API->>API: Store Connected Account\n API-->>CLI: Connected Account Created\n \n Note over CLI,Cache: Subsequent Requests\n \n CLI->>Cache: Check Cache\n alt Cache Hit\n Cache-->>CLI: Return Cached Accounts\n else Cache Miss\n Cache->>API: Fetch Fresh Data\n API-->>Cache: Connected Account Data\n Cache-->>CLI: Return Data\n end\n \n CLI->>API: Execute Tool with Account\n API->>External: Use Account Credentials\n External-->>API: Service Response\n API-->>CLI: Tool Result\n```\n\n## CLI Commands\n\nThe Composio CLI provides a dedicated command group for managing connected accounts:\n\n### Command Structure\n\n| Command | Description | Entry Point |\n|---------|-------------|-------------|\n| `link` | Connect a new external account | `connected-accounts.link.cmd.ts` |\n| `list` | List all connected accounts | `connected-accounts.list.cmd.ts` |\n| `info` | Get details of a specific account | `connected-accounts.info.cmd.ts` |\n| `whoami` | Show currently authenticated identity | `connected-accounts.whoami.cmd.ts` |\n\n资料来源：[ts/packages/cli/src/commands/connected-accounts/connected-accounts.cmd.ts:14-18]()\n\n### Link Command\n\nThe `link` command initiates the OAuth flow to connect an external service:\n\n```bash\ncomposio link \n```\n\nThis command:\n1. Retrieves the OAuth configuration for the specified toolkit\n2. Opens a browser window for user authentication\n3. Handles the OAuth callback\n4. Stores the resulting connected account\n\n### List Command\n\nDisplay all connected accounts with their status:\n\n```bash\ncomposio connected-accounts list\n```\n\nThe output includes:\n- Account ID\n- Associated toolkit\n- Authentication status\n- Last used timestamp\n\n## Access Control (ACL)\n\nConnected Accounts support fine-grained access control through ACL (Access Control List) configurations.\n\n### ACL Parameters\n\n```typescript\nexport const UpdateConnectedAccountAclParamsSchema = ConnectedAccountAclConfigSchema.refine(\n acl =>\n acl.allowAllUsers !== undefined ||\n acl.allowedUserIds !== undefined ||\n acl.notAllowedUserIds !== undefined,\n {\n message: 'At least one of allowAllUsers, allowedUserIds, or notAllowedUserIds must be provided',\n }\n);\n```\n\n资料来源：[ts/packages/core/src/types/connectedAccounts.types.ts:1-10]()\n\n### ACL Configuration Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `allowAllUsers` | `boolean` | Grant access to all users in the organization |\n| `allowedUserIds` | `string[]` | Explicit list of user IDs granted access |\n| `notAllowedUserIds` | `string[]` | Explicit list of user IDs denied access |\n\n**Validation Rule:** At least one of these fields must be provided when updating ACL.\n\n## Tool Router Integration\n\nConnected Accounts are integrated into the Tool Router system, which manages tool execution and authentication routing.\n\n### Session Creation Flow\n\n```mermaid\ngraph TD\n Start([Create Tool Router Session]) --> CheckCache{Cache Scope
Provided?}\n \n CheckCache -->|Yes| FetchAuth[Fetch Auth Configs
from Cache]\n CheckCache -->|No| SkipCache[Skip Cache]\n \n FetchAuth --> CacheExists{Cached Data
Available?}\n CacheExists -->|Yes| UseCache[Use Cached Auth Configs]\n CacheExists -->|No| FetchLive[Fetch Live from API]\n \n SkipCache --> BuildContext[Build Connection Context]\n UseCache --> BuildContext\n FetchLive --> BuildContext\n \n BuildContext --> MergeAccounts[Merge Connected Accounts]\n MergeAccounts --> FilterAccounts[Filter Available Accounts]\n FilterAccounts --> ReturnContext[Return Connection Context]\n \n ReturnContext --> End([Session Ready])\n```\n\n### Connection Context Structure\n\nThe connection context aggregates authentication data for tool execution:\n\n```typescript\ninterface ConnectionContext {\n connectedToolkits: string[];\n authConfigs: Record;\n connectedAccounts: ConnectedAccount[];\n availableConnectedAccounts: AvailableConnectedAccount[];\n}\n```\n\n资料来源：[ts/packages/cli/src/effects/create-tool-router-session.ts:1-30]()\n\n### Connected Account Mapping\n\nConnected accounts are mapped to word IDs for efficient lookup:\n\n```typescript\nconst wordIds = Object.fromEntries(\n Object.entries(selected).flatMap(([toolkit, connectedAccountId]) => {\n const account = available[toolkit.toLowerCase()]?.find(\n item => item.id === connectedAccountId\n );\n return account?.wordId ? [[toolkit, account.wordId]] : [];\n })\n);\n```\n\n资料来源：[ts/packages/cli/src/effects/create-tool-router-session.ts:8-15]()\n\n## Caching System\n\nThe Connected Accounts system includes a sophisticated caching layer to optimize API calls and improve performance.\n\n### Cache Key Normalization\n\n| Normalization | Description |\n|--------------|-------------|\n| Toolkit slugs | Converted to lowercase |\n| Auth config IDs | Validated as non-empty strings |\n| Connected account IDs | Validated as non-empty strings |\n\n资料来源：[ts/packages/cli/src/services/consumer-short-term-cache.ts:1-30]()\n\n### Cache Merge Strategy\n\nWhen multiple sources provide connected account mappings, they are merged with the following precedence:\n\n1. **Later declarations override earlier ones**\n2. **Auth configs are merged object-wise**\n3. **Empty configurations are filtered out**\n\n```typescript\nconst mergeAuthConfigMappings = (params) => {\n const current = normalizeAuthConfigMappings(params.current);\n const next = normalizeAuthConfigMappings(params.next);\n if (!current) return next;\n if (!next) return current;\n\n return normalizeAuthConfigMappings({\n authConfigs: {\n ...(current.authConfigs ?? {}),\n ...(next.authConfigs ?? {}),\n },\n });\n};\n```\n\n资料来源：[ts/packages/cli/src/services/consumer-short-term-cache.ts:50-70]()\n\n## Tool Permission System\n\nWhen executing tools that require connected account authentication, Composio provides a permission confirmation flow.\n\n### Permission Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant CLI\n participant Browser\n participant Server\n \n Agent->>CLI: Execute Tool with Account\n CLI->>Server: Start Permission Server\n \n CLI->>Browser: Open Permission Dialog\n Note over Browser: \"Allow gmail?\"\n \n Browser->>Server: User Decision\n \n alt Allow for Session\n Server-->>CLI: Allow with Token\n CLI->>Agent: Execute Tool\n else Allow Once\n Server-->>CLI: Allow Once Token\n CLI->>Agent: Execute Tool\n else Deny\n Server-->>CLI: Deny\n CLI-->>Agent: Permission Denied\n end\n```\n\n### Permission Dialog\n\nThe permission dialog is rendered as an HTML page served on localhost:\n\n```html\n

Allow ${toolSlug}?

\n

Composio CLI is requesting permission to execute this tool${accountLabel ? ` for ${accountLabel}` : ''}.

\n```\n\n提供三个选项：\n- **Allow for this session** - 持续授权直到会话结束\n- **Allow once** - 仅本次执行授权\n- **Deny** - 拒绝执行\n\n资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-50]()\n\n## Python SDK Integration\n\n### Model Definition\n\n```python\nclass ConnectedAccount(BaseModel):\n id: str\n name: str\n integration_id: str\n connected_account_type: str\n connection_metadata: dict\n enabled: bool\n active: bool\n auth_scheme: str\n auth_expiry: Optional[datetime] = None\n redirect_uri: Optional[str] = None\n entity_id: Optional[str] = None\n user_id: Optional[str] = None\n scopes: list[str] = []\n account_id: Optional[str] = None\n```\n\n资料来源：[python/composio/core/models/connected_accounts.py:1-20]()\n\n### Usage Example\n\n```python\nfrom composio import Composio\nfrom composio.client.components import ConnectedAcocunts\n\ncomposio_client = Composio()\n\n# List all connected accounts\naccounts = composio_client.connected_accounts.list()\n\n# Get info for a specific account\naccount = composio_client.connected_accounts.get(account_id=\"acc_xxx\")\n\n# Link a new account\nnew_account = composio_client.connected_accounts.link(\n integration_id=\"int_xxx\",\n entity_id=\"entity_xxx\"\n)\n```\n\n## Common Use Cases\n\n### 1. Multi-Account Management\n\nUsers can connect multiple accounts from the same service provider:\n\n```bash\n# Connect personal Gmail\ncomposio link gmail --account personal\n\n# Connect work Gmail\ncomposio link gmail --account work\n```\n\n### 2. Cross-Toolkit Sharing\n\nOne connected account can provide authentication for multiple toolkits if they share the same OAuth provider.\n\n### 3. Organization-Level Accounts\n\nEnterprise users can share connected accounts across team members using ACL configurations:\n\n```python\n# Share account with entire organization\ncomposio_client.connected_accounts.update_acl(\n account_id=\"acc_xxx\",\n allow_all_users=True\n)\n\n# Share with specific users only\ncomposio_client.connected_accounts.update_acl(\n account_id=\"acc_xxx\",\n allowed_user_ids=[\"user_1\", \"user_2\"]\n)\n```\n\n## Related Commands Reference\n\n| Command | Description |\n|---------|-------------|\n| `composio connected-accounts link ` | Connect a new account |\n| `composio connected-accounts list` | List all connected accounts |\n| `composio connected-accounts info ` | Show account details |\n| `composio connected-accounts whoami` | Show current identity |\n| `composio dev playground-execute ` | Test tool with connected account |\n| `composio link ` | Quick link command (alias) |\n\n资料来源：[ts/packages/cli/src/services/command-hints.ts:1-50]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| Account not found | Toolkit not connected | Run `composio link ` |\n| Permission denied | ACL restricts access | Check with account owner to update ACL |\n| Token expired | OAuth token needs refresh | Re-link the account |\n| Cache stale | Old cached data | Use `--no-cache` flag or update cache settings |\n\n### Debug Mode\n\nEnable verbose logging to debug connected account issues:\n\n```bash\nCOMPOSIO_LOG_LEVEL=debug composio connected-accounts list\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：ComposioHQ/composio\n\n摘要：发现 12 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops。\n\n## 1. 安装坑 · 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_54d53b3e2a6e4cf4a3e4783f824ed87b | https://github.com/ComposioHQ/composio/issues/3269 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shar…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shares:{})\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1b88beb594aa433eb998eac3b16a20e0 | https://github.com/ComposioHQ/composio/issues/3422 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：[Feature] Custom auth configs shouldn't require a dev project to use\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] Custom auth configs shouldn't require a dev project to use\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1d62ba62e77b47ff88b50d2db41a8cf7 | https://github.com/ComposioHQ/composio/issues/3271 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 4. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `composio` 与安装入口 `@composio/core` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @composio/core`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:762304524 | https://github.com/ComposioHQ/composio | repo=composio; install=@composio/core\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:762304524 | https://github.com/ComposioHQ/composio | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:762304524 | https://github.com/ComposioHQ/composio | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：@composio/core@0.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：@composio/core@0.10.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66f9d5fd557f41c7845ca5dd7d93ae6f | https://github.com/ComposioHQ/composio/releases/tag/%40composio/core%400.10.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | issue_or_pr_quality=unknown\n\n## 12. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：ComposioHQ/composio\n\n摘要：发现 12 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops。\n\n## 1. 安装坑 · 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_54d53b3e2a6e4cf4a3e4783f824ed87b | https://github.com/ComposioHQ/composio/issues/3269 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shar…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shares:{})\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1b88beb594aa433eb998eac3b16a20e0 | https://github.com/ComposioHQ/composio/issues/3422 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：[Feature] Custom auth configs shouldn't require a dev project to use\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] Custom auth configs shouldn't require a dev project to use\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1d62ba62e77b47ff88b50d2db41a8cf7 | https://github.com/ComposioHQ/composio/issues/3271 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 4. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `composio` 与安装入口 `@composio/core` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @composio/core`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:762304524 | https://github.com/ComposioHQ/composio | repo=composio; install=@composio/core\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:762304524 | https://github.com/ComposioHQ/composio | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:762304524 | https://github.com/ComposioHQ/composio | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：@composio/core@0.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：@composio/core@0.10.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66f9d5fd557f41c7845ca5dd7d93ae6f | https://github.com/ComposioHQ/composio/releases/tag/%40composio/core%400.10.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | issue_or_pr_quality=unknown\n\n## 12. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# composio - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 composio 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Introduction to Composio。围绕“Introduction to Composio”模拟一次用户任务，不展示安装或运行结果。\n2. getting-started：Getting Started。围绕“Getting Started”模拟一次用户任务，不展示安装或运行结果。\n3. architecture-overview：System Architecture。围绕“System Architecture”模拟一次用户任务，不展示安装或运行结果。\n4. core-concepts：Core Concepts。围绕“Core Concepts”模拟一次用户任务，不展示安装或运行结果。\n5. typescript-sdk：TypeScript SDK。围绕“TypeScript SDK”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Introduction to Composio”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. getting-started\n输入：用户提供的“Getting Started”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture-overview\n输入：用户提供的“System Architecture”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. core-concepts\n输入：用户提供的“Core Concepts”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. typescript-sdk\n输入：用户提供的“TypeScript SDK”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Introduction to Composio”形成一个小中间产物，并等待用户确认。\n- Step 2 / getting-started：Step 2 必须围绕“Getting Started”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture-overview：Step 3 必须围绕“System Architecture”形成一个小中间产物，并等待用户确认。\n- Step 4 / core-concepts：Step 4 必须围绕“Core Concepts”形成一个小中间产物，并等待用户确认。\n- Step 5 / typescript-sdk：Step 5 必须围绕“TypeScript SDK”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/ComposioHQ/composio\n- https://github.com/ComposioHQ/composio#readme\n- .agents/skills/bug-fixing-guide/SKILL.md\n- .agents/skills/building-agents/SKILL.md\n- .agents/skills/building-agents-using-anthropic/SKILL.md\n- .agents/skills/building-agents-using-autogen/SKILL.md\n- .agents/skills/building-agents-using-cloudflare/SKILL.md\n- .agents/skills/building-agents-using-crewai/SKILL.md\n- .agents/skills/building-agents-using-google/SKILL.md\n- .agents/skills/building-agents-using-langchain/SKILL.md\n- .agents/skills/building-agents-using-langgraph/SKILL.md\n- .agents/skills/building-agents-using-llamaindex/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 composio 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：ComposioHQ/composio\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install @composio/core\n```\n\n来源：https://github.com/ComposioHQ/composio#readme\n\n## 来源\n\n- repo: https://github.com/ComposioHQ/composio\n- docs: https://github.com/ComposioHQ/composio#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_2338278d08fa4b36b2924d1ece43ba6f" }