n8n-nodes-openai-responses-agent

Experimental OpenAI Responses Agent for self-hosted n8n. This package is not intended for n8n Cloud and is not an n8n-verified community node.

Beta.2

The node runs a real tool-calling loop through the connected OpenAI Chat Model and n8n's execution engine. It preserves JSON and binary data returned by standard AI Tools before the standard Agent projection removes binary properties.

Beta.1 added primary/fallback models, Memory, Output Parser, sequential and parallel AI Tools, multimodal binary routing, optional Files API uploads, retention, a best-effort metadata cache, batching, streaming, and intermediate steps. Beta.2 fixes uploaded native file inputs so the Responses API receives only file_id, as required by its mutually exclusive file-source contract. The final Main output follows Agent semantics and normally contains { "output": "..." }.

Connections and credentials

Connect an OpenAI Chat Model with Use Responses API enabled and one or more AI Tools. The Chat Model owns model inference credentials.

The optional OpenAI Responses Files API credential belongs to this package and is used only for file create/delete operations. Configure it with access to the same OpenAI project as the Chat Model when files require upload. The package does not inspect private fields on the connected Chat Model.

File cache behavior

The cache stores only metadata in node-scoped workflow static data. It never stores bytes, API keys, or Base64. Production executions may reuse cached file_id values; manual executions intentionally do not rely on persistent cache state. Queue-mode updates are best-effort and concurrent updates may cause duplicate uploads.

Cached IDs are reused without a preventive retrieve request. A structured missing/expired/inaccessible-file error invalidates only the Agent-owned cached ID, causes one replacement upload, and retries that invocation once. Persistent files are deleted best-effort before cache eviction; failed cleanup remains as a tombstone for a future retry.

Important limits

• OpenAI Responses API is required.
• Main image passthrough defaults on; Main PDF passthrough defaults off.
• Tool image, PDF, and other-file passthrough default on.
• File cache defaults on; retention defaults to 30 days.
• Persistent Memory stores textual observations and call correlation, not replayable binary attachments or file IDs from prior turns.
• Experimental software: validate in staging before production use.

Development

pnpm install --ignore-workspace
pnpm typecheck
pnpm lint
pnpm test
pnpm build

The lint configuration intentionally uses configWithoutCloudSupport, because this package has the runtime AI dependency required by the self-hosted integration.

License

MIT. n8n and LangChain are separate upstream projects and are not authored by this package.