n8n

Installation

Install the @orq-ai/n8n-nodes-orq package through the n8n Community Nodes manager:

Open n8n and go to Settings
Select Community Nodes
Click Install a community node
Enter @orq-ai/n8n-nodes-orq and click Install

You may need to refresh your browser or restart n8n Desktop after installation.

Credentials

In n8n, go to Credentials and click New
Search for Orq API
Paste your API key from Workspace Settings
Name the credential and save

Quick Start

Add a Manual Trigger node
Add an Orq Deployment node and connect it
Select a deployment, add a message with role user and your prompt text
Click Execute Workflow

n8n workflow with Manual Trigger connected to Orq Deployment node

Nodes Reference

Three nodes are available:

Orq Agent: Run an Agent for multi-step tasks with tools and autonomous reasoning.
Orq Deployment: Invoke a Deployment for direct, single LLM calls with prompt templates.
Orq Knowledge Base Search: Search an Orq.ai Knowledge Base for RAG and context retrieval.

Orq Agent

Run an Orq.ai Agent for complex, multi-step tasks. The node sends a message to the agent, waits for it to complete (including any tool calls), and returns the final response.

Parameter	Type	Description
Agent	Dropdown	Select from available agents in your workspace
Message	Text	The message to send to the agent
Timeout (seconds)	Number	HTTP timeout in seconds. Defaults to 600 (10 min) to match server-side execution limits

Additional Fields

Field	Description
Previous Response ID	Continue from a prior response. Mutually exclusive with Conversation ID
Conversation ID	Thread this call into an existing long-lived conversation (`conv_...`). Mutually exclusive with Previous Response ID
Memory Entity ID	Attach a persistent memory entity so the agent can recall facts across calls
Store Response	Whether Orq persists this response server-side (default on). When off, the response cannot be referenced as a Previous Response ID by a downstream node
Variables	Template variables passed to the agent’s prompt. Each row has Name, Value, and a Secret toggle to redact the value from logs
Metadata	Key-value tags attached to this call, queryable in the Orq.ai dashboard. Max 16 pairs

Output

Show fields

string

Unique identifier for this response. Pass as Previous Response ID in a downstream node to continue the conversation.

string

The agent that was invoked.

string

Final status: completed or incomplete.

boolean

true when the response completed successfully.

string

The agent’s response text. Use {{ $json.response }} in downstream nodes.

object

Full response body.

object

Token counts, when present.

boolean

true when status is incomplete.

string

Reason for an incomplete status, when present.

The node branches on the agent’s final status: completed routes to the success branch, incomplete returns a partial response with incomplete: true, and failed throws with the server error message.

Orq Deployment

Invoke an Orq.ai Deployment with messages, routing context, and variable inputs.

Parameter	Type	Description
Deployment Key	Dropdown	Select from available deployments in your workspace
Context	Key-value pairs	Routing context for the deployment (e.g. `environment: production`). Learn more
Inputs	Key-value pairs	Values for `{{variable}}` placeholders defined in the deployment prompt. Add one entry per variable
Messages	Collection	Conversation messages to pass to the deployment

Messages

Each message has a Role (User, System, or Assistant). System and Assistant messages take plain text. User messages support two content types:

Content Type	Fields
Text	Message text
Image	Image Source (URL or Base64 Data URI) and an optional text description

Some models require text alongside images. Check your model’s documentation if image-only messages return errors.

Output

Show fields

string

Deployment invocation ID.

string

Model used for the response.

string

Provider that served the request.

array

Response choices. Use {{ $json.choices[0].message.content }} in downstream nodes to get the text response.

object

Raw response from the upstream provider.

boolean

Whether the response is complete.

Orq Knowledge Base Search

Run semantic, keyword, or hybrid search over an Orq.ai Knowledge Base.

Parameter	Type	Description
Knowledge Base	Dropdown	Select from available knowledge bases in your workspace
Query	Text	The search query
Metadata Filter Type	Options	`None`, `AND` (all conditions must match), `OR` (any condition must match), or `Custom JSON` (advanced recursive filter)

When AND or OR is selected, add one or more conditions. Each condition takes:

Field	Description
Field	The metadata field to filter on
Operator	`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`
Value	The value to compare against. For `in` and `nin`, use comma-separated values

When Custom JSON is selected, provide a recursive filter structure directly:

{
  "$and": [
    { "field1": { "eq": "value1" } },
    { "$or": [
      { "field2": { "gt": 100 } },
      { "field3": { "in": ["a", "b"] } }
    ]}
  ]
}

Additional Options

Option	Description
Chunk Limit	Number of results to return (1 to 20). Defaults to the knowledge base setting
Threshold	Minimum similarity score (0 to 1). Defaults to the knowledge base setting
Search Type	`Vector Search`, `Keyword Search`, or `Hybrid Search` (default)

Output

array

Array of matching chunks. Use {{ $json.matches[0].text }} in downstream nodes to get the top result.

Show matches[]

string

Chunk ID.

string

The matched chunk text.

object

Any metadata attached to the chunk.

object

Show properties

number

Similarity score for the match.

number

Rerank score, if reranking is enabled.

OpenTelemetry Observability

n8n (v2.19.0+) exports OpenTelemetry traces for every workflow execution. Point n8n at the Orq.ai OTLP collector to see workflow runs, node performance, and agent invocations in Traces.

OpenTelemetry tracing in n8n is in Preview. Metrics export is not yet supported.

Prerequisites

n8n v2.19.0 or later
An API key with trace ingestion permissions

Configure the OTLP exporter

Option 1: Settings UI (n8n v2.27.0+)

Open Settings > OpenTelemetry
Turn on Enable OpenTelemetry
Under Collector connection, set the OTLP endpoint to https://my.orq.ai/v2/otel and add the header authorization=Bearer <YOUR_ORQ_API_KEY>
Select Save settings, then run Send test trace under Verify configuration to confirm the collector accepts the export

Environment variables override the UI settings, so leave the matching variables unset to manage tracing from the UI. Option 2: Environment variables Set three environment variables where n8n runs. Docker, Docker Compose, systemd, or .env all work:

export N8N_OTEL_ENABLED=true
export N8N_OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel"
export N8N_OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <YOUR_ORQ_API_KEY>"

environment:
  - N8N_OTEL_ENABLED=true
  - N8N_OTEL_EXPORTER_OTLP_ENDPOINT=https://my.orq.ai/v2/otel
  - N8N_OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer <YOUR_ORQ_API_KEY>

Restart n8n after setting the variables.

n8n appends /v1/traces to the endpoint automatically. Point it at the base URL (https://my.orq.ai/v2/otel), not at /v2/otel/v1/traces.

What n8n sends

n8n exports standard OTLP HTTP traces (Protobuf encoding) with three span types:

Span name	When	Key attributes
`workflow.execute`	One per execution	`n8n.workflow.name`, `n8n.execution.status`, `n8n.execution.mode`, `n8n.workflow.node_count`
`node.execute`	One per node, nested under workflow	`n8n.node.name`, `n8n.node.type`, `n8n.node.input_items`, `n8n.node.output_items`
`<agent_name>.generate` / `<agent_name>.stream`, plus `execute_tool <tool_name>` children	Per agent invocation (n8n v2.33.0+)	`gen_ai.*` attributes (model, tokens, tool calls)

Resource attributes include service.name (default n8n), service.version, and n8n.instance.id.

By default n8n exports traces for production executions only. Set N8N_OTEL_TRACES_PRODUCTION_ONLY=false to include manual test runs.

Agent spans require n8n v2.33.0+ and the Agents feature. Older n8n versions export only workflow.execute and node.execute spans.

What appears in Orq.ai

Workflow and node spans land as generic traces named workflow.execute with child node.execute spans. Inspect trace status, timing, and node-level attributes, but no model or cost data is available.
Agent spans use GenAI semantic conventions and render with model, token usage, and cost data in the Traces UI.

Custom attributes

n8n supports custom attributes on workflows, nodes, and projects via n8n.workflow.custom.*, n8n.node.custom.*, and n8n.project.custom.*. Node-level attributes appear in span details in Orq.ai.

Workflow and project custom attributes are part of the n8n export but are not exposed in Orq.ai.

Model Providers

Coding Agents

Chat Interfaces

Frameworks & SDKs

Automations

Installation

Credentials

Quick Start

Nodes Reference

Orq Agent

Additional Fields

Output

Orq Deployment

Messages

Output

Orq Knowledge Base Search

Additional Options

Output

OpenTelemetry Observability

Prerequisites

Configure the OTLP exporter

What n8n sends

What appears in Orq.ai

Custom attributes

​Installation

​Credentials

​Quick Start

​Nodes Reference

​Orq Agent

​Additional Fields

​Output

​Orq Deployment

​Messages

​Output

​Orq Knowledge Base Search

​Additional Options

​Output

​OpenTelemetry Observability

​Prerequisites

​Configure the OTLP exporter

​What n8n sends

​What appears in Orq.ai

​Custom attributes

Installation

Credentials

Quick Start

Nodes Reference

Orq Agent

Additional Fields

Output

Orq Deployment

Messages

Output

Orq Knowledge Base Search

Additional Options

Output

OpenTelemetry Observability

Prerequisites

Configure the OTLP exporter

What n8n sends

What appears in Orq.ai

Custom attributes