Update content to change language to client-facing, update quickstart#1125
Update content to change language to client-facing, update quickstart#1125Aviatorscode2 wants to merge 8 commits into
Conversation
❌ Deploy Preview for docs-novu failed. Why did it fail? →
|
📝 WalkthroughWalkthroughThis PR reorganizes the agents documentation section by clarifying ACI's role as a communication infrastructure layer, introducing a new landing page for agents, and updating the managed agent quickstart from a dashboard-based to CLI-based flow. The ACI definition page was rewritten to explain how messages are normalized, identities resolved, conversations persisted, and responses delivered. A new agents index page serves as the entry point, explaining the infrastructure vs. intelligence boundary and providing navigation cards. The managed agent quickstart was completely revised to guide users through the Novu CLI ( Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
content/docs/agents/get-started/what-is-aci.mdx (1)
127-127:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUse consistent product/channel capitalization for Slack.
Line 127 uses “slack provider” while the rest of the page uses “Slack provider.” Please standardize to “Slack” for consistency.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@content/docs/agents/get-started/what-is-aci.mdx` at line 127, The phrase "slack provider" in the sentence "Create your first agent, connect a slack provider, and send a message in under 5 minutes." should be capitalized to "Slack provider" to match the rest of the document; update that exact string in content/docs/agents/get-started/what-is-aci.mdx so all occurrences use "Slack" consistently.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@content/docs/agents/get-started/what-is-aci.mdx`:
- Line 90: Update the pluralization in the sentence that currently reads "The
agent's tools, skill and their configuration" in
content/docs/agents/get-started/what-is-aci.mdx by changing "skill" to "skills"
so it reads "The agent's tools, skills and their configuration"; locate the
sentence by searching for the exact phrase "The agent's tools, skill and their
configuration" and make the single-word fix.
In `@content/docs/agents/index.mdx`:
- Around line 26-29: Remove the duplicated introductory sentence so only one of
the two similar lines remains; specifically, keep a single sentence that reads
either "Novu Connect accepts two kinds of agents. You choose how you want to
bring the intelligence." or "Novu Connect accepts two kinds of agent brains. You
choose how you want to bring the intelligence." and delete the other duplicate
occurrence to eliminate redundancy in the agents/agent brains intro.
---
Outside diff comments:
In `@content/docs/agents/get-started/what-is-aci.mdx`:
- Line 127: The phrase "slack provider" in the sentence "Create your first
agent, connect a slack provider, and send a message in under 5 minutes." should
be capitalized to "Slack provider" to match the rest of the document; update
that exact string in content/docs/agents/get-started/what-is-aci.mdx so all
occurrences use "Slack" consistently.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 6c9549ae-b345-4232-afb6-028361b76b3e
⛔ Files ignored due to path filters (1)
public/images/agents/quickstart/novu-connect-demo.gifis excluded by!**/*.gif
📒 Files selected for processing (5)
content/docs/agents/get-started/what-is-aci.mdxcontent/docs/agents/index.mdxcontent/docs/agents/managed-agent/quickstart.mdxcontent/docs/agents/meta.jsonsrc/middleware.ts
💤 Files with no reviewable changes (1)
- src/middleware.ts
| - MCP servers and their configuration. | ||
| - The agent's tools and their configuration. | ||
| - The agent's business logic and decision-making. | ||
| - The agent's tools, skill and their configuration. |
There was a problem hiding this comment.
Fix pluralization in managed-agent bullet list.
Line 90 says “tools, skill and their configuration”; this should be “tools, skills and their configuration” for grammatical correctness.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@content/docs/agents/get-started/what-is-aci.mdx` at line 90, Update the
pluralization in the sentence that currently reads "The agent's tools, skill and
their configuration" in content/docs/agents/get-started/what-is-aci.mdx by
changing "skill" to "skills" so it reads "The agent's tools, skills and their
configuration"; locate the sentence by searching for the exact phrase "The
agent's tools, skill and their configuration" and make the single-word fix.
| Novu Connect accepts two kinds of agents. You choose how you want to bring the intelligence. | ||
|
|
||
| Novu Connect accepts two kinds of agent brains. You choose how you want to bring the intelligence. | ||
|
|
There was a problem hiding this comment.
Remove duplicated “two kinds of agents” intro copy.
Lines 26–29 repeat the same message twice (“two kinds of agents/agent brains”). Keep one sentence to avoid redundancy.
🧰 Tools
🪛 LanguageTool
[style] ~28-~28: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...nds of agent brains. You choose how you want to bring the intelligence. ### External ...
(REP_WANT_TO_VB)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@content/docs/agents/index.mdx` around lines 26 - 29, Remove the duplicated
introductory sentence so only one of the two similar lines remains;
specifically, keep a single sentence that reads either "Novu Connect accepts two
kinds of agents. You choose how you want to bring the intelligence." or "Novu
Connect accepts two kinds of agent brains. You choose how you want to bring the
intelligence." and delete the other duplicate occurrence to eliminate redundancy
in the agents/agent brains intro.
Source: Linters/SAST tools
| ## 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. |
There was a problem hiding this comment.
If a list is longer than three items, I generally reformat it into an actual list, either ordered or unordered.
| 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. | ||
|
|
||
| The agent brain is either Custom code agent or Managed agent. | ||
| 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. |
There was a problem hiding this comment.
Same comment as previous. Apply throughout.
|
|
||
| ## Start building | ||
|
|
||
| Follow the quickstart to create your first agent, connect a Slack provider, and send your first message in under 5 minutes. |
There was a problem hiding this comment.
Link to quickstart?
|
|
||
| Click **Create Agent** when you are done. | ||
| ## Create an agent | ||
|
|
There was a problem hiding this comment.
Add context paragraph?
|
|
||
| * **Communication infrastructure**: Webhook ingestion, message normalization, conversation state, identity resolution, and delivery across channels. ACI owns this layer. | ||
|
|
||
| * **Agent intelligence**: Your LLM, prompts, tools, managed agent configuration, business logic, or custom runtime. You own this layer. |
There was a problem hiding this comment.
See earlier comment about lists.
|
|
||
| ## Connect the agent | ||
|
|
||
| Novu Connect accepts two kinds of agents. You choose how you want to bring the intelligence. |
There was a problem hiding this comment.
Why do we have two almost identical paragraphs here?
|
|
||
| Novu Connect accepts two kinds of agents. You choose how you want to bring the intelligence. | ||
|
|
||
| Novu Connect accepts two kinds of agent brains. You choose how you want to bring the intelligence. |
There was a problem hiding this comment.
Need to explain "agent brains."
Co-authored-by: DianaHackmamba <diana@hackmamba.io>
Co-authored-by: DianaHackmamba <diana@hackmamba.io>
Co-authored-by: DianaHackmamba <diana@hackmamba.io>
Co-authored-by: DianaHackmamba <diana@hackmamba.io>
Co-authored-by: DianaHackmamba <diana@hackmamba.io>
Co-authored-by: DianaHackmamba <diana@hackmamba.io>
Co-authored-by: DianaHackmamba <diana@hackmamba.io>
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| Novu Connect accepts two kinds of agents. You choose how you want to bring the intelligence. | ||
|
|
||
| Novu Connect accepts two kinds of agent brains. You choose how you want to bring the intelligence. |
There was a problem hiding this comment.
| Novu Connect accepts two kinds of agents. You choose how you want to bring the intelligence. | |
| Novu Connect accepts two kinds of agent brains. You choose how you want to bring the intelligence. | |
| Novu Connect accepts two kinds of agent brains. You choose how you want to bring the intelligence. |
Prompt To Fix With AI
This is a comment left during a code review.
Path: content/docs/agents/index.mdx
Line: 26-28
Comment:
Duplicated intro sentence in the "Connect the agent" section. Two near-identical paragraphs appear back-to-back — one says "two kinds of agents" and the other says "two kinds of agent brains". The second line is the more precise phrasing; the first should be removed.
```suggestion
Novu Connect accepts two kinds of agent brains. You choose how you want to bring the intelligence.
```
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| - MCP servers and their configuration. | ||
| - The agent's tools and their configuration. | ||
| - The agent's business logic and decision-making. | ||
| - The agent's tools, skill and their configuration. |
There was a problem hiding this comment.
| - The agent's tools, skill and their configuration. | |
| - The agent's tools, skills and their configuration. |
Prompt To Fix With AI
This is a comment left during a code review.
Path: content/docs/agents/get-started/what-is-aci.mdx
Line: 90
Comment:
Typo: "skill" should be "skills" to be consistent with the plural noun used throughout the rest of the section.
```suggestion
- The agent's tools, skills and their configuration.
```
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
|
|
||
| You can also mention the bot in a channel where it has been added. | ||
|
|
||
| Open Slack, where you'll see a message from your agent. Send it a direct message to get started. You'll then be prompted by the agent to connect your Linear and GitHub MCP servers, once you do, your agent is ready. |
There was a problem hiding this comment.
The line "You'll then be prompted by the agent to connect your Linear and GitHub MCP servers" only holds if the user copied the engineering-assistant example description from step 2. A user who described a customer support bot or a marketing agent will not see that prompt, and the step will appear broken or confusing to them. Consider making this line conditional or generalize it to something like "Depending on the tools configured, your agent may prompt you to connect external integrations like Linear or GitHub."
Prompt To Fix With AI
This is a comment left during a code review.
Path: content/docs/agents/managed-agent/quickstart.mdx
Line: 87
Comment:
**Quickstart "Send a message" step is tied to the example agent description**
The line "You'll then be prompted by the agent to connect your Linear and GitHub MCP servers" only holds if the user copied the engineering-assistant example description from step 2. A user who described a customer support bot or a marketing agent will not see that prompt, and the step will appear broken or confusing to them. Consider making this line conditional or generalize it to something like "Depending on the tools configured, your agent may prompt you to connect external integrations like Linear or GitHub."
How can I resolve this? If you propose a fix, please make it concise.| <Card href="/agents/conversations" title="Conversation observability" icon={<MessagesSquare />}> | ||
| Monitor, inspect, and manage live agent conversations. | ||
| </Card> | ||
| </Cards> No newline at end of file |
There was a problem hiding this comment.
\ No newline at end of file).
| <Card href="/agents/conversations" title="Conversation observability" icon={<MessagesSquare />}> | |
| Monitor, inspect, and manage live agent conversations. | |
| </Card> | |
| </Cards> | |
| <Card href="/agents/conversations" title="Conversation observability" icon={<MessagesSquare />}> | |
| Monitor, inspect, and manage live agent conversations. | |
| </Card> | |
| </Cards> |
Prompt To Fix With AI
This is a comment left during a code review.
Path: content/docs/agents/index.mdx
Line: 86-89
Comment:
File is missing a trailing newline. Most editors and linters expect a newline at the end of the file, and the diff confirms it is absent (`\ No newline at end of file`).
```suggestion
<Card href="/agents/conversations" title="Conversation observability" icon={<MessagesSquare />}>
Monitor, inspect, and manage live agent conversations.
</Card>
</Cards>
```
How can I resolve this? If you propose a fix, please make it concise.| <Card icon={<MessagesSquare />} href="/agents/conversations" title="Conversation observability"> | ||
| View and manage agent conversations in the dashboard. | ||
| View and manage agent conversations from the Novu Connect dashboard. | ||
| </Card> | ||
| </Cards> | ||
| </Cards> No newline at end of file |
There was a problem hiding this comment.
\ No newline at end of file).
| <Card icon={<MessagesSquare />} href="/agents/conversations" title="Conversation observability"> | |
| View and manage agent conversations in the dashboard. | |
| View and manage agent conversations from the Novu Connect dashboard. | |
| </Card> | |
| </Cards> | |
| </Cards> | |
| <Card icon={<MessagesSquare />} href="/agents/conversations" title="Conversation observability"> | |
| View and manage agent conversations from the Novu Connect dashboard. | |
| </Card> | |
| </Cards> |
Prompt To Fix With AI
This is a comment left during a code review.
Path: content/docs/agents/managed-agent/quickstart.mdx
Line: 106-109
Comment:
File is missing a trailing newline. The diff confirms it is absent (`\ No newline at end of file`).
```suggestion
<Card icon={<MessagesSquare />} href="/agents/conversations" title="Conversation observability">
View and manage agent conversations from the Novu Connect dashboard.
</Card>
</Cards>
```
How can I resolve this? If you propose a fix, please make it concise.2 participants
Summary by CodeRabbit
/agents→what-is-acimapping.Greptile Summary
This PR updates the agents documentation to use more client-facing language, rewrites the managed agent quickstart around the Novu CLI (
npx novu connect), and adds a newagents/index.mdxoverview page. The/agentsmiddleware redirect is removed in favour of the new index page, and a demo GIF is added to the quickstart.agents/index.mdx: Introduces an agents landing page covering ACI, both agent types, the conversation flow, and navigation cards — but contains a duplicated intro paragraph that needs one copy removed.what-is-aci.mdxlanguage pass: Broad editorial improvements; one minor typo (skill→skills) in the managed-agent controls list.Confidence Score: 4/5
Safe to merge after the duplicate paragraph in index.mdx is resolved; all other changes are editorial improvements or straightforward navigation updates.
The only change that will be immediately visible to readers in a confusing way is the duplicated intro paragraph in index.mdx — one of the two near-identical sentences must be removed before this page goes live. All other findings are minor typos or style issues that do not break functionality or navigation.
content/docs/agents/index.mdx needs the duplicate paragraph removed before publishing.
Important Files Changed
/agents→/agents/get-started/what-is-aciredirect now that a dedicatedindex.mdxserves the/agentsroute directly; straightforward and correct.indexpage to the agents navigation structure; no issues.Flowchart
%%{init: {'theme': 'neutral'}}%% flowchart TD A[User visits /agents] -->|Before this PR| B[middleware redirect\n/agents → /agents/get-started/what-is-aci] A -->|After this PR| C[agents/index.mdx\nOverview landing page] C --> D[What is ACI?\n/agents/get-started/what-is-aci] C --> E[Managed Agent Quickstart\n/agents/managed-agent/quickstart] C --> F[Custom Code Quickstart\n/agents/custom-code-agent/quickstart] E --> G[Step 1: npx novu connect] G --> H[Step 2: Create agent via CLI] H --> I[Step 3: Connect Slack] I --> J[Step 4: Send a message]Prompt To Fix All With AI
Reviews (1): Last reviewed commit: "Update content/docs/agents/managed-agent..." | Re-trigger Greptile