From 1242db071b0d3a273d302bb407b753e0fbdea338 Mon Sep 17 00:00:00 2001 From: Harshil Agrawal Date: Tue, 20 May 2025 15:27:26 +0200 Subject: [PATCH 1/4] adding slackbot tutorial --- src/content/docs/agents/tutorials/index.mdx | 16 ++ .../slackbot-knowledgebase/index.mdx | 261 ++++++++++++++++++ 2 files changed, 277 insertions(+) create mode 100644 src/content/docs/agents/tutorials/index.mdx create mode 100644 src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx diff --git a/src/content/docs/agents/tutorials/index.mdx b/src/content/docs/agents/tutorials/index.mdx new file mode 100644 index 00000000000000..c3ec470e487cb7 --- /dev/null +++ b/src/content/docs/agents/tutorials/index.mdx @@ -0,0 +1,16 @@ +--- +type: overview +pcx_content_type: navigation +title: Tutorials +hideChildren: true +sidebar: + order: 12 +--- + +import { GlossaryTooltip, ListTutorials } from "~/components"; + +View tutorials to help you get started with Agents. + +## Docs + + diff --git a/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx b/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx new file mode 100644 index 00000000000000..29e2efd5f1d52d --- /dev/null +++ b/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx @@ -0,0 +1,261 @@ +--- +updated: 2025-05-20 +difficulty: Beginner +content_type: Tutorial +pcx_content_type: tutorial +title: Building a Slackbot with Agents SDK +products: + - Agents + - AutoRAG +languages: + - JavaScript + - TypeScript +--- + +import { + Render, + Steps, + PackageManagers, + WranglerConfig, + Details, +} from "~/components"; + +In this tutorial, you will create an AI-powered Slackbot. The bot will answer user's questions, using the content embeded with [AutoRAG](/autorag). You will use the Agents SDK to create the agent. + +For each new thread, you will have a new instance of the agent. You will also store the messages of each thread in the state of the agent. This will allow you to maintain the conversation context. + +While this tutorial focuses on building a Slackbot, the same principles can be applied to any use-case that requires an AI-powered agent. You can even extend this tutorial to build agents for incident response, customer support, or any other use-case that requires an AI-powered agent. + +## Prerequisites + +Before you begin, you'll need the following: + + + +3. You will also need a Slack workspace where you have permission to create and manage apps. + +## Step 1: Create a Worker project + +Create a new Workers project by running the following command: + + + + + +You will need to install the [Cloudflare Agents SDK](), [AI SDK](), OpenAI provider for AI SDK, [zod](), the [Slack Web API package](). + + + +Your project is now set up. You can start building your agent! + +## Step 2: Handle Slack events + +The worker will receive events from Slack. You will need to handle these events and process them accordingly. Slack sends two types of events: + +- `url_verification`: To verify the request is from Slack. +- `event_callback`: Event callback for the events you subscribe to. + +You will need to handle both of the events. The `url_verification` event can be handled by our worker and doesn't need to be processed by the agent. The `event_callback` event will be processed by the agent. + +To handle the `url_verification` event, you will need to: + +1. Check the event type is `url_verification`. +2. Return the `challenge` value in the response. + +In your `index.ts` file, update the `fetch` handler with the below code: + +```ts title="src/index.ts" {1-5} {9-25} +import { + type GenericMessageEvent, + WebClient, + type AppMentionEvent, +} from "@slack/web-api"; + +export default { + async fetch(request: Request) { + const body = (await request.json()) as { + type: string; + challenge?: string; + event: GenericMessageEvent | AppMentionEvent; + }; + + if (body.type === "url_verification") { + return new Response(body.challenge, { status: 200 }); + } + + if (request.method !== "POST") { + return new Response("Not found", { status: 404 }); + } + + if (body.type !== "event_callback") { + return new Response("Not found", { status: 404 }); + } + }, +}; +``` + +The code above handles the `url_verification` event. It also checks if the request method is `POST` and checks if the event type is not `event_callback`. If any of these conditions are not met, it returns a `404 Not Found` response. + +For the `event_callback` type, you will need to + +1. extract the timestamp of the event or the message thread. +2. Create a new instance of the agent using the timestamp. +3. Pass the event data to the agent. + +Add the below code to your `fetch` handler: + +```ts title="src/index.ts" {17-20} +... +export default { + async fetch(request, env, ctx): Promise { + const body = (await request.json()) as { type: string; challenge?: string; event: GenericMessageEvent | AppMentionEvent }; + + if (body.type === 'url_verification') { + return new Response(body.challenge, { status: 200 }); + } + + if (request.method !== 'POST') { + return new Response('Not found', { status: 404 }); + } + + if (body.type !== 'event_callback') { + return new Response('Not found', { status: 404 }); + } + + let threadId = body.event.thread_ts || body.event.ts; + let agent = await getAgentByName(env.KnowledgeBaseAgent, threadId); + return await agent.chat(body.event); + }, +} satisfies ExportedHandler; +``` + +Note that you have not created the Agent yet. You will create it in the next step. + +## Step 1: Create a Slack app + +1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) and click on `Create New App`. Select the "From scratch" option. +2. Enter a name for your app and select the workspace where you want to create the app. +3. Go to the `OAuth & Permissions` page and add the following Bot Token Scopes to your app: + - `app_mentions:read` + - `assistant:write` + - `chat:write` + - `im:read` + - `im:write` +4. In the `Advanced token security via token rotation` section, install the app to your workspace and copy the `Bot User OAuth Token`. +5. Go to the `Event Subscriptions` page and enable `Enable Events` and add the following bot event subscriptions: + - `app_mention` + - `assistant_thread_started` + - `message.channels` + - `message.im` +6. Generate a Slack app token with the `xapp-` prefix and set the `SLACK_APP_TOKEN` environment variable. +7. Generate a bot token with the `xoxb-` prefix and set the `SLACK_BOT_TOKEN` environment variable. + +### Install the Cloudflare Agents SDK + +Open your terminal and run the following command to install the Cloudflare Agents SDK: + +```bash +npm install @cloudflare/agents +``` + +### Configure your Cloudflare account + +1. Log in to your Cloudflare account. +2. Create a new API token with the "Workers:Write" permission. +3. Set the `CLOUDFLARE_API_TOKEN` environment variable with the value of your API token. +4. Set the `CLOUDFLARE_ACCOUNT_ID` environment variable with your Cloudflare account ID. + +### Set up your Slack app + +1. Create a new Slack app at [https://api.slack.com/apps](https://api.slack.com/apps). +2. Enable the "Socket Mode" feature. +3. Add the following scopes to your app: + - `app_mentions:read` + - `chat:write` + - `im:read` + - `im:write` +4. Generate a Slack app token with the `xapp-` prefix and set the `SLACK_APP_TOKEN` environment variable. +5. Generate a bot token with the `xoxb-` prefix and set the `SLACK_BOT_TOKEN` environment variable. + +## Building your first AI agent + +### Create a new agent + +Create a new file named `agent.js` and add the following code: + +```javascript +// agent.js +import { Agent } from "@cloudflare/agents"; + +class MyAgent extends Agent { + constructor(options) { + super(options); + } + + async handleEvent(event) { + // Implement your agent's logic here + console.log("Received event:", event); + } +} + +export default MyAgent; +``` + +### Define agent's capabilities + +In the `agent.js` file, you can define your agent's capabilities by implementing the `handleEvent` method. This method will be called whenever the agent receives an event from Slack. + +### Implement the agent's logic + +Inside the `handleEvent` method, you can implement your agent's logic to process the event and take appropriate actions. For example, you can send a message to Slack, update a database, or call an external API. + +## Connecting to Slack + +### Integrate the agent with your Slack app + +To integrate your agent with your Slack app, you need to create a new Cloudflare Worker and configure it to use your Slack app token and bot token. + +### Handle Slack events + +The Cloudflare Agents SDK provides a `handleEvent` method that you can use to handle Slack events. This method will be called whenever your agent receives an event from Slack. + +### Send messages to Slack + +You can send messages to Slack using the Slack API. The Cloudflare Agents SDK provides a `slack` object that you can use to interact with the Slack API. + +## Advanced features (Optional) + +### Using environment variables + +You can use environment variables to store sensitive information, such as API keys and tokens. This allows you to keep your code secure and avoid hardcoding sensitive information in your code. + +### Logging and monitoring + +You can use logging and monitoring to track the performance of your agent and identify any issues. The Cloudflare Agents SDK provides a `logger` object that you can use to log messages. + +### Error handling + +You can use error handling to gracefully handle errors that may occur in your agent. The Cloudflare Agents SDK provides an `errorHandler` object that you can use to handle errors. + +## Deployment + +### Deploy your agent to Cloudflare Workers + +1. Create a new Cloudflare Worker. +2. Copy the code from your `agent.js` file to the Worker. +3. Set the `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` environment variables in the Worker settings. +4. Deploy the Worker. + +### Test your agent in Slack + +1. Invite your Slack app to a channel in your Slack workspace. +2. Send a message to the channel that mentions your app. +3. Verify that your agent receives the event and responds appropriately. From 19f546706ce6830af3d5f08a8d63983589e61b2c Mon Sep 17 00:00:00 2001 From: Harshil Agrawal Date: Fri, 30 May 2025 16:17:46 +0200 Subject: [PATCH 2/4] add tutorial for slack --- .../slackbot-knowledgebase/index.mdx | 363 ++++++++++++++---- 1 file changed, 296 insertions(+), 67 deletions(-) diff --git a/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx b/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx index 29e2efd5f1d52d..2a9f00b780c53e 100644 --- a/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx +++ b/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx @@ -112,7 +112,7 @@ For the `event_callback` type, you will need to Add the below code to your `fetch` handler: -```ts title="src/index.ts" {17-20} +```ts title="src/index.ts" {18-20} ... export default { async fetch(request, env, ctx): Promise { @@ -139,7 +139,195 @@ export default { Note that you have not created the Agent yet. You will create it in the next step. -## Step 1: Create a Slack app +## Step 3: Create the Agent + +To create an Agent, you need to extend the `Agent` class. The `Agent` class is a base class that provides the basic functionality for an Agent. + +For your agent, you will need to implement the following method: + +- `callAi`: This method will call the AI to generate an answer. +- `postToSlack`: This method handles posting messages on Slack. +- `chat`: This method will be called when the agent receives a message from the user. + +In this tutorial, you will use the AI SDK to generate responses from the AI. You will use the model `gpt-4o` from OpenAI provider. + +```ts title="src/index.ts" +import { Agent, getAgentByName } from "agents"; +import { generateText } from "ai"; +import { createOpenAI } from "@ai-sdk/openai"; +import { env } from "cloudflare:workers"; +import { + type GenericMessageEvent, + WebClient, + type AppMentionEvent, +} from "@slack/web-api"; + +export class KnowledgeBaseAgent extends Agent { + async callAi(userText: string) { + if (!userText) { + console.log("No text in message, skipping"); + return "I couldn't understand that message. Could you please rephrase?"; + } + + const openai = createOpenAI({ apiKey: env.OPENAI_API_KEY }); + const { text, response } = await generateText({ + model: openai("gpt-4o"), + system: `You are a Slackbot Support Assistant. You help users with their questions and issues. You have access to tools that retrieve information from the knowledge base. + Keep your responses concise and to the point. + `, + messages: [ + { + role: "user", + content: userText, + }, + ], + tools: { + KnowledgeBaseTool, + }, + maxSteps: 2, + }); + + const formattedResponse = text + ? text.replace(/\[(.*?)\]\((.*?)\)/g, "<$2|$1>").replace(/\*\*/g, "*") + : "I'm sorry, I couldn't generate a response."; + + return formattedResponse; + } + + async chat(body: GenericMessageEvent | AppMentionEvent): Promise { + // Wait for the postToSlack function to complete + this.ctx.waitUntil(this.postToSlack(body)); + + // Return a 200 response + return new Response(JSON.stringify({ status: "ok" }), { status: 200 }); + } + + async postToSlack(body: GenericMessageEvent | AppMentionEvent) { + const client = new WebClient(env.SLACK_BOT_TOKEN); + // Skip messages from bots or from this bot itself + if (body.bot_profile || body.bot_id || body.subtype === "message_changed") { + console.log("Skipping bot message"); + return; + } + + // Only process direct messages or mentions to avoid loops + if (body.type === "app_mention" || body.type === "message") { + try { + const userMessage = body.text || ""; + const response = await this.callAi(userMessage); + + // Send response in thread if possible + await client.chat.postMessage({ + channel: body.channel, + text: response, + // Add thread_ts if the message is in a thread to keep conversations organized + thread_ts: body.thread_ts || body.ts, + mrkdwn: true, + }); + + return { status: "responded" }; + } catch (error) { + console.error("Error processing message:", error); + return { + status: "error", + message: error instanceof Error ? error.message : String(error), + }; + } + } + } +} +``` + +The above code does the following: + +1. `callAi` + +- Checks if the user message is empty +- Calls the AI to generate a response passing the user message and the knowledge base tool +- Formats the response +- Returns the response + +2. `chat` + +- Calls the `postToSlack` method to post the answer in the thread +- Returns a success response + +3. `postToSlack` + +- Creates a new client using the bot token +- Checks if the message is from a bot or from this bot itself +- Checks if the message is a direct message or a mention +- Calls the `callAi` method to generate a response +- Sends the response in the thread + +Agents are built on top of Durable Objects. This means that each agent is a durable object. You need to update your `wrangler` configuration file to include the durable object binding for the agent. + + +```toml +[[durable_objects.bindings]] +name = "KnowledgeBaseAgent" +class_name = "KnowledgeBaseAgent" + +[[migrations]] +tag = "v1" +new_sqlite_classes = ["KnowledgeBaseAgent"] + +``` + + +You now have a Slackbot that can answer user's questions. To make sure it uses the knowledge base, you will need to add the knowledge base tool to the AI model. + +## Step 4: Create the knowledge base tool + +To make sure your users get the best answers, you will need to add the knowledge base tool to the AI model. The KnowledgeBaseTool is a tool that uses AutoRAG to retrieve information. You will need to create and configure a new AutoRAG instance. You can follow the [AutoRAG getting started](/autorag/tutorials/quick-start) to create and configure a new AutoRAG instance. + +Once you have created and configured the AutoRAG instance, you will need to create the knowledge base tool. The knowledge base tool will be used to retrieve information from the knowledge base. You will use AI bindings to use AutoRAG. In your `wrangler` configuration file, add the following binding: + + +```toml +[ai] +binding = "AI" +``` + + + +Next, in your `index.ts` file, add the following code: + +```ts {2-17} +... +import {z} from "zod"; +import { tool, generateText } from "ai"; + +const KnowledgeBaseTool = tool({ + description: "Search the knowledge base for an answer to the user's question", + parameters: z.object({ + question: z.string().describe('The question to search for in the knowledge base'), + }), + execute: async ({ question }) => { + const resp = await env.AI.autorag('autorag-demo').aiSearch({ + query: question, + stream: false, + }); + return resp; + }, +}); +... + +``` + +The above code does the following: + +1. Creates a tool using the `tool` function from the AI SDK +2. The tool has a description and parameters +3. The tool has an execute function that takes a question as input, uses AutoRAG to retrieve information from the knowledge base, and returns the answer + +You can now use the knowledge base tool in your agent. You already passed this tool to the AI model in the `callAi` method. + +The next step is to create a Slack app, and configure the credentials. + +## Step 5: Create a Slack app + +To create a Slack app, follow these steps: 1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) and click on `Create New App`. Select the "From scratch" option. 2. Enter a name for your app and select the workspace where you want to create the app. @@ -155,107 +343,148 @@ Note that you have not created the Agent yet. You will create it in the next ste - `assistant_thread_started` - `message.channels` - `message.im` -6. Generate a Slack app token with the `xapp-` prefix and set the `SLACK_APP_TOKEN` environment variable. -7. Generate a bot token with the `xoxb-` prefix and set the `SLACK_BOT_TOKEN` environment variable. -### Install the Cloudflare Agents SDK +:::note -Open your terminal and run the following command to install the Cloudflare Agents SDK: +You will need to add a URL in the `Request URL` field in the `Event Subscriptions` page. This URL will be used to receive events from Slack. You will add this URL after deploying the worker. -```bash -npm install @cloudflare/agents +::: + +6. In your project directory, create a `.dev.vars` file and add the Bot token you copied in the previous step. + +```text title=".dev.vars" +SLACK_BOT_TOKEN=xoxb-1234567890-1234567890-1234567890 ``` -### Configure your Cloudflare account +You will also need to add the OpenAI API key to the `.dev.vars` file. You can get the API key from [https://platform.openai.com/account/api-keys](https://platform.openai.com/account/api-keys). -1. Log in to your Cloudflare account. -2. Create a new API token with the "Workers:Write" permission. -3. Set the `CLOUDFLARE_API_TOKEN` environment variable with the value of your API token. -4. Set the `CLOUDFLARE_ACCOUNT_ID` environment variable with your Cloudflare account ID. +```text title=".dev.vars" +OPENAI_API_KEY=sk-1234567890 +``` -### Set up your Slack app +## Step 6: Deploy the worker -1. Create a new Slack app at [https://api.slack.com/apps](https://api.slack.com/apps). -2. Enable the "Socket Mode" feature. -3. Add the following scopes to your app: - - `app_mentions:read` - - `chat:write` - - `im:read` - - `im:write` -4. Generate a Slack app token with the `xapp-` prefix and set the `SLACK_APP_TOKEN` environment variable. -5. Generate a bot token with the `xoxb-` prefix and set the `SLACK_BOT_TOKEN` environment variable. +Your Slack app is now ready to receive events from Slack. You will need to deploy the agent to Cloudflare Workers. Slack will send events to the worker, and the worker will process the events and send responses to Slack. -## Building your first AI agent +:::note -### Create a new agent +Application running on `localhost` will not receive events from Slack. You will need to deploy the worker to Cloudflare Workers. Alternatively, you can use a reverse proxy to forward events from Slack to your application running on `localhost` using [Cloudflare Tunnels](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/). -Create a new file named `agent.js` and add the following code: +::: -```javascript -// agent.js -import { Agent } from "@cloudflare/agents"; +To deploy, execut the following command: -class MyAgent extends Agent { - constructor(options) { - super(options); - } +```bash +npm run deploy +``` - async handleEvent(event) { - // Implement your agent's logic here - console.log("Received event:", event); - } -} +The output returns the URL of the deployed worker. Copy the URL and add it to the `Request URL` field in the `Event Subscriptions` page of your Slack app. Click on `Save Changes` to save the URL. -export default MyAgent; +Next, add the credentials for your deployed Worker. Run the following command to do so: + +```bash +npx wrangler secret bulk .dev.vars ``` -### Define agent's capabilities +This command will add the credentials to your deployed Worker from your `.dev.vars` file. -In the `agent.js` file, you can define your agent's capabilities by implementing the `handleEvent` method. This method will be called whenever the agent receives an event from Slack. +## Step 7: Test the agent -### Implement the agent's logic +Make sure that the app is installed in your workspace. Add the app to a channel or a direct message and mention the app. The app should respond with a message. -Inside the `handleEvent` method, you can implement your agent's logic to process the event and take appropriate actions. For example, you can send a message to Slack, update a database, or call an external API. +The Slackbot will respond in the message thread. If you ask a follow-up question in the same thread, you will notice that the Slackbot doesn't provide the expected answer. This is because it doesn't have the context of the previous conversation. You will need to store the messages of each thread in the state of the agent. -## Connecting to Slack +## Step 8: Store the messages in Agent's state -### Integrate the agent with your Slack app +For your user to be able to ask follow-up questions, your agent needs the context of the previous conversation. You will need to store the messages of each thread in the state of the agent. -To integrate your agent with your Slack app, you need to create a new Cloudflare Worker and configure it to use your Slack app token and bot token. +To store the messages in the state of the agent, you will need to modify the `index.ts` file. -### Handle Slack events +```ts {1,5, 7-12,21-29,38,49-55} +import { tool, generateText, type Message, appendResponseMessages } from 'ai'; +... -The Cloudflare Agents SDK provides a `handleEvent` method that you can use to handle Slack events. This method will be called whenever your agent receives an event from Slack. +// Add Message[] as the second generic parameter to Agent +export class KnowledgeBaseAgent extends Agent { -### Send messages to Slack + async onStart(): Promise { + // Initialize state as an empty array if it doesn't exist + if (!this.state) { + this.setState([]); + } + } -You can send messages to Slack using the Slack API. The Cloudflare Agents SDK provides a `slack` object that you can use to interact with the Slack API. + async callAi(userText: string) { + // Make sure we have text to process + if (!userText) { + console.log('No text in message, skipping'); + return "I couldn't understand that message. Could you please rephrase?"; + } -## Advanced features (Optional) + // Append user message to history + this.setState([ + ...(Array.isArray(this.state) ? this.state : []), + { + id: crypto.randomUUID(), + role: 'user', + content: userText, + }, + ]); + + const openai = createOpenAI({ apiKey: env.OPENAI_API_KEY }); + // Generate context-aware response + const { text, response } = await generateText({ + model: openai('gpt-4o'), + system: `You are a Slackbot Support Assistant. You help users with their questions and issues. You have access to tools that retrieve information from the knowledge base. + Keep your responses concise and to the point. + `, + messages: Array.isArray(this.state) ? this.state : [], + tools: { + KnowledgeBaseTool, + }, + maxSteps: 2, + }); + + const formattedResponse = text + ? text.replace(/\[(.*?)\]\((.*?)\)/g, '<$2|$1>').replace(/\*\*/g, '*') + : "I'm sorry, I couldn't generate a response."; + + // Add assistant response to history + this.setState( + appendResponseMessages({ + messages: Array.isArray(this.state) ? this.state : [], + responseMessages: response.messages, + }) + ); + + // Format the response for Slack + return formattedResponse; + } -### Using environment variables + ... -You can use environment variables to store sensitive information, such as API keys and tokens. This allows you to keep your code secure and avoid hardcoding sensitive information in your code. +} +``` -### Logging and monitoring +The above code does the following: -You can use logging and monitoring to track the performance of your agent and identify any issues. The Cloudflare Agents SDK provides a `logger` object that you can use to log messages. +1. Imports the `Message` type from the AI SDK +2. Adds `Message[]` as the second generic parameter to `Agent`. This defines the type of the state of the agent. +3. Initializes the state as an empty array if it doesn't exist +4. Appends the user message to the state +5. Calls the LLM by passing the state as the messages for context +6. Appends the assistant response to the state. -### Error handling +Save and deploy the worker. The agent should now be able to maintain the conversation context. -You can use error handling to gracefully handle errors that may occur in your agent. The Cloudflare Agents SDK provides an `errorHandler` object that you can use to handle errors. +## Summary -## Deployment +In this tutorial, you have created an AI-powered Slackbot. The bot can answer user's questions, using the content embeded with [AutoRAG](/autorag). You have used the Agents SDK to create the agent. The agent has a state that stores the messages of each thread. This allows the agent to maintain the conversation context. -### Deploy your agent to Cloudflare Workers +You can now use the agent to answer user's questions in your Slack app. -1. Create a new Cloudflare Worker. -2. Copy the code from your `agent.js` file to the Worker. -3. Set the `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` environment variables in the Worker settings. -4. Deploy the Worker. +You can extend this tutorial to build agents for incident response, customer support, or any other use-case that requires an AI agent. You can add more tools to the agent to retrieve information from different sources, or you can use different LLMs to generate responses. -### Test your agent in Slack +The Agents SDK provides a lot of features that you can use to build AI agents. You can find more information about the Agents SDK in the [Agents API Reference](/agents/api-reference/). -1. Invite your Slack app to a channel in your Slack workspace. -2. Send a message to the channel that mentions your app. -3. Verify that your agent receives the event and responds appropriately. +If you are looking for the complete source code for this tutorial, you can find it in the [GitHub repository](https://github.com/harshil1712/slack-cf-autorag-agent). \ No newline at end of file From 262c0ba804986c93114dcd877a99b75aa356056d Mon Sep 17 00:00:00 2001 From: Harshil Agrawal Date: Tue, 3 Jun 2025 14:58:29 +0200 Subject: [PATCH 3/4] minor improvements --- .../slackbot-knowledgebase/index.mdx | 36 ++++++++++--------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx b/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx index 2a9f00b780c53e..adccc4bbe74c1c 100644 --- a/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx +++ b/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx @@ -22,7 +22,9 @@ import { In this tutorial, you will create an AI-powered Slackbot. The bot will answer user's questions, using the content embeded with [AutoRAG](/autorag). You will use the Agents SDK to create the agent. -For each new thread, you will have a new instance of the agent. You will also store the messages of each thread in the state of the agent. This will allow you to maintain the conversation context. +For each new thread, you will have a new instance of the agent. You will also store the messages of each thread in the state of the agent. This will allow you to maintain the conversation context. If a user asks a follow-up question, the agent will have access to the previous messages and can provide a more accurate response. + +Using the Agents SDK, you don't need to implement the state management logic. The SDK provide you with the necessary tools to manage the state seamlessly. You also don't need an external database to store the messages, as they are stored in the persistent storage of the agent. While this tutorial focuses on building a Slackbot, the same principles can be applied to any use-case that requires an AI-powered agent. You can even extend this tutorial to build agents for incident response, customer support, or any other use-case that requires an AI-powered agent. @@ -50,7 +52,7 @@ Create a new Workers project by running the following command: }} /> -You will need to install the [Cloudflare Agents SDK](), [AI SDK](), OpenAI provider for AI SDK, [zod](), the [Slack Web API package](). +You will need to install the [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/), [AI SDK](https://www.npmjs.com/package/ai), OpenAI provider for AI SDK, [zod](https://www.npmjs.com/package/zod), the [Slack Web API package](https://www.npmjs.com/package/@slack/web-api). @@ -58,12 +60,14 @@ Your project is now set up. You can start building your agent! ## Step 2: Handle Slack events -The worker will receive events from Slack. You will need to handle these events and process them accordingly. Slack sends two types of events: +Based on the Slack events you subscribe to, the Worker will receive events from Slack. You will need to handle these events and process them accordingly. Slack sends two types of events: - `url_verification`: To verify the request is from Slack. - `event_callback`: Event callback for the events you subscribe to. -You will need to handle both of the events. The `url_verification` event can be handled by our worker and doesn't need to be processed by the agent. The `event_callback` event will be processed by the agent. +You will need to handle both of these events. The `url_verification` event can be handled by our Worker. This event is used to verify the request is from Slack and doesn't need AI capabilities to be processed by the agent. + +The `event_callback` event will be processed by the agent. This event contains the actual events you subscribed to. It will provide the event data that will be used by the agent to generate responses. To handle the `url_verification` event, you will need to: @@ -275,6 +279,12 @@ new_sqlite_classes = ["KnowledgeBaseAgent"] ``` +You will also need to add the OpenAI API key to the `.dev.vars` file. You can get the API key from [https://platform.openai.com/account/api-keys](https://platform.openai.com/account/api-keys). + +```text title=".dev.vars" +OPENAI_API_KEY=sk-1234567890 +``` + You now have a Slackbot that can answer user's questions. To make sure it uses the knowledge base, you will need to add the knowledge base tool to the AI model. ## Step 4: Create the knowledge base tool @@ -346,7 +356,7 @@ To create a Slack app, follow these steps: :::note -You will need to add a URL in the `Request URL` field in the `Event Subscriptions` page. This URL will be used to receive events from Slack. You will add this URL after deploying the worker. +You will need to add a URL in the `Request URL` field in the `Event Subscriptions` page. This URL will be used to receive events from Slack. You will add this URL after deploying the Worker. ::: @@ -356,19 +366,13 @@ You will need to add a URL in the `Request URL` field in the `Event Subscription SLACK_BOT_TOKEN=xoxb-1234567890-1234567890-1234567890 ``` -You will also need to add the OpenAI API key to the `.dev.vars` file. You can get the API key from [https://platform.openai.com/account/api-keys](https://platform.openai.com/account/api-keys). - -```text title=".dev.vars" -OPENAI_API_KEY=sk-1234567890 -``` - -## Step 6: Deploy the worker +## Step 6: Deploy the Worker -Your Slack app is now ready to receive events from Slack. You will need to deploy the agent to Cloudflare Workers. Slack will send events to the worker, and the worker will process the events and send responses to Slack. +Your Slack app is now ready to receive events from Slack. You will need to deploy the agent to Cloudflare Workers. Slack will send events to the Worker, and the Worker will process the events and send responses to Slack. :::note -Application running on `localhost` will not receive events from Slack. You will need to deploy the worker to Cloudflare Workers. Alternatively, you can use a reverse proxy to forward events from Slack to your application running on `localhost` using [Cloudflare Tunnels](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/). +Application running on `localhost` will not receive events from Slack. You will need to deploy the Worker to Cloudflare Workers. Alternatively, you can use a reverse proxy to forward events from Slack to your application running on `localhost` using [Cloudflare Tunnels](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/). ::: @@ -378,7 +382,7 @@ To deploy, execut the following command: npm run deploy ``` -The output returns the URL of the deployed worker. Copy the URL and add it to the `Request URL` field in the `Event Subscriptions` page of your Slack app. Click on `Save Changes` to save the URL. +The output returns the URL of the deployed Worker. Copy the URL and add it to the `Request URL` field in the `Event Subscriptions` page of your Slack app. Click on `Save Changes` to save the URL. Next, add the credentials for your deployed Worker. Run the following command to do so: @@ -475,7 +479,7 @@ The above code does the following: 5. Calls the LLM by passing the state as the messages for context 6. Appends the assistant response to the state. -Save and deploy the worker. The agent should now be able to maintain the conversation context. +Save and deploy the Worker. The agent should now be able to maintain the conversation context. ## Summary From 6e666818d7d958a643c19132dcb72915e9b08cbf Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Tue, 12 Aug 2025 15:42:12 +0100 Subject: [PATCH 4/4] Fixing broken link --- .../docs/agents/tutorials/slackbot-knowledgebase/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx b/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx index adccc4bbe74c1c..306e858637c81b 100644 --- a/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx +++ b/src/content/docs/agents/tutorials/slackbot-knowledgebase/index.mdx @@ -65,7 +65,7 @@ Based on the Slack events you subscribe to, the Worker will receive events from - `url_verification`: To verify the request is from Slack. - `event_callback`: Event callback for the events you subscribe to. -You will need to handle both of these events. The `url_verification` event can be handled by our Worker. This event is used to verify the request is from Slack and doesn't need AI capabilities to be processed by the agent. +You will need to handle both of these events. The `url_verification` event can be handled by our Worker. This event is used to verify the request is from Slack and doesn't need AI capabilities to be processed by the agent. The `event_callback` event will be processed by the agent. This event contains the actual events you subscribed to. It will provide the event data that will be used by the agent to generate responses. @@ -289,7 +289,7 @@ You now have a Slackbot that can answer user's questions. To make sure it uses t ## Step 4: Create the knowledge base tool -To make sure your users get the best answers, you will need to add the knowledge base tool to the AI model. The KnowledgeBaseTool is a tool that uses AutoRAG to retrieve information. You will need to create and configure a new AutoRAG instance. You can follow the [AutoRAG getting started](/autorag/tutorials/quick-start) to create and configure a new AutoRAG instance. +To make sure your users get the best answers, you will need to add the knowledge base tool to the AI model. The KnowledgeBaseTool is a tool that uses AutoRAG to retrieve information. You will need to create and configure a new AutoRAG instance. You can follow the [AutoRAG getting started](/autorag/get-started/) to create and configure a new AutoRAG instance. Once you have created and configured the AutoRAG instance, you will need to create the knowledge base tool. The knowledge base tool will be used to retrieve information from the knowledge base. You will use AI bindings to use AutoRAG. In your `wrangler` configuration file, add the following binding: