n8n/dist/modules/agents/integrations/agent-chat-integration.d.ts

n8n Workflow Automation Tool

import { AgentIntegrationConfig, type RichCardComponentType } from '@n8n/api-types';
import type { Thread, Author, Message } from 'chat';
import type { Logger } from 'n8n-workflow';
import type { ChatInstance } from './chat-integration.service';
import type { SuspendComponent } from './component-mapper';
import type { IntegrationAction, IntegrationActionDefinition, IntegrationActionResult, IntegrationContextQuery, IntegrationContextQueryDefinition, IntegrationMessageContext, IntegrationToolConnectionDescriptor, ReplyExpectation } from './integration-tools';
export interface AgentChatIntegrationContext {
    agentId: string;
    projectId: string;
    credentialId: string;
    credential: Record<string, unknown>;
    ingressEnabled: boolean;
    webhookUrlFor: (platform: string) => string;
}
export interface UnauthenticatedWebhookResponse {
    status: number;
    body: unknown;
}
export interface WebhookRequestContext {
    headers: Readonly<Record<string, string | string[] | undefined>>;
    body: unknown;
}
export type WebhookRequestResolution = {
    type: 'reject';
    response: UnauthenticatedWebhookResponse;
} | {
    type: 'select';
    connectionSelector: string;
} | {
    type: 'no_match';
};
export interface AgentChatIntegrationBuilderGuidance {
    capabilities: string[];
    useIntegrationWhen: string[];
    useNodeToolWhen: string[];
}
export interface PlatformAgentContext {
    agentUserId?: string;
}
export interface BridgeStatusHandle {
    clearBeforeResponse(): Promise<void>;
}
export declare function onceStatusHandle(handle: BridgeStatusHandle | undefined): BridgeStatusHandle | undefined;
export interface BridgeExecutionContext {
    platformAgentContext: PlatformAgentContext;
    forceBuffered?: boolean;
    statusHandle?: BridgeStatusHandle;
    historyContext?: string;
}
export type BridgeResumeExecutionContext = Pick<BridgeExecutionContext, 'forceBuffered' | 'statusHandle'>;
export interface BridgeMessageContextParams {
    chat: ChatInstance;
    thread: Thread<unknown, unknown>;
    message: Message<unknown>;
    logger: Logger;
    agentId: string;
    statusRetry?: AbortController;
    isNewMention: boolean;
    replyExpectation: ReplyExpectation;
}
export interface ActionDecisionMessageParams {
    approved?: boolean;
    selectedLabel?: string;
    raw: unknown;
    user: Author;
}
export type ActionDecisionMessageFormatter = (params: ActionDecisionMessageParams) => string | undefined;
export interface SettleActionMessageParams {
    agentId: string;
    integration: AgentIntegrationConfig;
    threadId: string;
    messageId: string;
    content: string;
}
export type SettleActionMessage = (params: SettleActionMessageParams) => Promise<void>;
export declare abstract class AgentChatIntegration {
    abstract readonly type: string;
    abstract readonly credentialTypes: string[];
    abstract readonly displayLabel: string;
    abstract readonly displayIcon: string;
    readonly builderGuidance?: AgentChatIntegrationBuilderGuidance;
    readonly supportedComponents?: readonly RichCardComponentType[];
    readonly contextToolDefinitions: IntegrationContextQueryDefinition[];
    readonly actionToolDefinitions: IntegrationActionDefinition[];
    readonly contextToolGuidance?: string[];
    readonly actionToolGuidance?: string[];
    get contextQueries(): IntegrationContextQuery[];
    get actions(): IntegrationAction[];
    readonly needsShortCallbackData: boolean;
    readonly deleteActionMessageBeforeResume: boolean;
    readonly disableStreaming: boolean;
    readonly internal: boolean;
    readonly requiresChatInstance: boolean;
    requiresLeader(): boolean;
    abstract createAdapter(ctx: AgentChatIntegrationContext): Promise<unknown>;
    validateConfig?(integration: AgentIntegrationConfig): void;
    handleUnauthenticatedWebhook?(body: unknown): UnauthenticatedWebhookResponse | undefined;
    resolveWebhookRequest?(request: WebhookRequestContext): WebhookRequestResolution;
    matchesWebhookConnection?(credential: Record<string, unknown>, connectionSelector: string): boolean;
    onBeforeConnect?(ctx: AgentChatIntegrationContext): Promise<void>;
    onAfterConnect?(ctx: AgentChatIntegrationContext): Promise<void>;
    onBeforeDisconnect?(ctx: AgentChatIntegrationContext): Promise<void>;
    prepareSentThread?(thread: Thread<unknown, unknown>): Promise<void>;
    onConnected?(ctx: AgentChatIntegrationContext): Promise<void>;
    onDisconnected?(ctx: AgentChatIntegrationContext): Promise<void>;
    normalizeComponents?(components: SuspendComponent[]): SuspendComponent[];
    formatThreadId?: {
        fromSdk: (thread: Thread<unknown, unknown>) => string;
        toSdk: (threadId: string) => string;
    };
    isUserAllowed?(author: Author, settings: AgentIntegrationConfig | undefined): boolean;
    getPlatformAgentContext?(chat: ChatInstance): PlatformAgentContext;
    prepareInboundText?(text: string, context: PlatformAgentContext): string;
    getReplyExpectation?(params: {
        message: Message<unknown>;
        isNewMention: boolean;
        platformAgentContext: PlatformAgentContext;
    }): ReplyExpectation;
    formatActionDecisionMessage?(params: ActionDecisionMessageParams): string | undefined;
    settleActionMessage?(params: SettleActionMessageParams): Promise<void>;
    shouldSubscribeToNewMention?(params: {
        thread: Thread<unknown, unknown>;
        message: Message<unknown>;
    }): boolean;
    createBridgeExecutionContext?(params: BridgeMessageContextParams): Promise<BridgeExecutionContext>;
    createResumeExecutionContext?(params: {
        chat: ChatInstance;
        thread: Thread<unknown, unknown>;
        logger: Logger;
        agentId: string;
    }): Promise<BridgeResumeExecutionContext>;
    executeContextQuery?(params: PlatformContextQueryParams): Promise<unknown>;
    executeAction?(params: PlatformActionParams): Promise<IntegrationActionResult | undefined>;
}
export interface PlatformContextQueryParams {
    chat: ChatInstance | undefined;
    descriptor: IntegrationToolConnectionDescriptor;
    query: IntegrationContextQuery;
    input: Record<string, unknown>;
}
export interface PlatformActionParams {
    chat: ChatInstance | undefined;
    descriptor: IntegrationToolConnectionDescriptor;
    action: IntegrationAction;
    input: Record<string, unknown>;
    currentMessageContext?: IntegrationMessageContext;
}
export declare class ChatIntegrationRegistry {
    private readonly integrations;
    register(integration: AgentChatIntegration): void;
    get(type: string): AgentChatIntegration | undefined;
    require(type: string): AgentChatIntegration;
    list(): AgentChatIntegration[];
    listPublic(): AgentChatIntegration[];
}