diff --git a/content/docs/agents/custom-code-agent/concepts.mdx b/content/docs/agents/custom-code-agent/concepts.mdx index db084cc26..bf353578a 100644 --- a/content/docs/agents/custom-code-agent/concepts.mdx +++ b/content/docs/agents/custom-code-agent/concepts.mdx @@ -128,7 +128,7 @@ The same handler code works on every connected provider; adding a provider does } href="/agents/custom-code-agent/quickstart" title="Quickstart"> Create an agent, connect Slack, and get a reply in-thread. - } href="/agents/custom-code-agent/build-your-first-agent" title="Build your first agent"> + } href="/agents/custom-code-agent/connect-your-first-agent" title="Connect your first agent"> Walk through a full support-bot handler file. diff --git a/content/docs/agents/custom-code-agent/build-your-first-agent.mdx b/content/docs/agents/custom-code-agent/connect-your-first-agent.mdx similarity index 67% rename from content/docs/agents/custom-code-agent/build-your-first-agent.mdx rename to content/docs/agents/custom-code-agent/connect-your-first-agent.mdx index 92c9b0d8a..f133353c1 100644 --- a/content/docs/agents/custom-code-agent/build-your-first-agent.mdx +++ b/content/docs/agents/custom-code-agent/connect-your-first-agent.mdx @@ -1,22 +1,22 @@ --- -title: "Build your first Agent" -pageTitle: 'Tutorial: Build your first Agent' -description: 'Build a Pipelinr support agent with handlers, cards, metadata, an LLM, and conversation resolution.' +title: "Connect your first agent" +pageTitle: 'Tutorial: Connect your first agent' +description: 'Build a Pipeliner support agent with handlers, cards, metadata, an LLM, and conversation resolution.' icon: Sparkles --- import { Steps, Step } from 'fumadocs-ui/components/steps'; import { Brain, ThumbsUp, Mail, LayoutGrid, Rocket } from 'lucide-react'; -Once you've scaffolded an agent, the next question is usually: *What do I actually put in this file?* +This is the fastest path from nothing to a working agent. You create the agent in Novu, scaffold a bridge app, and write the handler code that powers a small support bot, all in one sitting. -This walkthrough builds a small support bot for a fake product called Pipelinr. You add one piece at a time in `support-agent.tsx` until the bot greets users, routes by topic, answers with an LLM, and resolves the thread when the user is done. +The bot is for a fake product called Pipeliner. You add one piece at a time in `support-agent.tsx` until the bot greets users, routes by topic, answers with an LLM, and resolves the thread when the user is done. -For API reference, see [Handle events](/agents/custom-code-agent/setup-your-agent/handle-events), [Reply](/agents/custom-code-agent/setup-your-agent/reply), and [Signals](/agents/custom-code-agent/setup-your-agent/signals). +This page keeps each setup step to the minimum you need to get going. For the full reference on any step, follow the linked pages under [Set up your agent](/agents/custom-code-agent/setup-your-agent/overview). ## What you're building -In this tutorial, you build a Pipelinr support bot that: +In this tutorial, you build a Pipeliner support bot that: - Greets the user and asks whether their issue is a **Billing** question, a **Technical** issue, or **Something else** - Stores the user's choice and answers follow-up questions with an LLM @@ -24,6 +24,62 @@ In this tutorial, you build a Pipelinr support bot that: That flow covers `onMessage`, `onAction`, metadata, LLM replies, and `ctx.resolve()`. +## Before you start + +You need: + +- A [Novu account](https://dashboard.novu.co). +- Node.js 18+ installed. +- A chat provider you can connect. This tutorial uses Slack. + +## Set up the project + +These three steps get you from an empty folder to a running agent. Each one links to a more detailed page if you want the full walkthrough. + + + + +### Create the agent and connect a provider + +In the Novu dashboard, open **Agents** and click **Create agent**. Set the **Identifier** to `support-agent`, since that value must match the agent id you use in code. + +On the guided setup page, open **Select provider**, choose **Slack**, and follow the prompts to create and install the Slack app. When it finishes, you get a welcome message from the agent in Slack. + +For the full provider flow (Slack tokens, install, permissions), see the [Quickstart](/agents/custom-code-agent/quickstart) and [Create an agent](/agents/custom-code-agent/setup-your-agent/create-an-agent). + + + + +### Scaffold the bridge app + +The bridge app is the project that receives events from Novu and runs your handler code. Copy the pre-filled command from the agent setup page, or run: + +```bash +npx novu@latest init -t agent \ + --agent-identifier support-agent \ + --secret-key \ + --api-url +``` + +Run it in the directory where you want the project. The CLI generates a Next.js app with a starter agent. For details, see [Scaffold your project](/agents/custom-code-agent/setup-your-agent/scaffold-your-project). + + + + +### Run it locally + +On the agent detail page, set the bridge to **Local**. Then, from the project directory, start the app: + +```bash +npm run dev:novu +``` + +This starts your app, opens a dev tunnel, and registers the bridge URL with Novu. When it connects, you get another message from your agent in Slack. Leave this running, it hot-reloads as you edit the handler in the next section. + + + + + ## Where the code goes The scaffold creates a Next.js bridge app. All tutorial code goes in `app/novu/agents/support-agent.tsx`: @@ -36,18 +92,18 @@ app/ support-agent.tsx # agent handlers you edit in this tutorial ``` -The scaffold also adds `app/api/novu/route.ts`, which exposes your agents over HTTP. You do not need to change that file for this tutorial. +The scaffold also adds `app/api/novu/route.ts`, which exposes your agents over HTTP. You do not need to change that file for this tutorial. Make sure `index.ts` re-exports your agent so the route picks it up; the scaffold wires this up for the starter agent already. Everything below happens inside `support-agent.tsx`. ## Build the agent -Follow the steps below to add handlers, cards, metadata, an LLM, and conversation resolution to `support-agent.tsx`. +Follow the steps below to add handlers, cards, metadata, an LLM, and conversation resolution to `support-agent.tsx`. For the API reference behind each step, see [Handle events](/agents/custom-code-agent/setup-your-agent/handle-events), [Reply](/agents/custom-code-agent/setup-your-agent/reply), and [Signals](/agents/custom-code-agent/setup-your-agent/signals). -### Step 1: Define the agent shell +### Define the agent shell Start with the bare minimum: an `agent()` call with an id and an `onMessage` handler. The agent id (`support-agent`) must match the identifier you set in the Novu dashboard. @@ -71,7 +127,7 @@ At this point the agent echoes messages back. In the next step, replace that beh -### Step 2: Handle the first message +### Handle the first message Replace the echo handler with a welcome card. On the first message, the bot introduces itself and asks the user to pick a topic. @@ -87,7 +143,7 @@ export const supportAgent = agent('support-agent', { if (isFirstMessage) { return ( - + What can I help you with today?