novuhq · djabarovgeorge · May 12, 2026 · May 10, 2026 · May 10, 2026 · May 11, 2026
diff --git a/.source b/.source
diff --git a/apps/api/src/app/agents/agent-analytics.ts b/apps/api/src/app/agents/agent-analytics.ts
@@ -35,7 +35,7 @@ export function trackAgentIntegrationConnected(
     integrationId: string;
     integrationIdentifier: string;
     providerId: string;
-    channel: string;
+    channel?: string;
     connectionSource: 'existing_integration' | 'novu_email_provisioned';
   }
 ): void {

diff --git a/apps/api/src/app/agents/agents.controller.ts b/apps/api/src/app/agents/agents.controller.ts
@@ -11,6 +11,7 @@ import {
   Post,
   Put,
   Query,
+  UseFilters,
   UseGuards,
   UseInterceptors,
 } from '@nestjs/common';
@@ -28,6 +29,7 @@ import { ExternalApiAccessible } from '../auth/framework/external-api.decorator'
 import { ThrottlerCategory } from '../rate-limiting/guards';
 import {
   ApiCommonResponses,
+  ApiConflictResponse,
   ApiNoContentResponse,
   ApiNotFoundResponse,
   ApiResponse,
@@ -37,11 +39,13 @@ import {
   AddAgentIntegrationRequestDto,
   AgentIntegrationResponseDto,
   AgentResponseDto,
+  AgentRuntimeConfigResponseDto,
   CreateAgentRequestDto,
   ListAgentIntegrationsQueryDto,
   ListAgentIntegrationsResponseDto,
   ListAgentsQueryDto,
   ListAgentsResponseDto,
+  PatchAgentRuntimeConfigRequestDto,
   UpdateAgentBridgeRequestDto,
   UpdateAgentIntegrationRequestDto,
   UpdateAgentRequestDto,
@@ -53,6 +57,7 @@ import {
   SendWhatsAppTestTemplateRequestDto,
   SendWhatsAppTestTemplateResponseDto,
 } from './dtos/send-whatsapp-test-template.dto';
+import { AgentRuntimeExceptionFilter } from './filters/agent-runtime-exception.filter';
 import { AgentConversationEnabledGuard } from './guards/agent-conversation-enabled.guard';
 import { AddAgentIntegrationCommand } from './usecases/add-agent-integration/add-agent-integration.command';
 import { AddAgentIntegration } from './usecases/add-agent-integration/add-agent-integration.usecase';
@@ -64,6 +69,8 @@ import { DeleteAgentCommand } from './usecases/delete-agent/delete-agent.command
 import { DeleteAgent } from './usecases/delete-agent/delete-agent.usecase';
 import { GetAgentCommand } from './usecases/get-agent/get-agent.command';
 import { GetAgent } from './usecases/get-agent/get-agent.usecase';
+import { GetAgentRuntimeConfigCommand } from './usecases/get-agent-runtime-config/get-agent-runtime-config.command';
+import { GetAgentRuntimeConfig } from './usecases/get-agent-runtime-config/get-agent-runtime-config.usecase';
 import { type AgentEmojiEntry, ListAgentEmoji } from './usecases/list-agent-emoji/list-agent-emoji.usecase';
 import { ListAgentIntegrationsCommand } from './usecases/list-agent-integrations/list-agent-integrations.command';
 import { ListAgentIntegrations } from './usecases/list-agent-integrations/list-agent-integrations.usecase';
@@ -81,6 +88,8 @@ import { UpdateAgentCommand } from './usecases/update-agent/update-agent.command
 import { UpdateAgent } from './usecases/update-agent/update-agent.usecase';
 import { UpdateAgentIntegrationCommand } from './usecases/update-agent-integration/update-agent-integration.command';
 import { UpdateAgentIntegration } from './usecases/update-agent-integration/update-agent-integration.usecase';
+import { UpdateAgentRuntimeConfigCommand } from './usecases/update-agent-runtime-config/update-agent-runtime-config.command';
+import { UpdateAgentRuntimeConfig } from './usecases/update-agent-runtime-config/update-agent-runtime-config.usecase';
 
 @ThrottlerCategory(ApiRateLimitCategoryEnum.CONFIGURATION)
 @ApiCommonResponses()
@@ -103,6 +112,8 @@ export class AgentsController {
     private readonly listAgentEmojiUsecase: ListAgentEmoji,
     private readonly sendAgentTestEmailUsecase: SendAgentTestEmail,
     private readonly sendAgentWelcomeMessageUsecase: SendAgentWelcomeMessage,
+    private readonly getAgentRuntimeConfigUsecase: GetAgentRuntimeConfig,
+    private readonly updateAgentRuntimeConfigUsecase: UpdateAgentRuntimeConfig,
     private readonly configureWhatsAppWebhookUsecase: ConfigureWhatsAppWebhook,
     private readonly sendWhatsAppTestTemplateUsecase: SendWhatsAppTestTemplate
   ) {}
@@ -126,6 +137,7 @@ export class AgentsController {
     description: 'Creates an agent scoped to the current environment. The identifier must be unique per environment.',
   })
   @RequirePermissions(PermissionsEnum.AGENT_WRITE)
+  @UseFilters(AgentRuntimeExceptionFilter)
   createAgent(@UserSession() user: UserSessionData, @Body() body: CreateAgentRequestDto): Promise<AgentResponseDto> {
     return this.createAgentUsecase.execute(
       CreateAgentCommand.create({
@@ -136,6 +148,9 @@ export class AgentsController {
         identifier: body.identifier,
         description: body.description,
         active: body.active,
+        runtime: body.runtime,
+        managedRuntime: body.managedRuntime,
+        creationSource: body.creationSource,
       })
     );
   }
@@ -478,7 +493,10 @@ export class AgentsController {
   @HttpCode(HttpStatus.NO_CONTENT)
   @ApiOperation({
     summary: 'Delete agent',
-    description: 'Deletes an agent by identifier and removes all agent-integration links.',
+    description:
+      'Deletes an agent by identifier and removes all agent-integration links. ' +
+      'For managed-runtime agents, pass `deleteFromProvider=true` to also archive the agent on the provider side (e.g. Anthropic). ' +
+      'By default only the Novu record is deleted and the provider agent is left intact.',
   })
   @ApiNoContentResponse({
     description: 'The agent was deleted.',
@@ -487,13 +505,86 @@ export class AgentsController {
     description: 'The agent was not found.',
   })
   @RequirePermissions(PermissionsEnum.AGENT_WRITE)
-  deleteAgent(@UserSession() user: UserSessionData, @Param('identifier') identifier: string): Promise<void> {
+  deleteAgent(
+    @UserSession() user: UserSessionData,
+    @Param('identifier') identifier: string,
+    @Query('deleteFromProvider') deleteFromProvider?: string
+  ): Promise<void> {
     return this.deleteAgentUsecase.execute(
       DeleteAgentCommand.create({
         userId: user._id,
         environmentId: user.environmentId,
         organizationId: user.organizationId,
         identifier,
+        deleteFromProvider: deleteFromProvider === 'true',
+      })
+    );
+  }
+
+  @Get('/:identifier/runtime/config')
+  @ApiResponse(AgentRuntimeConfigResponseDto, 200)
+  @ApiOperation({
+    summary: 'Get agent runtime config',
+    description:
+      'Fetches the live runtime configuration for a managed agent from the provider ' +
+      '(model, system prompt, MCP servers, tools). Returns 422 for self-hosted agents.',
+  })
+  @ApiNotFoundResponse({ description: 'Agent or its runtime integration was not found.' })
+  @ApiConflictResponse({
+    description:
+      'AGENT_RUNTIME_DRIFT — the agent record exists in Novu but the provider reports it as deleted or unreachable. ' +
+      'Re-provision or delete the agent.',
+  })
+  @RequirePermissions(PermissionsEnum.AGENT_READ)
+  @UseFilters(AgentRuntimeExceptionFilter)
+  getAgentRuntimeConfig(
+    @UserSession() user: UserSessionData,
+    @Param('identifier') identifier: string
+  ): Promise<AgentRuntimeConfigResponseDto> {
+    return this.getAgentRuntimeConfigUsecase.execute(
+      GetAgentRuntimeConfigCommand.create({
+        userId: user._id,
+        environmentId: user.environmentId,
+        organizationId: user.organizationId,
+        identifier,
+      })
+    );
+  }
+
+  @Patch('/:identifier/runtime/config')
+  @ApiResponse(AgentRuntimeConfigResponseDto, 200)
+  @ApiOperation({
+    summary: 'Update agent runtime config',
+    description:
+      'Applies a partial update to the managed agent runtime config on the provider. ' +
+      'Accepts any combination of model, systemPrompt, mcpServers, tools, and skills. ' +
+      'Server-side diffing issues the minimal set of provider API calls. ' +
+      'An empty body is accepted and returns the current config unchanged.',
+  })
+  @ApiNotFoundResponse({ description: 'Agent or its runtime integration was not found.' })
+  @ApiConflictResponse({
+    description:
+      'AGENT_RUNTIME_DRIFT — the agent record exists in Novu but the provider reports it as deleted or unreachable. ' +
+      'Re-provision or delete the agent.',
+  })
+  @RequirePermissions(PermissionsEnum.AGENT_WRITE)
+  @UseFilters(AgentRuntimeExceptionFilter)
+  updateAgentRuntimeConfig(
+    @UserSession() user: UserSessionData,
+    @Param('identifier') identifier: string,
+    @Body() body: PatchAgentRuntimeConfigRequestDto
+  ): Promise<AgentRuntimeConfigResponseDto> {
+    return this.updateAgentRuntimeConfigUsecase.execute(
+      UpdateAgentRuntimeConfigCommand.create({
+        userId: user._id,
+        environmentId: user.environmentId,
+        organizationId: user.organizationId,
+        identifier,
+        model: body.model,
+        systemPrompt: body.systemPrompt,
+        mcpServers: body.mcpServers,
+        tools: body.tools,
+        skills: body.skills,
       })
     );
   }

diff --git a/apps/api/src/app/agents/agents.module.ts b/apps/api/src/app/agents/agents.module.ts
@@ -4,6 +4,7 @@ import {
   ChannelEndpointRepository,
   ConversationActivityRepository,
   ConversationRepository,
+  IntegrationRepository,
 } from '@novu/dal';
 
 import { AuthModule } from '../auth/auth.module';
@@ -12,6 +13,7 @@ import { SharedModule } from '../shared/shared.module';
 import { AgentEmailActionsController } from './agent-email-actions.controller';
 import { AgentsController } from './agents.controller';
 import { AgentsWebhookController } from './agents-webhook.controller';
+import { AgentRuntimeExceptionFilter } from './filters/agent-runtime-exception.filter';
 import { AgentAttachmentStorage } from './services/agent-attachment-storage.service';
 import { AgentConfigResolver } from './services/agent-config-resolver.service';
 import { AgentConversationService } from './services/agent-conversation.service';
@@ -27,10 +29,12 @@ import { USE_CASES } from './usecases';
   controllers: [AgentsController, AgentsWebhookController, AgentEmailActionsController],
   providers: [
     ...USE_CASES,
+    AgentRuntimeExceptionFilter,
     ChannelConnectionRepository,
     ChannelEndpointRepository,
     ConversationRepository,
     ConversationActivityRepository,
+    IntegrationRepository,
     AgentAttachmentStorage,
     AgentConfigResolver,
     AgentSubscriberResolver,

diff --git a/apps/api/src/app/agents/dtos/agent-integration-response.dto.ts b/apps/api/src/app/agents/dtos/agent-integration-response.dto.ts
@@ -17,8 +17,12 @@ export class AgentIntegrationResponseIntegrationDto {
   @ApiProperty()
   providerId: string;
 
-  @ApiProperty({ enum: ChannelTypeEnum, enumName: 'ChannelTypeEnum' })
-  channel: ChannelTypeEnum;
+  @ApiPropertyOptional({
+    description: 'Delivery channel; not set for agent-runtime integrations.',
+    enum: ChannelTypeEnum,
+    enumName: 'ChannelTypeEnum',
+  })
+  channel?: ChannelTypeEnum;
 
   @ApiProperty()
   active: boolean;

diff --git a/apps/api/src/app/agents/dtos/agent-integration-summary.dto.ts b/apps/api/src/app/agents/dtos/agent-integration-summary.dto.ts
@@ -1,4 +1,4 @@
-import { ApiProperty } from '@nestjs/swagger';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { ChannelTypeEnum } from '@novu/shared';
 
 export class AgentIntegrationSummaryDto {
@@ -14,8 +14,12 @@ export class AgentIntegrationSummaryDto {
   @ApiProperty()
   identifier: string;
 
-  @ApiProperty({ enum: ChannelTypeEnum, enumName: 'ChannelTypeEnum' })
-  channel: ChannelTypeEnum;
+  @ApiPropertyOptional({
+    description: 'Delivery channel; not set for agent-runtime integrations.',
+    enum: ChannelTypeEnum,
+    enumName: 'ChannelTypeEnum',
+  })
+  channel?: ChannelTypeEnum;
 
   @ApiProperty()
   active: boolean;

diff --git a/apps/api/src/app/agents/dtos/agent-response.dto.ts b/apps/api/src/app/agents/dtos/agent-response.dto.ts
@@ -1,8 +1,21 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import type { AgentRuntime } from '@novu/shared';
+import { AgentCreationSourceEnum } from '@novu/shared';
 
 import { AgentBehaviorDto } from './agent-behavior.dto';
 import { AgentIntegrationSummaryDto } from './agent-integration-summary.dto';
 
+export class ManagedRuntimeResponseDto {
+  @ApiProperty()
+  providerId: string;
+
+  @ApiProperty()
+  integrationId: string;
+
+  @ApiProperty()
+  externalAgentId: string;
+}
+
 export class AgentResponseDto {
   @ApiProperty()
   _id: string;
@@ -31,6 +44,18 @@ export class AgentResponseDto {
   @ApiPropertyOptional({ description: 'Whether the dev bridge override is active' })
   devBridgeActive?: boolean;
 
+  @ApiPropertyOptional({
+    enum: ['self-hosted', 'managed'],
+    description: 'Whether the agent brain is self-hosted (bridge) or managed by a third-party provider',
+  })
+  runtime?: AgentRuntime;
+
+  @ApiPropertyOptional({
+    type: ManagedRuntimeResponseDto,
+    description: 'Present when runtime is "managed". Contains provider and external identifiers.',
+  })
+  managedRuntime?: ManagedRuntimeResponseDto;
+
   @ApiProperty()
   _environmentId: string;
 
@@ -43,6 +68,12 @@ export class AgentResponseDto {
   @ApiProperty()
   updatedAt: string;
 
+  @ApiPropertyOptional({
+    enum: AgentCreationSourceEnum,
+    description: 'Which section of the Novu Dashboard was used to create this agent.',
+  })
+  creationSource?: AgentCreationSourceEnum;
+
   @ApiPropertyOptional({ type: [AgentIntegrationSummaryDto] })
   integrations?: AgentIntegrationSummaryDto[];
 }