fix(ai): validate AI agent output field names against schema-key constraint (#21834)

## Problem On a self-hosted instance, an AI Agent workflow action fails at run time with an opaque model error: ``` The model returned the following errors: tools.0.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$' ``` This is Anthropic's validation on tool `input_schema` **property keys**. An AI Agent's structured **Output** fields are turned into a JSON schema and passed to the model as a tool; each output **variable name** becomes a property key. Anthropic rejects any key that does not match `^[a-zA-Z0-9_.-]{1,64}$` — most commonly a name containing a **space** (e.g. `meetings brief`), but also names over 64 characters or with other symbols. Until now nothing validated this: `fieldsToSchema` writes `properties[field.name]` verbatim, so a bad name only failed once the workflow executed, with an error that gives the user no idea what to fix. It doesn't reproduce on every instance — it depends purely on how the workflow's output variables happen to be named. ## Fix Introduce a single shared check, `isValidAgentResponseSchemaPropertyKey`, and enforce it in two places: - **Backend** — `validateAgentResponseFormat` now rejects invalid output field names at agent **save time** with a clear `userFriendlyMessage`, instead of letting the broken schema reach the model. This also gates agents created via the API and re-saves of existing bad data. - **Frontend** — the output schema builder shows an inline error on the Variable Name field as soon as an invalid name is entered. ## Tests - Unit test for the shared validity check (valid + invalid cases: spaces, leading space, empty, > 64 chars, symbols, unicode). - Unit test for `validateAgentResponseFormat` covering text/json formats, valid names, a space in a name, an over-length name, and reporting multiple invalid names at once. ## Notes for the reporter The immediate unblock for an affected workflow is to rename the output variable to remove the space (e.g. `meetings brief` → `meetings_brief`) and retry the run. With this change the bad name is caught up front with an explanation rather than failing mid-run.  <a href="https://cubic.dev/pr/twentyhq/twenty/pull/21834?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
2026-06-19 13:50:44 +02:00
parent 576f88b5c5
commit 0064ff6741
6 changed files with 152 additions and 1 deletions
@@ -0,0 +1,89 @@
+import { type AgentResponseFormat } from 'src/engine/metadata-modules/ai/ai-agent/types/agent-response-format.type';
+import { AiExceptionCode } from 'src/engine/metadata-modules/ai/ai.exception';
+import { validateAgentResponseFormat } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/utils/validate-agent-response-format.util';
+
+type JsonResponseFormat = Extract<AgentResponseFormat, { type: 'json' }>;
+
+const buildJsonFormat = (
+  properties: JsonResponseFormat['schema']['properties'],
+): AgentResponseFormat => ({
+  type: 'json',
+  schema: {
+    type: 'object',
+    properties,
+    required: Object.keys(properties),
+    additionalProperties: false,
+  },
+});
+
+describe('validateAgentResponseFormat', () => {
+  it('should return no error for a text response format', () => {
+    const errors = validateAgentResponseFormat({
+      responseFormat: { type: 'text' },
+    });
+
+    expect(errors).toEqual([]);
+  });
+
+  it('should return no error when all property names are valid', () => {
+    const errors = validateAgentResponseFormat({
+      responseFormat: buildJsonFormat({
+        meetings_brief: { type: 'string' },
+        count: { type: 'number' },
+      }),
+    });
+
+    expect(errors).toEqual([]);
+  });
+
+  it('should return an error when a property name contains a space', () => {
+    const errors = validateAgentResponseFormat({
+      responseFormat: buildJsonFormat({
+        'meetings brief': { type: 'string' },
+      }),
+    });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0].code).toBe(AiExceptionCode.INVALID_AGENT_INPUT);
+    expect(errors[0].message).toContain('meetings brief');
+  });
+
+  it('should return an error when a property name exceeds 64 characters', () => {
+    const errors = validateAgentResponseFormat({
+      responseFormat: buildJsonFormat({
+        ['a'.repeat(65)]: { type: 'string' },
+      }),
+    });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0].code).toBe(AiExceptionCode.INVALID_AGENT_INPUT);
+  });
+
+  it('should not throw when a json schema is missing its properties', () => {
+    // Legacy or API-provided data can omit properties despite the type
+    const malformedFormat = {
+      type: 'json',
+      schema: { type: 'object' },
+    } as AgentResponseFormat;
+
+    expect(() =>
+      validateAgentResponseFormat({ responseFormat: malformedFormat }),
+    ).not.toThrow();
+    expect(
+      validateAgentResponseFormat({ responseFormat: malformedFormat }),
+    ).toEqual([]);
+  });
+
+  it('should report every invalid property name at once', () => {
+    const errors = validateAgentResponseFormat({
+      responseFormat: buildJsonFormat({
+        'meetings brief': { type: 'string' },
+        'sales rep': { type: 'string' },
+      }),
+    });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('meetings brief');
+    expect(errors[0].message).toContain('sales rep');
+  });
+});
@@ -1,5 +1,6 @@
 import { msg, t } from '@lingui/core/macro';
-import { isDefined } from 'twenty-shared/utils';
+import { isValidAgentResponseSchemaPropertyKey } from 'twenty-shared/ai';
+import { isDefined, isNonEmptyArray } from 'twenty-shared/utils';

 import { AiExceptionCode } from 'src/engine/metadata-modules/ai/ai.exception';
 import {
@@ -32,6 +33,22 @@ export const validateAgentResponseFormat = ({
    });
  }

+  if (type === 'json' && isDefined(responseFormat.schema)) {
+    const invalidPropertyNames = Object.keys(
+      responseFormat.schema.properties ?? {},
+    ).filter(
+      (propertyName) => !isValidAgentResponseSchemaPropertyKey(propertyName),
+    );
+
+    if (isNonEmptyArray(invalidPropertyNames)) {
+      errors.push({
+        code: AiExceptionCode.INVALID_AGENT_INPUT,
+        message: t`Output field names must use only letters, numbers, underscores, dots or hyphens and be at most 64 characters: ${invalidPropertyNames.join(', ')}`,
+        userFriendlyMessage: msg`Output field names can only contain letters, numbers, underscores, dots or hyphens (max 64 characters).`,
+      });
+    }
+  }
+
  if (
    type === 'text' &&
    isDefined((responseFormat as unknown as AgentJsonResponseFormat).schema)