星战科技xingzhan.cloud
返回市场
代理工具包

代理工具包

作者：clerk1607 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

技术文档摘要

<p align="center"> <a href="https://clerk.com?utm_source=github&utm_medium=clerk_agent_toolkit" target="_blank" rel="noopener noreferrer"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://gips1.baidu.com/it/u=2366866215,1108874133&fm=3081&app=3_081&f=PNG?w=400&h=400"> <img src="https://gips0.baidu.com/it/u=1772555498,1274360467&fm=3081&app=3081&f=PNG?w=400&h=400" height="64"> </picture> </a> <br /> <h1 align="center">@clerk/agent-toolkit</h1> </p> <div align="center">

Chat on Discord Clerk documentation Follow on Twitter

变更日志 · 报告错误 · 请求功能 · 获取帮助

</div>

[!IMPORTANT]

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

如果您的应用代码路径是预设的，那么总是建议直接调用API而不是使用代理和工具调用。

此SDK仅推荐用于测试目的，除非您对代理的行为有信心并已实施必要的安全措施，如护栏和最佳实践。

目录

<!-- TOC --> <!-- TOC -->

开始使用

使用此 SDK 将 Clerk 集成到您的代理工作流程中。Clerk 代理工具包使流行的代理框架（包括 Vercel 的 AI SDK 和 LangChain）能够通过工具（也称为函数调用）与 Clerk 集成。

此包公开了 Clerk 功能的一个子集给代理框架，允许您构建强大的代理系统，能够管理用户、用户数据、组织等。

API 参考

导入路径

Clerk 代理工具包提供两个主要的导入路径：

  • @clerk/agent-toolkit/ai-sdk：与 Vercel 的 AI SDK 集成的辅助函数。
  • @clerk/agent-toolkit/langchain：与 Langchain 集成的辅助函数。
  • @clerk/agent-toolkit/modelcontextprotocol：与模型上下文协议（MCP）集成的低级辅助函数。

工具包在各个框架中提供了相同的工具和核心 API，但它们的公共接口可能会略有不同，以适应每个框架的设计：

方法

初始化与通用辅助函数

  • createClerkToolkit(options)：实例化一个新的 Clerk 工具包。
  • 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 服务器。更多详细信息，请参阅

有关每个工具的更多信息，请参阅框架特定的目录或Clerk 后端 API 文档。

前提条件

  • ai-sdk："^3.4.7 || ^4.0.0"，或 langchain："^0.3.6"
  • 已存在的 Clerk 应用程序。免费创建您的账户。
  • 兼容 Langchain 的 AI 模型的 API 密钥。

示例仓库

使用 Vercel 的 AI SDK

  1. 安装 Clerk 代理工具包：

    npm install @clerk/agent-toolkit

  2. 在项目中设置 Clerk 秘密密钥为环境变量。确保您还配置了任何所需的 LLM 模型密钥。

    CLERK_SECRET_KEY=sk_

  3. 从 /ai-sdk 路径导入辅助函数，实例化一个新的 Clerk toolkit，并在您的代理函数中使用它：

// 从 ai-sdk 路径导入辅助函数
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();
  // 可选 - 从请求中获取认证上下文
  const authContext = await auth.protect();

  // 实例化一个新的 Clerk 工具包
  // 可选 - 将工具包范围限定到此会话
  const toolkit = await createClerkToolkit({ authContext });

  const result = streamText({
    model: openai('gpt-4o'),
    messages,
    // 可选 - 将会话声明注入到系统提示中
    system: toolkit.injectSessionClaims(systemPrompt),
    tools: {
      // 提供您想要使用的工具
      ...toolkit.users(),
      ...toolkit.organizations(),
    },
  });

  return result.toDataStreamResponse();
}

使用 Langchain

  1. 安装 Clerk 代理工具包：

    npm install @clerk/agent-toolkit

  2. 设置 Clerk 秘密密钥为环境变量：

    CLERK_SECRET_KEY=sk_

  3. 从 /langchain 路径导入辅助函数，实例化一个新的 Clerk toolkit，并在您的代理函数中使用它：

// 从 langchain 路径导入辅助函数
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();
  // 可选 - 从请求中获取认证上下文
  const authContext = await auth.protect();

  // 实例化一个新的 Clerk 工具包
  // 可选 - 将工具包范围限定到特定用户
  const toolkit = await createCClerkToolkit({ authContext });

  const model = new ChatOpenAI({ model: 'gpt-4o', temperature: 0 });

  // 绑定您想要使用的工具到模型
  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 || []) {
    // 调用选定的工具
    const selectedTool = toolkit.toolMap()[toolCall.name];
    const toolMessage = await selectedTool.invoke(toolCall);
    messages.push(toolMessage);
  }

  // 为了简化设置，此示例使用 ai-sdk langchain 适配器
  // 将结果流回 /langchain 页面。
  // 更多详细信息，请参阅：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 服务器

要使用 npx 在本地运行 Clerk MCP 服务器，运行以下命令：

// 提供 Clerk 秘密密钥作为环境变量
CLERK_SECRET_KEY=sk_123 npx -y @clerk/agent-toolkit -p local-mcp

// 或者，您可以将秘密密钥作为参数传递
npx -y @clerk/agent-toolkit -p local-mcp --secret-key sk_123

默认情况下，MCP 服务器将使用所有可用的 Clerk 工具，如可用工具部分所述。要限制服务器可用的工具，使用 --tools (-t) 标志：

// 此示例假设已经设置了 CLERK_SECRET_KEY 环境变量

// 使用所有工具
npx -y @clerk/agent-toolkit -p local-mcp
npx -y @clerk/agent-toolkit -p local-mcp --tools="*"

// 使用特定工具类别
npx -y @clerk/agent-toolkit -p local-mcp --tools users
npx -y @clerk/agent-toolkit -p local-mcp --tools "users.*"

// 使用多个工具类别
npx -y @clerk/agent-toolkit -p local-mcp --tools users organizations

// 使用特定工具
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 Desktop 文档。

高级用法

使用自定义 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) {
  // 创建一个新的 Clerk 客户端
  const clerkClient = createClerkClient({ secretKey: 'sk_' });

  // 使用自定义客户端实例化一个新的 Clerk 工具包
  const toolkit = await createClerkToolkit({ clerkClient });

  // 如常使用工具包
  const result = streamText({
    model: openai('gpt-4o'),
    messages,
    tools: toolkit.users(),
  });
}

支持

您可以通过以下方式联系我们：

贡献

我们欢迎来自社区的所有贡献！如果您想以任何方式做出贡献，请阅读我们的贡献指南和行为准则。

许可

本项目采用 MIT 许可证。

更多详细信息，请参阅LICENSE。