fix(ai-builder): Add guidance for referencing Webhook and AI Agent output (#24301)

packages/@n8n/ai-workflow-builder.ee/src/prompts/chains/parameter-updater/guides/index.ts

@@ -11,3 +11,6 @@ export { EMBEDDING_NODES_GUIDE } from './embedding-nodes';
 export { RESOURCE_LOCATOR_GUIDE } from './resource-locator';
 export { SYSTEM_MESSAGE_GUIDE } from './system-message';
 export { TEXT_FIELDS_GUIDE } from './text-fields';
+
+// Context-aware guides
+export { PREDECESSOR_OUTPUT_GUIDE } from './predecessor-output';

packages/@n8n/ai-workflow-builder.ee/src/prompts/chains/parameter-updater/guides/predecessor-output.ts

@@ -0,0 +1,30 @@
+import type { NodeTypeGuide } from '../types';
+
+/**
+ * Guide for correctly referencing output from special node types.
+ *
+ * Some nodes have non-standard output structures that require specific
+ * referencing patterns. This guide helps the parameter updater generate
+ * correct expressions when data comes from these nodes.
+ */
+export const PREDECESSOR_OUTPUT_GUIDE: NodeTypeGuide = {
+	patterns: ['*'], // Applies to all nodes being configured
+	content: `
+### Referencing Output from Special Node Types
+
+#### AI Agent Output Structure
+AI Agent nodes (n8n-nodes-langchain.agent) wrap their response in an "output" object:
+- Without Structured Output Parser: Use \`$json.output\` to access the response string
+- With Structured Output Parser (hasOutputParser: true in node settings): Use \`$json.output.fieldName\` to access parsed fields
+- Use \`$('AI Agent').item.json.output.fieldName\` when referencing a node, instead of \`$('AI Agent').item.json.fieldName\`
+- WRONG: \`$json.summary\` → CORRECT: \`$json.output.summary\`
+
+#### Webhook Node Output Structure
+When referencing data from a Webhook node (n8n-nodes-base.webhook), the incoming request is structured under \`$json\`:
+- \`$json.headers\` - HTTP headers, example: \`$json.headers.authorization\`
+- \`$json.params\` - URL path parameters, example route: \`/users/:id\`, access: \`$json.params.id\`
+- \`$json.query\` - Query string parameters, example URL: \`?user_id=123\`, access: \`$json.query.user_id\`
+- \`$json.body\` - Request payload, example JSON: \`{ "userName": "sam" }\`, access: \`$json.body.userName\`
+
+CRITICAL: When referencing data from a Webhook node, do NOT use \`$json.fieldName\` directly - always specify the container (body, query, params, or headers).`,
+};

packages/@n8n/ai-workflow-builder.ee/src/prompts/chains/parameter-updater/registry.ts

@@ -18,6 +18,7 @@ import {
 	GMAIL_GUIDE,
 	HTTP_REQUEST_GUIDE,
 	IF_NODE_GUIDE,
+	PREDECESSOR_OUTPUT_GUIDE,
 	RESOURCE_LOCATOR_GUIDE,
 	SET_NODE_GUIDE,
 	SWITCH_NODE_GUIDE,
@@ -47,6 +48,8 @@ const guides: NodeTypeGuide[] = [
 	RESOURCE_LOCATOR_GUIDE,
 	SYSTEM_MESSAGE_GUIDE,
 	TEXT_FIELDS_GUIDE,
+	// Context-aware guides
+	PREDECESSOR_OUTPUT_GUIDE,
 ];
 
 /**