Add pre-execution validation for tool and workflow execution

[devincapriola]

VoltAgent provides guardrails, workflows, and tool integrations that enable agents to take real actions (API calls, tool execution, etc).

It would be valuable to have a deterministic validation step at the moment of execution to ensure consistency and correctness of these actions.

Currently:

• actions are generated and passed through workflows
• guardrails and validation logic guide behavior
• execution depends on the final payload produced at runtime

However, there does not appear to be a system-level validation step that verifies the exact payload at the execution boundary.

Adding validation at execution would help ensure that the final action being executed is complete, expected, and consistent with system constraints.

Suggested approach

Introduce a validation step before execution that verifies:

• tool or workflow being executed
• parameters (schema + expected values)
• agent context
• destination or external system
• timestamp / validity window
• optional nonce or replay protection

If validation fails → execution does not occur.

This could be implemented as a wrapper around execution functions, ensuring validation is consistently enforced across all workflows rather than relying on individual configurations.

Context

Guardrails and validation logic are valuable for guiding behavior, but a final validation step at execution helps ensure correctness at the point where actions are actually committed.

[tracilyn-io]

Pre-execution validation would close a real gap. Right now if a tool's input schema is satisfied but the semantic constraints aren't (e.g., a file path that exists but points outside an allowed directory), the agent proceeds. A validation hook before execution gives you a place to enforce those constraints without embedding them in every tool implementation. Would the proposed interface allow async validation (e.g., checking permissions against an external policy service), or is this scoped to synchronous checks only?

[devincapriola]

Async validation would make sense here.

I’d treat synchronous validation as the baseline for fast local checks (schema, expected values, execution context), and allow optional async validation for cases where external checks are needed.

That would cover things like:

• permission checks against a policy service
• validating access to external resources
• enforcing environment or tenant-specific constraints

The key part is that execution stays blocked until validation completes successfully.

[omeraplak]

Thanks again for opening this and for the clear write-up.

I added a first implementation in #1219 that introduces pre-execution validators for both agent tool execution and workflow execution. The goal is to give VoltAgent a deterministic execution-boundary check that can inspect the final tool/workflow payload and context right before anything actually runs.

Validators can be synchronous or asynchronous, so they can call policy services, tenant permission APIs, nonce stores, or other external checks before allowing execution.

Example usage for tool execution:

const agent = new Agent({
  name: "Policy Controlled Assistant",
  instructions: "You enforce tenant policy.",
  model: "openai/gpt-4o",
  tools: [updateRecordTool],
  executionValidators: {
    tools: [
      async ({ toolName, args, operationContext }) => {
        const tenant = operationContext?.requestHeaders?.["x-tenant-id"];
        const allowed = await checkTenantToolAccess({
          tenant,
          toolName,
          args,
        });

        if (!allowed) {
          return {
            pass: false,
            message: "This tenant cannot update records.",
            code: "TOOL_TENANT_DENIED",
            httpStatus: 403,
            metadata: { tenant, args },
          };
        }
      },
    ],
  },
});

Example usage for workflow execution:

const workflow = createWorkflowChain({
  id: "tenant-report",
  input: z.object({ tenantId: z.string() }),
  result: z.object({ ok: z.boolean() }),
  executionValidators: [
    async ({ input, context }) => {
      const allowedTenants = context.get("allowedTenants");

      if (
        Array.isArray(allowedTenants) &&
        typeof input === "object" &&
        input !== null &&
        "tenantId" in input &&
        !(await checkTenantWorkflowAccess({
          tenantId: input.tenantId,
          allowedTenants,
        }))
      ) {
        return {
          pass: false,
          message: "Tenant is not allowed for this workflow.",
          code: "WORKFLOW_TENANT_DENIED",
          httpStatus: 403,
        };
      }
    },
  ],
}).andThen({
  id: "finish",
  execute: async () => ({ ok: true }),
});

This currently covers tool/workflow identity, final args/input, agent or workflow context, timestamps, request headers, custom failure codes/statuses, and metadata. It should also leave room for nonce/replay protection to be implemented in userland validators using request context, headers, args, or workflow input.

When you have a chance, I would love your feedback on whether this validator context matches the execution-boundary checks you had in mind, especially around destination validation and replay/validity-window policies.

[devincapriola]

This is exactly the direction I was pointing at.

Having validation run right at execution with access to the final payload and context is the key piece.

The fact that it supports async checks is important too that opens the door for real policy and permission enforcement.

I’ll dig into it more, but curious how you’re thinking about things like destination validation and replay/validity window handling.