从用户访谈到 45 个实战样例：Composio Examples 样例库的规划设计与落地逻辑

从用户访谈到 45 个实战样例：Composio Examples 样例库的规划设计与落地逻辑

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio

本文基于 Composio 文档仓库中的决策记录 examples.md 展开，完整呈现 Composio 文档站 Examples（示例库）页面的重构规划：它的用户调研数据来源、8 大类约 45 个样例的目录结构、四条核心设计原则，以及该规划在当前仓库中的实际落地形态（示例页面路由、gallery 元数据机制与可运行示例的分级校验体系），帮助读者理解一个 Agent 平台如何系统性规划并维护其示例内容生态。

规划背景：从 50 个真实用例出发

该决策记录的核心依据是用户访谈分析：团队从 Slack 的#user-interviews频道中提取了50 个真实用例（原始材料为 157 条消息，其中 77 条具有实质内容），并据此设计了示例页面的完整结构。

这正是该规划最重要的方法论：示例库的内容目录不是拍脑袋的分类，而是从真实用户意图中归纳出来的。每个样例都对应一个明确的用户目标（如"自动分诊 GitHub issue 并指派负责人"），而不是按技术概念堆砌。

该文档在 docs/decisions/ 目录中的定位是"cookbook/examples restructuring plan"（示例库重构规划），与同目录的 cookbooks-revamp-plan.md（历史任务追踪器）共同构成示例内容体系的设计依据。

总体结构：8 大类、约 45 个样例

规划将示例页划分为以下 8 个板块，总计约 45 个样例。以下完整继承原文档的目录表格：

Getting started（入门）

Example	What it demonstrates
Hello, world	First tool execution, basic setup
Connect your first app in 60 seconds	OAuth flow, connected accounts

Guides（指南）

Example	What it demonstrates
Building a Chat Agent	Core agentic loop, conversation context
Building a RAG Agent	Tool router + knowledge retrieval
Building a Slackbot Agent	Real-time messaging, event handling
Building a Natural Language Data Analysis Agent	Complex queries, structured output
Get started with Claude Code	MCP setup, Claude integration
Get started with OpenAI Agents SDK	Native tools with OpenAI
Get started with Vercel AI SDK	Streaming, Next.js integration
Get started with LangChain	LangChain tools wrapper
Get started with Mastra	Mastra framework integration
Get started with CrewAI	Multi-agent with CrewAI

Agents（智能体）

Example	What it demonstrates
Build a PR review agent with GitHub and Claude	Multi-tool (GitHub + AI), code context
Deploy an email assistant that drafts responses	Email integration, response generation
Create a Slack bot with access to 1000+ tools	Tool router, many toolkits
Run a research agent that searches, scrapes, and summarizes	Web tools, chaining outputs
Build an AI SDR that enriches leads automatically	CRM + web research, data enrichment
Build an agentic RAG agent over your docs	RAG + tool calling combined
Build a data analysis agent with natural language queries	Database tools, natural language to SQL
Build a voice agent with real-time tool calling	Voice + tools, real-time streaming
Spawn sub-agents for parallel task execution	Sub-agents, parallel processing
Orchestrate multiple agents on a complex workflow	Multi-agent coordination, handoffs
SEO data retrieval agent	Specialized data APIs, reporting

Code & DevOps（代码与 DevOps）

Example	What it demonstrates
Auto-triage GitHub issues and assign owners	GitHub API, classification, automation
Sync Linear tickets to Slack on status change	Cross-tool sync, webhooks
Post CI failure summaries to Discord	CI integration, notifications
Create Jira tickets from Slack messages	Slack → Jira, message parsing

Communication & Social（沟通与社交）

Example	What it demonstrates
Send personalized emails at scale with Gmail	Bulk operations, personalization
Build a Discord bot that manages your server	Discord API, bot commands
Auto-respond to Slack DMs with context	Slack events, contextual responses
LinkedIn content strategy agent	LinkedIn API, content generation

Sales & CRM（销售与客户管理）

Example	What it demonstrates
HubSpot CRM automation: new lead → research → enrich	CRM integration, data enrichment pipeline

Productivity & Data（效率与数据）

Example	What it demonstrates
Sync databases to Google Sheets automatically	Database + Sheets, data sync
Build a meeting notes → Notion pipeline	Transcription + Notion, structured data
Create calendar events from natural language	NLP input, calendar APIs
Download attachments and process them	File download, file processing
Turn documents into structured output	Document parsing, structured extraction
Shopify sales reporting to Slack	E-commerce data, scheduled reports

Triggers & Background jobs（触发器与后台任务）

Example	What it demonstrates
Build a Shopify customer support agent	E-commerce + support, always-on agent
Run an agent when new emails arrive	Email triggers, event-driven
Auto-review PRs on push	GitHub webhooks, automated review
Daily digest: Summarize GitHub activity to Slack	Scheduled jobs, aggregation
Weekly business report automation	Cron-style scheduling, multi-source data
Webhook → process → route to the right tool	Generic webhooks, routing logic

从分类分布可以看出规划的意图：Agents 与 Productivity & Data 是重心（各 11 个和 6 个样例），Sales & CRM 目前仅 1 个样例，属于明确标注的待扩展区（见下文"未来规划"）。

设计原则：四条关键决策

原文档的 Design Notes 给出了四条设计决策，它们解释了为什么目录长成上面这个样子：

1. 领域分类 + 行动导向命名：风格参考 Modal 的 examples 站点——按业务领域分类（而非按 API 或框架分类），样例标题直接描述用户要做的事（如 "Auto-triage GitHub issues and assign owners"），让读者按目标而非按技术栈检索。
2. "Get started with..." 板块：参考 Vercel AI SDK cookbook 的组织方式，把框架快速上手（Claude Code、OpenAI Agents SDK、Vercel AI SDK、LangChain、Mastra、CrewAI）独立成一个板块，覆盖各生态用户的入口习惯。
3. 框架作为标签页（tabs）而非一级分类：AI SDK、LangChain 等框架不作为顶层分类出现，而是作为同一个示例内部的 tab 展示。这避免了"按框架切分后同一用例内容重复三份"的维护问题。
4. 高级特性嵌入真实用例：文件上传/下载、子代理（sub-agents）等高级功能不单独成节，而是内嵌在真实场景示例中自然带出（例如"Download attachments and process them"就是文件处理特性的载体）。

从规划到落地：当前仓库中 Examples 页的实现

规划文档是"意图"，当前仓库则展示了"现状"。二者对照，可以看到规划已被部分实现，且实现方式对规划做了有意识的收敛。

已上线的四个端到端示例

当前文档内容目录 docs/content/examples/ 下的meta.json（meta.json）登记了 4 个示例页面：

• general-agent-with-pi：Pi + Composio 通用智能体，接入 Slack（触发器、按用户会话、共享连接、重定向授权链接与代理）
• standup-slackbot：每日站会机器人，用白标自有 Slack 应用 + tool-router 会话 + 手动工具执行 + 代理，为每位成员从其已连接工具生成站会草稿
• local-sandbox-pr-reviewer：在自有沙箱中运行 PR 审查器，同时通过 Composio 会话调用 GitHub 工具
• imessage-agent：用自定义 toolkit 将本地 iMessage 包装为进程内工具，并通过 eve provider 与整个 Composio 工具目录放在同一会话中

示例首页（index.mdx）的定位是："End-to-end builds that wire Composio into working agents. Each one is a complete project you can read top to bottom and run."——即每个示例都是一个可从头读到尾、可直接运行的完整项目，这与规划中"行动导向、领域驱动"的原则一致。

Gallery 元数据机制：规划中"Featured + 分类"的实现

页面路由docs/app/(home)/examples/[[...slug]]/page.tsx负责渲染：无 slug 时展示自定义 Featured Gallery，有 slug 时走标准文档页渲染器。gallery 数据不集中配置，而是从每个示例 MDX 的 frontmattergallery块中读取（title/description 用页面自身的，categories、logos、featured、order由gallery块提供）。例如 standup-slackbot.mdx 的 frontmatter：

gallery: categories: [Background agents] logos: [slack, github, linear] featured: true order: 1

对应的 examples-gallery.tsx 组件实现了分类筛选与卡片网格。值得注意的是实现层将规划的 8 类收敛为 3 条赛道：General agents、Background agents、Coding agents，外加一个Featured视图（按featured: true过滤，order控制排序，默认 99）。这与规划文档中"Future Plans → Featured Section"（顶部放 5 个 "wow" 示例的 hero 网格）直接呼应——Featured 机制已经落地，而 8 类业务分类在落地阶段被让位给了更贴近产品形态的"agent 类型"三分法。空分类还会显示 "More examples in this category are on the way." 的占位提示，与规划中"随内容增长渐进更新"的节奏一致。

示例的可持续维护：examples-manifest.json 分级校验体系

示例内容生态最容易被忽视的成本是"示例腐化"——文档更新后示例代码跑不通。当前仓库用一套机器可执行的清单来解决这个问题，这是对规划文档"长期维护"诉求的源码级回答。

仓库根目录的 examples-manifest.json 是"runnable example entrypoints 清单"，由 harness/run.mjs 消费。文件头部的$comment定义了四级（tier）执行策略：

• tier 1：无人值守可直接跑（unattended），只需环境变量（如OPENAI_API_KEY）
• tier 2：需要预置状态（provisioned state），由scripts/examples-provision.mjs提前准备好账号、auth config 等，示例通过ids字段引用（如COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID）
• tier 3：有界执行——输出匹配readiness正则即判定就绪后终止。清单特别强调：readiness 正则必须锚定示例成功时打印的带标签输出行（例如Visit this URL to authorize: https?://），绝不能只用裸https?://，防止错误信息里的 URL 被误判为就绪
• tier X：明确排除，并给出reason。例如ts/file-handling因"设计上会真实发送邮件"（outbound-email）被排除；ts/tool-router/webhook-server因依赖外部隧道（external-tunnel）被排除；llmMock: false标记那些 LLM 流量无法走 mock 服务器、只能真实金丝雀验证的条目

每个条目还声明了toolkits（示例会触碰的工具包，如hackernews、gmail、github）、timeoutSec和env。从清单覆盖的包来看（ts/examples/下 anthropic、langchain、llamaindex、mastra、openai、tool-router、triggers、vercel 等，Python 侧为 python/examples/），它实际上把规划中"Guides 板块"的框架入门样例（OpenAI / LangChain / Mastra / Vercel 等）落实成了可回归测试的一批真实入口点。换言之：文档站里的"示例"与仓库里被 CI 守护的"可运行示例"是同一套内容资产。

未来规划：Featured、Templates 与 MCP 入口

原文档 Future Plans 部分列出了五个方向，其中部分已在仓库中找到对应物：

1. Featured Section：顶部 hero 网格展示 5 个"wow"示例，类似 Modal 的 featured examples。对应实现即上文featured/order字段与Featured筛选视图。
2. Templates：提供可克隆的预置起步模板，点名了 "AI Email Assistant Template"、"GitHub Bot Template"、"Slack Bot Template"。
3. 更多 Sales & CRM 示例：Salesforce 自动化、deal tracking agent、pipeline management agent——补上当前仅 1 个样例的短板。
4. MCP 专属板块：Connect Composio MCP to Claude Desktop、Use Composio MCP with Cursor 等。文档特别注明"这是用户的一个大入口"（a big entry point for users），与 standup-slackbot.mdx 等示例中大量出现的 MCP / tool-router / 会话引用互为印证。
5. 文件处理示例：处理并总结上传的 PDF、下载并分析附件——文档注明这是访谈中被用户高频提及的需求。

此外，规划要求整体再增加约 20 个示例以达到目标质量水位，且命名要更具体、更行动导向，覆盖边缘场景与高级模式。

小结

docs/decisions/examples.md 这份决策记录的价值在于它完整保留了 Composio 示例内容生态的"从需求到结构"的推导链：用户访谈（50 用例）→ 8 类约 45 样例的目录 → 四条设计原则（领域分类、行动导向、框架做 tab、高级特性嵌入式教学）→ 未来扩展路线。而当前仓库展示了这条链路的落地切片：docs/content/examples/下的 4 个端到端示例、frontmatter-driven 的 gallery 机制、以及examples-manifest.json+ harness 的分级可运行性守护。对于正在为自己的 Agent 平台规划文档示例体系的团队，这套"访谈驱动的目录设计 + 元数据驱动的页面渲染 + 清单驱动的可运行性回归"的组合是一个可直接参考的工程范式。

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio