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).
2.1.0.0 Added background mode (with RetrieveResponse and CancelResponse operations) and optional initial polling.

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.

Operation

Type: List Input
Selects which Responses API operation the Node performs.

• CreateResponse - Create a new response (default). Runs synchronously unless Background is enabled.
• RetrieveResponse - Fetch the current state of an existing response identified by CurrResponseId. Use this to poll a background response until it reaches a terminal status.
• CancelResponse - Cancel an in-progress response identified by CurrResponseId. Only responses created with Background enabled can be cancelled.

Background

Type: Boolean Input
Applies only to CreateResponse. When enabled, the Node returns immediately with the response id and a non-terminal status (queued or in_progress) instead of waiting for completion. Retrieve the response later with RetrieveResponse, or cancel it with CancelResponse. When disabled (default), the Node waits for the full response.

InitialPollTimeoutSecs

Type: Int32 Input
Applies only to a background CreateResponse. When greater than 0, after creating the background response the Node polls it (about once per second) until it reaches a terminal status or this timeout elapses, then returns the latest state. 0 (default) returns immediately without polling. This is a convenience for short-running background requests so you do not need a separate RetrieveResponse call.

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.

CurrResponseId

Type: String Input
The ID of an existing response to act on. Required for RetrieveResponse and CancelResponse; ignored for CreateResponse. This is distinct from PrevResponseId, which chains a new response onto a prior 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 */
  },
  "usage": {
    /* token usage, or null */
  }
}

When available, usage reports token counts (input, output, total, and cached token details).
Use Response when you need the full payload, e.g. 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

• Leave Operation on CreateResponse to generate a response, or choose RetrieveResponse or CancelResponse to act on an existing response by CurrResponseId.
• Enable Background to run a create asynchronously, then poll with RetrieveResponse (or set InitialPollTimeoutSecs to have the Node poll for you).
• 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 Connection's 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\"}"
}

Background Mode

Background mode runs a CreateResponse asynchronously in OpenAI's infrastructure, so a long-running request does not block the Workflow while it completes. The typical pattern is:

1. Set Operation to CreateResponse and enable Background. The Node returns immediately with an id and a non-terminal status (queued or in_progress).
2. Poll with Operation set to RetrieveResponse, passing the id as CurrResponseId, until status is terminal (completed, failed, cancelled, or incomplete).
3. Optionally cancel a running response with Operation set to CancelResponse and the same CurrResponseId.

Set InitialPollTimeoutSecs to a small positive value if you want the Node to poll for you immediately after creating a background response. Short-running requests then complete within a single Node call, without a separate RetrieveResponse step.

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:

• File Search Guide
• Vector Stores API
• Vector Store Files API

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. For long-running requests, use Background mode (see Background Mode) instead of waiting synchronously.

Error handling

• Non-2xx HTTP responses are raised as Flowgear errors and include the OpenAI error object when possible.
• For a foreground CreateResponse, a 2xx response that still contains an error object is also treated as an error to avoid silent failures.
• For background operations (RetrieveResponse, CancelResponse, and a background CreateResponse), a terminal error is surfaced on NormalisedResponse.error instead of being raised, so you can inspect a failed or cancelled response while polling.

See Also

• OpenAI Responses API Reference
• OpenAI Background Mode Guide
• OpenAI Models
• OpenAI Prompt Caching Guide
• OpenAI Tools and Function Calling Guide