@clerk/agent-toolkit 0.0.6-canary.v20250306110334

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Clerk, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+<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://images.clerk.com/static/logo-dark-mode-400x400.png">
+      <img src="https://images.clerk.com/static/logo-light-mode-400x400.png" height="64">
+    </picture>
+  </a>
+  <br />
+  <h1 align="center">@clerk/agent-toolkit</h1>
+</p>
+
+<div align="center">
+
+[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord)
+[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=clerk_agent_toolkit)
+[![Follow on Twitter](https://img.shields.io/twitter/follow/ClerkDev?style=social)](https://twitter.com/intent/follow?screen_name=ClerkDev)
+
+[Changelog](https://github.com/clerk/javascript/blob/main/packages/agent-toolkit/CHANGELOG.md)
+·
+[Report a Bug](https://github.com/clerk/javascript/issues/new?assignees=&labels=needs-triage&projects=&template=BUG_REPORT.yml)
+·
+[Request a Feature](https://feedback.clerk.com/roadmap)
+·
+[Get Help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_agent_toolkit)
+
+</div>
+
+> [!IMPORTANT]
+>
+> Agent behavior is typically non-deterministic. Ensure you thoroughly test your integration and evaluate your application's performance. Additionally, consider scoping this toolkit's tools to specific users to limit resource access.
+>
+> If your app's code path is predetermined, it's always preferable to call APIs directly instead of using agents and tool calling.
+>
+> This SDK is recommended for testing purposes only unless you are confident in the agent's behavior and have implemented necessary security measures such as guardrails and best practices.
+
+## Table of Contents
+
+<!-- TOC -->
+
+- [Table of Contents](#table-of-contents)
+- [Getting Started](#getting-started)
+- [API Reference](#api-reference)
+  - [Import Paths](#import-paths)
+  - [Methods](#methods)
+- [Prerequisites](#prerequisites)
+- [Example Repository](#example-repository)
+- [Using Vercel's AI SDK](#using-vercels-ai-sdk)
+- [Using Langchain](#using-langchain)
+- [Advanced Usage](#advanced-usage)
+  - [Using a Custom `clerkClient`](#using-a-custom-clerkclient)
+- [Support](#support)
+- [Contributing](#contributing)
+- [License](#license)
+<!-- TOC -->
+
+## Getting Started
+
+Use this SDK to integrate [Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_agent_toolkit) into your agentic workflows. The Clerk Agent Toolkit enables popular agent frameworks, including Vercel's AI SDK and LangChain, to integrate with Clerk using tools (also known as function calling).
+
+This package exposes a subset of Clerk's functionality to agent frameworks, allowing you to build powerful agentic systems capable of managing users, user data, organizations, and more.
+
+## API Reference
+
+### Import Paths
+
+The Clerk Agent Toolkit package provides two main import paths:
+
+- `@clerk/agent-toolkit/ai-sdk`: Helpers for integrating with Vercel's AI SDK.
+- `@clerk/agent-toolkit/langchain`: Helpers for integrating with Langchain.
+
+The toolkit offers the same tools and core APIs across frameworks, but their public interfaces may vary slightly to align with each framework's design:
+
+### Methods
+
+**Initialization & generic helpers**:
+
+- `createClerkToolkit(options)`: Instantiates a new Clerk toolkit.
+- `toolkit.injectSessionClaims(systemPrompt)`: Injects session claims (`userId`, `sessionId`, `orgId`, etc.) into the system prompt, making them accessible to the AI model.
+
+**Available tools**:
+
+Currently, are only exposing a subset of Clerk Backend API functionality as tools. We plan to expand this list as we receive feedback from the community. You are welcome to open an issue or reach out to us on Discord to request additional tools.
+
+- `toolkit.users()`: Provides tools for managing users. [Details](https://github.com/clerk/javascript/blob/main/packages/agent-toolkit/src/lib/tools/users.ts).
+- `toolkit.organizations()`: Provides tools for managing organizations. [Details](https://github.com/clerk/javascript/blob/main/packages/agent-toolkit/src/lib/tools/organizations.ts).
+- `toolkit.invitations()`: Provides tools for managing invitations. [Details](https://github.com/clerk/javascript/blob/main/packages/agent-toolkit/src/lib/tools/invitations.ts).
+- `toolkit.allTools()`: Returns all available tools.
+
+**Langchain-specific methods:**
+
+- `toolkit.toolMap()`: Returns an object mapping available tools, useful for calling tools by name.
+
+For more details on each tool, refer to the framework-specific directories or the [Clerk Backend API documentation](https://clerk.com/docs/reference/backend-api).
+
+## Prerequisites
+
+- `ai-sdk`: `"^3.4.7 || ^4.0.0"`, or `langchain`: `"^0.3.6"`
+- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_agent_toolkit).
+- An API key for an AI model compatible with Langchain
+
+## Example Repository
+
+- [Clerk AI SDK Example](https://github.com/clerk/agent-toolkit-example)
+
+## Using Vercel's AI SDK
+
+1. Install the Clerk Agent Toolkit package:
+
+   ```shell
+   npm install @clerk/agent-toolkit
+   ```
+
+2. Set the Clerk secret key as an environment variable in your project. Ensure you also configure any required LLM model keys.
+
+   ```
+   CLERK_SECRET_KEY=sk_
+   ```
+
+3. Import the helper from the `/ai-sdk` path, instantiate a new Clerk `toolkit`, and use it in your agent function:
+
+```typescript
+// 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 userId from the request
+  const { userId } = await auth.protect();
+
+  // Instantiate a new Clerk toolkit
+  // Optional - scope the toolkit to a specific user
+  const toolkit = await createClerkToolkit({ context: { userId } });
+
+  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();
+}
+```
+
+## Using Langchain
+
+1. Install the Clerk Agent Toolkit package:
+
+   ```shell
+   npm install @clerk/agent-toolkit
+   ```
+
+2. Set the Clerk secret key as an environment variable:
+
+   ```shell
+   CLERK_SECRET_KEY=sk_
+   ```
+
+3. Import the helper from the `/langchain` path, instantiate a new Clerk `toolkit`, and use it in your agent function:
+
+```typescript
+// 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();
+  const { userId } = await auth.protect();
+
+  // Instantiate a new Clerk toolkit
+  // Optional - scope the toolkit to a specific user
+  const toolkit = await createClerkToolkit({ context: { userId } });
+
+  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);
+}
+```
+
+## Advanced Usage
+
+### Using a Custom `clerkClient`
+
+If you need to set the Clerk secret key dynamically or use different Clerk instances, pass a custom `clerkClient`. Install `@clerk/backend` into your project and call the `createClerkClient` function:
+
+```typescript
+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(),
+  });
+}
+```
+
+## Support
+
+You can get in touch with us in any of the following ways:
+
+- Join our official community [Discord server](https://clerk.com/discord)
+- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_agent_toolkit)
+
+## Contributing
+
+We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md).
+
+## License
+
+This project is licensed under the **MIT license**.
+
+See [LICENSE](https://github.com/clerk/javascript/blob/main/packages/agent-toolkit/LICENSE) for more information.

package/dist/ai-sdk/index.d.ts

@@ -0,0 +1,37 @@
+import { S as SdkAdapter, C as ClerkToolkitBase, f as flatTools, a as CreateClerkToolkitParams, t as tools } from '../index-BtdcFG6Y.js';
+import { Tool } from 'ai';
+import '@clerk/backend';
+import 'zod';
+import '@clerk/backend/internal';
+
+/**
+ * Converts a `ClerkTool` to an AI SDK `Tool`.
+ */
+declare const adapter: SdkAdapter<Tool>;
+
+type AdaptedTools = {
+    [key in keyof typeof tools]: () => {
+        [tool in keyof (typeof tools)[key]]: ReturnType<typeof adapter>;
+    };
+};
+type ClerkToolkit = ClerkToolkitBase & {
+    /**
+     * Returns an object with all the tools from all categories in the Clerk toolkit.
+     *
+     * Most LLM providers recommend that for each LLM call, the number of available tools should be kept to a minimum,
+     * usually around 10-20 tools. This increases the LLM's accuracy when picking the right tool.
+     *
+     * As a result, we also recommend to use the fine-grained tool categories, for example, `toolkit.users` instead.
+     */
+    allTools: () => {
+        [key in keyof typeof flatTools]: ReturnType<typeof adapter>;
+    };
+} & AdaptedTools;
+/**
+ * Creates a Clerk toolkit with the given parameters.
+ * The toolkit is a collection of tools that can be used to augment the AI's capabilities,
+ * For more details, refer to the [package's docs](https://github.com/clerk/javascript/blob/main/packages/agent-toolkit/README.md).
+ */
+declare const createClerkToolkit: (params?: CreateClerkToolkitParams) => Promise<ClerkToolkit>;
+
+export { type ClerkToolkit, createClerkToolkit };

package/dist/ai-sdk/index.js

@@ -0,0 +1,42 @@
+import {
+  clerkClient,
+  defaultToolkitContext,
+  flatTools,
+  injectSessionClaims,
+  shallowTransform,
+  tools
+} from "../chunk-K5TBM24J.js";
+
+// src/ai-sdk/adapter.ts
+import { tool } from "ai";
+var adapter = (clerkClient2, context, clerkTool) => {
+  return tool({
+    description: clerkTool.description,
+    parameters: clerkTool.parameters,
+    execute: clerkTool.bindRunnable(clerkClient2, context)
+  });
+};
+
+// src/ai-sdk/index.ts
+var createClerkToolkit = async (params = {}) => {
+  const clerkClient2 = params.clerkClient || clerkClient;
+  const context = params.context || defaultToolkitContext;
+  const adaptedTools = shallowTransform(tools, (toolSection) => {
+    return () => shallowTransform(toolSection, (t) => {
+      return adapter(clerkClient2, context, t);
+    });
+  });
+  const allTools = () => {
+    return shallowTransform(flatTools, (t) => adapter(clerkClient2, context, t));
+  };
+  adaptedTools.organizations();
+  return Promise.resolve({
+    ...adaptedTools,
+    allTools,
+    injectSessionClaims: injectSessionClaims(context)
+  });
+};
+export {
+  createClerkToolkit
+};
+//# sourceMappingURL=index.js.map

package/dist/ai-sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ai-sdk/adapter.ts","../../src/ai-sdk/index.ts"],"sourcesContent":["import type { Tool } from 'ai';\nimport { tool } from 'ai';\n\nimport type { SdkAdapter } from '../lib/types';\n\n/**\n * Converts a `ClerkTool` to an AI SDK `Tool`.\n */\nexport const adapter: SdkAdapter<Tool> = (clerkClient, context, clerkTool) => {\n  return tool({\n    description: clerkTool.description,\n    parameters: clerkTool.parameters,\n    execute: clerkTool.bindRunnable(clerkClient, context),\n  });\n};\n","import { clerkClient as _clerkClient } from '../lib/clerk-client';\nimport { defaultToolkitContext } from '../lib/constants';\nimport { injectSessionClaims } from '../lib/inject-session-claims';\nimport { flatTools, tools } from '../lib/tools';\nimport type { ClerkToolkitBase, CreateClerkToolkitParams } from '../lib/types';\nimport { shallowTransform } from '../lib/utils';\nimport { adapter } from './adapter';\n\ntype AdaptedTools = {\n  [key in keyof typeof tools]: () => { [tool in keyof (typeof tools)[key]]: ReturnType<typeof adapter> };\n};\n\nexport type ClerkToolkit = ClerkToolkitBase & {\n  /**\n   * Returns an object with all the tools from all categories in the Clerk toolkit.\n   *\n   * Most LLM providers recommend that for each LLM call, the number of available tools should be kept to a minimum,\n   * usually around 10-20 tools. This increases the LLM's accuracy when picking the right tool.\n   *\n   * As a result, we also recommend to use the fine-grained tool categories, for example, `toolkit.users` instead.\n   */\n  allTools: () => { [key in keyof typeof flatTools]: ReturnType<typeof adapter> };\n} & AdaptedTools;\n\n/**\n * Creates a Clerk toolkit with the given parameters.\n * The toolkit is a collection of tools that can be used to augment the AI's capabilities,\n * For more details, refer to the [package's docs](https://github.com/clerk/javascript/blob/main/packages/agent-toolkit/README.md).\n */\nexport const createClerkToolkit = async (params: CreateClerkToolkitParams = {}): Promise<ClerkToolkit> => {\n  const clerkClient = params.clerkClient || _clerkClient;\n  const context = params.context || defaultToolkitContext;\n\n  const adaptedTools = shallowTransform(tools, toolSection => {\n    return () =>\n      shallowTransform(toolSection, t => {\n        return adapter(clerkClient, context, t);\n      });\n  }) as AdaptedTools;\n\n  const allTools = () => {\n    return shallowTransform(flatTools, t => adapter(clerkClient, context, t));\n  };\n\n  adaptedTools.organizations();\n\n  return Promise.resolve({\n    ...adaptedTools,\n    allTools,\n    injectSessionClaims: injectSessionClaims(context),\n  });\n};\n"],"mappings":";;;;;;;;;;AACA,SAAS,YAAY;AAOd,IAAM,UAA4B,CAACA,cAAa,SAAS,cAAc;AAC5E,SAAO,KAAK;AAAA,IACV,aAAa,UAAU;AAAA,IACvB,YAAY,UAAU;AAAA,IACtB,SAAS,UAAU,aAAaA,cAAa,OAAO;AAAA,EACtD,CAAC;AACH;;;ACeO,IAAM,qBAAqB,OAAO,SAAmC,CAAC,MAA6B;AACxG,QAAMC,eAAc,OAAO,eAAe;AAC1C,QAAM,UAAU,OAAO,WAAW;AAElC,QAAM,eAAe,iBAAiB,OAAO,iBAAe;AAC1D,WAAO,MACL,iBAAiB,aAAa,OAAK;AACjC,aAAO,QAAQA,cAAa,SAAS,CAAC;AAAA,IACxC,CAAC;AAAA,EACL,CAAC;AAED,QAAM,WAAW,MAAM;AACrB,WAAO,iBAAiB,WAAW,OAAK,QAAQA,cAAa,SAAS,CAAC,CAAC;AAAA,EAC1E;AAEA,eAAa,cAAc;AAE3B,SAAO,QAAQ,QAAQ;AAAA,IACrB,GAAG;AAAA,IACH;AAAA,IACA,qBAAqB,oBAAoB,OAAO;AAAA,EAClD,CAAC;AACH;","names":["clerkClient","clerkClient"]}