Skip to content

The open alternative to Salesforce, designed for AI.

Let callers choose the agent's output format, starting with workflow AI steps (#27919)

Félix Malfaitb65361440b05
diff --git a/packages/twenty-client-sdk/src/metadata/generated/schema.graphql b/packages/twenty-client-sdk/src/metadata/generated/schema.graphql
index 4b65a3711e8..3a112d2e9a2 100644
--- a/packages/twenty-client-sdk/src/metadata/generated/schema.graphql
+++ b/packages/twenty-client-sdk/src/metadata/generated/schema.graphql
@@ -4162,6 +4162,7 @@ input RunAgentInput {
input: [RunAgentMessageInput!]
messages: [RunAgentMessageInput!] @deprecated(reason: "Use input instead.")
prompt: String @deprecated(reason: "Use input instead.")
+ responseFormat: JSON
runAsWorkspaceMemberId: UUID
thread: RunAgentThreadInput
}
diff --git a/packages/twenty-client-sdk/src/metadata/generated/schema.ts b/packages/twenty-client-sdk/src/metadata/generated/schema.ts
index 760c208b3fd..9f6c1b01e40 100644
--- a/packages/twenty-client-sdk/src/metadata/generated/schema.ts
+++ b/packages/twenty-client-sdk/src/metadata/generated/schema.ts
@@ -7312,7 +7312,7 @@ export interface RowLevelPermissionPredicateGroupInput {id?: (Scalars['UUID'] |
export interface RowLevelPermissionPredicateInput {fieldMetadataId: Scalars['UUID'],id?: (Scalars['UUID'] | null),operand: RowLevelPermissionPredicateOperand,positionInRowLevelPermissionPredicateGroup?: (Scalars['Float'] | null),rowLevelPermissionPredicateGroupId?: (Scalars['UUID'] | null),subFieldName?: (Scalars['String'] | null),value?: (Scalars['JSON'] | null),workspaceMemberFieldMetadataId?: (Scalars['String'] | null),workspaceMemberSubFieldName?: (Scalars['String'] | null)}
-export interface RunAgentInput {additionalInstructions?: (Scalars['String'] | null),agentUniversalIdentifier: Scalars['String'],input?: (RunAgentMessageInput[] | null),messages?: (RunAgentMessageInput[] | null),prompt?: (Scalars['String'] | null),runAsWorkspaceMemberId?: (Scalars['UUID'] | null),thread?: (RunAgentThreadInput | null)}
+export interface RunAgentInput {additionalInstructions?: (Scalars['String'] | null),agentUniversalIdentifier: Scalars['String'],input?: (RunAgentMessageInput[] | null),messages?: (RunAgentMessageInput[] | null),prompt?: (Scalars['String'] | null),responseFormat?: (Scalars['JSON'] | null),runAsWorkspaceMemberId?: (Scalars['UUID'] | null),thread?: (RunAgentThreadInput | null)}
export interface RunAgentMessageAttachmentInput {fileId: Scalars['UUID'],filename?: (Scalars['String'] | null)}
diff --git a/packages/twenty-client-sdk/src/metadata/generated/types.ts b/packages/twenty-client-sdk/src/metadata/generated/types.ts
index 71fc3675144..7fe142b3bc4 100644
--- a/packages/twenty-client-sdk/src/metadata/generated/types.ts
+++ b/packages/twenty-client-sdk/src/metadata/generated/types.ts
@@ -11226,6 +11226,9 @@ export default {
"prompt": [
1
],
+ "responseFormat": [
+ 289
+ ],
"runAsWorkspaceMemberId": [
493
],
diff --git a/packages/twenty-docs/developers/extend/apps/logic/skills-and-agents.mdx b/packages/twenty-docs/developers/extend/apps/logic/skills-and-agents.mdx
index 32cdafdd864..f9549ca25c8 100644
--- a/packages/twenty-docs/developers/extend/apps/logic/skills-and-agents.mdx
+++ b/packages/twenty-docs/developers/extend/apps/logic/skills-and-agents.mdx
@@ -64,7 +64,7 @@ Key points:
- `description` (optional) provides context about what the agent does.
- `icon` (optional) sets the icon displayed in the UI.
- `modelId` (optional) overrides the default AI model used by the agent.
-- `responseFormat` (optional) controls the shape of the agent's output. Defaults to `{ type: 'text' }` for free-form text. Use `{ type: 'json', schema }` to force structured JSON output.
+- `responseFormat` (optional) sets the agent's default output shape. Defaults to `{ type: 'text' }` for free-form text. Use `{ type: 'json', schema }` to force structured JSON output. A `runAgent()` call or a workflow AI step can ask for a different shape, which takes precedence.
- `roleUniversalIdentifier` (optional) binds the agent to a role your app defines. That role must not grant more than the application role, or the build fails; see [Agent roles](/developers/extend/apps/config/roles#agent-roles).
By default an agent returns free-form text. To get structured output, set `responseFormat` to `{ type: 'json' }` and provide a `schema`:
@@ -188,6 +188,29 @@ alongside `AI`. `filename` is optional and only labels the file for the model.
`agent-chat` folder. Anything else fails the call instead of quietly
answering without the file.
+### Asking for a structured result
+
+Pass `responseFormat` to get a shape for this call only. It takes precedence over
+the agent's own `responseFormat`, so one agent can serve callers that need
+different outputs. It uses the same schema as `defineAgent()`:
+
+```ts src/logic-functions/score-lead.ts
+const { result } = await runAgent({
+ agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
+ input: `Score this lead: ${JSON.stringify(lead)}`,
+ responseFormat: {
+ type: 'json',
+ schema: {
+ type: 'object',
+ properties: {
+ score: { type: 'number', description: 'Lead score from 0 to 100' },
+ },
+ required: ['score'],
+ },
+ },
+});
+```
+
### Continuing a conversation
Pass a `thread` and Twenty keeps the conversation for you: each call sends only
diff --git a/packages/twenty-front/src/generated-metadata/graphql.ts b/packages/twenty-front/src/generated-metadata/graphql.ts
index 9d2d512faac..592b0e24c44 100644
--- a/packages/twenty-front/src/generated-metadata/graphql.ts
+++ b/packages/twenty-front/src/generated-metadata/graphql.ts
@@ -6241,6 +6241,7 @@ export type RunAgentInput = {
additionalInstructions?: InputMaybe<Scalars['String']['input']>;
agentUniversalIdentifier: Scalars['String']['input'];
input?: InputMaybe<Array<RunAgentMessageInput>>;
+ responseFormat?: InputMaybe<Scalars['JSON']['input']>;
runAsWorkspaceMemberId?: InputMaybe<Scalars['UUID']['input']>;
thread?: InputMaybe<RunAgentThreadInput>;
};
diff --git a/packages/twenty-front/src/modules/object-core/agents/components/CoreAgentResponseFormat.tsx b/packages/twenty-front/src/modules/object-core/agents/components/CoreAgentResponseFormat.tsx
deleted file mode 100644
index e03f76181de..00000000000
--- a/packages/twenty-front/src/modules/object-core/agents/components/CoreAgentResponseFormat.tsx
+++ /dev/null
@@ -1,90 +0,0 @@
-import { type OutputSchemaField } from '@/ai/types/OutputSchemaField';
-import { fieldsToSchema } from '@/ai/utils/fieldsToSchema';
-import { schemaToFields } from '@/ai/utils/schemaToFields';
-import { Select } from '@/ui/input/components/Select';
-import { AgentOutputSchemaBuilder } from '@/ai/components/AgentOutputSchemaBuilder';
-import { styled } from '@linaria/react';
-import { t } from '@lingui/core/macro';
-import { useState } from 'react';
-import { type AgentResponseSchema } from 'twenty-shared/ai';
-import { themeCssVariables } from 'twenty-ui/theme';
-
-const StyledContainer = styled.div`
- display: flex;
- flex-direction: column;
- gap: ${themeCssVariables.spacing[2]};
-`;
-
-type CoreAgentResponseFormatProps = {
- responseFormat?: {
- type: 'text' | 'json';
- schema?: AgentResponseSchema;
- };
- onResponseFormatChange: (format: {
- type: 'text' | 'json';
- schema?: AgentResponseSchema;
- }) => void;
- disabled?: boolean;
-};
-
-export const CoreAgentResponseFormat = ({
- responseFormat,
- onResponseFormatChange,
- disabled,
-}: CoreAgentResponseFormatProps) => {
- const formatType = responseFormat?.type || 'text';
- const schema: AgentResponseSchema = responseFormat?.schema || {
- type: 'object' as const,
- properties: {},
- required: [],
- additionalProperties: false as const,
- };
-
- const [visualBuilderFields, setVisualBuilderFields] = useState<
- OutputSchemaField[]
- >(() => schemaToFields(schema));
-
- const handleFormatTypeChange = (newType: 'text' | 'json') => {
- if (newType === 'json') {
- setVisualBuilderFields(schemaToFields(schema));
- }
-
- // TODO: Remove text response format support once prod migration upgrades legacy agents to JSON format.
- onResponseFormatChange(
- newType === 'text' ? { type: 'text' } : { type: 'json', schema },
- );
- };
-
- const handleVisualBuilderChange = (updatedFields: OutputSchemaField[]) => {
- setVisualBuilderFields(updatedFields);
- onResponseFormatChange({
- type: 'json',
- schema: fieldsToSchema(updatedFields),
- });
- };
-
- return (
- <StyledContainer>
- <Select
- dropdownId="agent-response-format-type"
- label={t`Response Format`}
- value={formatType}
- onChange={handleFormatTypeChange}
- options={[
- // TODO: Remove string option once text response format support is fully dropped.
- { label: t`String`, value: 'text' as const },
- { label: t`JSON`, value: 'json' as const },
- ]}
- disabled={disabled}
- />
-
- {formatType === 'json' && (
- <AgentOutputSchemaBuilder
- fields={visualBuilderFields}
- onChange={handleVisualBuilderChange}
- readonly={disabled}
- />
- )}
- </StyledContainer>
- );
-};
diff --git a/packages/twenty-front/src/modules/object-core/agents/components/CoreAgentSettingsTab.tsx b/packages/twenty-front/src/modules/object-core/agents/components/CoreAgentSettingsTab.tsx
index bcbe4bca99b..09e9638b694 100644
--- a/packages/twenty-front/src/modules/object-core/agents/components/CoreAgentSettingsTab.tsx
+++ b/packages/twenty-front/src/modules/object-core/agents/components/CoreAgentSettingsTab.tsx
@@ -15,7 +15,6 @@ import { Button } from 'twenty-ui/primitives/input';
import { themeCssVariables } from 'twenty-ui/theme';
import { type Agent } from '~/generated-metadata/graphql';
import { CoreAgentDeleteConfirmationModal } from '@/object-core/agents/components/CoreAgentDeleteConfirmationModal';
-import { CoreAgentResponseFormat } from '@/object-core/agents/components/CoreAgentResponseFormat';
import { computeMetadataNameFromLabel } from '@/object-metadata/utils/computeMetadataNameFromLabel';
import { type CoreAgentFormValues } from '@/object-core/agents/validation-schemas/coreAgentFormSchema';
import { useAtomStateValue } from '@/ui/utilities/state/jotai/hooks/useAtomStateValue';
@@ -146,15 +145,6 @@ export const CoreAgentSettingsTab = ({
disabled={disabled}
/>
</StyledFormContainer>
- <StyledFormContainer>
- <CoreAgentResponseFormat
- responseFormat={formValues.responseFormat}
- onResponseFormatChange={(format) =>
- onFieldChange('responseFormat', format)
- }
- disabled={disabled}
- />
- </StyledFormContainer>
{!disabled && agent && formValues.isCustom && (
<Section.Root>
<Section.Header
diff --git a/packages/twenty-front/src/modules/object-core/agents/hooks/useCoreAgentSave.ts b/packages/twenty-front/src/modules/object-core/agents/hooks/useCoreAgentSave.ts
index f827698da53..4f3cac77d3e 100644
--- a/packages/twenty-front/src/modules/object-core/agents/hooks/useCoreAgentSave.ts
+++ b/packages/twenty-front/src/modules/object-core/agents/hooks/useCoreAgentSave.ts
@@ -73,7 +73,6 @@ export const useCoreAgentSave = ({
roleId: formValues.role,
prompt: formValues.prompt,
modelConfiguration: formValues.modelConfiguration,
- responseFormat: formValues.responseFormat,
// Stored triggers the form could not parse are left out of formValues, so
// only send triggers when the user edited them to avoid deleting those
...(!isDeeplyEqual(formValues.triggers, originalFormValues.triggers) && {
diff --git a/packages/twenty-front/src/modules/object-core/agents/hooks/useCreateCoreAgent.ts b/packages/twenty-front/src/modules/object-core/agents/hooks/useCreateCoreAgent.ts
index c607ec957d9..8294ee45229 100644
--- a/packages/twenty-front/src/modules/object-core/agents/hooks/useCreateCoreAgent.ts
+++ b/packages/twenty-front/src/modules/object-core/agents/hooks/useCreateCoreAgent.ts
@@ -45,7 +45,6 @@ export const useCreateCoreAgent = () => {
icon: 'IconLego',
prompt: 'You are a helpful AI assistant.',
modelId: AUTO_SELECT_WORKSPACE_DEFAULT_MODEL_ID,
- responseFormat: { type: 'text' },
},
},
});
diff --git a/packages/twenty-front/src/modules/object-core/agents/utils/__tests__/getCoreAgentInitialFormValues.test.ts b/packages/twenty-front/src/modules/object-core/agents/utils/__tests__/getCoreAgentInitialFormValues.test.ts
index fe3b88441f4..062d7a96e14 100644
--- a/packages/twenty-front/src/modules/object-core/agents/utils/__tests__/getCoreAgentInitialFormValues.test.ts
+++ b/packages/twenty-front/src/modules/object-core/agents/utils/__tests__/getCoreAgentInitialFormValues.test.ts
@@ -40,7 +40,6 @@ describe('getCoreAgentInitialFormValues', () => {
prompt: 'You qualify leads.',
isCustom: true,
modelConfiguration: { webSearch: { enabled: true } },
- responseFormat: { type: 'json', schema: {} },
triggers: [
{
id: '6f1b5a3e-3c3f-4f4a-9a43-0a7f5d6c2b11',
@@ -53,16 +52,14 @@ describe('getCoreAgentInitialFormValues', () => {
});
});
- it('falls back to the default icon, empty configuration and text format when the agent has none', () => {
+ it('falls back to the default icon and an empty configuration when the agent has none', () => {
const formValues = getCoreAgentInitialFormValues({
...agent,
icon: null,
modelConfiguration: null,
- responseFormat: null,
});
expect(formValues.icon).toBe('IconLego');
expect(formValues.modelConfiguration).toEqual({});
- expect(formValues.responseFormat).toEqual({ type: 'text' });
});
});
diff --git a/packages/twenty-front/src/modules/object-core/agents/utils/getCoreAgentInitialFormValues.ts b/packages/twenty-front/src/modules/object-core/agents/utils/getCoreAgentInitialFormValues.ts
index 8ba668cd555..48a8589ad41 100644
--- a/packages/twenty-front/src/modules/object-core/agents/utils/getCoreAgentInitialFormValues.ts
+++ b/packages/twenty-front/src/modules/object-core/agents/utils/getCoreAgentInitialFormValues.ts
@@ -24,8 +24,6 @@ export const getCoreAgentInitialFormValues = (
prompt: agent.prompt,
isCustom: agent.isCustom,
modelConfiguration: agent.modelConfiguration || {},
- // TODO: Fallback can be removed once all text response format agents are migrated.
- responseFormat: agent.responseFormat || { type: 'text' },
triggers: parseAgentTriggers(agent.triggers ?? []),
};
};
diff --git a/packages/twenty-front/src/modules/object-core/agents/validation-schemas/coreAgentFormSchema.ts b/packages/twenty-front/src/modules/object-core/agents/validation-schemas/coreAgentFormSchema.ts
index 0fa2bb3c717..f38d4561ba9 100644
--- a/packages/twenty-front/src/modules/object-core/agents/validation-schemas/coreAgentFormSchema.ts
+++ b/packages/twenty-front/src/modules/object-core/agents/validation-schemas/coreAgentFormSchema.ts
@@ -1,4 +1,3 @@
-import { type AgentResponseSchema } from 'twenty-shared/ai';
import { AGENT_TRIGGER_LIMITS } from 'twenty-shared/application';
import { z } from 'zod';
import { coreAgentTriggerSchema } from '@/object-core/agents/validation-schemas/coreAgentTriggerSchema';
@@ -29,12 +28,6 @@ export const coreAgentFormSchema = z.object({
.optional(),
})
.optional(),
- responseFormat: z
- .object({
- type: z.enum(['text', 'json']),
- schema: z.custom<AgentResponseSchema>().optional(),
- })
- .optional(),
triggers: z
.array(coreAgentTriggerSchema)
.max(AGENT_TRIGGER_LIMITS.MAX_TRIGGERS_PER_AGENT)
diff --git a/packages/twenty-front/src/modules/workflow/workflow-steps/workflow-actions/ai-agent-action/components/WorkflowAiAgentPromptTab.tsx b/packages/twenty-front/src/modules/workflow/workflow-steps/workflow-actions/ai-agent-action/components/WorkflowAiAgentPromptTab.tsx
index 6c7cfe6fb82..b40f0a9e5c1 100644
--- a/packages/twenty-front/src/modules/workflow/workflow-steps/workflow-actions/ai-agent-action/components/WorkflowAiAgentPromptTab.tsx
+++ b/packages/twenty-front/src/modules/workflow/workflow-steps/workflow-actions/ai-agent-action/components/WorkflowAiAgentPromptTab.tsx
@@ -1,7 +1,6 @@
import { SettingsAgentModelCapabilities } from '@/ai/components/SettingsAgentModelCapabilities';
import { type OutputSchemaField } from '@/ai/types/OutputSchemaField';
import { AiModelPicker } from '@/ai/components/AiModelPicker';
-import { agentResponseSchemaToOutputSchema } from '@/ai/utils/agentResponseSchemaToOutputSchema';
import { createDefaultOutputSchemaField } from '@/ai/utils/createDefaultOutputSchemaField';
import { fieldsToSchema } from '@/ai/utils/fieldsToSchema';
import { schemaToFields } from '@/ai/utils/schemaToFields';
@@ -23,7 +22,6 @@ import {
} from 'twenty-shared/ai';
import { CoreObjectNameSingular } from 'twenty-shared/types';
import { type WorkflowConversation } from 'twenty-shared/workflow';
-import { useDebouncedCallback } from 'use-debounce';
import {
FeatureFlagKey,
UpdateOneAgentDocument,
@@ -41,7 +39,7 @@ type WorkflowAiAgentPromptTabProps = {
onRecipientChange: (workspaceMemberId: string | undefined) => void;
conversation: WorkflowConversation | undefined;
onConversationChange: (conversation: WorkflowConversation) => void;
- onActionUpdate?: (action: WorkflowAiAgentAction) => void;
+ onResponseSchemaChange: (responseSchema: AgentResponseSchema) => void;
};
export const WorkflowAiAgentPromptTab = ({
@@ -55,7 +53,7 @@ export const WorkflowAiAgentPromptTab = ({
onRecipientChange,
conversation,
onConversationChange,
- onActionUpdate,
+ onResponseSchemaChange,
}: WorkflowAiAgentPromptTabProps) => {
const [workflowAiAgentActionAgent, setWorkflowAiAgentActionAgent] =
useAtomState(workflowAiAgentActionAgentState);
@@ -67,8 +65,13 @@ export const WorkflowAiAgentPromptTab = ({
const [outputSchemaFields, setOutputSchemaFields] = useState<
OutputSchemaField[]
>(() => {
- const schema: AgentResponseSchema = workflowAiAgentActionAgent
- ?.responseFormat?.schema || {
+ // steps saved before the format moved to them still carry it on their agent
+ const responseFormat =
+ action.settings.input.responseFormat ??
+ workflowAiAgentActionAgent?.responseFormat;
+ const schema: AgentResponseSchema = (responseFormat?.type === 'json'
+ ? responseFormat.schema
+ : undefined) || {
type: 'object' as const,
properties: {},
required: [],
@@ -107,25 +110,6 @@ export const WorkflowAiAgentPromptTab = ({
);
};
- const updateResponseSchema = async (schema: AgentResponseSchema) => {
- await updateAgentField({
- responseFormat: { type: 'json' as const, schema },
- });
-
- onActionUpdate?.({
- ...action,
- settings: {
- ...action.settings,
- outputSchema: agentResponseSchemaToOutputSchema(schema),
- },
- });
- };
-
- const debouncedUpdateResponseSchema = useDebouncedCallback(
- updateResponseSchema,
- 300,
- );
-
if (!workflowAiAgentActionAgent) {
return null;
}
@@ -148,7 +132,7 @@ export const WorkflowAiAgentPromptTab = ({
const handleOutputSchemaChange = (updatedFields: OutputSchemaField[]) => {
setOutputSchemaFields(updatedFields);
- void debouncedUpdateResponseSchema(fieldsToSchema(updatedFields));
+ onResponseSchemaChange(fieldsToSchema(updatedFields));
};
return (
diff --git a/packages/twenty-front/src/modules/workflow/workflow-steps/workflow-actions/ai-agent-action/components/WorkflowEditActionAiAgent.tsx b/packages/twenty-front/src/modules/workflow/workflow-steps/workflow-actions/ai-agent-action/components/WorkflowEditActionAiAgent.tsx
index 326cd3a9ab9..95140c7c595 100644
--- a/packages/twenty-front/src/modules/workflow/workflow-steps/workflow-actions/ai-agent-action/components/WorkflowEditActionAiAgent.tsx
+++ b/packages/twenty-front/src/modules/workflow/workflow-steps/workflow-actions/ai-agent-action/components/WorkflowEditActionAiAgent.tsx
@@ -1,3 +1,4 @@
+import { agentResponseSchemaToOutputSchema } from '@/ai/utils/agentResponseSchemaToOutputSchema';
import { TabListRoot } from '@/ui/layout/tab-list/components/TabListRoot';
import { WorkflowStepTabPanel } from '@/workflow/workflow-steps/components/WorkflowStepTabPanel';
import { TabList } from '@/ui/layout/tab-list/components/TabList';
@@ -19,6 +20,7 @@ import { useQuery } from '@apollo/client/react';
import { styled } from '@linaria/react';
import { useLingui } from '@lingui/react/macro';
import { useEffect, useState } from 'react';
+import { type AgentResponseSchema } from 'twenty-shared/ai';
import { SettingsPath } from 'twenty-shared/types';
import { isDefined } from 'twenty-shared/utils';
import { type WorkflowConversation } from 'twenty-shared/workflow';
@@ -86,6 +88,9 @@ export const WorkflowEditActionAiAgent = ({
const [conversation, setConversation] = useState(
action.settings.input.conversation,
);
+ const [responseSchema, setResponseSchema] = useState<
+ AgentResponseSchema | undefined
+ >(undefined);
// saves every field from the latest render, so editing one does not drop a pending edit of another
const saveInput = useDebouncedCallback(() => {
@@ -103,7 +108,13 @@ export const WorkflowEditActionAiAgent = ({
humanInputInstructions,
workspaceMemberId: recipientWorkspaceMemberId,
conversation,
+ ...(isDefined(responseSchema)
+ ? { responseFormat: { type: 'json', schema: responseSchema } }
+ : {}),
},
+ ...(isDefined(responseSchema)
+ ? { outputSchema: agentResponseSchemaToOutputSchema(responseSchema) }
+ : {}),
},
});
}, 500);
@@ -128,6 +139,13 @@ export const WorkflowEditActionAiAgent = ({
saveInput();
};
+ const handleResponseSchemaChange = (
+ nextResponseSchema: AgentResponseSchema,
+ ) => {
+ setResponseSchema(nextResponseSchema);
+ saveInput();
+ };
+
const tabs: SingleTabProps[] = [
{
id: WORKFLOW_AI_AGENT_TABS.PROMPT,
@@ -238,11 +256,7 @@ export const WorkflowEditActionAiAgent = ({
onRecipientChange={handleRecipientChange}
conversation={conversation}
onConversationChange={handleConversationChange}
- onActionUpdate={
- actionOptions.readonly === true
- ? undefined
- : actionOptions.onActionUpdate
- }
+ onResponseSchemaChange={handleResponseSchemaChange}
/>
</WorkflowStepBody>
)}
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/__tests__/compute-workflow-manifest-output-schema.util.spec.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/__tests__/compute-workflow-manifest-output-schema.util.spec.ts
new file mode 100644
index 00000000000..aaf64afd850
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/__tests__/compute-workflow-manifest-output-schema.util.spec.ts
@@ -0,0 +1,59 @@
+import { type WorkflowStepManifest } from 'twenty-shared/application';
+import { type BaseOutputSchemaV2 } from 'twenty-shared/workflow';
+
+import { computeWorkflowManifestOutputSchema } from 'src/engine/core-modules/application/application-manifest/utils/compute-workflow-manifest-output-schema.util';
+
+type AiAgentStepManifest = Extract<WorkflowStepManifest, { type: 'AI_AGENT' }>;
+
+const AGENT_UNIVERSAL_IDENTIFIER = '6f1b5a3e-3c3f-4f4a-9a43-0a7f5d6c2b11';
+
+const AGENT_OUTPUT_SCHEMA: BaseOutputSchemaV2 = {
+ answer: { isLeaf: true, type: 'string', label: 'answer', value: 'text' },
+};
+
+const buildAiAgentStep = (
+ input: Partial<AiAgentStepManifest['input']>,
+): AiAgentStepManifest => ({
+ universalIdentifier: 'step-universal-identifier',
+ name: 'Summarize',
+ type: 'AI_AGENT',
+ nextStepIds: [],
+ input: { prompt: 'Summarize the deal', ...input },
+});
+
+const references = {
+ agentOutputSchemaByUniversalIdentifier: new Map([
+ [AGENT_UNIVERSAL_IDENTIFIER, AGENT_OUTPUT_SCHEMA],
+ ]),
+};
+
+describe('computeWorkflowManifestOutputSchema', () => {
+ it("uses the AI step's own output format over its agent's", () => {
+ const outputSchema = computeWorkflowManifestOutputSchema({
+ step: buildAiAgentStep({
+ agentUniversalIdentifier: AGENT_UNIVERSAL_IDENTIFIER,
+ responseFormat: {
+ type: 'json',
+ schema: {
+ type: 'object',
+ properties: { summary: { type: 'string' } },
+ },
+ },
+ }),
+ references,
+ });
+
+ expect(Object.keys(outputSchema)).toEqual(['summary']);
+ });
+
+ it("falls back to the agent's output format when the step gives none", () => {
+ const outputSchema = computeWorkflowManifestOutputSchema({
+ step: buildAiAgentStep({
+ agentUniversalIdentifier: AGENT_UNIVERSAL_IDENTIFIER,
+ }),
+ references,
+ });
+
+ expect(outputSchema).toBe(AGENT_OUTPUT_SCHEMA);
+ });
+});
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/compute-workflow-manifest-output-schema.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/compute-workflow-manifest-output-schema.util.ts
index 50e56149e50..0078e964a6a 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/compute-workflow-manifest-output-schema.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/compute-workflow-manifest-output-schema.util.ts
@@ -10,7 +10,11 @@ export const computeWorkflowManifestOutputSchema = ({
references,
}: {
step: WorkflowStepManifest;
- references: WorkflowManifestReferences;
+ references: Pick<
+ WorkflowManifestReferences,
+ | 'logicFunctionOutputSchemaByUniversalIdentifier'
+ | 'agentOutputSchemaByUniversalIdentifier'
+ >;
}): Record<string, unknown> => {
if (
isDefined(step.outputSchema) &&
@@ -34,6 +38,10 @@ export const computeWorkflowManifestOutputSchema = ({
}
if (step.type === 'AI_AGENT') {
+ if (isDefined(step.input.responseFormat)) {
+ return computeAiAgentOutputSchema(step.input.responseFormat);
+ }
+
return isDefined(step.input.agentUniversalIdentifier)
? (references.agentOutputSchemaByUniversalIdentifier?.get(
step.input.agentUniversalIdentifier,
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/dtos/run-agent.input.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/dtos/run-agent.input.ts
index dedc7ff404a..086daae26ba 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/dtos/run-agent.input.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/dtos/run-agent.input.ts
@@ -1,6 +1,8 @@
import { Field, InputType } from '@nestjs/graphql';
import { Type } from 'class-transformer';
+import GraphQLJSON from 'graphql-type-json';
+import { type AgentResponseFormat } from 'twenty-shared/ai';
import {
ArrayMaxSize,
ArrayNotEmpty,
@@ -61,6 +63,10 @@ export class RunAgentInputDTO {
@Field({ nullable: true })
additionalInstructions?: string;
+ @IsOptional()
+ @Field(() => GraphQLJSON, { nullable: true })
+ responseFormat?: AgentResponseFormat;
+
@IsOptional()
@ValidateNested()
@Type(() => RunAgentThreadInputDTO)
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/__tests__/agent-run.service.spec.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/__tests__/agent-run.service.spec.ts
index b2836a73f15..4e55cbcebe1 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/__tests__/agent-run.service.spec.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/__tests__/agent-run.service.spec.ts
@@ -259,6 +259,33 @@ describe('AgentRunService', () => {
});
});
+ it('keeps the output format the call asks for with the run', async () => {
+ const { service, agentRunnerService } = buildService();
+ const responseFormat = {
+ type: 'json' as const,
+ schema: {
+ type: 'object' as const,
+ properties: { summary: { type: 'string' as const } },
+ },
+ };
+
+ await run(service, { input: userInput('Summarize'), responseFormat });
+
+ expect(runInput(agentRunnerService).spec).toMatchObject({ responseFormat });
+ });
+
+ it('refuses an output format that is not one', async () => {
+ const { service, agentRunnerService } = buildService();
+
+ await expect(
+ run(service, {
+ input: userInput('Summarize'),
+ responseFormat: { type: 'json', schema: { properties: 'nope' } },
+ }),
+ ).rejects.toThrow('Invalid response format');
+ expect(agentRunnerService.run).not.toHaveBeenCalled();
+ });
+
it('records the member who called without an application as the sender', async () => {
const { service, agentRunnerService } = buildService();
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/__tests__/agent-runner.service.spec.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/__tests__/agent-runner.service.spec.ts
index 402dd346953..f64d848927a 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/__tests__/agent-runner.service.spec.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/__tests__/agent-runner.service.spec.ts
@@ -4,6 +4,8 @@ import { UsageOperationType } from 'src/engine/core-modules/usage/enums/usage-op
import { AgentRunnerService } from 'src/engine/metadata-modules/ai/ai-agent-execution/services/agent-runner.service';
import { type AgentExecutionResult } from 'src/engine/metadata-modules/ai/ai-agent-execution/types/agent-execution-result.type';
import { type AgentRunnerRunInput } from 'src/engine/metadata-modules/ai/ai-agent-execution/types/agent-runner-run-input.type';
+import { AgentEntity } from 'src/engine/metadata-modules/ai/ai-agent/entities/agent.entity';
+import { type AgentResponseFormat } from 'src/engine/metadata-modules/ai/ai-agent/types/agent-response-format.type';
const CREATED_BY = {
source: 'WORKFLOW',
@@ -44,6 +46,9 @@ const buildExecution = (
...overrides,
});
+const buildAgent = (responseFormat: AgentResponseFormat): AgentEntity =>
+ Object.assign(new AgentEntity(), { id: 'agent-id', responseFormat });
+
const RUN_INPUT: AgentRunnerRunInput = {
workspaceId: 'workspace-id',
conversation: { threadId: 'thread-id', isCreated: false },
@@ -206,6 +211,49 @@ describe('AgentRunnerService', () => {
);
});
+ it("asks for the caller's output format over the agent's own", async () => {
+ const { service, agentAsyncExecutorService } = buildService();
+ const callerResponseFormat = {
+ type: 'json' as const,
+ schema: {
+ type: 'object' as const,
+ properties: { summary: { type: 'string' as const } },
+ },
+ };
+
+ await service.run({
+ ...RUN_INPUT,
+ agent: buildAgent({ type: 'text' }),
+ spec: { ...RUN_INPUT.spec, responseFormat: callerResponseFormat },
+ });
+
+ expect(agentAsyncExecutorService.executeAgent).toHaveBeenCalledTimes(1);
+ expect(agentAsyncExecutorService.executeAgent).toHaveBeenCalledWith(
+ expect.objectContaining({ responseFormat: callerResponseFormat }),
+ );
+ });
+
+ it("falls back to the agent's output format when the caller gives none", async () => {
+ const { service, agentAsyncExecutorService } = buildService();
+ const agentResponseFormat = {
+ type: 'json' as const,
+ schema: {
+ type: 'object' as const,
+ properties: { summary: { type: 'string' as const } },
+ },
+ };
+
+ await service.run({
+ ...RUN_INPUT,
+ agent: buildAgent(agentResponseFormat),
+ });
+
+ expect(agentAsyncExecutorService.executeAgent).toHaveBeenCalledTimes(1);
+ expect(agentAsyncExecutorService.executeAgent).toHaveBeenCalledWith(
+ expect.objectContaining({ responseFormat: agentResponseFormat }),
+ );
+ });
+
it.each([true, false])(
'offers every human-input tool only to a run that can ask humans (%s)',
async (canAskHumans) => {
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts
index b142a3e1755..7e0b9bc518e 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts
@@ -15,6 +15,7 @@ import { type RunAgentMessage } from 'twenty-shared/application';
import {
ASK_QUESTION_TOOL_NAME,
AUTO_SELECT_WORKSPACE_DEFAULT_MODEL_ID,
+ type AgentResponseFormat,
type ExtendedUIMessage,
PROPOSE_TOOL_CALL_TOOL_NAME,
REQUEST_FORM_TOOL_NAME,
@@ -327,8 +328,10 @@ export class AgentAsyncExecutorService {
priorMessages = [],
pausingTools = {},
canAskHumans = false,
+ responseFormat,
}: {
agent: AgentEntity | null;
+ responseFormat?: AgentResponseFormat;
messages: RunAgentMessage[];
// a continued conversation, with the tool calls and results plain run messages cannot carry
priorMessages?: ExtendedUIMessage[];
@@ -347,7 +350,7 @@ export class AgentAsyncExecutorService {
);
}
- assertAgentResponseFormatHasOutputFieldsOrThrow(agent?.responseFormat);
+ assertAgentResponseFormatHasOutputFieldsOrThrow(responseFormat);
await this.aiBillingService.assertAiExecutionAllowed({
workspaceId,
@@ -608,9 +611,7 @@ export class AgentAsyncExecutorService {
executionSteps = textResponse.steps;
const agentSchema =
- agent?.responseFormat?.type === 'json'
- ? agent.responseFormat.schema
- : undefined;
+ responseFormat?.type === 'json' ? responseFormat.schema : undefined;
let result: object = { response: textResponse.text };
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-run.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-run.service.ts
index 50fc55ab42d..4c40878f741 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-run.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-run.service.ts
@@ -13,8 +13,10 @@ import {
type RunAgentResult,
type RunAgentThread,
} from 'twenty-shared/application';
+import { type AgentResponseFormat } from 'twenty-shared/ai';
import { type ActorMetadata } from 'twenty-shared/types';
import { isDefined, isPlainObject } from 'twenty-shared/utils';
+import { agentResponseFormatSchema } from 'twenty-shared/workflow';
import { z } from 'zod';
import { buildActorMetadataFromAuthContext } from 'src/engine/core-modules/actor/utils/build-actor-metadata-from-auth-context.util';
@@ -62,6 +64,7 @@ type RunAgentServiceInput = {
prompt?: string | null;
messages?: RunAgentMessage[] | null;
additionalInstructions?: string | null;
+ responseFormat?: unknown;
thread?: RunAgentThread | null;
runAsWorkspaceMemberId?: string;
};
@@ -150,6 +153,10 @@ export class AgentRunService implements AgentRunCallerHandler, OnModuleInit {
);
}
+ const responseFormat = this.parseResponseFormatOrThrow(
+ input.responseFormat,
+ );
+
const agent = await this.agentRepository.findOne(workspace.id, {
where: {
universalIdentifier: input.agentUniversalIdentifier,
@@ -245,6 +252,7 @@ export class AgentRunService implements AgentRunCallerHandler, OnModuleInit {
baseSystemPrompt: AGENT_RUN_BASE_SYSTEM_PROMPT,
// kept with the run rather than in its messages, so a run that waits still has them when it goes on
instructions: input.additionalInstructions ?? null,
+ ...(isDefined(responseFormat) ? { responseFormat } : {}),
// the call returns before anyone could answer, so the run can wait but not ask
capabilities: {
canAskHumans: false,
@@ -575,4 +583,27 @@ export class AgentRunService implements AgentRunCallerHandler, OnModuleInit {
viaApplication: application,
});
}
+
+ // the resolver runs no validation pipe, so the format is checked here before it reaches the model
+ private parseResponseFormatOrThrow(
+ responseFormat: unknown,
+ ): AgentResponseFormat | undefined {
+ if (!isDefined(responseFormat)) {
+ return undefined;
+ }
+
+ const parsedResponseFormat =
+ agentResponseFormatSchema.safeParse(responseFormat);
+
+ if (!parsedResponseFormat.success) {
+ throw new AiException(
+ `Invalid response format: ${parsedResponseFormat.error.issues
+ .map((issue) => issue.message)
+ .join(', ')}`,
+ AiExceptionCode.INVALID_AGENT_INPUT,
+ );
+ }
+
+ return parsedResponseFormat.data;
+ }
}
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-runner.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-runner.service.ts
index ebf064e89cb..81e07985c4c 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-runner.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-runner.service.ts
@@ -263,6 +263,7 @@ export class AgentRunnerService {
].join('\n\n'),
pausingTools: createAgentWaitTools(),
canAskHumans: spec.capabilities.canAskHumans,
+ responseFormat: spec.responseFormat ?? agent?.responseFormat,
workspaceId,
executionContext,
additionalExcludedToolNames: spec.additionalExcludedToolNames,
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/types/agent-run-spec.type.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/types/agent-run-spec.type.ts
index ac3cfe63b52..e53a2892da0 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/types/agent-run-spec.type.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/types/agent-run-spec.type.ts
@@ -1,3 +1,5 @@
+import { type AgentResponseFormat } from 'twenty-shared/ai';
+
import { type AgentToolLoadingStrategy } from 'src/engine/metadata-modules/ai/ai-agent-execution/types/agent-tool-loading-strategy.type';
// What a suspended run needs to continue without its caller building it again.
@@ -9,6 +11,7 @@ export type AgentRunSpec = {
baseSystemPrompt: string;
// the caller's own instructions, after what the engine says about its pausing tools
instructions: string | null;
+ responseFormat?: AgentResponseFormat;
capabilities: {
// ask_question, request_form and propose_tool_call, answered from the conversation
canAskHumans: boolean;
diff --git a/packages/twenty-server/src/modules/workflow/workflow-builder/workflow-schema/workflow-schema.workspace-service.ts b/packages/twenty-server/src/modules/workflow/workflow-builder/workflow-schema/workflow-schema.workspace-service.ts
index a4059b27700..9e05ded7369 100644
--- a/packages/twenty-server/src/modules/workflow/workflow-builder/workflow-schema/workflow-schema.workspace-service.ts
+++ b/packages/twenty-server/src/modules/workflow/workflow-builder/workflow-schema/workflow-schema.workspace-service.ts
@@ -150,6 +150,10 @@ export class WorkflowSchemaWorkspaceService {
};
}
case WorkflowActionType.AI_AGENT: {
+ if (isDefined(step.settings.input.responseFormat)) {
+ return computeAiAgentOutputSchema(step.settings.input.responseFormat);
+ }
+
return this.computeAiAgentActionOutputSchema({
agentId: step.settings.input.agentId,
workspaceId,
diff --git a/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/types/workflow-ai-agent-action-input.type.ts b/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/types/workflow-ai-agent-action-input.type.ts
index e82d20bee93..0d172dded53 100644
--- a/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/types/workflow-ai-agent-action-input.type.ts
+++ b/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/types/workflow-ai-agent-action-input.type.ts
@@ -1,8 +1,10 @@
+import { type AgentResponseFormat } from 'twenty-shared/ai';
import { type WorkflowConversation } from 'twenty-shared/workflow';
export type WorkflowAiAgentActionInput = {
agentId?: string;
prompt?: string;
+ responseFormat?: AgentResponseFormat;
humanInputInstructions?: string;
workspaceMemberId?: string;
conversation?: WorkflowConversation;
diff --git a/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/utils/__tests__/build-workflow-agent-run-spec.util.spec.ts b/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/utils/__tests__/build-workflow-agent-run-spec.util.spec.ts
index eafb7a6fed3..4ad2597ae21 100644
--- a/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/utils/__tests__/build-workflow-agent-run-spec.util.spec.ts
+++ b/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/utils/__tests__/build-workflow-agent-run-spec.util.spec.ts
@@ -67,4 +67,30 @@ describe('buildWorkflowAgentRunSpec', () => {
}).additionalExcludedToolNames,
).toContain('send_email');
});
+
+ it("asks for the step's output format", () => {
+ const responseFormat = {
+ type: 'json' as const,
+ schema: {
+ type: 'object' as const,
+ properties: { summary: { type: 'string' as const } },
+ },
+ };
+
+ const spec = buildWorkflowAgentRunSpec({
+ step: buildStep({ agentId: 'agent-id', responseFormat }),
+ isApplicationBound: false,
+ });
+
+ expect(spec.responseFormat).toEqual(responseFormat);
+ });
+
+ it("leaves the agent's output format to apply when the step gives none", () => {
+ const spec = buildWorkflowAgentRunSpec({
+ step: buildStep({ agentId: 'agent-id' }),
+ isApplicationBound: false,
+ });
+
+ expect(spec).not.toHaveProperty('responseFormat');
+ });
});
diff --git a/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/utils/build-workflow-agent-run-spec.util.ts b/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/utils/build-workflow-agent-run-spec.util.ts
index 38b6c2c122f..badf3eda7c8 100644
--- a/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/utils/build-workflow-agent-run-spec.util.ts
+++ b/packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/ai-agent/utils/build-workflow-agent-run-spec.util.ts
@@ -1,4 +1,5 @@
import { isNonEmptyString } from '@sniptt/guards';
+import { isDefined } from 'twenty-shared/utils';
import { type AgentRunSpec } from 'src/engine/metadata-modules/ai/ai-agent-execution/types/agent-run-spec.type';
import { WORKFLOW_BASE_SYSTEM_PROMPT } from 'src/modules/workflow/workflow-executor/workflow-actions/ai-agent/constants/workflow-base-system-prompt.constant';
@@ -14,7 +15,8 @@ export const buildWorkflowAgentRunSpec = ({
step: WorkflowAiAgentAction;
isApplicationBound: boolean;
}): AgentRunSpec => {
- const { agentId, humanInputInstructions } = step.settings.input;
+ const { agentId, humanInputInstructions, responseFormat } =
+ step.settings.input;
const trimmedHumanInputInstructions = humanInputInstructions?.trim();
const canAskHumans = isNonEmptyString(trimmedHumanInputInstructions);
@@ -28,6 +30,7 @@ export const buildWorkflowAgentRunSpec = ({
capabilities: {
canAskHumans,
},
+ ...(isDefined(responseFormat) ? { responseFormat } : {}),
...(isApplicationBound
? {
additionalExcludedToolNames: [
diff --git a/packages/twenty-server/src/modules/workflow/workflow-tools/tools/__tests__/update-workflow-agent.tool.spec.ts b/packages/twenty-server/src/modules/workflow/workflow-tools/tools/__tests__/update-workflow-agent.tool.spec.ts
index 08140631740..87ec024e3f1 100644
--- a/packages/twenty-server/src/modules/workflow/workflow-tools/tools/__tests__/update-workflow-agent.tool.spec.ts
+++ b/packages/twenty-server/src/modules/workflow/workflow-tools/tools/__tests__/update-workflow-agent.tool.spec.ts
@@ -27,16 +27,11 @@ const buildTool = ({
.fn()
.mockResolvedValue(draftCoreVersions),
};
- const flatEntityMapsCacheService = {
- invalidateFlatEntityMaps: jest.fn().mockResolvedValue(undefined),
- };
-
const tool = createUpdateWorkflowAgentTool(
{
agentService,
coreWorkflowVersionMutationService,
coreWorkflowVersionListService,
- flatEntityMapsCacheService,
} as never,
{
workspaceId: WORKSPACE_ID,
@@ -49,7 +44,6 @@ const buildTool = ({
agentService,
coreWorkflowVersionMutationService,
coreWorkflowVersionListService,
- flatEntityMapsCacheService,
};
};
@@ -58,45 +52,72 @@ describe('createUpdateWorkflowAgentTool', () => {
jest.clearAllMocks();
});
- it('should resync the linked AI_AGENT step output schema when responseFormat changes', async () => {
+ it('should set the response format on the linked AI_AGENT steps rather than on the agent', async () => {
const step = buildAiAgentStep(AGENT_ID);
- const {
- tool,
- coreWorkflowVersionMutationService,
- flatEntityMapsCacheService,
- } = buildTool({
- draftCoreVersions: [{ id: 'core-version-1', steps: [step] }],
- });
+ const responseFormat = {
+ type: 'json',
+ schema: {
+ type: 'object',
+ properties: { summary: { type: 'string' } },
+ },
+ };
+ const { tool, agentService, coreWorkflowVersionMutationService } =
+ buildTool({
+ draftCoreVersions: [{ id: 'core-version-1', steps: [step] }],
+ });
const result = (await tool.execute({
agentId: AGENT_ID,
- responseFormat: {
- type: 'json',
- schema: {
- type: 'object',
- properties: { summary: { type: 'string' } },
- },
- },
+ responseFormat,
} as never)) as Record<string, unknown>;
expect(result.success).toBe(true);
- expect(
- flatEntityMapsCacheService.invalidateFlatEntityMaps,
- ).toHaveBeenCalledWith({
- workspaceId: WORKSPACE_ID,
- flatMapsKeys: ['flatAgentMaps'],
- });
+ expect(agentService.updateOneAgent).not.toHaveBeenCalled();
+ expect(coreWorkflowVersionMutationService.updateStep).toHaveBeenCalledTimes(
+ 1,
+ );
expect(coreWorkflowVersionMutationService.updateStep).toHaveBeenCalledWith({
workspaceId: WORKSPACE_ID,
coreWorkflowVersionId: 'core-version-1',
- step,
+ step: {
+ ...step,
+ settings: {
+ ...step.settings,
+ input: { agentId: AGENT_ID, responseFormat },
+ },
+ },
+ });
+ });
+
+ it('should set the response format on every step using the agent in a draft', async () => {
+ const firstStep = buildAiAgentStep(AGENT_ID, 'step-1');
+ const secondStep = buildAiAgentStep(AGENT_ID, 'step-2');
+ const { tool, coreWorkflowVersionMutationService } = buildTool({
+ draftCoreVersions: [
+ { id: 'core-version-1', steps: [firstStep, secondStep] },
+ ],
});
+
+ await tool.execute({
+ agentId: AGENT_ID,
+ responseFormat: { type: 'text' },
+ } as never);
+
+ expect(coreWorkflowVersionMutationService.updateStep).toHaveBeenCalledTimes(
+ 2,
+ );
+ expect(
+ coreWorkflowVersionMutationService.updateStep.mock.calls.map(
+ ([{ step }]) => step.id,
+ ),
+ ).toEqual(['step-1', 'step-2']);
});
- it('should not resync when responseFormat is not provided', async () => {
+ it('should only update the agent when responseFormat is not provided', async () => {
const step = buildAiAgentStep(AGENT_ID);
const {
tool,
+ agentService,
coreWorkflowVersionMutationService,
coreWorkflowVersionListService,
} = buildTool({
@@ -109,6 +130,11 @@ describe('createUpdateWorkflowAgentTool', () => {
} as never)) as Record<string, unknown>;
expect(result.success).toBe(true);
+ expect(agentService.updateOneAgent).toHaveBeenCalledTimes(1);
+ expect(agentService.updateOneAgent).toHaveBeenCalledWith({
+ input: { id: AGENT_ID, prompt: 'You are a helpful assistant' },
+ workspaceId: WORKSPACE_ID,
+ });
expect(
coreWorkflowVersionListService.findDraftCoreWorkflowVersions,
).not.toHaveBeenCalled();
@@ -127,7 +153,7 @@ describe('createUpdateWorkflowAgentTool', () => {
],
});
- await tool.execute({
+ const result = await tool.execute({
agentId: AGENT_ID,
responseFormat: { type: 'text' },
} as never);
@@ -135,9 +161,11 @@ describe('createUpdateWorkflowAgentTool', () => {
expect(
coreWorkflowVersionMutationService.updateStep,
).not.toHaveBeenCalled();
+ expect(result.success).toBe(false);
+ expect(result.message).toContain('no draft AI_AGENT step uses agent');
});
- it('should still report agent update success when the resync fails', async () => {
+ it('should report a failure when the steps cannot be updated', async () => {
const step = buildAiAgentStep(AGENT_ID);
const { tool, coreWorkflowVersionMutationService } = buildTool({
draftCoreVersions: [{ id: 'core-version-1', steps: [step] }],
@@ -152,7 +180,7 @@ describe('createUpdateWorkflowAgentTool', () => {
responseFormat: { type: 'text' },
} as never)) as Record<string, unknown>;
- expect(result.success).toBe(true);
- expect(result.message).toContain('failed to resync');
+ expect(result.success).toBe(false);
+ expect(result.error).toBe('boom');
});
});
diff --git a/packages/twenty-server/src/modules/workflow/workflow-tools/tools/update-workflow-agent.tool.ts b/packages/twenty-server/src/modules/workflow/workflow-tools/tools/update-workflow-agent.tool.ts
index 7146f7701f6..312c99f45a3 100644
--- a/packages/twenty-server/src/modules/workflow/workflow-tools/tools/update-workflow-agent.tool.ts
+++ b/packages/twenty-server/src/modules/workflow/workflow-tools/tools/update-workflow-agent.tool.ts
@@ -1,33 +1,18 @@
import { isDefined } from 'twenty-shared/utils';
-import { WorkflowActionType } from 'twenty-shared/workflow';
+import {
+ agentResponseFormatSchema,
+ WorkflowActionType,
+} from 'twenty-shared/workflow';
import { z } from 'zod';
import { type AgentResponseFormat } from 'src/engine/metadata-modules/ai/ai-agent/types/agent-response-format.type';
import { type ModelId } from 'src/engine/metadata-modules/ai/ai-models/types/model-id.type';
+import { type WorkflowAiAgentAction } from 'src/modules/workflow/workflow-executor/workflow-actions/types/workflow-action.type';
import {
type WorkflowToolContext,
type WorkflowToolDependencies,
} from 'src/modules/workflow/workflow-tools/types/workflow-tool-dependencies.type';
-const agentResponseFormatSchema = z.union([
- z.object({ type: z.literal('text') }),
- z.object({
- type: z.literal('json'),
- schema: z.object({
- type: z.literal('object'),
- properties: z.record(
- z.string(),
- z.object({
- type: z.enum(['string', 'number', 'boolean']),
- description: z.string().optional(),
- }),
- ),
- required: z.array(z.string()).optional(),
- additionalProperties: z.literal(false).optional(),
- }),
- }),
-]);
-
const updateAgentSchema = z.object({
agentId: z
.string()
@@ -54,27 +39,24 @@ const updateAgentSchema = z.object({
),
});
-const resyncAiAgentStepOutputSchemas = async (
+const setAiAgentStepsResponseFormat = async (
deps: Pick<
WorkflowToolDependencies,
- | 'coreWorkflowVersionListService'
- | 'coreWorkflowVersionMutationService'
- | 'flatEntityMapsCacheService'
+ 'coreWorkflowVersionListService' | 'coreWorkflowVersionMutationService'
>,
{
workspaceId,
userWorkspaceId,
agentId,
+ responseFormat,
}: {
workspaceId: string;
userWorkspaceId: string | undefined;
agentId: string;
+ responseFormat: AgentResponseFormat;
},
-): Promise<void> => {
- await deps.flatEntityMapsCacheService.invalidateFlatEntityMaps({
- workspaceId,
- flatMapsKeys: ['flatAgentMaps'],
- });
+): Promise<number> => {
+ let updatedStepCount = 0;
const draftCoreVersions =
await deps.coreWorkflowVersionListService.findDraftCoreWorkflowVersions({
@@ -82,23 +64,31 @@ const resyncAiAgentStepOutputSchemas = async (
});
for (const draftCoreVersion of draftCoreVersions) {
- const matchingStep = draftCoreVersion.steps?.find(
- (step) =>
+ const matchingSteps = (draftCoreVersion.steps ?? []).filter(
+ (step): step is WorkflowAiAgentAction =>
step.type === WorkflowActionType.AI_AGENT &&
step.settings?.input?.agentId === agentId,
);
- if (!isDefined(matchingStep)) {
- continue;
- }
+ for (const matchingStep of matchingSteps) {
+ await deps.coreWorkflowVersionMutationService.updateStep({
+ workspaceId,
+ userWorkspaceId,
+ coreWorkflowVersionId: draftCoreVersion.id,
+ step: {
+ ...matchingStep,
+ settings: {
+ ...matchingStep.settings,
+ input: { ...matchingStep.settings.input, responseFormat },
+ },
+ },
+ });
- await deps.coreWorkflowVersionMutationService.updateStep({
- workspaceId,
- userWorkspaceId,
- coreWorkflowVersionId: draftCoreVersion.id,
- step: matchingStep,
- });
+ updatedStepCount++;
+ }
}
+
+ return updatedStepCount;
};
export const createUpdateWorkflowAgentTool = (
@@ -107,18 +97,17 @@ export const createUpdateWorkflowAgentTool = (
| 'agentService'
| 'coreWorkflowVersionListService'
| 'coreWorkflowVersionMutationService'
- | 'flatEntityMapsCacheService'
>,
context: WorkflowToolContext,
) => ({
name: 'update_workflow_agent' as const,
description: `Update the agent used by a workflow AI_AGENT step.
-Use this tool to configure the agent created when an AI_AGENT step is added: set its system prompt, the model it should use, and the format of its output.
+Use this tool to configure the agent created when an AI_AGENT step is added: set its system prompt, the model it should use, and the format of the step's output.
- prompt: the agent's system prompt (its role, behavior and task).
- modelId: optional model id; omit to keep the auto-selected model.
-- responseFormat: { type: "text" } for free-form text (referenced as {{stepId.response}}), or { type: "json", schema: { ... } } for structured output whose fields can be referenced as {{stepId.fieldName}}.
+- responseFormat: set on the draft AI_AGENT steps using this agent. { type: "text" } for free-form text (referenced as {{stepId.response}}), or { type: "json", schema: { ... } } for structured output whose fields can be referenced as {{stepId.fieldName}}.
To find the agentId, look at the AI_AGENT step's settings.input.agentId field.`,
inputSchema: updateAgentSchema,
@@ -132,36 +121,46 @@ To find the agentId, look at the AI_AGENT step's settings.input.agentId field.`,
const { agentId, prompt, modelId, responseFormat } = parameters;
const { workspaceId } = context;
- const updatedAgent = await deps.agentService.updateOneAgent({
- input: {
- id: agentId,
- ...(isDefined(prompt) ? { prompt } : {}),
- ...(isDefined(modelId) ? { modelId: modelId as ModelId } : {}),
- ...(isDefined(responseFormat) ? { responseFormat } : {}),
- },
+ if (isDefined(prompt) || isDefined(modelId)) {
+ await deps.agentService.updateOneAgent({
+ input: {
+ id: agentId,
+ ...(isDefined(prompt) ? { prompt } : {}),
+ ...(isDefined(modelId) ? { modelId: modelId as ModelId } : {}),
+ },
+ workspaceId,
+ });
+ }
+
+ if (!isDefined(responseFormat)) {
+ return {
+ success: true,
+ message: `Successfully updated agent ${agentId}`,
+ agentId,
+ };
+ }
+
+ const updatedStepCount = await setAiAgentStepsResponseFormat(deps, {
workspaceId,
+ userWorkspaceId: context.userWorkspaceId,
+ agentId,
+ responseFormat,
});
- if (isDefined(responseFormat)) {
- try {
- await resyncAiAgentStepOutputSchemas(deps, {
- workspaceId,
- userWorkspaceId: context.userWorkspaceId,
- agentId,
- });
- } catch (resyncError) {
- return {
- success: true,
- message: `Successfully updated agent ${agentId}, but failed to resync workflow step output schema: ${resyncError.message}`,
- agentId: updatedAgent.id,
- };
- }
+ if (updatedStepCount === 0) {
+ return {
+ success: false,
+ error: 'No draft AI_AGENT step uses this agent',
+ message: `The response format was not applied: no draft AI_AGENT step uses agent ${agentId}. Create a draft version first.`,
+ agentId,
+ };
}
return {
success: true,
- message: `Successfully updated agent ${agentId}`,
- agentId: updatedAgent.id,
+ message: `Successfully updated agent ${agentId} and the response format of ${updatedStepCount} draft step(s)`,
+ agentId,
+ updatedStepCount,
};
} catch (error) {
return {
diff --git a/packages/twenty-shared/src/application/runAgentType.ts b/packages/twenty-shared/src/application/runAgentType.ts
index 6f0621e8f55..bd16c2f342e 100644
--- a/packages/twenty-shared/src/application/runAgentType.ts
+++ b/packages/twenty-shared/src/application/runAgentType.ts
@@ -1,3 +1,5 @@
+import { type AgentResponseFormat } from '@/ai/types/AgentResponseFormat';
+
import { type RunAgentMessageAttachment } from './runAgentMessageAttachmentType';
export type RunAgentMessageRole = 'user' | 'assistant';
@@ -16,6 +18,7 @@ export type RunAgentThread = {
export type RunAgentInput = {
agentUniversalIdentifier: string;
additionalInstructions?: string;
+ responseFormat?: AgentResponseFormat;
thread?: RunAgentThread;
runAsWorkspaceMemberId?: string;
} & (
diff --git a/packages/twenty-shared/src/application/workflowStepManifestType.ts b/packages/twenty-shared/src/application/workflowStepManifestType.ts
index 4098f3dfc3c..88dac2a3cdf 100644
--- a/packages/twenty-shared/src/application/workflowStepManifestType.ts
+++ b/packages/twenty-shared/src/application/workflowStepManifestType.ts
@@ -2,6 +2,8 @@ import { z } from 'zod';
import { isDefined } from '@/utils/validation/isDefined';
+import { agentResponseFormatSchema } from '@/workflow/schemas/agent-response-format-schema';
+
import { workflowHttpRequestActionSettingsSchema } from '@/workflow/schemas/http-request-action-settings-schema';
import { workflowClassifyActionSettingsSchema } from '@/workflow/schemas/classify-action-settings-schema';
import { workflowIteratorActionSettingsSchema } from '@/workflow/schemas/iterator-action-settings-schema';
@@ -189,6 +191,7 @@ export const workflowStepManifestSchema = z.discriminatedUnion('type', [
z.strictObject({
agentUniversalIdentifier: z.uuid().optional(),
prompt: z.string(),
+ responseFormat: agentResponseFormatSchema.optional(),
}),
),
]);
diff --git a/packages/twenty-shared/src/workflow/index.ts b/packages/twenty-shared/src/workflow/index.ts
index 167be7edda1..ffc113870c4 100644
--- a/packages/twenty-shared/src/workflow/index.ts
+++ b/packages/twenty-shared/src/workflow/index.ts
@@ -31,6 +31,7 @@ export type {
WorkflowLayoutOptions,
} from './layout/utils/compute-workflow-layout.util';
export { computeWorkflowLayout } from './layout/utils/compute-workflow-layout.util';
+export { agentResponseFormatSchema } from './schemas/agent-response-format-schema';
export { workflowAiAgentActionSchema } from './schemas/ai-agent-action-schema';
export { workflowAiAgentActionSettingsSchema } from './schemas/ai-agent-action-settings-schema';
export { baseTriggerSchema } from './schemas/base-trigger-schema';
diff --git a/packages/twenty-shared/src/workflow/schemas/agent-response-format-schema.ts b/packages/twenty-shared/src/workflow/schemas/agent-response-format-schema.ts
new file mode 100644
index 00000000000..72547ebb342
--- /dev/null
+++ b/packages/twenty-shared/src/workflow/schemas/agent-response-format-schema.ts
@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+import { isValidAgentResponseSchemaPropertyKey } from '@/ai/utils/is-valid-agent-response-schema-property-key.util';
+
+const agentResponseSchemaSchema = z.object({
+ type: z.literal('object'),
+ properties: z
+ .record(
+ z.string(),
+ z.object({
+ type: z.enum(['string', 'number', 'boolean']),
+ description: z.string().optional(),
+ }),
+ )
+ .refine(
+ (properties) =>
+ Object.keys(properties).every(isValidAgentResponseSchemaPropertyKey),
+ {
+ message:
+ 'Output field names can only contain letters, numbers, underscores, dots or hyphens (max 64 characters)',
+ },
+ ),
+ required: z.array(z.string()).optional(),
+ additionalProperties: z.literal(false).optional(),
+});
+
+export const agentResponseFormatSchema = z.discriminatedUnion('type', [
+ z.object({ type: z.literal('text') }),
+ z.object({ type: z.literal('json'), schema: agentResponseSchemaSchema }),
+]);
diff --git a/packages/twenty-shared/src/workflow/schemas/ai-agent-action-settings-schema.ts b/packages/twenty-shared/src/workflow/schemas/ai-agent-action-settings-schema.ts
index c171e3f71b3..c45072aaecb 100644
--- a/packages/twenty-shared/src/workflow/schemas/ai-agent-action-settings-schema.ts
+++ b/packages/twenty-shared/src/workflow/schemas/ai-agent-action-settings-schema.ts
@@ -1,4 +1,6 @@
import { z } from 'zod';
+
+import { agentResponseFormatSchema } from './agent-response-format-schema';
import { baseWorkflowActionSettingsSchema } from './base-workflow-action-settings-schema';
import { workflowConversationSchema } from './workflow-conversation-schema';
@@ -7,6 +9,7 @@ export const workflowAiAgentActionSettingsSchema =
input: z.object({
agentId: z.string().optional(),
prompt: z.string().optional(),
+ responseFormat: agentResponseFormatSchema.optional(),
// Empty by default: stopping for a person pauses the run, which existing workflows were not built to expect.
humanInputInstructions: z.string().optional(),
// the member the agent's conversation is with, the workflow's creator when empty