docs/agents/managed-agent/concepts.mdx
This page covers the building blocks of a managed agent and how they fit together.
A connector links your Novu agent to an AI platform. The platform receives each user message, reasons about it, uses built-in tools and any enabled MCP servers if needed, and returns a response that Novu delivers to the chat provider.
| Connector | Status |
|---|---|
| Claude (Anthropic) | Available |
| OpenAI | Coming soon |
| AWS Bedrock | Coming soon |
Each connector needs platform credentials. For Claude, you provide:
If you want to try things out first, you can use the Novu demo credentials. They give you a limited number of free conversations without an Anthropic account.
The system prompt is a set of instructions that define the agent's behavior. It runs at the start of every conversation turn and shapes how the model responds.
A useful system prompt typically includes:
You set the system prompt in the dashboard when creating the agent, and you can update it at any time from the agent settings page.
You can create a managed agent in two ways:
Novu provides starter templates for common use cases like customer support, internal ops, and onboarding. Templates give you a working prompt you can customize.
Every managed agent has access to system tools provided by the AI platform. These are always available without any setup:
| Tool | What it does |
|---|---|
| Bash | Execute shell commands in a sandboxed environment |
| Read | Read files from the filesystem, including text, images, PDFs, and notebooks |
| Write | Create or overwrite files on the filesystem |
| Edit | Perform find-and-replace edits inside a file |
| Glob | Find files by name using pattern matching |
| Grep | Search file contents using regex patterns |
| Web search | Search the internet for current information |
| Web fetch | Fetch and read content from a URL |
The platform decides when to call these tools based on the user's message and the system prompt. For example, if a user asks "What is the latest pricing for AWS Lambda?", the agent will use web search to find the answer. If the user asks "Find all config files in the project", the agent will use glob and grep.
All built-in tools are enabled by default when you create a managed agent. MCP servers and custom skills are not enabled by default and need to be added separately.
On top of the built-in tools, MCP (Model Context Protocol) servers give the agent access to external services and data sources you choose. When you enable an MCP server, the AI platform gains access to its capabilities.
sequenceDiagram
participant Admin
participant Dashboard as Novu Dashboard
participant Connector as AI Connector
participant McpServer as MCP Server
Admin->>Dashboard: Enable MCP server
Dashboard->>Connector: Sync configuration
Note over Connector,McpServer: During conversation
Connector->>McpServer: Call tool when needed
McpServer-->>Connector: Tool result
Connector->>Connector: Include in reasoning
The connector platform decides when and whether to use a tool. You do not need to write code to trigger tool calls.
Common MCP servers include:
The list of available servers is shown on the agent settings page in the dashboard.
Some MCP servers require OAuth authorization from the end user. When a subscriber first interacts with the agent through a tool that needs authorization, they receive a prompt to connect their account.
Novu manages the OAuth flow:
sequenceDiagram
participant User
participant Agent as Managed Agent
participant Novu
participant ExtService as External Service
Agent->>User: Send authorization link
User->>ExtService: Click link and authorize
ExtService->>Novu: OAuth callback with tokens
Novu->>Novu: Store tokens securely
Note over Agent,ExtService: Subsequent turns
Novu->>ExtService: Pass tokens on tool calls
Authorization is per subscriber, per MCP server. Once a user authorizes, the connection persists across conversations until they revoke it.
You can enable up to 64 MCP servers per agent.
Skills are instruction files that teach the agent how to handle specific tasks. They are useful when the system prompt alone is not detailed enough for a multi-step workflow.
A skill is a SKILL.md file with structured instructions. It might describe how to triage a support ticket, how to generate a report from a data source, or how to walk a user through an onboarding flow.
You can add skills from the agent settings page in two ways:
The platform assigns each skill a stable ID. If you upload a skill with the same title again, it creates a new version automatically.
Managed agents follow this conversation lifecycle:
| State | What it means |
|---|---|
| Active | The conversation is open. New messages are processed by the agent. |
| Resolved | The conversation has been closed. The underlying platform session is archived. |
| Reopened | A new user message after resolution starts a fresh platform session and reopens the conversation automatically. |
When the agent calls a tool during a conversation, Novu shows a plan card in the chat thread. The plan card displays which tool the agent is about to use and its current status (thinking, running, complete). This gives users visibility into what the agent is doing before the final response appears.
For MCP tools that need user authorization, the plan card pauses and shows an authorization prompt. After the user authorizes, the agent continues from where it left off.
Responses stream progressively rather than arriving all at once. The platform handles streaming automatically.
Managed agents support these chat providers:
| Provider | Status |
|---|---|
| Slack | Available |
| Microsoft Teams | Available |
| Available | |
| Available | |
| Telegram | Available |
Provider setup is done from the agent settings page in the dashboard. Each provider has its own connection flow (app creation, OAuth, etc.).