feat: use JSON for agent configuration#28339
Open
yehorkardash wants to merge 56 commits inton8n-agentsfrom
Open
feat: use JSON for agent configuration#28339yehorkardash wants to merge 56 commits inton8n-agentsfrom
yehorkardash wants to merge 56 commits inton8n-agentsfrom
Conversation
…agents-json-config
n8n-assistant
bot
added
core
Bundle ReportChanges will decrease total bundle size by 87.43kB (-0.19%) ⬇️. This is within the configured threshold ✅ Detailed changes
Affected Assets, Files, and Routes:view changes for bundle: editor-ui-esmAssets Changed:
|
Merging this PR will not alter performance
Comparing 
Footnotes
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
7 issues found across 61 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/cli/src/modules/agents/schema-text-serializer.ts">
<violation number="1" location="packages/cli/src/modules/agents/schema-text-serializer.ts:55">
P2: Array item unions are reduced to `unknown`, so discriminated-union item schemas lose their shape in output.</violation>
<violation number="2" location="packages/cli/src/modules/agents/schema-text-serializer.ts:85">
P1: Union fields are serialized as `array of ...`, which misrepresents `oneOf`/`anyOf` schemas.</violation>
</file>
<file name="packages/cli/src/modules/agents/__tests__/agent-secure-runtime.test.ts">
<violation number="1" location="packages/cli/src/modules/agents/__tests__/agent-secure-runtime.test.ts:318">
P2: Pass the tool input object as the second argument. The current call sends `'double'` into the handler, so the test won't produce `{ result: 42 }`.</violation>
</file>
<file name="packages/frontend/editor-ui/src/features/agents/components/AgentCodeEditor.vue">
<violation number="1" location="packages/frontend/editor-ui/src/features/agents/components/AgentCodeEditor.vue:102">
P2: Avoid duplicating the tool editor initialization logic; reuse `createToolEditor()` in the expanded-tools watcher to prevent divergence between two code paths.</violation>
<violation number="2" location="packages/frontend/editor-ui/src/features/agents/components/AgentCodeEditor.vue:180">
P2: Destroy and remove `toolViews` entries when a tool ID is removed from `agentTools` to avoid stale editor instances accumulating during runtime updates.</violation>
</file>
<file name="packages/@n8n/agents/src/sdk/agent.ts">
<violation number="1" location="packages/@n8n/agents/src/sdk/agent.ts:550">
P2: `snapshot` leaks a mutable reference to internal `thinkingConfig`, so external code can mutate agent state through what is documented as a read-only view.</violation>
</file>
<file name="packages/cli/src/modules/agents/agents.service.ts">
<violation number="1" location="packages/cli/src/modules/agents/agents.service.ts:25">
P2: Custom agent: **Quality & Performance Review**
Top-level import of `@n8n/workflow-sdk` eagerly loads a heavy dependency even though it is only needed in node-tool config validation flow.</violation>
</file>
Architecture diagram
sequenceDiagram
participant UI as Browser (Frontend)
participant API as Agents Controller
participant Tools as Agents Builder Tools
participant Sandbox as Secure Runtime (IVM)
participant DB as Database (Agents Table)
Note over UI,DB: NEW: JSON-Based Agent Builder Flow
UI->>API: POST /chat (Builder Mode)
API->>Tools: Invoke Builder LLM
alt NEW: Update Configuration (write_config / patch_config)
Tools->>Tools: NEW: tryParseConfigJson()
Tools->>Tools: NEW: fast-json-patch (if patching)
Tools->>Tools: NEW: AgentJsonConfigSchema.safeParse (Zod)
alt Validation Success
Tools->>DB: NEW: updateConfig (Persist JSON)
DB-->>Tools: ok: true
else Validation Failure
Tools-->>Tools: formatZodErrors()
Tools-->>API: { ok: false, errors }
end
end
alt NEW: Define Custom Tool (build_custom_tool)
Tools->>Sandbox: NEW: describeToolSecurely(tsCode)
Sandbox->>Sandbox: Compile TS to JS
Sandbox-->>Tools: ToolDescriptor (JSON Schema)
Tools->>DB: NEW: Save TS + Descriptor to 'tools' column
DB-->>Tools: Saved
end
alt Shared Discovery Tools
Tools->>DB: list_workflows / list_credentials
DB-->>Tools: Result sets
Tools->>Tools: search_nodes / get_node_types
end
Tools-->>API: Stream chunks / Tool results
API-->>UI: SSE Stream (configUpdated / toolUpdated)
Note over UI,DB: NEW: Runtime Agent Bootstrapping
UI->>API: POST /chat (Agent Execution)
API->>DB: Fetch JSON config & custom tools
DB-->>API: Agent record (JSON schema + tools)
API->>API: NEW: buildFromJson()
Note right of API: Binds custom tools to Isolated-VM handlers
API->>API: Agent.execute()
API-->>UI: Response
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
packages/cli/src/modules/agents/__tests__/agent-secure-runtime.test.ts
Outdated
Show resolved
Hide resolved
packages/frontend/editor-ui/src/features/agents/components/AgentCodeEditor.vue
Show resolved
Hide resolved
packages/frontend/editor-ui/src/features/agents/components/AgentCodeEditor.vue
Show resolved
Hide resolved
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
Contributor
Performance ComparisonComparing current → latest master → 14-day baseline Memory consumption baseline with starter plan resources
docker-stats
Idle baseline with Instance AI module loaded
How to read this table
|
Contributor
There was a problem hiding this comment.
1 issue found across 3 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/cli/src/modules/agents/json-config/schema-text-serializer.ts">
<violation number="1" location="packages/cli/src/modules/agents/json-config/schema-text-serializer.ts:346">
P2: `serializeArrayUnion()` drops `(required)` / `(default: ...)` metadata for array-union fields, so required fields can be rendered as if optional.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
packages/cli/src/modules/agents/json-config/schema-text-serializer.ts
Outdated
Show resolved
Hide resolved
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a JSON-based builder mode for the agent builder. The builder LLM now writes and patches the agent configuration as raw JSON strings rather than through writing typescript code. Custom tools are still written using typescript.
The builder prompt includes examples of using different features and simplified json schema of the agent config.
There's a custom json schema serializer that reduces token size of schema by around ~40%
Serialized agent schema
The builder has access to two groups of tools:
Config tools (JSON mode)
write_configpatch_configfast-json-patch, validates the result, and persists itBoth tools return
{ ok: true }on success or{ ok: false, errors }with structured path/message/expected/received fields on failure.patch_configadditionally returns astage("parse","patch", or"schema") indicating where the failure occurred.Shared tools (always present)
build_custom_toolToolbuilder API; validates the code in a sandbox before savinglist_credentialslist_workflowssearch_nodesget_node_typessearch_nodesValidation pipeline
write_configandpatch_configpass every config through the same pipeline:tryParseConfigJson— catchesJSON.parsefailures with position infoAgentJsonConfigSchema.safeParse(Zod) — validates schema shape and field constraintsagentsService.updateConfig— persists to the databaseZod errors are normalized by
formatZodErrorsinto{ path, message, expected, received }objects so the LLM can self-correct.Related Linear tickets, Github issues, and Community forum posts
Review / Merge checklist
Backport to Beta,Backport to Stable, orBackport to v1(if the PR is an urgent fix that needs to be backported)