AI Agent icon

AI Agent

Agent capable of using tools, subagents, and structured output.
Join our community

Overview

This node acts as a flexible interface to OpenAI or OpenRouter language models, enabling users to send chat messages and receive AI-generated responses. It supports advanced features such as structured output formats, tool calling with iterative cycles, and memory management for chat history. This node is beneficial in scenarios like building conversational AI assistants, automating customer support chats, generating content based on prompts, or integrating AI-driven decision-making tools.

Practical examples:

  • A chatbot that remembers previous interactions and calls external tools to fetch data before responding.
  • Generating structured JSON outputs for automated report generation or data extraction.
  • Using fallback models automatically if the primary model fails or is unavailable.

Properties

Name Meaning
Model Select an OpenAI or OpenRouter model from a list or specify by ID. Models determine the AI capabilities used for generating responses.
Messages One or more chat messages to send to the model. Each message has a role (assistant, system, user, chat history array, or chat memory) and content. Supports raw text or JSON arrays for complex inputs including multimodal data (images, audio, PDFs).
Response Format The format of the model's output: Plain Text, JSON Mode (valid JSON), Structured Output via JSON Schema, or Structured Output via Visual Editor schema.
Tools Mode Enables enforcing structured output through a tool, allowing structured output on models that do not natively support it.
JSON Schema Defines the JSON schema for structured output when using the JSON Schema response format.
Structured Output Name Name identifier for the structured output object when using the visual editor schema.
Description Description of the structured output for clarity/documentation purposes.
Array Indicates if the structured output is an array of objects rather than a single object.
Array Name Name of the array when structured output is an array (plural form).
Array Description Description of the array contents.
Properties Definitions of properties for structured output, including name, type (string, string array, boolean, integer, number), descriptions, and optional enumerations.
Extra Outputs Additional fields to include in the node output: Chat History, HTTP Request sent, HTTP Response received, Tool Calls made during execution.
Include System Messages in Chat History Whether to include system messages in the chat history output.
Include Reasoning in Chat History Whether to include reasoning details in assistant messages within chat history, useful for maintaining context across tool calls.
Include Tool Calls in Chat History Whether to include tool call messages in the chat history output.
Options Collection of additional options: custom parameters for the API request, fallback model selection, frequency penalty, max tokens, max tool call iterations, number of completions, presence penalty, temperature, top_p sampling.

Output

The node outputs a JSON object containing the AI-generated response according to the selected response format. Depending on configuration, the output may also include:

  • The full chat history exchanged with the model, optionally including system messages, reasoning details, and tool calls.
  • The exact HTTP request sent to the model API.
  • The full HTTP response received from the model API.
  • Intermediate tool call inputs and outputs if tool calling is enabled.

If the model supports multimodal inputs, the node can handle images, audio, and PDFs encoded as URLs or base64 data, but binary data output is not explicitly described here.

Dependencies

  • Requires access to OpenAI or OpenRouter API endpoints.
  • Needs an API key credential configured in n8n for authentication.
  • Uses internal shared modules for routing execution and model search.
  • Network connectivity to the chosen AI service provider.

Troubleshooting

  • Invalid JSON syntax in chat history input: If the JSON array provided for chat history messages is malformed, the node will raise an error. Ensure valid JSON formatting.
  • Model not found or invalid model ID: Selecting a model not supported or misspelling the model ID can cause failures. Use the provided searchable list or verify model IDs from official documentation.
  • Token limits exceeded: Setting max_token_completions too high may cause errors or increased costs. Adjust token limits according to your quota and needs.
  • Too many tool call iterations: Setting maxToolsIterations too high or -1 (no limit) might lead to long-running executions or infinite loops. Use reasonable limits.
  • API authentication errors: Ensure the API key credential is correctly set up and has sufficient permissions.
  • Structured output schema mismatches: When using structured output modes, ensure the JSON schema or visual editor definitions match the expected output format to avoid parsing errors.

Links and References

Discussion