From 9216c510234b5de20f4d71eb495768933675f697 Mon Sep 17 00:00:00 2001 From: Pawan Jain Date: Tue, 5 May 2026 23:33:44 +0530 Subject: [PATCH 1/5] feat: initialized agents docs --- content/docs/agents/add-connect-components.mdx | 5 +++++ content/docs/agents/core-concepts.mdx | 5 +++++ content/docs/agents/deploy-your-agent.mdx | 5 +++++ content/docs/agents/index.mdx | 5 +++++ content/docs/agents/manage-conversations.mdx | 5 +++++ content/docs/agents/meta.json | 15 +++++++++++++++ content/docs/agents/quickstart.mdx | 5 +++++ content/docs/agents/receive-inbound-email.mdx | 5 +++++ .../agents/setup-your-agent/connect-providers.mdx | 5 +++++ .../connect-your-code/handle-events.mdx | 5 +++++ .../setup-your-agent/connect-your-code/index.mdx | 5 +++++ .../setup-your-agent/connect-your-code/meta.json | 6 ++++++ .../connect-your-code/reply-types.mdx | 5 +++++ .../connect-your-code/use-signals.mdx | 5 +++++ content/docs/agents/setup-your-agent/index.mdx | 5 +++++ content/docs/agents/setup-your-agent/meta.json | 6 ++++++ content/docs/meta.json | 2 +- src/app/layout.config.tsx | 6 ++++++ src/app/llms.txt/route.ts | 1 + src/middleware.ts | 9 ++++++++- 20 files changed, 108 insertions(+), 2 deletions(-) create mode 100644 content/docs/agents/add-connect-components.mdx create mode 100644 content/docs/agents/core-concepts.mdx create mode 100644 content/docs/agents/deploy-your-agent.mdx create mode 100644 content/docs/agents/index.mdx create mode 100644 content/docs/agents/manage-conversations.mdx create mode 100644 content/docs/agents/meta.json create mode 100644 content/docs/agents/quickstart.mdx create mode 100644 content/docs/agents/receive-inbound-email.mdx create mode 100644 content/docs/agents/setup-your-agent/connect-providers.mdx create mode 100644 content/docs/agents/setup-your-agent/connect-your-code/handle-events.mdx create mode 100644 content/docs/agents/setup-your-agent/connect-your-code/index.mdx create mode 100644 content/docs/agents/setup-your-agent/connect-your-code/meta.json create mode 100644 content/docs/agents/setup-your-agent/connect-your-code/reply-types.mdx create mode 100644 content/docs/agents/setup-your-agent/connect-your-code/use-signals.mdx create mode 100644 content/docs/agents/setup-your-agent/index.mdx create mode 100644 content/docs/agents/setup-your-agent/meta.json diff --git a/content/docs/agents/add-connect-components.mdx b/content/docs/agents/add-connect-components.mdx new file mode 100644 index 000000000..2ac0c6c76 --- /dev/null +++ b/content/docs/agents/add-connect-components.mdx @@ -0,0 +1,5 @@ +--- +title: "Add Connect Components" +pageTitle: 'Novu Agents Add Connect Components' +description: 'Add Connect UI components so users can link accounts and channels to your agent.' +--- diff --git a/content/docs/agents/core-concepts.mdx b/content/docs/agents/core-concepts.mdx new file mode 100644 index 000000000..6c56fb4fd --- /dev/null +++ b/content/docs/agents/core-concepts.mdx @@ -0,0 +1,5 @@ +--- +title: "Core Concepts" +pageTitle: 'Novu Agents Core Concepts' +description: 'Learn the core concepts of Novu Agents' +--- diff --git a/content/docs/agents/deploy-your-agent.mdx b/content/docs/agents/deploy-your-agent.mdx new file mode 100644 index 000000000..52daeec2b --- /dev/null +++ b/content/docs/agents/deploy-your-agent.mdx @@ -0,0 +1,5 @@ +--- +title: "Deploy Your Agent" +pageTitle: 'Novu Agents Deployment' +description: 'Deploy your Novu Agent to production environments.' +--- diff --git a/content/docs/agents/index.mdx b/content/docs/agents/index.mdx new file mode 100644 index 000000000..81f240627 --- /dev/null +++ b/content/docs/agents/index.mdx @@ -0,0 +1,5 @@ +--- +title: "Overview" +pageTitle: 'Novu Agents Overview' +description: 'Explore Novu Agents: conversational agents built on Novu.' +--- \ No newline at end of file diff --git a/content/docs/agents/manage-conversations.mdx b/content/docs/agents/manage-conversations.mdx new file mode 100644 index 000000000..7fab69c81 --- /dev/null +++ b/content/docs/agents/manage-conversations.mdx @@ -0,0 +1,5 @@ +--- +title: "Manage Conversations" +pageTitle: 'Novu Agents Manage Conversations' +description: 'Manage agent conversations, history, and lifecycle in Novu.' +--- diff --git a/content/docs/agents/meta.json b/content/docs/agents/meta.json new file mode 100644 index 000000000..c3b1a4d00 --- /dev/null +++ b/content/docs/agents/meta.json @@ -0,0 +1,15 @@ +{ + "root": true, + "title": "Agents", + "description": "Agents", + "pages": [ + "index", + "quickstart", + "core-concepts", + "setup-your-agent", + "manage-conversations", + "deploy-your-agent", + "add-connect-components", + "receive-inbound-email" + ] +} diff --git a/content/docs/agents/quickstart.mdx b/content/docs/agents/quickstart.mdx new file mode 100644 index 000000000..5b5864502 --- /dev/null +++ b/content/docs/agents/quickstart.mdx @@ -0,0 +1,5 @@ +--- +title: "Quickstart" +pageTitle: 'Novu Agents Quickstart' +description: 'Get started with Novu Agents' +--- diff --git a/content/docs/agents/receive-inbound-email.mdx b/content/docs/agents/receive-inbound-email.mdx new file mode 100644 index 000000000..60510cb08 --- /dev/null +++ b/content/docs/agents/receive-inbound-email.mdx @@ -0,0 +1,5 @@ +--- +title: "Receive Inbound Email" +pageTitle: 'Novu Agents Inbound Email' +description: 'Receive and process inbound email with your Novu Agent.' +--- diff --git a/content/docs/agents/setup-your-agent/connect-providers.mdx b/content/docs/agents/setup-your-agent/connect-providers.mdx new file mode 100644 index 000000000..4de85069b --- /dev/null +++ b/content/docs/agents/setup-your-agent/connect-providers.mdx @@ -0,0 +1,5 @@ +--- +title: "Connect Providers" +pageTitle: 'Novu Agents Connect Providers' +description: 'Connect channels and third-party providers to your Novu Agent.' +--- diff --git a/content/docs/agents/setup-your-agent/connect-your-code/handle-events.mdx b/content/docs/agents/setup-your-agent/connect-your-code/handle-events.mdx new file mode 100644 index 000000000..2138a3230 --- /dev/null +++ b/content/docs/agents/setup-your-agent/connect-your-code/handle-events.mdx @@ -0,0 +1,5 @@ +--- +title: "Handle Events" +pageTitle: 'Novu Agents Handle Events' +description: 'Handle agent events in your webhooks, handlers, and backend services.' +--- diff --git a/content/docs/agents/setup-your-agent/connect-your-code/index.mdx b/content/docs/agents/setup-your-agent/connect-your-code/index.mdx new file mode 100644 index 000000000..f3191b47a --- /dev/null +++ b/content/docs/agents/setup-your-agent/connect-your-code/index.mdx @@ -0,0 +1,5 @@ +--- +title: "Connect Your Code" +pageTitle: 'Novu Agents Connect Your Code' +description: 'Integrate your codebase with Novu Agents using events, replies, and signals.' +--- diff --git a/content/docs/agents/setup-your-agent/connect-your-code/meta.json b/content/docs/agents/setup-your-agent/connect-your-code/meta.json new file mode 100644 index 000000000..d807d526f --- /dev/null +++ b/content/docs/agents/setup-your-agent/connect-your-code/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Connect Your Code", + "description": "Connect Your Code", + "defaultOpen": true, + "pages": ["index", "handle-events", "reply-types", "use-signals"] +} diff --git a/content/docs/agents/setup-your-agent/connect-your-code/reply-types.mdx b/content/docs/agents/setup-your-agent/connect-your-code/reply-types.mdx new file mode 100644 index 000000000..c47590dad --- /dev/null +++ b/content/docs/agents/setup-your-agent/connect-your-code/reply-types.mdx @@ -0,0 +1,5 @@ +--- +title: "Reply Types" +pageTitle: 'Novu Agents Reply Types' +description: 'Choose and send the right reply types from your agent handlers.' +--- diff --git a/content/docs/agents/setup-your-agent/connect-your-code/use-signals.mdx b/content/docs/agents/setup-your-agent/connect-your-code/use-signals.mdx new file mode 100644 index 000000000..461bf02d8 --- /dev/null +++ b/content/docs/agents/setup-your-agent/connect-your-code/use-signals.mdx @@ -0,0 +1,5 @@ +--- +title: "Use Signals" +pageTitle: 'Novu Agents Use Signals' +description: 'Use signals to coordinate state and behavior across your agent integration.' +--- diff --git a/content/docs/agents/setup-your-agent/index.mdx b/content/docs/agents/setup-your-agent/index.mdx new file mode 100644 index 000000000..938f79041 --- /dev/null +++ b/content/docs/agents/setup-your-agent/index.mdx @@ -0,0 +1,5 @@ +--- +title: "Setup Your Agent" +pageTitle: 'Novu Agents Setup Your Agent' +description: 'Set up your Novu Agent: connect providers and wire up your application code.' +--- diff --git a/content/docs/agents/setup-your-agent/meta.json b/content/docs/agents/setup-your-agent/meta.json new file mode 100644 index 000000000..864012bc9 --- /dev/null +++ b/content/docs/agents/setup-your-agent/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Setup Your Agent", + "description": "Setup Your Agent", + "defaultOpen": true, + "pages": ["index", "connect-providers", "connect-your-code"] +} diff --git a/content/docs/meta.json b/content/docs/meta.json index 9b8b82658..7be3772a6 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1,3 +1,3 @@ { - "pages": ["platform", "guides", "framework", "community", "api-reference"] + "pages": ["platform", "agents", "guides", "framework", "community", "api-reference"] } diff --git a/src/app/layout.config.tsx b/src/app/layout.config.tsx index 182a25265..78d109c71 100644 --- a/src/app/layout.config.tsx +++ b/src/app/layout.config.tsx @@ -44,6 +44,12 @@ export const baseOptions: BaseLayoutProps = { text: 'Platform', active: 'nested-url', }, + { + url: '/agents', + type: 'button', + text: 'Agents', + active: 'nested-url', + }, { url: '/guides', type: 'button', diff --git a/src/app/llms.txt/route.ts b/src/app/llms.txt/route.ts index 53401bae4..141d0e89e 100644 --- a/src/app/llms.txt/route.ts +++ b/src/app/llms.txt/route.ts @@ -9,6 +9,7 @@ const SECTION_LABELS: Record = { community: 'Community', 'api-reference': 'API Reference', guides: 'Guides', + agents: 'Agents', }; export function GET() { diff --git a/src/middleware.ts b/src/middleware.ts index 952931802..88da1d9a7 100644 --- a/src/middleware.ts +++ b/src/middleware.ts @@ -16,7 +16,14 @@ export const config = { ], }; -const MARKDOWN_SECTIONS = ['/platform', '/framework', '/community', '/api-reference', '/guides']; +const MARKDOWN_SECTIONS = [ + '/platform', + '/agents', + '/framework', + '/community', + '/api-reference', + '/guides', +]; function isDocPage(pathname: string): boolean { return MARKDOWN_SECTIONS.some( From 8bc6411f17025f22d71a5b2ca47c8ba1ed45f10c Mon Sep 17 00:00:00 2001 From: Victor Yakubu <57350321+Aviatorscode2@users.noreply.github.com> Date: Wed, 6 May 2026 21:41:12 +0100 Subject: [PATCH 2/5] Setup the get started structure (#1079) --- content/docs/agents/{ => get-started}/core-concepts.mdx | 1 + content/docs/agents/get-started/meta.json | 3 +++ content/docs/agents/{ => get-started}/quickstart.mdx | 1 + content/docs/agents/get-started/what-is-aci.mdx | 6 ++++++ content/docs/agents/meta.json | 7 ++++--- 5 files changed, 15 insertions(+), 3 deletions(-) rename content/docs/agents/{ => get-started}/core-concepts.mdx (90%) create mode 100644 content/docs/agents/get-started/meta.json rename content/docs/agents/{ => get-started}/quickstart.mdx (91%) create mode 100644 content/docs/agents/get-started/what-is-aci.mdx diff --git a/content/docs/agents/core-concepts.mdx b/content/docs/agents/get-started/core-concepts.mdx similarity index 90% rename from content/docs/agents/core-concepts.mdx rename to content/docs/agents/get-started/core-concepts.mdx index 6c56fb4fd..800f66b3e 100644 --- a/content/docs/agents/core-concepts.mdx +++ b/content/docs/agents/get-started/core-concepts.mdx @@ -2,4 +2,5 @@ title: "Core Concepts" pageTitle: 'Novu Agents Core Concepts' description: 'Learn the core concepts of Novu Agents' +icon: Blocks --- diff --git a/content/docs/agents/get-started/meta.json b/content/docs/agents/get-started/meta.json new file mode 100644 index 000000000..3470899ed --- /dev/null +++ b/content/docs/agents/get-started/meta.json @@ -0,0 +1,3 @@ +{ + "pages": ["what-is-aci", "core-concepts", "quickstart"] +} diff --git a/content/docs/agents/quickstart.mdx b/content/docs/agents/get-started/quickstart.mdx similarity index 91% rename from content/docs/agents/quickstart.mdx rename to content/docs/agents/get-started/quickstart.mdx index 5b5864502..56e8a07e0 100644 --- a/content/docs/agents/quickstart.mdx +++ b/content/docs/agents/get-started/quickstart.mdx @@ -2,4 +2,5 @@ title: "Quickstart" pageTitle: 'Novu Agents Quickstart' description: 'Get started with Novu Agents' +icon: Zap --- diff --git a/content/docs/agents/get-started/what-is-aci.mdx b/content/docs/agents/get-started/what-is-aci.mdx new file mode 100644 index 000000000..ade9b85ff --- /dev/null +++ b/content/docs/agents/get-started/what-is-aci.mdx @@ -0,0 +1,6 @@ +--- +title: "What is ACI?" +pageTitle: 'What is ACI?' +description: 'An introduction to Novu Agents and Agent-Customer Interaction (ACI).' +icon: CircleHelp +--- diff --git a/content/docs/agents/meta.json b/content/docs/agents/meta.json index c3b1a4d00..277efd266 100644 --- a/content/docs/agents/meta.json +++ b/content/docs/agents/meta.json @@ -3,9 +3,10 @@ "title": "Agents", "description": "Agents", "pages": [ - "index", - "quickstart", - "core-concepts", + "---Get Started---", + "get-started/what-is-aci", + "get-started/core-concepts", + "get-started/quickstart", "setup-your-agent", "manage-conversations", "deploy-your-agent", From 6f8cfba8d2abbf0921a471ac4baf9f9241446d73 Mon Sep 17 00:00:00 2001 From: Victor Yakubu <57350321+Aviatorscode2@users.noreply.github.com> Date: Thu, 7 May 2026 21:32:22 +0100 Subject: [PATCH 3/5] Initial content draft for the what is ACI page (#1080) * Initial content draft for the what is ACI page * Update content/docs/agents/get-started/what-is-aci.mdx Co-authored-by: DianaHackmamba * Update content/docs/agents/get-started/what-is-aci.mdx Co-authored-by: DianaHackmamba --------- Co-authored-by: DianaHackmamba --- .../docs/agents/get-started/what-is-aci.mdx | 114 +++++++++++++++++- 1 file changed, 112 insertions(+), 2 deletions(-) diff --git a/content/docs/agents/get-started/what-is-aci.mdx b/content/docs/agents/get-started/what-is-aci.mdx index ade9b85ff..4afb5df4d 100644 --- a/content/docs/agents/get-started/what-is-aci.mdx +++ b/content/docs/agents/get-started/what-is-aci.mdx @@ -1,6 +1,116 @@ --- title: "What is ACI?" -pageTitle: 'What is ACI?' -description: 'An introduction to Novu Agents and Agent-Customer Interaction (ACI).' +pageTitle: 'What is Agent Communication Infrastructure (ACI)?' +description: 'Learn what ACI is, what it solves, and how it helps agents communicate across channels.' icon: CircleHelp --- + +import { BookText, HomeIcon } from 'lucide-react'; + +Agent Communication Infrastructure (ACI) is a protocol-driven infrastructure layer for enabling structured, stateful communication between autonomous agents and your users across messaging platforms. + +ACI sits between messaging platforms and your agent logic. Instead of building separate integrations for each channel, ACI provides a unified interface for webhooks, message delivery, conversation state, and subscriber identity. + +The agent itself can be powered by an LLM, custom code, a rules engine, a human-in-the-loop workflow, or a combination of systems. ACI doesn't define the agent’s intelligence. It defines the communication infrastructure around it. + +## What does ACI solve? + +Software is becoming more conversational. Users no longer only click through interfaces or receive one-way notifications. They ask questions, reply to messages, clarify requests, approve actions, send files, react with emojis, and expect software to continue the conversation in channels where they already are. + +At the same time, agents are becoming more capable. And most teams already have agents that answers users questions, analyze information, trigger workflows, escalate issues, and coordinate with other systems. + +In most cases, these agents only work inside one platform, getting these agents into a different platform requires rebuilding the communication layer from scratch. + +This creates an infrastructure problem where each channel has its own webhook format, identity model, threading behavior, permissions, message formatting, interaction patterns, and delivery constraints. Teams that want to expose an agent across Slack, Microsoft Teams, WhatsApp, email, or other channels often end up rebuilding the same communication plumbing for every channel. + +ACI exists to standardize that layer. It separates the communication layer from the agent logic, so teams can connect agents to different messaging platforms without hand-building every channel integration from scratch. + +You build your agent once. ACI handles delivery everywhere. The goal isn't only to send messages but to let agents hold useful conversations across channels while preserving context, control, and visibility. + +## How ACI works + +ACI introduces a three-part architecture that separates platform delivery from agent intelligence. + +### Communication channels + +Communication channels are the places where users interact with the agent, such as Slack, Microsoft Teams, WhatsApp, Telegram, and more. When a user sends a message on any of these platforms, it enters the ACI layer. + +### Bridge + +The bridge is the infrastructure layer in the middle. It receives the platform webhook, normalizes the message into a standard format, and resolves the user's identity. + +It creates or loads the conversation with its full history, and forwards everything to your server as a single context object. + +When your agent replies, the bridge delivers the response back to the correct platform thread, persists it in the conversation history, and records the activity. Your server never talks to the platform directly. + +### Agent brain + +The agent brain is your code. Your server receives the context object and processes it however you decide. Call an LLM, run business logic, route to a human, or combine all three. + +The brain is entirely yours. The agent can be an AI, a human, a human assisted by AI, or anything else. There's no limitation on what the brain can be. + +The channel-agnostic nature of this architecture means that when you connect a new provider, your agent implementation doesn't change. Not a single line of code. The same brain that responds on Slack will respond on Microsoft Teams, WhatsApp, or email without modification. + +## What ACI handles vs. what you control + +ACI draws a clear boundary between infrastructure and intelligence. + +**The infrastructure handles:** +* Webhook ingestion and message normalization across all connected platforms. +* Message delivery to the correct platform thread. +* Conversation persistence and state management. +* Subscriber identity resolution, matching platform users to a unified identity. +* Typing indicators and platform-specific formatting. +* Conversation context and history, passed to your agent on every message. + +**You control:** +* Your LLM, prompts, and model configuration. +* Your tools and function calls. +* Your business logic and decision-making. +* Your API keys and credentials. +* Your choice of runtime, which can be managed agents, Vercel AI SDK, LangChain, OpenAI SDK, or any custom code of your choosing. + +ACI is opinionated about infrastructure and unopinionated about intelligence. It handles the delivery problem so you can focus on the capability problem. + +## Common use cases + +ACI is built for teams that have an agent or are building one and need to connect it to the messaging platforms where their users already are. + +Common use cases include: + +* Support agents that answer questions from Slack, Microsoft Teams, WhatsApp, or email. +* Internal operations agents that triage requests and route work. +* Conversational agents that collect information from users and continue the conversation across turns. +* File-processing agents that receive attachments and respond with analysis or follow-up actions. +* Human-in-the-loop agents that escalate complex conversations to a person. +* Workflow agents that trigger notifications, approvals, summaries, or follow-ups from within a conversation. +* Multi-channel agents that need one communication interface across several providers. + +## Start building + + + } + > + Create your first agent and connect it to Slack in under 10 minutes. + + } title="Connect your providers">Learn how to connect any provider of your choice. + } href="/" title="Connect your code"> + Learn how to connect your to the Novu + + } href="/" title="Add agent logic"> + Learn how to connect your agent brain to the agent communication layer + + + +## Learn more + + + } href="/" title="Understand concepts"> + You can include icons too. + + + + From 010da988b9e9fd32580111390732639d81cabf01 Mon Sep 17 00:00:00 2001 From: Pawan Jain Date: Fri, 8 May 2026 19:23:45 +0530 Subject: [PATCH 4/5] fix: add create agent, handlers and reply types (#1081) * fix: add create agent, handlers and reply types * fix: add manage conversations * fix: add review comments suggestions --- .cursor/skills/pre-pr-review-fixes/SKILL.md | 83 ++++++++++ content/docs/agents/manage-conversations.mdx | 45 +++++- .../setup-your-agent/connect-providers.mdx | 2 + .../connect-your-code/handle-events.mdx | 129 ++++++++++++++++ .../connect-your-code/meta.json | 2 +- .../connect-your-code/reply-types.mdx | 143 ++++++++++++++++++ .../connect-your-code/use-signals.mdx | 98 +++++++++++- .../docs/agents/setup-your-agent/index.mdx | 30 +++- .../docs/agents/setup-your-agent/meta.json | 2 +- .../manage-conversations/agent-lifecycle.png | Bin 0 -> 742906 bytes .../manage-agent-conversations.gif | Bin 0 -> 6657078 bytes .../setup-your-agent/create-a-new-agent.gif | Bin 0 -> 1945381 bytes .../handle-events/agent-conversation-flow.png | Bin 0 -> 764310 bytes .../use-signals/signal-flow.png | Bin 0 -> 575564 bytes 14 files changed, 524 insertions(+), 10 deletions(-) create mode 100644 .cursor/skills/pre-pr-review-fixes/SKILL.md create mode 100644 public/images/agents/manage-conversations/agent-lifecycle.png create mode 100644 public/images/agents/manage-conversations/manage-agent-conversations.gif create mode 100644 public/images/agents/setup-your-agent/create-a-new-agent.gif create mode 100644 public/images/agents/setup-your-agent/handle-events/agent-conversation-flow.png create mode 100644 public/images/agents/setup-your-agent/use-signals/signal-flow.png diff --git a/.cursor/skills/pre-pr-review-fixes/SKILL.md b/.cursor/skills/pre-pr-review-fixes/SKILL.md new file mode 100644 index 000000000..504c21c29 --- /dev/null +++ b/.cursor/skills/pre-pr-review-fixes/SKILL.md @@ -0,0 +1,83 @@ +--- +name: pre-pr-review-fixes +description: Fix pull request feedback before opening or updating a PR. Use when the user asks to address reviewer comments, clean up docs/style issues before PR, or apply repeated feedback patterns (wording, headings, spacing, capitalization, markdown tables, and consistency fixes). +disable-model-invocation: true +--- + +# Pre-PR Review Fixes + +Use this skill to systematically apply reviewer feedback before creating or updating a PR. + +## When to use + +- User asks to "fix PR comments" or "address review feedback" +- User asks to "prepare this for PR" or "clean this up before PR" +- Same reviewer repeatedly flags style/structure issues across multiple files + +## Why this is a skill (not a rule) + +- This workflow is task-specific and should run on demand. +- A global rule would trigger too often and add overhead to unrelated tasks. +- Skills are easier to extend with new reviewer patterns over time. + +## Inputs expected + +- PR URL or PR number +- Reviewer name(s) to prioritize (if applicable) +- Optional scope limits (files/folders) + +## Workflow + +1. Fetch review feedback + - Pull top-level review summaries and inline comments. + - Filter to actionable reviewer comments (ignore bot noise unless requested). +2. Build an action list + - Group comments by file and section. + - Normalize into concrete edits (wording, formatting, structure, examples, links). + - Deduplicate repeated comments and mark global patterns to apply throughout. +3. Apply fixes in files + - Edit only requested/scope-relevant files. + - Keep existing technical intent; change style/clarity unless behavior changes are requested. +4. Validate + - Run lints on edited files. + - Re-read changed sections to ensure comment intent is fully addressed. +5. Report back + - List updated files. + - Map key edits to reviewer themes. + - Call out any comments that were ambiguous or not applicable. + +## Common docs fixes checklist + +- Add a context paragraph before a heading/table when needed +- Avoid bold text as faux headings; use real heading levels +- Use italics (not bold) for light emphasis when requested +- Remove extra blank lines (keep one empty line between blocks) +- Fix incomplete/ambiguous phrasing +- Standardize reference style: "For ..., refer to [Link](url)." +- Replace vague endings like `etc.` with explicit wording +- Keep capitalization consistent across bullets/tables +- Ensure markdown tables are valid and readable + +## Comment triage rules + +- **Apply directly:** explicit suggestions and clear style requests +- **Apply throughout:** repeated reviewer guidance across multiple files +- **Ask user before changing:** unclear product intent, technical behavior changes, or conflicting reviewer guidance +- **Skip with note:** non-actionable comments (for example, design critique with no available source/update path) + +## Output format to user + +Use this structure: + +1. Files changed +2. What was fixed (by reviewer theme) +3. What was not changed (and why) +4. Validation result (lint/tests run) + +## Extension notes + +To extend this skill, add: + +- A `patterns.md` file with reviewer-specific conventions +- A `commands.md` file with reusable `gh` queries for PR feedback +- Team-specific wording conventions for docs pages diff --git a/content/docs/agents/manage-conversations.mdx b/content/docs/agents/manage-conversations.mdx index 7fab69c81..fa5682dc1 100644 --- a/content/docs/agents/manage-conversations.mdx +++ b/content/docs/agents/manage-conversations.mdx @@ -1,5 +1,44 @@ --- -title: "Manage Conversations" -pageTitle: 'Novu Agents Manage Conversations' -description: 'Manage agent conversations, history, and lifecycle in Novu.' +title: "Agent conversations" +pageTitle: 'Manage agents conversations' +description: 'How to manage agent conversations, their history, lifecycle and observability.' --- + +Novu provides full observability for agent conversations. You can view and manage conversations in the Novu dashboard. To access the conversations, go to the Activity Feed page on the dashboard and switch to the Agent Conversations tab. + +## Conversation lifecycle + +An agent conversation follows a simple state machine: + +![Agent conversation lifecycle](/images/agents/manage-conversations/agent-lifecycle.png) + +- **Active** — The conversation is ongoing. Messages increment the count, metadata can be updated, and `lastActivityAt` is refreshed. +- **Resolved** — The agent called `ctx.resolve()`. The `onResolve` handler fires, and an optional summary is stored. If the user sends another message, then the conversation automatically reopens. + +## Conversation observability + +Every conversation is fully observable in the Novu dashboard. Navigate to your agent's detail page to see all conversations, their status, and a complete timeline of activity. + +The dashboard shows: + +- **Conversation list** — All conversations for the agent, with status (active / resolved), last message preview, message count, and last activity timestamp. +- **Full message history** — Every message exchanged between the user and the agent, including rich content (cards, markdown, files). +- **Metadata** — All key-value pairs set via `ctx.metadata.set()`, visible per conversation. +- **Signal activity** — A log of all signals fired (metadata changes, workflow triggers, resolve events). +- **Participant details** — Which subscribers and platform users are part of each conversation, with identity resolution status. +- **Platform context** — Which platform and thread the conversation is happening on. + +![Manage agent conversations list](/images/agents/manage-conversations/manage-agent-conversations.gif) + +## Supported platforms + +| Platform | Status | Notes | +| --- | --- | --- | +| Slack | Available | Text, markdown, files, interactive cards, reactions, typing indicators. File uploads require the files:write bot scope. | +| Microsoft Teams | Available | Text, markdown, files, and cards via Bot Framework. Dashboard includes a guided onboarding flow with one-click app package download. | +| WhatsApp | Available | Text, markdown, interactive buttons. Inbound media is surfaced via attachments; outbound file attachments are not supported yet. | +| Email | Available | Text, markdown, files, interactive cards, emoji reactions (Gmail only). | + + +Platform capabilities vary. For example, typing indicators are only shown on platforms that support them, and message editing depends on platform adapter support. + \ No newline at end of file diff --git a/content/docs/agents/setup-your-agent/connect-providers.mdx b/content/docs/agents/setup-your-agent/connect-providers.mdx index 4de85069b..e45e5b5c5 100644 --- a/content/docs/agents/setup-your-agent/connect-providers.mdx +++ b/content/docs/agents/setup-your-agent/connect-providers.mdx @@ -3,3 +3,5 @@ title: "Connect Providers" pageTitle: 'Novu Agents Connect Providers' description: 'Connect channels and third-party providers to your Novu Agent.' --- + +Once an agent is created, providers can be connected to the agent. This page guides you through how to connect your first provider to the agent and then later extend the agent to connect more providers. diff --git a/content/docs/agents/setup-your-agent/connect-your-code/handle-events.mdx b/content/docs/agents/setup-your-agent/connect-your-code/handle-events.mdx index 2138a3230..0aa7bc3c6 100644 --- a/content/docs/agents/setup-your-agent/connect-your-code/handle-events.mdx +++ b/content/docs/agents/setup-your-agent/connect-your-code/handle-events.mdx @@ -3,3 +3,132 @@ title: "Handle Events" pageTitle: 'Novu Agents Handle Events' description: 'Handle agent events in your webhooks, handlers, and backend services.' --- + +Agents receive events as users interact in a conversation. This page explains the event flow and shows how to handle each event type in your code. + +## Agent conversation flow + +Agent conversation starts when a user sends a message in a conversation with your agent. This message is then processed by the agent and the agent replies to the user. This conversation is then stored in the Novu platform and can be accessed later. Below is the flow of how a conversation works with your agent: + +![Agent Conversation Flow](/images/agents/setup-your-agent/handle-events/agent-conversation-flow.png) + +## Agent events + +A conversational agent responds to four types of events: + +| Event | When it fires | Common use case | +| --- | --- | --- | +| `onMessage` | User sends a text message in the thread | Process the message with your LLM and reply | +| `onAction` | User clicks a button or selects a value in an interactive card | Handle form submissions, button clicks, dropdown selections | +| `onReaction` | User adds or removes an emoji reaction on a message | Capture feedback (thumbs up/down), trigger follow-ups | +| `onResolve` | The conversation is marked as resolved | Clean up, log analytics, send a summary email | + +### onMessage + +`onMessage` is the primary handler event for the agent. It fires every time a user sends a message in a conversation with your agent. + +```typescript +import { agent } from '@novu/agent'; + +export const myAgent = agent("my-agent", { + onMessage: async (ctx) => { + const userMessage = ctx.message?.text ?? ''; + const conversationHistory = ctx.history; + const subscriber = ctx.subscriber; + + const response = await yourLLM.chat(userMessage, conversationHistory); + + ctx.metadata.set('lastIntent', response.intent); + await ctx.reply(response.text); + }, +}); +``` + +#### Handling attachments + +Inbound messages to the agent can include file attachments (images, documents, audio, video) when the platform supports them. Novu normalizes provider files into ctx.message.attachments with downloadable signed URLs: + +```typescript +import { agent } from '@novu/agent'; + +export const myAgent = agent("my-agent", { + onMessage: async (ctx) => { + const attachments = ctx.message?.attachments ?? []; + + for (const file of attachments) { + // file.type — 'image', 'document', 'audio', 'video' + // file.url — short-lived download URL + // file.name — original filename + // file.mimeType — e.g. 'image/jpeg' + // file.size — size in bytes + } + } +}); +``` + + + Download attachment URLs promptly inside your handler. These signed links are valid for 15 minutes. If a link expires before your agent reads it, then re-request the file through a subsequent event or conversation history where available. Inbound attachments are limited to 25 MB per file. + + +### onAction + +`onAction` event is fired when a user clicks a button or selects a value in an interactive card. For interactive cards, refer to [Interactive cards](/agents/setup-your-agent/connect-your-code/reply-types#interactive-cards). This event is used to handle form submissions, button clicks, dropdown selections, and more. + +```typescript +import { agent } from '@novu/agent'; + +export const myAgent = agent("my-agent", { + onAction: async (ctx) => { + const { actionId, value } = ctx.action!; + + // Handle the action based on the actionId + if (actionId === 'approve' && value === 'true') { + // Reply to the user + await ctx.reply('Request approved!'); + + // Trigger the approval workflow + ctx.trigger('approval-workflow', { + to: ctx.subscriber?.subscriberId, + payload: { approved: true }, + }); + } + } +}); +``` + +### onReaction + +`onReaction` event is fired when a user adds or removes an emoji reaction on a message. This event is used to capture feedback (thumbs up/down), trigger follow-ups, and more. + +```typescript +import { agent } from '@novu/agent'; + +export const myAgent = agent("my-agent", { + onReaction: async (ctx) => { + const { emoji, added, message } = ctx.reaction!; + + if (emoji.name === 'thumbs_up' && added) { + ctx.metadata.set('userSatisfied', true); + } else if (emoji.name === 'thumbs_down' && added) { + ctx.metadata.set('userUnsatisfied', true); + } + await ctx.reply('Thank you for your feedback!'); + }, +}); +``` + +### onResolve + +`onResolve` event is fired when the conversation is marked as resolved via `ctx.resolve()` or the resolve signal is triggered. This event is used to clean up, log analytics, send a summary email, and more. + +```typescript +import { agent } from '@novu/agent'; + +export const myAgent = agent("my-agent", { + onResolve: async (ctx) => { + // Clean up the conversation + ctx.metadata.set('resolvedAt', new Date().toISOString()); + await ctx.reply('Conversation resolved!'); + }, +}); +``` \ No newline at end of file diff --git a/content/docs/agents/setup-your-agent/connect-your-code/meta.json b/content/docs/agents/setup-your-agent/connect-your-code/meta.json index d807d526f..2780a4986 100644 --- a/content/docs/agents/setup-your-agent/connect-your-code/meta.json +++ b/content/docs/agents/setup-your-agent/connect-your-code/meta.json @@ -2,5 +2,5 @@ "title": "Connect Your Code", "description": "Connect Your Code", "defaultOpen": true, - "pages": ["index", "handle-events", "reply-types", "use-signals"] + "pages": ["handle-events", "reply-types", "use-signals"] } diff --git a/content/docs/agents/setup-your-agent/connect-your-code/reply-types.mdx b/content/docs/agents/setup-your-agent/connect-your-code/reply-types.mdx index c47590dad..c75831ac6 100644 --- a/content/docs/agents/setup-your-agent/connect-your-code/reply-types.mdx +++ b/content/docs/agents/setup-your-agent/connect-your-code/reply-types.mdx @@ -3,3 +3,146 @@ title: "Reply Types" pageTitle: 'Novu Agents Reply Types' description: 'Choose and send the right reply types from your agent handlers.' --- + +The public reply API is `ctx.reply(content, options?)`. The content argument must be either a plain text string, markdown value or a `ChatElement` card. File attachments are passed in the optional second argument. + +## Plain text + +The most basic reply is a plain text string. + +```typescript +await ctx.reply('Hello! How can I help?'); +``` + +## Markdown + +Markdown is supported for rich text replies. Use markdown to format your replies with headings, lists, links, and other rich text elements. + +```typescript +await ctx.reply('**Report generated.** See the attached PDF.'); +``` + +## Sending attachments + +You can include files in your markdown or plain text replies. The files are displayed as inline attachments in the reply. + + + Attachment files are limited to 25 MB per file. Files are only supported with string/markdown replies, not card replies. Provide each file with exactly one of url or data properties. + +File reference type: + +```tsx +type FileRef = { + filename: string; + mimeType?: string; + data?: string | Uint8Array | ArrayBuffer | Blob; + url?: string; +}; +``` + +Use `url` for files larger than a few megabytes. Novu fetches public HTTP(S) URLs server-side, and uploads the resulting file to the provider. Use `data` for small generated files that your agent already has in memory. +```tsx +// Public URL: recommended for larger files +await ctx.reply('Here is your report.', { + files: [{ filename: 'report.pdf', mimeType: 'application/pdf', url: reportUrl }], +}); + +// Inline binary data: useful for generated files +const csv = new TextEncoder().encode('name,total\nNovu,42'); +await ctx.reply('CSV generated.', { + files: [{ filename: 'report.csv', mimeType: 'text/csv', data: csv }], +}); + +// Node Buffer also works because Buffer extends Uint8Array +const screenshot = await page.screenshot(); +await ctx.reply('Screenshot attached.', { + files: [{ filename: 'screenshot.png', mimeType: 'image/png', data: screenshot }], +}); +``` + +Inline `data` can also be a base64 string, but passing binary values such as `Uint8Array`, `ArrayBuffer`, `Blob`, or a Node `Buffer` is usually easier when working with AI SDKs, PDF generators, screenshots, audio, or other generated files. + +## Interactive cards + +Cards are rich, structured messages with buttons, dropdowns, links, and more. They can be built using *function calls* or *JSX*. + +### Function call API + +Use this API when building card structures as function calls. + +```tsx +import { + Card, Button, CardText, Actions, + Select, SelectOption, Divider, CardLink, +} from '@novu/framework'; + +await ctx.reply(Card({ title: 'Order #1234', children: [ + CardText('Your order is ready for pickup.'), + Divider(), + Actions([ + Button({ id: 'ack', label: 'Acknowledge' }), + Button({ id: 'escalate', label: 'Escalate', style: 'danger' }), + ]), + CardLink({ url: 'https://example.com/order/1234', children: 'View details' }), +] })); +``` + +### JSX API + +Use this API when you prefer JSX syntax. Configure `tsconfig.json` with `"jsxImportSource": "@novu/framework"`. + +```tsx +import { + Card, Button, CardText, Actions, + Select, SelectOption, Divider, CardLink, +} from '@novu/framework'; + +await ctx.reply( + + Your order is ready for pickup. + + +