使用说明
@clerk/agent-toolkit
[!重要]
代理行为通常是不确定的。确保您彻底测试您的集成并评估应用程序的性能。此外,考虑将此工具包的工具范围限定为特定用户,以限制资源访问。
如果你的应用程序的代码路径是预先确定的,那么最好直接调用API,而不是使用代理和工具调用。
除非您对代理的行为有信心,并且已经实施了必要的安全措施,如护栏和最佳实践,否则建议仅将此SDK用于测试目的。
目录
入门指南
使用此SDK进行集成 职员 进入您的代理工作流程。Clerk Agent Toolkit使流行的代理框架(包括Vercel的AI SDK和LangChain)能够使用工具(也称为函数调用)与Clerk集成。
此包向代理框架公开了Clerk功能的一个子集,允许您构建能够管理用户、用户数据、组织等的强大代理系统。
API 参考
导入路径
Clerk Agent Toolkit包提供了两个主要的导入路径:
@clerk/agent-toolkit/ai-sdk:有助于与Vercel的AI SDK集成。@clerk/agent-toolkit/langchain:有助于与Langchain集成。@clerk/agent-toolkit/modelcontextprotocol:用于与模型上下文协议(MCP)集成的低级助手。
该工具包跨框架提供相同的工具和核心API,但它们的公共接口可能会略有不同,以与每个框架的设计保持一致:
方法
初始化和通用帮助程序
createClerkToolkit(options):即时提供一个新的办事员工具包。toolkit.injectSessionClaims(systemPrompt):注入会话声明(userId,sessionId,orgId等)进入系统提示,使其可供AI模型访问。
可用工具
目前,仅将Clerk后端API功能的一个子集公开为工具。我们计划在收到社区反馈后扩展此列表。欢迎您在Discord上打开问题或联系我们以请求其他工具。
toolkit.users():提供管理用户的工具。 详情.toolkit.organizations():提供管理组织的工具。 详情.toolkit.invitations():提供用于管理邀请的工具。 详情.toolkit.allTools():返回所有可用工具。
Langchain特定方法
toolkit.toolMap():返回一个对象映射可用工具,可用于按名称调用工具。
MCP特定方法
createClerkMcpServer():实例化一个新的Clerk MCP服务器。有关更多详细信息,请参阅
有关每个工具的更多详细信息,请参阅特定于框架的目录或 办事员后台API文件.
先决条件
ai-sdk:"^3.4.7 || ^4.0.0",或langchain:"^0.3.6"- 现有的Clerk应用程序。 免费创建您的帐户.
- 与Langchain兼容的人工智能模型的API密钥
示例存储库
使用Vercel的AI SDK
-
安装职员代理工具包包:
npm install @clerk/agent-toolkit -
将Clerk密钥设置为项目中的环境变量。确保您还配置了任何所需的LLM模型密钥。
CLERK_SECRET_KEY=sk_ -
从导入助手
/ai-sdk路径,实例化一个新的Clerktoolkit,并在代理函数中使用它:
// Import the helper from the ai-sdk path
import { createClerkToolkit } from '@clerk/agent-toolkit/ai-sdk';
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
import { auth } from '@clerk/nextjs/server';
import { systemPrompt } from '@/lib/ai/prompts';
export const maxDuration = 30;
export async function POST(req: Request) {
const { messages } = await req.json();
// Optional - get the auth context from the request
const authContext = await auth.protect();
// Instantiate a new Clerk toolkit
// Optional - scope the toolkit to this session
const toolkit = await createClerkToolkit({ authContext });
const result = streamText({
model: openai('gpt-4o'),
messages,
// Optional - inject session claims into the system prompt
system: toolkit.injectSessionClaims(systemPrompt),
tools: {
// Provide the tools you want to use
...toolkit.users(),
...toolkit.organizations(),
},
});
return result.toDataStreamResponse();
}
使用Langchain
-
安装职员代理工具包包:
npm install @clerk/agent-toolkit -
将Clerk密钥设置为环境变量:
CLERK_SECRET_KEY=sk_ -
从导入助手
/langchain路径,实例化一个新的Clerktoolkit,并在代理函数中使用它:
// Import the helper from the langchain path
import { createClerkToolkit } from '@clerk/agent-toolkit/langchain';
import { ChatOpenAI } from '@langchain/openai';
import { auth } from '@clerk/nextjs/server';
import { HumanMessage, SystemMessage } from '@langchain/core/messages';
import { LangChainAdapter } from 'ai';
import { systemPrompt } from '@/lib/ai/prompts';
export const maxDuration = 30;
export async function POST(req: Request) {
const { prompt } = await req.json();
// Optional - get the auth context from the request
const authContext = await auth.protect();
// Instantiate a new Clerk toolkit
// Optional - scope the toolkit to a specific user
const toolkit = await createClerkToolkit({ authContext });
const model = new ChatOpenAI({ model: 'gpt-4o', temperature: 0 });
// Bind the tools you want to use to the model
const modelWithTools = model.bindTools(toolkit.users());
const messages = [new SystemMessage(toolkit.injectSessionClaims(systemPrompt)), new HumanMessage(prompt)];
const aiMessage = await modelWithTools.invoke(messages);
messages.push(aiMessage);
for (const toolCall of aiMessage.tool_calls || []) {
// Call the selected tool
const selectedTool = toolkit.toolMap()[toolCall.name];
const toolMessage = await selectedTool.invoke(toolCall);
messages.push(toolMessage);
}
// To simplify the setup, this example uses the ai-sdk langchain adapter
// to stream the results back to the /langchain page.
// For more details, see: https://sdk.vercel.ai/providers/adapters/langchain
const stream = await modelWithTools.stream(messages);
return LangChainAdapter.toDataStreamResponse(stream);
}
模型上下文协议(MCP服务器)
这 @clerk/agent-toolkit/modelcontextprotocol 导入路径为与模型上下文协议(MCP)集成提供了一个低级助手。这被认为是一个高级用例,因为大多数用户会对直接运行本地Clerk MCP服务器感兴趣。
运行本地MCP服务器
使用以下命令在本地运行Clerk MCP服务器 npx,运行以下命令:
// Provide the Clerk secret key as an environment variable
CLERK_SECRET_KEY=sk_123 npx -y @clerk/agent-toolkit -p local-mcp
// Alternatively, you can pass the secret key as an argument
npx -y @clerk/agent-toolkit -p local-mcp --secret-key sk_123
默认情况下,MCP服务器将使用所有可用的Clerk工具,如 可用工具: 部分。要限制服务器可用的工具,请使用 --tools (-t)标志:
// This example assumes the CLERK_SECRET_KEY environment variable is set
// Use all tools
npx -y @clerk/agent-toolkit -p local-mcp
npx -y @clerk/agent-toolkit -p local-mcp --tools="*"
// Use only a specific tool category
npx -y @clerk/agent-toolkit -p local-mcp --tools users
npx -y @clerk/agent-toolkit -p local-mcp --tools "users.*"
// Use multiple tool categories
npx -y @clerk/agent-toolkit -p local-mcp --tools users organizations
// Use specific tools
npx -y @clerk/agent-toolkit -p local-mcp --tools users.getUserCount organizations.getOrganization
使用 --help 标记以查看其他服务器选项。
使用Claude Desktop
将以下内容添加到您的 claude_desktop_config.json 使用本地MCP服务器的文件:
{
"mcpServers": {
"clerk": {
"command": "npx",
"args": ["-y", "@clerk/agent-toolkit", "-p=local-mcp", "--tools=users", "--secret-key=sk_123"]
}
}
}
有关更多信息,请参阅 Claude桌面文档.
高级用法
使用自定义 clerkClient
如果需要动态设置Clerk密钥或使用不同的Clerk实例,请传递自定义密钥 clerkClient.安装 @clerk/backend 进入您的项目并致电 createClerkClient 功能:
import { createClerkToolkit } from '@clerk/agent-toolkit/ai-sdk';
import { createClerkClient } from '@clerk/backend';
export async function POST(req: Request) {
// Create a new Clerk client
const clerkClient = createClerkClient({ secretKey: 'sk_' });
// Instantiate a new Clerk toolkit with the custom client
const toolkit = await createClerkToolkit({ clerkClient });
// Use the toolkit as usual
const result = streamText({
model: openai('gpt-4o'),
messages,
tools: toolkit.users(),
});
}
支持
您可以通过以下任何一种方式与我们联系:
- 加入我们的官方社区 Discord服务器
- 开 我们的支持页面
贡献
我们对所有社区贡献持开放态度!如果你想以任何方式做出贡献,请阅读 我们的贡献指南 和 行为准则.
许可证
该项目根据 MIT许可证.
看 许可证 了解更多信息。
