Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

10.8 KB
Raw Blame
import { isNil, spreadIfDefined } from '@activepieces/core-utils'
import { LATEST_CONTEXT_VERSION } from '@activepieces/pieces-framework'
import { AI_ROUTER_MAX_STATE_LENGTH, AiRouterAction, AiRouterActionSettings, AiRouterEvaluationError, AiRouterMatchMode, AiRouterStepOutput, BranchExecutionType, ChooseAiRouteResponse, FlowActionType, FlowRunStatus, ResumePayload, StepOutputStatus } from '@activepieces/shared'
import { z } from 'zod'
import { aiRouterApi } from '../api/ai-router-api'
import { waitpointClient } from '../piece-context/waitpoint-client'
import { utils } from '../utils'
import { BaseExecutor, failStep } from './base-executor'
import { executeBranches } from './branch-execution'
import { EngineConstants } from './context/engine-constants'
import { FlowExecutorContext } from './context/flow-execution-context'

export const aiRouterExecuter: BaseExecutor<AiRouterAction> = {
    async handle({
        action,
        executionState,
        constants,
    }) {
        const stepStartTime = performance.now()
        const stored = executionState.getStepOutput(action.name)
        if (stored?.type === FlowActionType.AI_ROUTER && stored.status === StepOutputStatus.SUCCEEDED && !isNil(stored.output)) {
            return executeBranches({
                action,
                executionState,
                constants,
                stepOutput: AiRouterStepOutput.init({ input: stored.input }).setOutput(stored.output),
                evaluations: stored.output.branches.map((branch) => branch.evaluation),
                stopAfterFirstMatch: false,
            })
        }
        const resuming = stored?.status === StepOutputStatus.PAUSED

        const { data: resolved, error: resolveError } = await utils.tryCatchAndThrowOnEngineError(() =>
            constants.getPropsResolver({ contextVersion: LATEST_CONTEXT_VERSION }).resolve<AiRouterActionSettings>({
                unresolvedInput: {
                    ...action.settings,
                },
                executionState,
            }),
        )
        if (resolveError) {
            return failStep({
                action,
                executionState,
                stepOutput: AiRouterStepOutput.init({ input: {} }),
                error: resolveError,
                durationMs: performance.now() - stepStartTime,
            })
        }
        const { censoredInput, resolvedInput } = resolved
        const matchMode = resolvedInput.matchMode ?? AiRouterMatchMode.BEST_MATCH
        const bestMatch = matchMode === AiRouterMatchMode.BEST_MATCH
        const options = toOptions(askableBranches({ branches: resolvedInput.branches, bestMatch }))
        const request = {
            apiUrl: constants.internalApiUrl,
            engineToken: constants.engineToken,
            state: truncate(asPlainText(resolvedInput.text)),
            question: asPlainText(resolvedInput.question),
            options,
            matchMode,
            flowId: constants.flowId,
            flowRunId: constants.flowRunId,
        }
        const nothingToAsk = Object.keys(options).length === 0

        if (!resuming && !nothingToAsk && canPause(constants)) {
            const { data: paused, error: pauseError } = await utils.tryCatchAndThrowOnEngineError(() =>
                pauseForAnswer({ action, executionState, constants, censoredInput, request }),
            )
            if (pauseError) {
                return failStep({
                    action,
                    executionState,
                    stepOutput: AiRouterStepOutput.init({ input: censoredInput }),
                    error: pauseError,
                    durationMs: performance.now() - stepStartTime,
                })
            }
            return paused
        }

        const { data: answer, error: answerError } = await utils.tryCatchAndThrowOnEngineError(() => {
            if (nothingToAsk) {
                return Promise.resolve<ChooseAiRouteResponse>({ matched: [] })
            }
            if (resuming) {
                return Promise.resolve(answerFromResume(constants.resumePayload))
            }
            return aiRouterApi.choose(request)
        })
        if (answerError) {
            return failStep({
                action,
                executionState,
                stepOutput: AiRouterStepOutput.init({ input: censoredInput }),
                error: answerError,
                durationMs: performance.now() - stepStartTime,
            })
        }

        const confident = confidentRoutes({ answer, minConfidence: resolvedInput.minConfidence, bestMatch })
        const evaluations = bestMatch
            ? bestMatchEvaluations({ branches: resolvedInput.branches, confident })
            : allMatchesEvaluations({ branches: resolvedInput.branches, confident })

        const stepOutput = AiRouterStepOutput.init({
            input: censoredInput,
        }).setOutput({
            branches: resolvedInput.branches.map((branch, index) => ({
                branchName: branch.branchName,
                branchIndex: index + 1,
                evaluation: evaluations[index],
            })),
            ...spreadIfDefined('choice', bestMatch ? chosenName({ branches: resolvedInput.branches, evaluations }) : undefined),
            ...spreadIfDefined('probabilities', answer.probabilities),
        }).setDuration(performance.now() - stepStartTime)

        return executeBranches({
            action,
            executionState,
            constants,
            stepOutput,
            evaluations,
            stopAfterFirstMatch: bestMatch,
        })
    },
}

async function pauseForAnswer({ action, executionState, constants, censoredInput, request }: PauseForAnswerParams): Promise<FlowExecutorContext> {
    const waitpoint = await waitpointClient.create({
        apiUrl: constants.internalApiUrl,
        engineToken: constants.engineToken,
        flowRunId: constants.flowRunId,
        projectId: constants.projectId,
        stepName: executionState.currentPath.waitpointKeyFor({ stepName: action.name }),
        type: 'WEBHOOK',
        version: 'V1',
        resumeDateTime: new Date(Date.now() + ANSWER_BACKSTOP_MS).toISOString(),
        workerHandlerId: constants.workerHandlerId ?? undefined,
        httpRequestId: constants.httpRequestId ?? undefined,
    })
    await aiRouterApi.start({ ...request, waitpointId: waitpoint.id })
    const paused = AiRouterStepOutput.init({ input: censoredInput }).setStatus(StepOutputStatus.PAUSED)
    return (await executionState.upsertStep(action.name, paused)).incrementStepsExecuted().setVerdict({ status: FlowRunStatus.PAUSED })
}

function answerFromResume(payload: ResumePayload | undefined): ChooseAiRouteResponse {
    const parsed = ResumeBody.safeParse(payload?.body)
    if (parsed.success && !isNil(parsed.data.failure)) {
        throw new AiRouterEvaluationError({ message: parsed.data.failure })
    }
    if (!parsed.success || isNil(parsed.data.output)) {
        throw new AiRouterEvaluationError({ message: 'The routing model did not answer before the step timed out' })
    }
    return parsed.data.output
}

function canPause(constants: EngineConstants): boolean {
    return !constants.actionRunMode && isNil(constants.stepNameToTest)
}

function askableBranches({ branches, bestMatch }: { branches: AiRouterActionSettings['branches'], bestMatch: boolean }): AiRouterActionSettings['branches'] {
    if (bestMatch) {
        return branches
    }
    return branches.filter((branch) => branch.branchType !== BranchExecutionType.FALLBACK)
}

function toOptions(branches: AiRouterActionSettings['branches']): Record<string, string> {
    const options: Record<string, string> = {}
    for (const branch of branches) {
        if (!Object.hasOwn(options, branch.branchName)) {
            options[branch.branchName] = criterionOf(branch)
        }
    }
    return options
}

function criterionOf(branch: AiRouterActionSettings['branches'][number]): string {
    const description = branch.description?.trim()
    if (!isNil(description) && description.length > 0) {
        return description
    }
    return branch.branchType === BranchExecutionType.FALLBACK ? FALLBACK_CRITERION : branch.branchName
}

function confidentRoutes({ answer, minConfidence, bestMatch }: ConfidentRoutesParams): string[] {
    if (isNil(minConfidence)) {
        return answer.matched
    }
    if (!bestMatch && !isNil(answer.probabilities)) {
        return Object.entries(answer.probabilities).filter(([, probability]) => probability >= minConfidence).map(([route]) => route)
    }
    return answer.matched.filter((route) => {
        const confidence = answer.probabilities?.[route]
        return isNil(confidence) || confidence >= minConfidence
    })
}

function bestMatchEvaluations({ branches, confident }: EvaluationsParams): boolean[] {
    const fallbackName = branches.find((branch) => branch.branchType === BranchExecutionType.FALLBACK)?.branchName
    const answered = confident[0]
    const known = !isNil(answered) && branches.some((branch) => branch.branchName === answered)
    const chosen = known ? answered : fallbackName
    return branches.map((branch) => branch.branchName === chosen)
}

function allMatchesEvaluations({ branches, confident }: EvaluationsParams): boolean[] {
    const matched = new Set(confident)
    const withoutFallback = branches.map((branch) => branch.branchType !== BranchExecutionType.FALLBACK && matched.has(branch.branchName))
    const nothingMatched = withoutFallback.every((match) => !match)
    return branches.map((branch, index) => branch.branchType === BranchExecutionType.FALLBACK ? nothingMatched : withoutFallback[index])
}

function chosenName({ branches, evaluations }: { branches: AiRouterActionSettings['branches'], evaluations: boolean[] }): string | undefined {
    const index = evaluations.findIndex((evaluation) => evaluation)
    return index === -1 ? undefined : branches[index].branchName
}

function asPlainText(value: unknown): string {
    if (typeof value === 'string') {
        return value
    }
    return JSON.stringify(value) ?? ''
}

function truncate(text: string): string {
    const cut = text.slice(0, AI_ROUTER_MAX_STATE_LENGTH)
    return LONE_HIGH_SURROGATE_AT_END.test(cut) ? cut.slice(0, -1) : cut
}

type EvaluationsParams = {
    branches: AiRouterActionSettings['branches']
    confident: string[]
}

type ConfidentRoutesParams = {
    answer: ChooseAiRouteResponse
    minConfidence: number | undefined
    bestMatch: boolean
}

const FALLBACK_CRITERION = 'Anything that fits none of the other routes'
const ANSWER_BACKSTOP_MS = 10 * 60 * 1000
const LONE_HIGH_SURROGATE_AT_END = /[\uD800-\uDBFF]$/

const ResumeBody = z.object({
    output: ChooseAiRouteResponse.optional(),
    failure: z.string().optional(),
})

type PauseForAnswerParams = {
    action: AiRouterAction
    executionState: FlowExecutorContext
    constants: EngineConstants
    censoredInput: unknown
    request: Parameters<typeof aiRouterApi.choose>[0]
}