{"_id":"@brendangubt/n8n-nodes-agent-langfuse","_rev":"2-309cd3c583dc6008a4a0f26149917acf","name":"@brendangubt/n8n-nodes-agent-langfuse","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"@brendangubt/n8n-nodes-agent-langfuse","version":"0.2.0","keywords":["n8n-community-node-package","langfuse","langchain","ai-agent","observability","tracing"],"author":{"name":"Brendan Gooden"},"license":"MIT","_id":"@brendangubt/n8n-nodes-agent-langfuse@0.2.0","maintainers":[{"name":"brendangubt","email":"brendan.gooden@ubteam.com"}],"contributors":[{"name":"diward","email":"edu.diward@gmail.com"}],"homepage":"https://github.com/brendangooden/n8n-nodes-agent-langfuse#readme","bugs":{"url":"https://github.com/brendangooden/n8n-nodes-agent-langfuse/issues"},"n8n":{"nodes":["dist/nodes/AgentLangfuse/AgentLangfuse.node.js"],"credentials":["dist/credentials/LangfuseApi.credentials.js"],"n8nNodesApiVersion":1},"dist":{"shasum":"e1f26dcddbd215d43a41703b3c76ba6ffb1741d5","tarball":"https://registry.npmjs.org/@brendangubt/n8n-nodes-agent-langfuse/-/n8n-nodes-agent-langfuse-0.2.0.tgz","fileCount":20,"integrity":"sha512-WYjo9xyFk7RIp7qTMuj35yP+IIgI1JgXS0xNrP37BT01YoKxvDY75E0tB7+Sw2aYqk0Y7t/j3EqHk2Nx1nIGGg==","signatures":[{"sig":"MEQCICHrpC6q8c9RKdyaWurtEllbFqtqFfSmC2N3BewZlA7CAiAQ/3YeO8vQSJ/viJXj65/LelEip72A73CpM8vNOcp6nQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":110396},"main":"index.js","engines":{"node":">=20.15"},"gitHead":"f9a36c67e5717651b2d8755f9876a9f213b0afdc","scripts":{"dev":"tsc --watch","build":"tsc && npm run copy-icons","copy-icons":"node -e \"const fs=require('fs'),s='nodes/AgentLangfuse/icons',d='dist/nodes/AgentLangfuse/icons';fs.mkdirSync(d,{recursive:true});fs.readdirSync(s).filter(f=>f.endsWith('.svg')).forEach(f=>fs.copyFileSync(s+'/'+f,d+'/'+f))\"","prepublishOnly":"npm run build"},"_npmUser":{"name":"brendangubt","email":"brendan.gooden@ubteam.com"},"repository":{"url":"git+https://github.com/brendangooden/n8n-nodes-agent-langfuse.git","type":"git"},"_npmVersion":"11.12.1","description":"n8n AI Agent node with native Langfuse integration: tracing + prompt management. Fork of n8n-nodes-agent-langfuse with prompt variable support.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"lodash":"^4.17.21","langfuse":"^3.0.0","langchain":"^0.3.0","@langchain/core":">=0.3.58 <0.4.0","@langchain/openai":"^0.4.0","langfuse-langchain":"^3.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^6.0.3","n8n-workflow":"^2.13.1"},"_npmOperationalInternal":{"tmp":"tmp/n8n-nodes-agent-langfuse_0.2.0_1780531107004_0.1701787792181404","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@brendangubt/n8n-nodes-agent-langfuse","version":"0.3.0","description":"n8n AI Agent node with native Langfuse integration: tracing + prompt management. Fork of n8n-nodes-agent-langfuse with prompt variable support.","keywords":["n8n-community-node-package","langfuse","langchain","ai-agent","observability","tracing"],"license":"MIT","author":{"name":"Brendan Gooden"},"contributors":[{"name":"diward","email":"edu.diward@gmail.com"}],"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/brendangooden/n8n-nodes-agent-langfuse.git"},"engines":{"node":">=20.15"},"main":"index.js","scripts":{"build":"tsc && npm run copy-icons","copy-icons":"node -e \"const fs=require('fs'),s='nodes/AgentLangfuse/icons',d='dist/nodes/AgentLangfuse/icons';fs.mkdirSync(d,{recursive:true});fs.readdirSync(s).filter(f=>f.endsWith('.svg')).forEach(f=>fs.copyFileSync(s+'/'+f,d+'/'+f))\"","dev":"tsc --watch","prepublishOnly":"npm run build"},"n8n":{"n8nNodesApiVersion":1,"credentials":["dist/credentials/LangfuseApi.credentials.js"],"nodes":["dist/nodes/AgentLangfuse/AgentLangfuse.node.js"]},"dependencies":{"@langchain/core":">=0.3.58 <0.4.0","@langchain/openai":"^0.4.0","langchain":"^0.3.0","langfuse":"^3.0.0","langfuse-langchain":"^3.0.0","lodash":"^4.17.21"},"devDependencies":{"n8n-workflow":"^2.13.1","typescript":"^6.0.3"},"gitHead":"ee095ac0eb4db9dae65c1f0250e81bc8f88c3040","_id":"@brendangubt/n8n-nodes-agent-langfuse@0.3.0","bugs":{"url":"https://github.com/brendangooden/n8n-nodes-agent-langfuse/issues"},"homepage":"https://github.com/brendangooden/n8n-nodes-agent-langfuse#readme","_nodeVersion":"22.22.3","_npmVersion":"11.16.0","dist":{"integrity":"sha512-GT7B3gaynQ+fwOuOFvv/0plpJOZqnhORAV/FwdZ7+qspCQnP8Gb5Y5CZAqq2OljULxvbN5D9f56j/Jz4mMbdMg==","shasum":"090196fe410657286cf726dc0352adaa94668e72","tarball":"https://registry.npmjs.org/@brendangubt/n8n-nodes-agent-langfuse/-/n8n-nodes-agent-langfuse-0.3.0.tgz","fileCount":20,"unpackedSize":111257,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@brendangubt%2fn8n-nodes-agent-langfuse@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC8UUWBoVkoG/pewfNeE9xzHvn3BS1Kxy0BHNxjQ8UU3gIgDrm5l4aCOHM4V3MfBBVw7/m1MEn9kDDqN26BVhdvAMI="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:d37d905e-4ac7-4ed9-9ee8-1b83a80bfc84"}},"directories":{},"maintainers":[{"name":"brendangubt","email":"brendan.gooden@ubteam.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/n8n-nodes-agent-langfuse_0.3.0_1780554694917_0.5959809956311739"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T23:58:26.812Z","modified":"2026-06-04T06:31:35.397Z","0.2.0":"2026-06-03T23:58:27.149Z","0.3.0":"2026-06-04T06:31:35.078Z"},"bugs":{"url":"https://github.com/brendangooden/n8n-nodes-agent-langfuse/issues"},"author":{"name":"Brendan Gooden"},"license":"MIT","homepage":"https://github.com/brendangooden/n8n-nodes-agent-langfuse#readme","keywords":["n8n-community-node-package","langfuse","langchain","ai-agent","observability","tracing"],"repository":{"type":"git","url":"git+https://github.com/brendangooden/n8n-nodes-agent-langfuse.git"},"description":"n8n AI Agent node with native Langfuse integration: tracing + prompt management. Fork of n8n-nodes-agent-langfuse with prompt variable support.","contributors":[{"name":"diward","email":"edu.diward@gmail.com"}],"maintainers":[{"name":"brendangubt","email":"brendan.gooden@ubteam.com"}],"readme":"# @brendangubt/n8n-nodes-agent-langfuse\n\n[![npm version](https://img.shields.io/npm/v/%40brendangubt%2Fn8n-nodes-agent-langfuse)](https://www.npmjs.com/package/@brendangubt/n8n-nodes-agent-langfuse)\n[![npm downloads](https://img.shields.io/npm/dm/%40brendangubt%2Fn8n-nodes-agent-langfuse)](https://www.npmjs.com/package/@brendangubt/n8n-nodes-agent-langfuse)\n[![license](https://img.shields.io/npm/l/%40brendangubt%2Fn8n-nodes-agent-langfuse)](LICENSE)\n\n> Fork of [n8n-nodes-agent-langfuse](https://github.com/Diward/n8n-nodes-agent-langfuse) by [diward](https://github.com/Diward), adding Langfuse prompt variable substitution and auto-loaded prompt variables.\n\nAn n8n community node that brings **AI Agent execution** and **[Langfuse](https://langfuse.com) observability** together in a single node. Select prompts from Langfuse, override models dynamically, and get full tracing — all without extra nodes in your workflow.\n\n> **First n8n node to combine Agent V3 architecture with native Langfuse prompt management and tracing.**\n\n![Node in n8n canvas](assets/node-canvas.png)\n\n## Why this node?\n\nIf you use n8n's AI Agent with Langfuse, you currently need:\n- An **HTTP Request node** to fetch prompts from Langfuse API\n- A **Code node** to extract the prompt content and model config\n- The **AI Agent node** itself\n- Manual configuration to pass tracing callbacks\n\n**This node replaces all of that with one node.** Select your Langfuse prompt from a dropdown, and the node handles everything: prompt injection, model override, tracing, and metadata.\n\n### vs. other Langfuse nodes\n\n| Feature | This node | Official Langfuse nodes | Wistron DXLab |\n|---------|-----------|------------------------|---------------|\n| Agent execution | Yes | No (separate nodes) | Yes |\n| Prompt selector dropdown | Yes | Yes (separate node) | No |\n| Model override from prompt config | Yes | N/A | No |\n| Auto metadata (project, prompt, version) | Yes | No | No |\n| Agent V3 architecture | Yes | N/A | No (V2) |\n| Streaming support | Yes | N/A | Limited |\n| Fallback model | Yes | N/A | Yes |\n| Batching | Yes | N/A | Yes |\n\n## Quick Start\n\n1. **Install** the node: Settings > Community Nodes > Install > `@brendangubt/n8n-nodes-agent-langfuse`\n2. **Create** a Langfuse API credential with your Base URL, Public Key, and Secret Key\n3. **Add** \"AI Agent + Langfuse\" to your workflow and connect a Chat Model\n4. **Select** a Langfuse prompt from the dropdown\n5. **Execute** — the agent runs with your prompt and traces to Langfuse automatically\n\n## Features\n\n- **Langfuse Prompt Selector** — Browse and select production prompts from Langfuse directly in the node UI. No HTTP Request nodes needed.\n- **Model Override** — Use the model and temperature defined in your Langfuse prompt config, or override manually. Switch models by changing Langfuse config — no workflow edits required.\n- **Automatic Tracing** — Every execution is traced to Langfuse with full LLM call details, tool usage, and intermediate steps. The trace name defaults to the **n8n node name**, so naming your node descriptively (e.g., \"AI Agent - Selector\") makes traces easy to find in Langfuse.\n- **Auto Metadata** — Project name, prompt name, and prompt version are automatically included in every trace. Add your own custom metadata on top.\n- **Streaming** — Full streaming support for real-time responses.\n- **Fallback Model** — Configure a backup model that activates if the primary fails.\n- **Batch Processing** — Process multiple items with configurable batch size and delay.\n- **Output Parser** — Connect structured output parsers for typed responses.\n- **Memory** — Connect memory nodes for conversational agents.\n\n## Installation\n\n### Community Nodes (Recommended)\n\n1. Go to **Settings > Community Nodes**\n2. Click **Install**\n3. Enter `@brendangubt/n8n-nodes-agent-langfuse`\n4. Click **Install**\n\n### Manual Installation\n\n```bash\ncd ~/.n8n/nodes\nnpm install @brendangubt/n8n-nodes-agent-langfuse\n# Restart n8n\n```\n\n## Setup\n\n### 1. Create Langfuse Credentials\n\n![Credential setup](assets/credential-setup.png)\n\n1. In n8n, go to **Credentials > New Credential**\n2. Search for **Langfuse API**\n3. Fill in:\n   - **Base URL**: Your Langfuse instance URL (e.g., `https://cloud.langfuse.com` or your self-hosted URL)\n   - **Public Key**: Your Langfuse project public key\n   - **Secret Key**: Your Langfuse project secret key\n4. Click **Test** to verify the connection — you should see \"Connection tested successfully\"\n\n> **Tip:** Find your keys in Langfuse under **Settings > Projects > [Your Project] > API Keys**\n\n### 2. Configure the Node\n\n![Node configuration](assets/node-configuration.png)\n\n1. Search for **\"AI Agent + Langfuse\"** in the node panel\n2. Drag it into your workflow\n3. Connect a **Chat Model** (OpenAI, OpenRouter, Anthropic, etc.) to the \"Chat Model\" input\n4. Select your Langfuse credential\n5. Choose your prompt from the dropdown\n6. Optionally connect **Tools**, **Memory**, or **Output Parser**\n\n## Configuration\n\n### Prompt Source\n\n| Option | Description |\n|--------|-------------|\n| **Langfuse Prompt** | Select a production prompt from your Langfuse project. The dropdown shows all `chat`-type prompts. |\n| **Manual** | Write the system message directly in the node (standard behavior). |\n\n### Langfuse Prompt Selector\n\n![Prompt dropdown](assets/prompt-dropdown.png)\n\nThe dropdown fetches all production `chat`-type prompts from your Langfuse project. Select one, and the node automatically:\n- Injects the prompt content as the system message\n- Reads the model and temperature from the prompt config (if Model Source = \"From Langfuse\")\n- Includes the prompt name and version in the trace metadata\n\n### Model Source (when using Langfuse Prompt)\n\n| Option | Description |\n|--------|-------------|\n| **From Langfuse** | Uses the `model` and `temperature` from your Langfuse prompt's config. The connected Chat Model provides the provider and API key — only the model name is overridden. |\n| **Manual Override** | Uses the model exactly as configured in the connected Chat Model node. |\n\n> **How model override works:** When you select \"From Langfuse\", the node creates a new LLM instance using the same provider and API key from your connected Chat Model, but with the model name from Langfuse. For example, if your Chat Model is configured with OpenRouter and `gpt-4.1-mini`, but your Langfuse prompt has `model: \"openai/gpt-5-nano\"`, the node will call OpenRouter with `gpt-5-nano`. Change models in Langfuse — no workflow changes needed.\n\n### Prompt Variables\n\nLangfuse chat prompts can contain `{{variable}}` placeholders in their `system` and `user` messages. The node reads the selected prompt and **auto-populates one input field per `{{variable}}`** — no need to type variable names by hand.\n\n- Select a Langfuse prompt, then open the **Prompt Variables** mapper. It lists every `{{var}}` referenced by that prompt's `system` and `user` messages.\n- Each value supports full n8n expression syntax (e.g. `{{ $json.customer }}`).\n- If you change the selected prompt, click the mapper's **refresh** icon to reload the field list for the new prompt.\n- If the prompt has no `{{variables}}`, the mapper shows a notice and there's nothing to fill in.\n\n**Missing variables throw a `NodeOperationError`** before any LLM call is made, listing exactly which names need values. Empty-string values count as missing — this runtime check is the real guard (the mapper marks fields required but won't hard-block execution).\n\n#### How the Langfuse user message interacts with Text / chatInput\n\n| Langfuse prompt contains... | Result |\n|---|---|\n| `system` only | Compiled system message is used. `Prompt Type` / `Text` (or `chatInput`) drives the human turn — existing behaviour. |\n| `system` + `user` | Compiled system message is used. **Compiled user message replaces the human turn**; `Prompt Type` / `Text` field is ignored. Map any free-form input via a variable instead (e.g. set the `question` field to `{{ $json.chatInput }}`). |\n\n**Example A — parameterised system prompt, free-form user input:**\n\n```\nLangfuse prompt:\n  system: \"You help customers of {{company}}.\"\n\nNode config:\n  Prompt Variables:  company = Acme\n  Prompt Type: Auto\n\nResult:\n  system → \"You help customers of Acme.\"\n  human  → chatInput from previous node (unchanged)\n```\n\n**Example B — fully parameterised prompt:**\n\n```\nLangfuse prompt:\n  system: \"You are a support agent.\"\n  user:   \"Ticket {{ticket_id}}: {{question}}\"\n\nNode config:\n  Prompt Variables:\n    ticket_id = {{ $json.ticketId }}\n    question  = {{ $json.message  }}\n\nResult (chatInput ignored):\n  system → \"You are a support agent.\"\n  human  → \"Ticket 4821: Where is my order?\"\n```\n\n### Prompt Type (User Input)\n\n| Option | Description |\n|--------|-------------|\n| **Auto (From Previous Node)** | Reads the `chatInput` field from the previous node's output. Works automatically with Chat Trigger and other AI nodes. |\n| **Define Below** | Write a fixed prompt text in the node. |\n\n> Ignored when the selected Langfuse prompt defines a `user`-role message — see **Prompt Variables** above.\n\n### Langfuse Metadata\n\n| Field | Description |\n|-------|-------------|\n| **Session ID** | Groups related traces in Langfuse. Supports n8n expressions (e.g., `{{ $json.sessionId }}`). |\n| **User ID** | Identifies the end user. Supports expressions. |\n| **Trace Name** | Custom name for the trace. **Defaults to the n8n node name** — so naming your node \"AI Agent - Selector\" will make the trace appear as \"AI Agent - Selector\" in Langfuse. |\n| **Custom Metadata (JSON)** | Any additional metadata you want to attach to traces. |\n\n#### Automatic Metadata\n\nThe following fields are **automatically included** in every trace — no configuration needed:\n\n| Field | Value | Source |\n|-------|-------|--------|\n| `project` | Your Langfuse project name | Langfuse API |\n| `prompt.name` | The selected prompt name | Langfuse prompt |\n| `prompt.version` | The production version number | Langfuse prompt |\n\nYour custom metadata is merged on top of the automatic fields. You can override any automatic field by including it in your Custom Metadata JSON.\n\n**Example Custom Metadata:**\n```json\n{\n  \"env\": \"prod\",\n  \"workflow\": \"{{ $workflow.name }}\",\n  \"n8n_exec_id\": \"{{ $execution.id }}\"\n}\n```\n\n**Resulting trace metadata:**\n```json\n{\n  \"project\": \"my-project\",\n  \"prompt\": { \"name\": \"my-agent\", \"version\": 3 },\n  \"env\": \"prod\",\n  \"workflow\": \"Customer Support Agent\",\n  \"n8n_exec_id\": 1234\n}\n```\n\n### Langfuse Trace Output\n\n![Langfuse trace](assets/langfuse-trace.png)\n\nEvery execution produces a full trace in Langfuse showing:\n- The complete LLM call chain (agent, prompt template, model call, output parsing)\n- Token usage and cost\n- The output with structured fields\n- All metadata (automatic + custom)\n\n### Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| System Message | \"You are a helpful assistant\" | System prompt (only when Prompt Source = Manual) |\n| Max Iterations | 10 | Maximum agent reasoning loops |\n| Return Intermediate Steps | false | Include tool calls and reasoning in output |\n| Enable Streaming | true | Stream responses in real-time |\n| Passthrough Binary Images | true | Forward images from input to the LLM |\n| Batch Size | 1 | Items to process in parallel |\n| Delay Between Batches | 0 ms | Wait time between batches |\n\n### Canvas Inputs\n\n| Input | Type | Required | Description |\n|-------|------|----------|-------------|\n| **Chat Model** | Language Model | Yes | Any LangChain-compatible model (OpenAI, OpenRouter, Anthropic, etc.). Provides the LLM provider and API key. |\n| **Tools** | Tool | No | Connect one or more tools for the agent to use. |\n| **Memory** | Memory | No | Conversation memory for multi-turn agents. |\n| **Output Parser** | Output Parser | No | Structured output format (enable \"Require Specific Output Format\" first). |\n| **Fallback Model** | Language Model | No | Backup model (enable \"Enable Fallback Model\" first). |\n\n## Examples\n\n### Basic: Agent with Langfuse Prompt\n\n```\nManual Trigger → AI Agent + Langfuse → Output\n                      ↑\n                 Chat Model (OpenRouter)\n```\n\n1. Set **Prompt Source** = \"Langfuse Prompt\"\n2. Select your prompt from the dropdown\n3. Set **Model Source** = \"From Langfuse\"\n4. Set **Prompt Type** = \"Define Below\" and enter a test message\n\n### Sub-workflow: Reusable Agent\n\n```\nSub-workflow Trigger → AI Agent + Langfuse → Return\n                            ↑        ↑\n                       Chat Model   Tool (HTTP)\n```\n\nPerfect for n8n pipelines where multiple workflows call the same agent. Each gets its own Langfuse trace with the correct prompt and model.\n\n### With Tools and Memory\n\n```\nChat Trigger → AI Agent + Langfuse → Response\n                    ↑    ↑    ↑\n              Chat Model Tool Memory\n```\n\nFull conversational agent with tool access and conversation history, all traced to Langfuse.\n\n## Multiple Langfuse Projects\n\nEach Langfuse API key pair belongs to one project. To use prompts from different projects:\n\n1. Create a **separate Langfuse API credential** for each project\n2. Select the appropriate credential in each node\n3. The project name in trace metadata updates automatically\n\n## Compatibility\n\n| Component | Version |\n|-----------|---------|\n| **n8n** | >= 1.70.0 |\n| **Node.js** | >= 20.15 |\n| **Langfuse** | Any version with API v2 (>= 2.0) |\n\nWorks with any LangChain-compatible Chat Model: OpenAI, OpenRouter, Anthropic, Azure OpenAI, Google Vertex AI, Ollama, and more.\n\n## Troubleshooting\n\n### \"Cannot connect to Langfuse\"\n- Verify your Base URL, Public Key, and Secret Key in the credential\n- Click \"Test\" in the credential editor to check connectivity\n- For self-hosted Langfuse: ensure n8n can reach the URL (check Docker networking, firewalls)\n\n### Prompt dropdown is empty\n- Check that your Langfuse project has `chat`-type prompts (not `text`-type)\n- Verify the credential has access to the correct project\n\n### Model from Langfuse not being used\n- The `model` field in your Langfuse prompt config must match your provider's model naming (e.g., `openai/gpt-5-nano` for OpenRouter, `gpt-4o` for OpenAI direct)\n- Check the Langfuse trace to confirm which model was actually called\n\n### \"Failed to receive response\" with Chat Trigger\n- This is usually a CORS issue with your n8n reverse proxy, not this node\n- Test with a Manual Trigger first to isolate the issue\n\n## Development\n\n```bash\ngit clone https://github.com/brendangooden/n8n-nodes-agent-langfuse.git\ncd n8n-nodes-agent-langfuse\nnpm install\nnpm run build\n\n# Install locally in n8n for testing\ncd ~/.n8n/nodes\nnpm install /path/to/n8n-nodes-agent-langfuse\n# Restart n8n\n```\n\n## Contributing\n\nContributions are welcome! Please open an issue first to discuss what you'd like to change.\n\n## License\n\n[MIT](LICENSE) - (c) 2026 [diward](https://github.com/Diward)\n\n## Credits\n\n- Original node by [diward](https://github.com/Diward) — [n8n-nodes-agent-langfuse](https://github.com/Diward/n8n-nodes-agent-langfuse)\n- Built on [LangChain](https://langchain.com) and [Langfuse](https://langfuse.com)\n- Icon: [Lucide](https://lucide.dev) bot icon + [Langfuse](https://lobehub.com/icons/langfuse) logo\n- Inspired by [n8n-nodes-ai-agent-langfuse](https://github.com/rorubyy/n8n-nodes-ai-agent-langfuse) by Wistron DXLab\n","readmeFilename":"README.md"}