代理工具包

Clerk代理工具包是一个用于集成到代理工作流中的工具集,支持管理用户、组织和邀请等功能,适用于AI模型集成和自动化任务。

  • by clerk
  • TypeScript
  • 本地部署
  • 1775 星标
  • 更新于
在 GitHub 查看 clerk/javascript

使用说明


@clerk/agent-toolkit

更新日志 · 报告Bug · 请求功能 · 获取帮助

[!重要]

代理行为通常是不确定的。确保您彻底测试您的集成并评估应用程序的性能。此外,考虑将此工具包的工具范围限定为特定用户,以限制资源访问。

如果你的应用程序的代码路径是预先确定的,那么最好直接调用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

  1. 安装职员代理工具包包:

    npm install @clerk/agent-toolkit
    
  2. 将Clerk密钥设置为项目中的环境变量。确保您还配置了任何所需的LLM模型密钥。

    CLERK_SECRET_KEY=sk_
    
  3. 从导入助手 /ai-sdk 路径,实例化一个新的Clerk toolkit,并在代理函数中使用它:

// 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

  1. 安装职员代理工具包包:

    npm install @clerk/agent-toolkit
    
  2. 将Clerk密钥设置为环境变量:

    CLERK_SECRET_KEY=sk_
    
  3. 从导入助手 /langchain 路径,实例化一个新的Clerk toolkit,并在代理函数中使用它:

// 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(),
  });
}

支持

您可以通过以下任何一种方式与我们联系:

贡献

我们对所有社区贡献持开放态度!如果你想以任何方式做出贡献,请阅读 我们的贡献指南 和 行为准则.

许可证

该项目根据 MIT许可证.

看 许可证 了解更多信息。