Home Nodes OpenAI ChatGPT Responses Call

OpenAI ChatGPT Responses Call

Use this node to call OpenAI's Responses API for text-based responses, tool calls, and conversation chaining.

This node is designed for practical workflows: pass instructions, provide input as plain text or JSON input items, and optionally expose tools (function, MCP, and hosted tools). It emits a normalised response shape so downstream nodes can read id, status, and output quickly.

Revision History

1.0.0.0 Initial release
2.0.0.0 Expanded tool support (function, MCP, and hosted tools: web search, file search, code interpreter, image generation).

Properties

Connection

Type: Connection Input

ApiKey
Type: Secret Input
Your OpenAI API key.

Model
Type: String Input
Model ID to use for Responses requests. Default is gpt-5-2025-08-07. For the full, up-to-date model list, see: OpenAI Models.

ReasoningEffort
Type: List Input
Controls reasoning effort for reasoning-capable models.

  • None - Disables additional reasoning effort for fastest responses. Supported on gpt-5.1 and later; earlier models do not support none.
  • Minimal - Very light reasoning; favors speed and lower token use.
  • Low - Light reasoning for simple tasks.
  • Medium - Balanced reasoning quality and latency (default).
  • High - Deeper reasoning for harder tasks; higher latency/token use.
  • XHigh - Maximum reasoning depth; slowest and most expensive. Supported on models after gpt-5.1-codex-max.

Model support varies. For example, gpt-5-pro only supports High, and gpt-5.1 supports None, Low, Medium, and High. If you choose a value not supported by your model, OpenAI will return an error.

ReasoningSummary
Type: List Input
Controls reasoning summary verbosity (or omission).

  • None - Do not return a reasoning summary.
  • Auto - Let the model decide summary verbosity.
  • Concise - Short summary only.
  • Detailed - Longer, more explicit summary.

Temperature
Type: Number Input
Sampling temperature, valid range 0.0 to 2.0. Lower values are more deterministic; higher values add randomness and creativity.

TextVerbosity
Type: List Input
Controls verbosity of text responses (output text tokens).

  • Low - Shorter, terse responses.
  • Medium - Balanced verbosity (default).
  • High - More detailed responses.

MaxOutputTokens
Type: Int32 Input
Maximum output tokens. 0 means no cap is sent.

Truncation
Type: List Input
Context overflow behavior.

  • Auto - Truncates input when needed to fit the model context.
  • Disabled - Fails if inputs exceed the model context.

ToolChoice
Type: List Input
Controls whether the model may call tools.

  • None - Do not call tools.
  • Auto - Let the model decide when to call tools.
  • Required - Force at least one tool call.

ParallelToolCalls
Type: Boolean Input
Allows multiple tool calls in a single response.

PromptCacheRetention
Type: List Input
Controls prompt cache retention policy. OpenAI supports in_memory and 24h retention in Responses requests.

  • Auto - Node selects 24h for supported models, otherwise in_memory.
  • InMemory - Short-lived in-memory caching only.
  • Hours24 - Request 24-hour retention where supported.

In-memory retention typically persists for 5-10 minutes of inactivity, up to about one hour.

PromptCacheKey
Type: String Input
Optional override for prompt_cache_key. When blank, the node derives a stable key from model, instructions, and tools.

Instructions

Type: Multiline Text Input
System or developer message inserted into the model context.

PrevResponseId

Type: String Input
If set, the node continues a conversation using a prior response ID. Leave blank to start a new conversation.

Input

Type: Multiline Text Input
User input. The node accepts plain text or JSON input items.

Tools

Type: JSON Input
JSON array of tools the model may call. Supported tool types:

  • function
  • mcp
  • web_search
  • web_search_preview
  • file_search
  • code_interpreter
  • image_generation

Response

Type: JSON Output
Raw JSON response body from OpenAI.

NormalisedResponse

Type: JSON Output
Compact response shape:

{
  "id": "<response id>",
  "status": "<status>",
  "output": [
    /* output items */
  ],
  "error": {
    /* error or null */
  }
}

Use Response when you need the full payload (for example, usage, metadata, or raw tool call details).

Setting up the Node

1) Create the Connection

  • Go to the Flowgear Console and create a Connection of type OpenAI ChatGPT Responses Call.
  • Set ApiKey and confirm the Model you want to use.
  • Leave PromptCacheKey blank if you want the node to generate a stable cache key automatically.

2) Configure the Connector Inputs

  • Set Instructions if you want a persistent system or developer directive.
  • Set Input to the user's prompt (plain text is fine).
  • Add Tools only if you want the model to call tools (function tools or MCP tools).
  • If you are chaining responses, set PrevResponseId from the previous run's NormalisedResponse.id.

3) Test before Invoke

Use the node Test action to validate the API key and network access (it calls GET /models).

Remarks

Input Formats

The node accepts multiple input styles for Input:

  • Plain text (becomes a single user message).
  • A JSON object representing one input item.
  • A JSON array of input items.
  • A quoted JSON string (treated as plain text).
  • A tool output item with type = function_call_output, plus the call_id from the tool call and your output payload.

If JSON parsing fails, the node falls back to a single user message using the raw text.

Example: tool output item passed to Input

{
  "type": "function_call_output",
  "call_id": "call_abc123",
  "output": "{\"status\":\"ok\",\"result\":\"42\"}"
}

Tools Schema

Tools must be a JSON array. Supported tool types:

  • function (custom function calls)
  • mcp (remote MCP servers or OpenAI connectors)
  • web_search / web_search_preview (hosted web search)
  • file_search (hosted retrieval over OpenAI vector stores)
  • code_interpreter (hosted code execution)
  • image_generation (hosted image generation)

Function Tool

Example (function tool):

[
  {
    "type": "function",
    "name": "lookupWeather",
    "description": "Returns current weather for a city",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string", "description": "City name" }
      },
      "required": ["city"],
      "additionalProperties": false
    }
  }
]

Use function tools to let the model call a specific Flowgear action with a structured JSON payload.
OpenAI Documentation: Function Calling

MCP Tool

Example (MCP tool - Remote Server without OAuth):

[
  {
    "type": "mcp",
    "server_label": "flowgear",
    "server_url": "https://mcp.example.com"
  }
]

Use MCP tools to connect the model to external MCP servers and their tool catalog.
OpenAI Documentation: Remote MCP Servers

Example (MCP tool - OpenAI Connector with OAuth token):

[
  {
    "type": "mcp",
    "server_label": "drive",
    "connector_id": "conn_123",
    "authorization": "Bearer <access_token>"
  }
]

Use connector-based MCP tools when OpenAI hosts the integration and an OAuth access token is available.
OpenAI Documentation: Remote MCP Servers

Notes:

  • Remote MCP servers typically use server_url. Any authentication requirements are determined by the MCP server.
  • OpenAI connectors use connector_id and require an OAuth access token in authorization.

MCP Authentication

This connector does not perform OAuth. When using connector_id, the OAuth login and token refresh must be handled outside this node, and the resulting access token must be passed via the authorization field.

Recommended Flowgear pattern:

  1. Handle the entire implementation of your own MCP client, or perhaps use the OAuthHandler to complete the provider login. The feasibility of this will be very specific to the MCP server you are trying to connect with.
  2. Store the access token securely.
  3. Inject the token into the MCP tool definition in Tools:
[
  {
    "type": "mcp",
    "server_label": "drive",
    "connector_id": "conn_123",
    "authorization": "Bearer <access_token>"
  }
]

If the token is missing or expired, OpenAI returns an authentication error.

Web Search Tool

Use web_search when the response needs current information from the public web.
OpenAI Documentation: Web Search Tool

Example (web_search):

[
  {
    "type": "web_search",
    "filters": { "allowed_domains": ["example.com"] },
    "search_context_size": "medium",
    "user_location": {
      "type": "approximate",
      "country": "US",
      "city": "Seattle",
      "region": "WA",
      "timezone": "America/Los_Angeles"
    }
  }
]

Use web_search_preview for lightweight web lookups where full context is not required.
OpenAI Documentation: Web Search Tool

Example (web_search_preview):

[
  {
    "type": "web_search_preview",
    "search_context_size": "medium",
    "user_location": {
      "type": "approximate",
      "country": "ZA",
      "city": "Johannesburg",
      "region": "Gauteng",
      "timezone": "Africa/Johannesburg"
    }
  }
]

File Search Tool

Use file_search to retrieve relevant passages from OpenAI vector stores.
OpenAI Documentation: File Search Tool

Example (file_search):

[
  {
    "type": "file_search",
    "vector_store_ids": ["vs_123"],
    "max_num_results": 5
  }
]

File Search Setup (OpenAI Vector Stores)

File Search requires an OpenAI vector store that already contains the files you want the model to retrieve. This node does not create vector stores or upload files automatically.

High-Level Setup Steps:

  1. Create a vector store in OpenAI.
  2. Upload one or more files to that vector store.
  3. Wait for the files to finish processing (status must be completed).
  4. Add the vector store ID to your tool definition as vector_store_ids.

OpenAI Documentation:

If results are consistently empty, confirm that the vector store contains files, the file processing status is completed, and the content is searchable (plain text or a supported document type).

Code Interpreter Tool

Use code_interpreter for calculations, data transformation, or running analysis code.
OpenAI Documentation: Code Interpreter Tool

Example (code_interpreter):

[
  {
    "type": "code_interpreter",
    "container": { "type": "auto" }
  }
]

Image Generation Tool

Use image_generation to create images from text prompts or structured instructions.
OpenAI Documentation: Image Generation Tool

Example (image_generation):

[
  {
    "type": "image_generation",
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "output_compression": 100,
    "background": "transparent",
    "action": "auto"
  }
]

Learn more about how tool and function calling works: OpenAI Tools and Function Calling Guide

Prompt Caching

Prompt caching is enabled by default. It reuses matching prompt prefixes, so that repeat requests can be faster and cheaper. OpenAI only caches exact prompt prefixes, so keep stable content (instructions, tools, schemas) at the beginning and put dynamic content at the end. Tools must be identical between requests to benefit from caching.

  • PromptCacheRetention controls whether the request uses in_memory or 24h retention.
  • PromptCacheKey can improve cache routing when many requests share the same prefix.
  • Cache hits appear as usage.prompt_tokens_details.cached_tokens (or usage.input_tokens_details.cached_tokens) in the raw response. Cached tokens are only non-zero for prompts at or above 1024 tokens and are reported in 128-token increments.
  • If you leave PromptCacheKey empty, the node generates a stable key from your selected model, instructions, and tools.

For best results, keep your long, stable instructions and tool definitions consistent across runs, and move user-specific data to the end of the prompt. If you batch many similar requests, set a stable PromptCacheKey derived from the shared prefix so OpenAI can route them efficiently.

Learn more about how prompt caching works: OpenAI Prompt Caching Guide

Streaming

This connector uses non-streaming Responses API calls and waits for the full response before returning.

Error handling

  • Non-2xx HTTP responses are raised as Flowgear errors and include the OpenAI error object when possible.
  • A 2xx response that still contains an error object is also treated as an error to avoid silent failures.

See Also