1. 项目概述当Supabase遇上AI Agent一个技能库的诞生最近在捣鼓AI Agent应用开发发现一个挺有意思的现象大家都能用LangChain、LlamaIndex这些框架快速搭出个Agent的架子但真想让这个Agent去干点具体、有用的活儿比如去查查数据库、发个邮件、调个第三方API立马就卡壳了。问题往往不在于大模型本身不够聪明而在于我们缺少一套标准化的、可复用的“技能”让Agent去调用。这就好比给一个天才配了一堆散装的、接口各异的工具他空有想法却无从下手。就在这个当口我注意到了Supabase官方开源的supabase/agent-skills项目。这名字起得直白就是“Agent技能库”。Supabase大家不陌生作为开源Firebase的替代品它在后端开发领域尤其是围绕PostgreSQL构建实时、可扩展应用方面已经积累了相当高的声誉。现在他们把手伸向了AI Agent领域意图很明显为基于Supabase构建的应用提供一套开箱即用、安全可控的AI Agent原生技能。这个项目解决的核心痛点正是我刚才提到的“最后一公里”问题。它不是一个独立的Agent框架而是一个技能插件集可以无缝集成到你现有的Agent工作流中比如用LangChain或自定义的Agent循环。其价值在于它将Supabase的核心能力——数据库操作、边缘函数调用、用户认证管理等——封装成了AI Agent可以理解和安全执行的标准化技能。开发者不再需要从零开始为Agent编写复杂的数据库查询逻辑或权限校验代码直接引入这些技能配置好上下文你的Agent就立刻获得了与Supabase后端深度交互的能力。简单来说agent-skills项目试图回答这样一个问题在一个以Supabase作为数据层和后端服务的应用里如何最高效、最安全地让AI Agent成为用户的智能助手去查询数据、触发操作、甚至基于业务逻辑做出简单决策接下来我就结合自己的研究和实验带你深入拆解这个项目的设计思路、核心技能以及如何将它应用到你的实际项目中。2. 核心设计理念与架构拆解2.1 为什么是“技能”而非“框架”在深入代码之前理解其设计哲学至关重要。agent-skills定位为“技能库”而非又一个“Agent框架”这体现了Supabase团队务实且生态友好的思路。当前AI Agent生态已经有不少成熟的框架如LangChain Agents、AutoGen、CrewAI等它们解决了Agent的调度、规划、记忆等通用问题。agent-skills并不想重复造轮子去和这些框架竞争。相反它选择做这些框架的“能力增强包”。它的目标很聚焦只解决与Supabase交互这一特定领域的问题。这种设计带来了几个明显优势低侵入性你不需要改变现有的Agent主体架构。无论是用LangChain的AgentExecutor还是自己写的简单循环都可以将agent-skills中的技能作为工具Tool或函数Function直接接入。专注性代码和功能高度集中在数据存取、服务调用和安全策略上避免了通用框架的复杂度代码更清晰也更容易维护和审计。标准化它为“如何让AI安全操作数据库”这类问题提供了一套Supabase官方的、经过实践检验的解决方案。这减少了不同团队、不同项目各自实现带来的安全风险和设计不一致性。2.2 技能的核心构成安全与上下文每个技能都不是一个简单的函数封装而是一个包含了执行逻辑、安全约束和自我描述的完整单元。这是agent-skills项目设计精妙的地方。1. 执行逻辑The How这是技能的本体即那段真正去执行查询、调用函数或管理文件的代码。例如一个“查询用户表”的技能其核心就是构建并执行一条SQL语句通过Supabase客户端库。但这里的执行逻辑是经过精心设计的它通常不接收原始的用户输入作为SQL而是接收结构化或半结构化的参数。2. 安全约束The Guard这是技能的“刹车系统”和“护栏”是项目最核心的价值之一。AI Agent的不可预测性使得直接赋予其数据库写权限是极其危险的。agent-skills在技能层面内置了多种安全机制RLS行级安全策略集成这是Supabase PostgreSQL的杀手级特性。agent-skills的技能在执行时会确保在有效的、权限受限的Supabase客户端上下文中运行。这意味着即使Agent试图执行DELETE FROM users只要RLS策略正确配置它也只能删除当前认证用户有权限删除的行。这实现了数据访问权限的天然继承。参数化查询与输入净化技能内部会强制使用参数化查询或ORM方法从根本上杜绝SQL注入攻击。对于文件操作等也会对路径进行校验和规范化。操作范围限制某些技能可能被设计为“只读”或者对可操作的表、函数白名单进行限制。这些约束在技能定义时就可以设定。3. 自我描述The What When为了让大模型LLM知道何时以及如何使用这个技能每个技能都必须提供清晰的元数据描述。这通常包括名称Name一个唯一标识符如query_database。描述Description用自然语言清晰说明这个技能是做什么的例如“根据提供的查询条件从指定的数据库表中检索数据。用户必须描述他们想查找什么。”参数模式Parameters Schema一个符合JSON Schema定义的结构详细说明技能需要哪些输入参数它们的类型、是否必填、以及含义。例如table_name字符串必填、filters对象选填。这个模式会被传递给LLMLLM根据此模式来理解如何“调用”这个技能。这种“逻辑安全描述”的三位一体设计使得技能既强大又安全同时还能被AI智能地理解和调用。2.3 项目架构一览虽然项目代码结构会不断演进但其核心目录通常围绕技能类型组织/skills /database # 数据库相关技能如查询、插入需谨慎 /functions # 调用Edge Functions的技能 /storage # 操作Supabase Storage的技能 /auth # 用户认证与管理相关技能权限要求高 /utils # 共享工具如Supabase客户端初始化、错误处理 /examples # 集成示例展示如何与LangChain等框架结合这种结构清晰地将不同维度的Supabase能力模块化开发者可以根据需要按需引入。3. 核心技能详解与实战配置了解了设计理念我们来看看agent-skills里具体有哪些“干货”。我会挑选几个最具代表性的技能拆解其用法、配置要点和背后的安全考量。3.1 数据库查询技能AI成为你的数据分析师这是最常用、也最直观的技能。它的作用是让Agent能够根据用户的自然语言描述从Supabase数据库中查询数据。技能原理自然语言转结构化参数LLM根据技能的参数模式将用户问题“帮我找出上个月所有活跃用户”解析为结构化参数例如{“table_name”: “users”, “filters”: {“last_login_at”: {“gte”: “2024-03-01”}}, “select_fields”: [“id”, “email”, “username”]}。构建安全查询技能内部接收到这些参数后会利用Supabase JavaScript/TypeScript客户端库构建一个类型安全且符合RLS的查询。例如supabase.from(table_name).select(select_fields).gte(‘last_login_at’, filters.last_login_at.gte)。执行并返回执行查询将结果以JSON或自然语言摘要的形式返回给Agent再由Agent呈现给用户。实战配置与代码示例假设你有一个LangChain Agent你想为其添加查询技能。// 1. 安装依赖 // npm install supabase/supabase-js supabase/agent-skills // 2. 初始化技能和Supabase客户端 import { createClient } from ‘supabase/supabase-js’; import { DatabaseSkill } from ‘supabase/agent-skills’; const supabaseUrl process.env.SUPABASE_URL; const supabaseKey process.env.SUPABASE_ANON_KEY; // 使用匿名密钥或服务角色密钥需极高安全考量 const supabase createClient(supabaseUrl, supabaseKey); // 创建数据库技能实例注入Supabase客户端 const dbSkill new DatabaseSkill(supabase); // 3. 将技能转换为LangChain Tool import { DynamicStructuredTool } from “langchain/tools”; const queryTool new DynamicStructuredTool({ name: dbSkill.name, // 例如 “query_database” description: dbSkill.description, schema: dbSkill.parametersSchema, // 自动获取技能定义的参数模式 func: async (args) { try { const result await dbSkill.execute(args); return JSON.stringify(result, null, 2); // 格式化返回给LLM } catch (error) { return Error executing query: ${error.message}; } }, }); // 4. 将queryTool添加到你的Agent工具列表中关键注意事项警告关于Supabase密钥的选择这是安全命脉。在开发测试中你可能使用anon key公开密钥但它受RLS限制。对于生产环境让Agent使用service_role key超级管理员密钥是极度危险的因为它会绕过RLS最佳实践是永远不要将service_role key暴露给前端或不可信的Agent环境。正确的做法是让Agent的请求通过一个受控的中间层如自定义的Edge Function在该中间层使用服务端密钥执行操作并在此层实现额外的业务逻辑审计和限流。3.2 边缘函数调用技能扩展Agent的无限可能Supabase Edge Functions边缘函数允许你运行自定义TypeScript代码。这个技能让Agent能够触发这些函数从而将能力扩展到数据库操作之外比如发送邮件、调用第三方API、进行复杂计算等。技能原理函数发现与描述技能需要知道有哪些Edge Function可用。这可以通过项目配置或动态读取来实现。每个函数都需要一个清晰的描述例如“send_email: 向指定用户发送邮件需要参数to,subject,body。”参数传递LLM根据函数描述从用户指令中提取参数。技能负责将这些参数序列化并通过Supabase客户端库的invoke方法调用对应的Edge Function。处理响应接收Edge Function的返回结果并将其传递给Agent。安全与设计考量权限控制Edge Function本身应实现权限校验通过验证JWT或检查秘密头。技能调用时传递的Supabase客户端应携带有限权限的会话。副作用管理明确哪些函数是幂等的可重复调用无副作用哪些不是。对于有副作用的函数如发送邮件、创建订单应在技能描述中明确警告并在Agent工作流中考虑增加用户确认环节。超时与错误处理设置合理的调用超时并准备好处理函数执行失败、网络错误等异常情况。3.3 存储管理技能让Agent处理文件这个技能允许Agent对Supabase Storage中的文件进行上传、下载、列出和删除操作。想象一个场景用户对Agent说“帮我把刚才讨论的会议纪要保存到‘项目文档’文件夹里”Agent就能调用此技能完成操作。实现要点路径安全必须严格校验用户提供的文件路径防止路径遍历攻击如../../../etc/passwd。技能应限制操作范围在特定的Storage Bucket内。文件类型限制可以在技能层面或Storage Bucket策略中限制可上传的文件类型MIME类型和大小。公共与私有明确文件是上传到公开Bucket还是私有Bucket。私有文件的下载链接需要签名技能需要能正确处理这两种情况。4. 集成实战构建一个智能客服Agent让我们通过一个更完整的例子将上述技能组合起来构建一个简单的内部系统智能客服Agent。这个Agent可以回答关于用户数据的问题并能帮用户上传头像。场景设定我们有一个员工信息系统Supabase后端员工可以向Agent提问例如“技术部有多少人”或“帮我把我的新头像图片更新一下”。架构步骤环境与依赖准备# 初始化项目并安装依赖 npm init -y npm install langchain langchain/openai supabase/supabase-js supabase/agent-skills技能组装与工具创建// agentTools.js import { createClient } from ‘supabase/supabase-js’; import { DatabaseSkill, StorageSkill } from ‘supabase/agent-skills’; import { DynamicStructuredTool } from “langchain/tools”; // 使用具有有限权限的Supabase客户端例如通过登录用户的JWT初始化 // 此处为示例实际应从安全的上下文中获取 const supabaseUrl process.env.SUPABASE_URL; const supabaseKey process.env.SUPABASE_ANON_KEY; // 或从用户会话获取 const supabase createClient(supabaseUrl, supabaseKey); // 1. 创建数据库查询技能只读 const querySkill new DatabaseSkill(supabase, { readOnly: true }); // 设置为只读模式更安全 const queryTool new DynamicStructuredTool({ name: querySkill.name, description: querySkill.description, schema: querySkill.parametersSchema, func: querySkill.execute.bind(querySkill), }); // 2. 创建存储上传技能限制到‘avatars’桶 const uploadSkill new StorageSkill(supabase, { allowedBuckets: [‘avatars’] }); const uploadTool new DynamicStructuredTool({ name: ‘upload_avatar’, description: ‘将图片文件上传到用户头像存储桶。需要参数file_path文件路径, file_contentbase64编码的文件内容’, schema: uploadSkill.getUploadSchema(), // 假设技能提供了特定的上传参数模式 func: uploadSkill.executeUpload.bind(uploadSkill), }); export const tools [queryTool, uploadTool];构建LangChain Agent// buildAgent.js import { ChatOpenAI } from “langchain/openai”; import { createReactAgent } from “langchain/agents”; import { tools } from “./agentTools.js”; const llm new ChatOpenAI({ modelName: “gpt-4-turbo-preview”, temperature: 0, apiKey: process.env.OPENAI_API_KEY, }); // 使用ReAct代理框架 const agent createReactAgent({ llm, tools, // 可以提供一个自定义的提示模板引导Agent更好地使用我们的技能 promptTemplate: 你是一个内部员工系统助手。你可以使用工具查询数据库信息或者帮用户上传头像图片。 使用工具时请严格按照工具要求的参数格式提供信息。 对于查询请求请引导用户提供更具体的筛选条件如部门、时间。 对于上传头像请求请确认用户已准备好图片。, }); // 运行Agent示例 const runAgent async (userInput) { const stream await agent.stream({ input: userInput }); for await (const chunk of stream) { if (‘agent’ in chunk) { console.log(chunk.agent.messages[chunk.agent.messages.length - 1]?.content); } else if (‘tools’ in chunk) { console.log([调用工具: ${chunk.tools[0].name}]); } else if (‘steps’ in chunk) { const finalStep chunk.steps[chunk.steps.length - 1]; console.log(finalStep.observation); } } }; // 模拟用户输入 // await runAgent(“技术部有多少名员工”); // await runAgent(“我要上传头像图片数据是: [base64数据]...”);前端集成与会话管理在实际应用中你需要一个前端如Web应用来收集用户输入并显示Agent回复。关键点是管理用户的Supabase认证会话并将这个会话安全地传递给后端或边缘函数用于初始化具有对应用户权限的Supabase客户端。绝对不要在前端用服务端密钥初始化客户端给Agent用。5. 安全加固、监控与进阶思考将AI Agent接入生产系统安全是重中之重。agent-skills提供了基础的安全框架但开发者需要在此基础上构建更全面的防御体系。5.1 多层安全防御策略第一层技能层安全由agent-skills提供RLS依赖确保所有数据库操作都通过正确配置了RLS的Supabase客户端进行。这是最核心的防线。输入校验与净化充分利用技能内部的参数校验和SQL参数化。操作白名单严格限制技能可访问的表、存储桶和边缘函数。第二层Agent编排层安全工具调用审批对于高风险操作如删除、发送邮件、支付可以在Agent调用工具前插入一个“人工确认”或“二次验证”步骤。例如让Agent生成一个待办事项由用户点击确认后再实际执行。对话历史审查定期审查Agent与用户的对话日志检查是否有诱导性提问或异常操作模式。输出过滤对Agent返回给用户的数据进行脱敏处理例如自动隐藏身份证号、手机号中间几位。第三层系统与运维层安全速率限制对每个用户或每个会话的Agent工具调用频率进行限制防止滥用。全面的日志记录记录每一次工具调用的详细信息谁用户ID、何时、调用了什么技能、输入参数是什么、输出结果是什么。这对于审计和事后追溯至关重要。独立的执行环境考虑将Agent的技能执行器即实际调用Supabase客户端的部分部署在一个独立的、网络受限的服务中与主应用逻辑隔离。5.2 性能优化与监控技能缓存对于频繁执行的只读查询技能如“获取产品列表”可以引入缓存机制如Redis减少对数据库的直接压力。超时控制为每个技能设置合理的执行超时时间避免因某个技能卡死导致整个Agent无响应。监控指标监控技能调用的成功率、延迟、错误类型。设置告警当错误率或延迟超过阈值时及时通知。5.3 自定义技能开发agent-skills项目提供的技能是通用的起点。真正的威力在于根据你的业务需求开发自定义技能。例如你可以创建一个“创建技术支持工单”技能它内部会先查询用户信息然后向tickets表插入一条记录并调用一个Edge Function向支持团队发送通知。开发自定义技能时遵循项目的模式定义清晰的技能描述和参数模式。在技能实现内部充分利用Supabase客户端的能力。嵌入必要的业务逻辑校验和安全检查。编写单元测试确保技能在各种边界条件下行为正确。supabase/agent-skills项目为基于Supabase的AI Agent应用开发打开了一扇大门。它通过提供一套标准化、安全化的原生技能极大地降低了开发门槛。然而它不是一个“一键部署”的解决方案而是一个强大的“工具箱”。成功的关键在于开发者深刻理解其安全模型并结合自身业务逻辑进行恰当的集成、扩展和加固。从简单的数据查询助手开始逐步构建能够处理复杂工作流的智能体这条路已经因为它的存在而变得清晰了许多。