diff --git a/content/docs/agents/get-started/what-is-aci.mdx b/content/docs/agents/get-started/what-is-aci.mdx index 2d6167bc5..ddadf72a9 100644 --- a/content/docs/agents/get-started/what-is-aci.mdx +++ b/content/docs/agents/get-started/what-is-aci.mdx @@ -6,26 +6,35 @@ icon: CircleHelp --- import { BookText, HomeIcon } from 'lucide-react'; + +Agent Communication Infrastructure (ACI) is the communication layer that connects agents to the messaging platforms where people already work, collaborate, and talk to businesses. -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 communication channels and your agent logic. Instead of building separate integrations for each platform, ACI gives your agent one communication interface for inbound messages, outbound replies, conversation state, user identity, and delivery across: -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. +* Slack +* Microsoft Teams +* WhatsApp +* Email +* Telegram +* Other supported platforms -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 or Platform managed agents like [Claude Managed Agent](https://platform.claude.com/docs/en/managed-agents/overview), [ AWS Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) and many more. ACI doesn't define the agent’s intelligence. It defines the communication infrastructure around it. +The agent brain can be powered by an LLM, custom code, a rules engine, a human-in-the-loop workflow, a managed agent platform, or a combination of systems. ACI does not define the agent’s intelligence. It defines the communication infrastructure around it. + +That means you can build an agent that your team uses internally, expose an agent to your product users, or create a customer-facing agent that lives in the channels your customers already use. ## 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. +Software is becoming more conversational. People 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 the 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. +At the same time, agents are becoming more capable. Teams are building agents that answer 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. +The problem is that most agents are still trapped inside one interface. Moving the same agent into Slack, Microsoft Teams, WhatsApp, email, Telegram, or another channel usually means rebuilding the communication layer for each platform. -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. +Each channel has its own webhook format, identity model, threading behavior, permissions, message formatting, interaction patterns, and delivery constraints. Without a shared communication layer, teams end up rebuilding the same infrastructure every time they want an agent to reach a new audience. -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. +ACI standardizes that layer. It separates communication infrastructure from agent intelligence, so you can connect an agent to multiple messaging platforms without hand-building every channel integration from scratch. -You create 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. +You create the agent once. ACI handles communication across connected channels. The goal is not only to send messages, but to let agents hold useful conversations while preserving context, control, and visibility. ## How ACI works @@ -35,31 +44,48 @@ ACI introduces a three-part architecture that separates platform delivery from a ### 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. +Communication channels are the places where people interact with the agent: + +* Slack +* Microsoft Teams +* WhatsApp +* Telegram +* Email +* Other supported platforms + +When a user sends a message in one of these channels, the message 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. +The bridge is the infrastructure layer between the communication channel and the agent's brain. -It creates or loads the conversation with its full history, and forwards everything to your server as a single context object. +It receives the platform webhook, normalizes the message into a standard format, and resolves the user's identity. It then creates or loads the conversation, attaches the relevant conversation history, and forwards the message to your configured agent brain as context. -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. +When the agent replies, the bridge delivers the response back to the correct platform, thread, or conversation. It also persists the response in the conversation history and records the activity for observability. -### Agent brain +### Agent -The agent brain is either Custom code agent or Managed agent. +The agent's brain is the system that decides how to respond. ACI supports different kinds of agents, including custom code agents and managed agents. -In case of Custom code agent, you can build agent brain with your custom code using agent sdk, lanchain etc. 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. +For a custom code agent, your server receives the context object and processes it however you decide. You can call an LLM, run business logic, use external APIs, route the conversation to a human, or combine multiple systems. You can build the agent brain with the Novu agent SDK, AI SDK, LangChain, OpenAI SDK, or any custom code of your choosing. -In case of Managed agent, platfrom like Claude manages the agent intelligence, it provides, system tools like grep, web search, connection to external tools like linear, notion using MCP. +For a managed agent, you configure the agent's behavior, system prompt, tools, skills, and external connections. The managed platform runs the agent harness and executes the agent loop, while ACI handles the communication layer between the managed agent and your connected channels. -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. +Because the agent brain is separate from the channel layer, your agent does not need channel-specific logic for each connected provider. The same agent can respond through the ACI bridge across: -## What ACI handles vs. what you control +* Slack +* Microsoft Teams +* WhatsApp +* Email +* Telegram +* Other supported channels -ACI draws a clear boundary between infrastructure and intelligence. -### The infrastructure handles +## What ACI handles and what you control + +ACI draws a clear boundary between communication infrastructure and agent intelligence. + +### ACI handles * Webhook ingestion and message normalization across all connected platforms. * Message delivery to the correct platform thread. @@ -70,7 +96,7 @@ ACI draws a clear boundary between infrastructure and intelligence. ### You control -In case of _Custom code agent_, you control: +For a custom code agent, you control: * Your LLM, prompts, and model configuration. * Your tools and function calls. @@ -78,13 +104,15 @@ In case of _Custom code agent_, you control: * 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. -In case of _Managed agent_, platform like Claude controls: +For a managed agent, you configure: +- The agent's instructions and behavior. - MCP servers and their configuration. -- The agent's tools and their configuration. -- The agent's business logic and decision-making. +- The agent's tools, skills and their configuration. +- The external systems the agent can access. +- The guardrails or constraints supported by the managed platform. -ACI is opinionated about infrastructure and unopinionated about intelligence. It handles the delivery problem so you can focus on the capability problem. +ACI is opinionated about communication infrastructure and unopinionated about intelligence. It handles the communication problem so you can focus on what your agent should do. ## Common use cases @@ -102,6 +130,8 @@ Common use cases include: ## Start building +Follow the quickstart to create your first agent, connect a Slack provider, and send your first message in under five minutes. + }> + Learn how ACI works, what it solves, and where it draws the line between infrastructure and intelligence. + + +## Connect the agent + +Novu Connect accepts two kinds of [agent brains](/platform/additional-resources/glossary#agent-brain). You choose how you want to bring it. + +### External connectors + +Delegate the agent logic entirely to a managed platform such as Claude Managed Agents. You configure the agent's behavior, system prompt, tools, skills, and MCP servers and the platform runs the intelligence. + +}> + Set up a fully managed agent powered by Claude. No custom server code required. + + +### Custom code + +Write your own agent logic. Handle events, call any LLM or API, and reply using the Novu agent SDK. Compatible with AI SDK, LangChain, OpenAI SDK, and any custom code of your choosing. + +}> + Build an agent with full control over logic, tools, and event handling. + + +## How a conversation flows + +ACI turns channel-specific messages into a standard communication flow between the user and your agent brain. + +1. A user sends a message on Slack, Teams, WhatsApp, or another supported channel. +2. Novu ingests the webhook, normalizes the event, and resolves the user's identity. +3. Novu sends the event to your agent brain with full conversation context. +4. Your agent processes the message and responds. +5. Novu delivers the reply back to the correct platform thread. +6. Novu persists the conversation and makes it visible in the Connect dashboard. + +## Start building + +}> + Follow the quickstart to create your first agent, connect a Slack provider, and send your first message in under 5 minutes. + + +## Learn more + +Explore the full documentation to go deeper on any part of Novu Connect. + + + }> + Understand the infrastructure layer and the problem it solves. + + }> + How inbound messages flow from a channel through to your agent and back. + + }> + How agents and provider connections work, and which channels are supported. + + }> + Configure a fully-managed agent powered by Claude. + + }> + Connect a Slack provider and send your first message in under five minutes. + + }> + Monitor, inspect, and manage live agent conversations. + + \ No newline at end of file diff --git a/content/docs/agents/managed-agent/quickstart.mdx b/content/docs/agents/managed-agent/quickstart.mdx index ed5528a9f..70d02ade5 100644 --- a/content/docs/agents/managed-agent/quickstart.mdx +++ b/content/docs/agents/managed-agent/quickstart.mdx @@ -1,83 +1,83 @@ --- title: "Quickstart" pageTitle: 'Managed Agent Quickstart' -description: 'Create a managed agent with Claude, connect it to Slack, and get a reply in under 10 minutes.' +description: 'Use the Novu CLI to create a managed agent, connect it to Slack, and get a reply in minutes.' icon: Zap --- import { Brain, Link, MessagesSquare } from 'lucide-react'; -This guide walks you through creating a managed agent powered by Claude, connecting it to Slack, and sending your first message. +This guide walks you through creating a managed agent using the Novu CLI, connecting it to Slack, and sending your first message. -By the end, you will have a working agent that receives messages from Slack and replies using Claude's reasoning. +![Novu connect demo](/images/agents/quickstart/novu-connect-demo.gif) -**Prerequisites:** +## Prerequisites -- A [Novu account](https://dashboard.novu.co). -- A Slack workspace where you can install apps. -- A Claude API key from the [Anthropic console](https://console.anthropic.com/settings/keys) (optional, you can use Novu demo credentials to start). +* Node.js installed on your machine. +* A [Novu account](https://connect.novu.co/) (you can create one during the setup flow). +* A Slack workspace where you can install apps. -## Create your agent +## Run the CLI -1. Go to the [Novu dashboard](https://dashboard.novu.co). -2. In the sidebar, click **Agents**. -3. Click **Add Agent**. -4. Under **External connectors**, select **Claude Managed Agent**. +In your terminal, run: - - - - -## Configure the connector - -Fill in the following fields to configure the connector: - -- **Integration name**: A display name for your connector. -- **API Key**: Your Claude API key from the [Anthropic console](https://console.anthropic.com/settings/keys). -- **Workspace ID**: Your Claude workspace ID from the [Anthropic console](https://console.anthropic.com/settings/workspaces). +```bash +npx novu connect +``` -## Set a system prompt - -You can create the agent in two ways: - -- **Create from prompt**: describe what you want the agent to do, and Novu generates a system prompt. You can also pick a preset template (Customer Support, Marketing, etc.). -- **Create manually**: give a name and identifier and write the system prompt yourself. - -For a manual prompt, something like this works well: - -```text -You are a helpful support agent for Acme Corp. Answer questions about -our products, pricing, and account setup. Keep responses short and -friendly. If you do not know the answer, say so and offer to connect -the user with a human. -``` - -Click **Create Agent** when you are done. +## Create an agent + +1. Choose where your agent runs. The CLI asks **Where do you want the agent to run?**, select an option, and then press **Enter**: + * Demo credentials + * Claude Managed Agents + * AWS Claude Managed Agents + + For this quickstart, select **Demo credentials**. +2. Describe your agent. Type a description of what you want the agent to do and press **Enter**. For example: + ```text + Create an engineering assistant agent that checks Linear and GitHub for open issues, pending PR reviews, and review requests. It summarizes what needs attention, flags blockers and stale tickets, and posts a short daily standup digest. It keeps responses concise and links back to the relevant Linear issue or GitHub pull request. + ``` + Novu generates the agent for you, including its system prompt, tools, MCP servers, and skills based on your description. +3. Review and create the agent. The CLI shows the generated agent for you to review. You can adjust any of the following fields before confirming: + * Name + * Identifier + * System prompt + * Tools + * MCP servers + * Skills + + If everything looks good, then select **Create this agent** and press **Enter**. + + If you want to change the description and regenerate, then select **Regenerate from description** and repeat the previous step. -## Connect a provider +## Connect Slack -1. On the agent setup page, click **Select provider**. -2. Choose **Slack**. -3. Follow the Slack setup steps in the dashboard: - - Generate a Slack App Configuration Token. - - Paste it in Novu and click **Create app**. - - Click **Install agent** to add the bot to your Slack workspace. +The CLI prompts you: **pick a channel to connect this agent to.** Select **Slack** and press **Enter**. + +Novu asks you to paste a Slack App Configuration Token. To get one: +1. Open [https://api.slack.com/apps](https://api.slack.com/apps). +2. Scroll to the bottom of the page. +3. Under **App Configuration Tokens**, click **Generate Token**. +4. Copy the access token, it starts with `xoxe.xoxp-`. +5. Paste the token into the terminal and press **Enter**. + + The CLI sends the token to your Novu account once to create the Slack app, then discards it; the token isn't stored. + +6. Add the app to your workspace. After pasting the token, the CLI prompts you to add the app to your Slack workspace. Press **Enter** and follow the link to install the bot. - -The configuration token is used once to create the Slack app and is not stored by Novu. - +Once installed, your agent is live and listening for messages in Slack. @@ -85,21 +85,16 @@ The configuration token is used once to create the Slack app and is not stored b ## Send a message -Open Slack and send a direct message to your new bot. Claude processes the message and the reply appears in the thread. - -You can also mention the bot in a channel where it has been added. - +Open Slack, where you see a message from your agent. Send it a direct message to get started. The agent then prompts you to connect your Linear and GitHub MCP servers; once you do, your agent is ready. + +You can also add and interact with the agent in any channel in the workspace. + +To manage your agent, add more channels, or view conversations from the Connect dashboard, create a Novu account at [connect.novu.co](https://connect.novu.co/). + -## What to do next - -- **Enable MCP servers**: Give the agent access to tools like Linear, GitHub, or Notion from the agent settings page. -- **Upload custom skills**: Add SKILL.md files to teach the agent domain-specific workflows. -- **Connect more providers**: Add Microsoft Teams, email, or other providers from the agent setup page. -- **View conversations**: Open the Activity Feed in the dashboard and switch to the Agent Conversations tab to see message history. - ## Next steps @@ -107,9 +102,9 @@ You can also mention the bot in a channel where it has been added. Learn about connectors, MCP servers, skills, and how conversations work. } href="/agents/managed-agent/configure-mcp-servers" title="Configure MCP servers"> - Enable external tools for your managed agent. + Give your agent access to external tools like Linear, GitHub, or Notion. } href="/agents/conversations" title="Conversation observability"> - View and manage agent conversations in the dashboard. + View and manage agent conversations from the Novu Connect dashboard. - + \ No newline at end of file diff --git a/content/docs/agents/meta.json b/content/docs/agents/meta.json index b91bf6f39..7548ba856 100644 --- a/content/docs/agents/meta.json +++ b/content/docs/agents/meta.json @@ -4,6 +4,7 @@ "description": "Agents", "pages": [ "---Get Started---", + "index", "get-started/what-is-aci", "get-started/mental-model", "get-started/agents-and-providers", diff --git a/content/docs/platform/additional-resources/glossary.mdx b/content/docs/platform/additional-resources/glossary.mdx index 1478e4f23..68005e28f 100644 --- a/content/docs/platform/additional-resources/glossary.mdx +++ b/content/docs/platform/additional-resources/glossary.mdx @@ -17,6 +17,10 @@ If you have any questions or need further clarification on any of the terms list An `actor` refers to a user or subscriber who initiates actions that trigger events within the system. Each actor is uniquely identified by an "actorId," also known as "subscriberId". Actors hold user-related variables and can enhance notifications by allowing their avatars to be displayed. +### Agent brain + +The agent brain is the system that decides how an agent responds. It can be powered by an LLM, custom code, a rules engine, a human-in-the-loop workflow, a managed agent platform, or a combination of systems. The agent brain is separate from the communication infrastructure that delivers messages across channels, which is handled by [ACI](/agents/get-started/what-is-aci). + ### Channels Novu lets you send notifications across different communication mediums, including emails, in-app messages, push notifications, SMS, and chat. Each of these five communication mediums is referred to as a notification 'channel'. diff --git a/public/images/agents/quickstart/novu-connect-demo.gif b/public/images/agents/quickstart/novu-connect-demo.gif new file mode 100644 index 000000000..51b81bbde Binary files /dev/null and b/public/images/agents/quickstart/novu-connect-demo.gif differ diff --git a/src/middleware.ts b/src/middleware.ts index 2a63e9ac9..88da1d9a7 100644 --- a/src/middleware.ts +++ b/src/middleware.ts @@ -172,9 +172,6 @@ export default async function middleware(request: NextRequest, event: NextFetchE '/platform/workflow/workflows.mdx': '/platform/workflow', '/docs/platform/workflow/layouts': '/platform/workflow/add-notification-content/channels-template-editors#email-layouts', - - // Agents section landing - '/agents': '/agents/get-started/what-is-aci', }; if (pathname in redirectMap) {