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
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
import { flowStructureUtil } from '@activepieces/core-execution'
import { AGENT_STEP_TIMEOUT_MS } from '@activepieces/core-piece-types'
import { ActivepiecesError, apId, ApId, ErrorCode, isNil, spreadIfDefined, tryCatch, unique } from '@activepieces/core-utils'
import { AgentConfig, AgentOutputField, AgentPieceProps, AgentRunSource, AgentTool, AgentToolType, AIProviderName, DEFAULT_AGENT_MAX_STEPS, LATEST_JOB_DATA_SCHEMA_VERSION, MAX_AGENT_OUTPUT_FIELDS, MAX_AGENT_STEP_BUDGET, MAX_AGENT_TEXT_LENGTH, MAX_AGENT_TOOLS, PrincipalType, TASK_COMPLETION_TOOL_NAME, WorkerJobType } from '@activepieces/shared'
import { FastifyBaseLogger } from 'fastify'
import { FastifyPluginAsyncZod } from 'fastify-type-provider-zod'
import { StatusCodes } from 'http-status-codes'
import { z } from 'zod'
import { aiCallContext } from '../../ai/usage/ai-call-context'
import { securityAccess } from '../../core/security/authorization/fastify-security'
import { redisConnections } from '../../database/redis-connections'
import { flowRunService } from '../../flows/flow-run/flow-run-service'
import { flowVersionService } from '../../flows/flow-version/flow-version.service'
import { assertCreditsAndAppSumoNotExceeded } from '../../platform/billing-provider'
import { projectService } from '../../project/project-service'
import { waitpointService } from '../../waitpoints/waitpoint-service'
import { WaitpointStatus } from '../../waitpoints/waitpoint-types'
import { jobQueue, JobType } from '../../workers/job-queue/job-queue'
import { agentHelpers } from './agent-helpers'
import { agentService } from './agent-service'
const RUN_PRINCIPALS = [PrincipalType.ENGINE] as const
export const agentRunController: FastifyPluginAsyncZod = async (app) => {
app.post('/runs', StartAgentRunRoute, async (request, reply) => {
const { instruction, flowRunId, waitpointId, agentId, providerConfigId, tools: inlineTools } = request.body
if (request.principal.type !== PrincipalType.ENGINE) {
throw new ActivepiecesError({
code: ErrorCode.AUTHORIZATION,
params: { message: 'Only a running flow can start an agent run' },
})
}
const { projectId, platform } = request.principal
const { allowed, count } = await agentHelpers.incrementAndCheckLimit({ key: `flow-agent-runs:${projectId}`, limit: RUNS_PER_MINUTE, ttlSeconds: 60 })
if (!allowed) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: `This project started ${count} agent runs in the last minute, above the limit of ${RUNS_PER_MINUTE}` } })
}
if (!isNil(agentId) && (inlineTools?.length ?? 0) > 0) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: 'This step both links an agent and carries its own tools, so which one to run is ambiguous' } })
}
if (!isNil(agentId)) {
await agentHelpers.assertAgentsSurfaceAvailable({ platformId: platform.id, log: request.log })
}
const linked = isNil(agentId) ? null : await resolvePublishedAgent({ projectId, externalId: agentId, flowRunId, waitpointId, log: request.log })
const runFields = isNil(linked)
? {
tools: request.body.tools,
structuredOutput: request.body.structuredOutput,
maxSteps: request.body.maxSteps ?? DEFAULT_AGENT_MAX_STEPS,
modelName: request.body.modelName ?? null,
...spreadIfDefined('provider', request.body.provider),
...spreadIfDefined('providerConfigId', providerConfigId),
...spreadIfDefined('modelTierId', request.body.modelTierId),
}
: agentHelpers.jobFieldsFromConfig({ config: linked.config })
const { tools, structuredOutput, provider } = runFields
const supportedToolTypes = [AgentToolType.PIECE, AgentToolType.MCP, AgentToolType.FLOW, AgentToolType.KNOWLEDGE_BASE]
const supportedTools = (tools ?? []).filter((tool) => supportedToolTypes.includes(tool.type))
const unsupported = unique((tools ?? []).map((tool) => tool.type)).filter((type) => !supportedToolTypes.includes(type))
if (unsupported.length > 0) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: `An agent step cannot use ${unsupported.join(' or ')} tools yet` } })
}
const usesCompletionTool = (structuredOutput?.length ?? 0) > 0
const reserved = (tools ?? []).filter((tool) => tool.toolName.startsWith(BUILT_IN_TOOL_PREFIX) || (usesCompletionTool && tool.toolName === TASK_COMPLETION_TOOL_NAME)).map((tool) => tool.toolName)
if (reserved.length > 0) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: `A tool cannot be named ${unique(reserved).join(' or ')}: names starting with "${BUILT_IN_TOOL_PREFIX}" belong to the agent's own tools` } })
}
const duplicated = unique((tools ?? []).map((tool) => tool.toolName).filter((name, index, all) => all.indexOf(name) !== index))
if (duplicated.length > 0) {
throw new ActivepiecesError({
code: ErrorCode.VALIDATION,
params: { message: `Two tools are both named ${duplicated.join(', ')}: each tool on a step needs its own name, or one silently replaces the other` },
})
}
const flowTools = await agentHelpers.resolveFlowTools({ projectId, tools: tools ?? [], log: request.log })
await agentHelpers.assertRunProviderConfigured({ platformId: platform.id, provider, providerConfigId: runFields.providerConfigId, modelTierId: runFields.modelTierId, scope: agentHelpers.runScopeOrThrow({ projectId }), log: request.log })
await assertCreditsAndAppSumoNotExceeded({ platformId: platform.id, log: request.log })
const { ownerId } = await projectService(request.log).getOneOrThrow(projectId)
const flowRun = await aiCallContext.runOf({ flowRunId, projectId })
const conversationId = apId()
const runId = apId()
const log = request.log.child({ conversation: { id: conversationId }, run: { id: runId } })
if (!isNil(agentId)) {
await claimWaitpointOrThrow({ waitpointId })
}
const { error: enqueueError } = await tryCatch(() => jobQueue(log).add({
id: apId(),
type: JobType.ONE_TIME,
data: {
schemaVersion: LATEST_JOB_DATA_SCHEMA_VERSION,
jobType: WorkerJobType.EXECUTE_AGENT_RUN,
conversationId,
runId,
projectId,
platformId: platform.id,
userId: ownerId,
userMessage: instruction,
source: AgentRunSource.FLOW_STEP,
flowRunId,
...spreadIfDefined('flowId', flowRun.flowId),
environment: flowRun.environment,
waitpointId,
flowTools,
...spreadIfDefined('agentId', linked?.id),
...runFields,
tools: supportedTools,
},
}))
if (!isNil(enqueueError)) {
await releaseWaitpointClaim({ waitpointId })
throw enqueueError
}
log.info({ project: { id: projectId } }, '[agentRunController] Enqueued flow-step agent run')
return reply.status(StatusCodes.OK).send({ conversationId, runId })
})
}
async function resolvePublishedAgent({ projectId, externalId, flowRunId, waitpointId, log }: {
projectId: string
externalId: string
flowRunId: string
waitpointId: string
log: FastifyBaseLogger
}): Promise<{ id: string, config: AgentConfig }> {
const flowRun = await flowRunService(log).getOneOrThrow({ id: flowRunId, projectId })
const waitpoint = await waitpointService(log).findByIdAndFlowRunId({ waitpointId, flowRunId, projectId })
if (isNil(waitpoint)) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: 'That waitpoint does not belong to this run, so there is no step to run an agent for' } })
}
if (waitpoint.status !== WaitpointStatus.PENDING) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: 'That step has already had its agent run. A finished waitpoint cannot start another one.' } })
}
const flowVersion = await flowVersionService(log).getOneOrThrow(flowRun.flowVersionId)
const named = flowStructureUtil.getAllSteps(flowVersion.trigger).filter((candidate) => candidate.name === waitpoint.stepName)
const namingThisAgent = named.filter((candidate) => flowStructureUtil.isAgentPiece(candidate) && candidate.settings.input?.[AgentPieceProps.AGENT_ID] === externalId)
if (namingThisAgent.length === 0) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: 'This step did not name that agent when the flow was saved. An agent has to be picked on the step, not supplied while the flow runs.' } })
}
if (namingThisAgent.length !== named.length) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: `More than one step in this flow is called "${waitpoint.stepName}" and they do not run the same agent, so which one paused is ambiguous. Rename one of them.` } })
}
const agent = await agentService(log).getProjectVisibleByExternalId({ projectId, externalId })
if (isNil(agent)) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: 'The agent this step runs is not available to this project. A flow runs unattended, so a step can only run an agent the whole project can see.' } })
}
if (isNil(agent.published)) {
throw new ActivepiecesError({ code: ErrorCode.VALIDATION, params: { message: `Publish "${agent.displayName}" before a flow can run it: a flow runs the published version, so there is nothing to run yet.` } })
}
return { id: agent.id, config: agent.published }
}
async function releaseWaitpointClaim({ waitpointId }: { waitpointId: string }): Promise<void> {
const redis = await redisConnections.useExisting()
await redis.del(waitpointClaimKey({ waitpointId }))
}
function waitpointClaimKey({ waitpointId }: { waitpointId: string }): string {
return `agent-run-claim:${waitpointId}`
}
async function claimWaitpointOrThrow({ waitpointId }: { waitpointId: string }): Promise<void> {
const redis = await redisConnections.useExisting()
const claimed = await redis.set(waitpointClaimKey({ waitpointId }), '1', 'EX', AGENT_RUN_CLAIM_TTL_SECONDS, 'NX')
if (isNil(claimed)) {
throw new ActivepiecesError({
code: ErrorCode.VALIDATION,
params: { message: 'An agent run for that step is already starting. A step runs its agent once, so this request was not started again.' },
})
}
}
const WAITPOINT_RESUME_LAG_ALLOWANCE_SECONDS = 60 * 60
const AGENT_RUN_CLAIM_TTL_SECONDS = AGENT_STEP_TIMEOUT_MS / 1_000 + WAITPOINT_RESUME_LAG_ALLOWANCE_SECONDS
const RUNS_PER_MINUTE = 60
const BUILT_IN_TOOL_PREFIX = 'ap_'
const StartAgentRunRequest = z.object({
instruction: z.string().min(1).max(MAX_AGENT_TEXT_LENGTH),
flowRunId: ApId,
waitpointId: ApId,
agentId: z.optional(ApId),
tools: z.array(AgentTool).max(MAX_AGENT_TOOLS).optional(),
structuredOutput: z.array(AgentOutputField).max(MAX_AGENT_OUTPUT_FIELDS).optional(),
maxSteps: z.number().int().positive().max(MAX_AGENT_STEP_BUDGET).optional(),
modelName: z.string().optional(),
provider: z.enum(AIProviderName).optional(),
providerConfigId: z.string().optional(),
modelTierId: z.optional(ApId),
})
const StartAgentRunResponse = z.object({
conversationId: z.string(),
runId: z.string(),
})
const StartAgentRunRoute = {
config: {
security: securityAccess.publicPlatform(RUN_PRINCIPALS),
},
schema: {
tags: ['agent'],
body: StartAgentRunRequest,
response: { [StatusCodes.OK]: StartAgentRunResponse },
},
}