|
| 1 | +# N8N AI Agent Tool Usage Display |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +Starting with version 2.2.0, the N8N pipeline automatically displays AI Agent tool calls in a user-friendly format. When your N8N workflow includes an AI Agent node that uses tools (like Wikipedia, Date/Time, Calculator, etc.), the pipeline will extract and display detailed information about each tool invocation. |
| 6 | + |
| 7 | +## Important Limitation |
| 8 | + |
| 9 | +> [!IMPORTANT] |
| 10 | +> **⚠️ Non-Streaming Mode Only**: Tool usage display is currently only available in **non-streaming mode**. N8N's AI Agent streaming responses do not include the `intermediateSteps` field, which is required to show tool calls. This is a limitation of N8N's streaming implementation, not the pipeline. |
| 11 | +> |
| 12 | +> **To see tool calls**: Configure your N8N workflow to use **non-streaming responses** (remove or disable streaming in the "Respond to Webhook" node). |
| 13 | +
|
| 14 | +## Features |
| 15 | + |
| 16 | +### Automatic Detection |
| 17 | + |
| 18 | +- Works with **non-streaming** N8N responses |
| 19 | +- Automatically extracts `intermediateSteps` from the N8N response payload |
| 20 | +- No additional configuration required |
| 21 | + |
| 22 | +### Rich Display Format |
| 23 | + |
| 24 | +Each tool call is displayed with: |
| 25 | + |
| 26 | +- 🔧 **Tool Name**: The name of the tool that was invoked |
| 27 | +- 🆔 **Call ID**: Unique identifier for debugging (e.g., `call_FB0sIgrwuIGJkOaROor7raU2`) |
| 28 | +- 📥 **Input**: The parameters passed to the tool (formatted as JSON) |
| 29 | +- 📤 **Result**: The tool's response/observation |
| 30 | +- 📝 **Log**: Optional log messages from the tool execution |
| 31 | + |
| 32 | +### Collapsible UI |
| 33 | + |
| 34 | +Uses HTML `<details>` tags for a clean, expandable interface: |
| 35 | + |
| 36 | +```txt |
| 37 | +🛠️ Tool Calls (3 steps) ▶ |
| 38 | + ├─ Step 1: Date_Time ▶ |
| 39 | + ├─ Step 2: Wikipedia ▶ |
| 40 | + └─ Step 3: Wikipedia ▶ |
| 41 | +``` |
| 42 | + |
| 43 | +Click to expand each step and view full details. |
| 44 | + |
| 45 | +## Example |
| 46 | + |
| 47 | +### N8N Response Format |
| 48 | + |
| 49 | +Your N8N AI Agent workflow should return data in this format: |
| 50 | + |
| 51 | +```json |
| 52 | +[ |
| 53 | + { |
| 54 | + "output": "Current time in Europe/London: 2025-10-10 09:46:45 BST (UTC+1)...", |
| 55 | + "intermediateSteps": [ |
| 56 | + { |
| 57 | + "action": { |
| 58 | + "tool": "Date_Time", |
| 59 | + "toolInput": { |
| 60 | + "Include_Current_Time": true, |
| 61 | + "Timezone": "Europe/London" |
| 62 | + }, |
| 63 | + "toolCallId": "call_FB0sIgrwuIGJkOaROor7raU2", |
| 64 | + "log": "Calling Date_Time with input: {...}" |
| 65 | + }, |
| 66 | + "observation": "[{\"currentDate\":\"2025-10-10T09:46:45.754+01:00\"}]" |
| 67 | + }, |
| 68 | + { |
| 69 | + "action": { |
| 70 | + "tool": "Wikipedia", |
| 71 | + "toolInput": { |
| 72 | + "input": "Europe/London time zone Wikipedia" |
| 73 | + }, |
| 74 | + "toolCallId": "call_QFUtaSdUI2PtgjhkDTmbRknt", |
| 75 | + "log": "Calling Wikipedia with input: {...}" |
| 76 | + }, |
| 77 | + "observation": "Page: Time zone\nSummary: Time zones are regions..." |
| 78 | + } |
| 79 | + ] |
| 80 | + } |
| 81 | +] |
| 82 | +``` |
| 83 | + |
| 84 | +### UI Display |
| 85 | + |
| 86 | +The user will see: |
| 87 | + |
| 88 | +1. **Main Response**: The agent's text response from the `output` field |
| 89 | +2. **Tool Calls Section**: A collapsible section with all tool invocations |
| 90 | + |
| 91 | +## Implementation Details |
| 92 | + |
| 93 | +### Streaming Mode ⚠️ |
| 94 | + |
| 95 | +> **Not Supported**: N8N AI Agent does not include `intermediateSteps` in streaming responses. The streaming mode only sends content chunks, not metadata. This is a limitation of N8N's implementation. |
| 96 | +
|
| 97 | +### Non-Streaming Mode ✅ |
| 98 | + |
| 99 | +- Tool calls are extracted from the complete response JSON |
| 100 | +- Supports both array `[{...}]` and object `{...}` response formats |
| 101 | +- Automatically detects and formats all tool calls from `intermediateSteps` |
| 102 | + |
| 103 | +### Data Structure Support |
| 104 | + |
| 105 | +The pipeline handles both response formats from N8N: |
| 106 | + |
| 107 | +**Array Format (typical for streaming):** |
| 108 | + |
| 109 | +```json |
| 110 | +[ |
| 111 | + { |
| 112 | + "output": "...", |
| 113 | + "intermediateSteps": [...] |
| 114 | + } |
| 115 | +] |
| 116 | +``` |
| 117 | + |
| 118 | +**Object Format (typical for non-streaming):** |
| 119 | + |
| 120 | +```json |
| 121 | +{ |
| 122 | + "output": "...", |
| 123 | + "intermediateSteps": [...] |
| 124 | +} |
| 125 | +``` |
| 126 | + |
| 127 | +## N8N Workflow Configuration |
| 128 | + |
| 129 | +To enable this feature, your N8N workflow must: |
| 130 | + |
| 131 | +1. **Use AI Agent Node**: Include an AI Agent node with tools |
| 132 | +2. **Disable Streaming**: In the "Respond to Webhook" node, ensure streaming is disabled |
| 133 | +3. **Return intermediateSteps**: Ensure your workflow returns the `intermediateSteps` array in the response |
| 134 | + |
| 135 | +### Example N8N Workflow Structure |
| 136 | + |
| 137 | +```txt |
| 138 | +Webhook Trigger |
| 139 | + ↓ |
| 140 | +AI Agent (with tools: Wikipedia, Date/Time, etc.) |
| 141 | + ↓ |
| 142 | +Function Node (format response) |
| 143 | + ↓ |
| 144 | +Respond to Webhook |
| 145 | +``` |
| 146 | + |
| 147 | +**Function Node Code Example:** |
| 148 | + |
| 149 | +```javascript |
| 150 | +// Get the AI Agent output |
| 151 | +const agentOutput = $('AI Agent').item.json; |
| 152 | + |
| 153 | +return { |
| 154 | + output: agentOutput.output, |
| 155 | + intermediateSteps: agentOutput.intermediateSteps || [] |
| 156 | +}; |
| 157 | +``` |
| 158 | + |
| 159 | +## Supported Tools |
| 160 | + |
| 161 | +The display works with any N8N tool, including: |
| 162 | + |
| 163 | +- 📅 Date/Time |
| 164 | +- 📚 Wikipedia |
| 165 | +- 🔍 Search |
| 166 | +- 🧮 Calculator |
| 167 | +- 🌐 HTTP Request |
| 168 | +- 📧 Email |
| 169 | +- 💾 Database queries |
| 170 | +- And any custom tools you create! |
| 171 | + |
| 172 | +## Troubleshooting |
| 173 | + |
| 174 | +### Tool Calls Not Showing? |
| 175 | + |
| 176 | +Check that: |
| 177 | + |
| 178 | +1. ✅ Your N8N workflow includes an AI Agent node with tools |
| 179 | +2. ✅ The response includes the `intermediateSteps` array |
| 180 | +3. ✅ The N8N pipeline version is 2.2.0 or higher |
| 181 | +4. ✅ The response structure matches the expected format (see examples above) |
| 182 | + |
| 183 | +### Debugging |
| 184 | + |
| 185 | +Enable debug logging in the pipeline to see: |
| 186 | + |
| 187 | +- Number of intermediate steps found |
| 188 | +- Tool call extraction process |
| 189 | +- Response parsing details |
| 190 | + |
| 191 | +The pipeline logs helpful messages like: |
| 192 | + |
| 193 | +```txt |
| 194 | +Found 3 intermediate steps |
| 195 | +Added 3 tool calls to response |
| 196 | +``` |
| 197 | + |
| 198 | +## Related Documentation |
| 199 | + |
| 200 | +- [N8N Integration Overview](./n8n-integration.md) |
| 201 | +- [N8N Template Workflows](../pipelines/n8n/) |
| 202 | +- [N8N AI Agent Documentation](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/) |
0 commit comments