Self-improving AI Employees for everyone
OpenAI Chat Model (openaiChatModel)
| Field | Value |
|---|---|
| Category | ai_chat_models |
| Backend handler | server/nodes/model/openai_chat_model/__init__.py (dispatch via BaseNode.execute() -> @Operation("chat") in server/nodes/model/_base.py) |
| AI service | server/services/ai.py::AIService.execute_chat |
| Tests | server/tests/nodes/test_ai_chat_models.py |
| Skill (if any) | n/a |
| Dual-purpose tool | yes - tool name openai_chat_model (advisor; usable_as_tool = True, group ('model', 'tool')) |
Purpose
Single-turn chat completion against the OpenAI API. Used either as a standalone workflow node (user enters a prompt, the node produces a response), wired into an AI Agent via the input-model handle, or connected as an advisor tool (usable_as_tool = True). Every chat-model node runs through the shared ChatModelBase.chat operation (in _base.py), which calls provider-neutral AIService.execute_chat; OpenAI-specific request policy lives in the native provider and shared model-policy helpers.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Upstream data; not consumed directly by the handler - prompt must be passed via parameters or template-resolved upstream |
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
prompt |
string | "" |
yes (non-empty) | - | User message content sent to the model |
system_prompt |
string | "" |
no | - | System prompt |
model |
string | "" (injected from stored models) |
no | - | Model ID. [FREE] prefix is stripped before the API call |
temperature |
number|null | null -> agent.default_temperature |
no | - | 0-2 for most OpenAI models; o-series (o1/o3/o4) force temperature=1 |
max_tokens |
number|null | null -> per-model default |
no | - | 1-200000; clamped via _resolve_max_tokens to the model's actual ceiling |
top_p |
number|null | 1.0 |
no | - | Nucleus sampling |
frequency_penalty |
number|null | 0.0 |
no | - | -2.0 to 2.0 |
presence_penalty |
number|null | 0.0 |
no | - | -2.0 to 2.0 |
response_format |
enum | text |
no | - | text or json_object |
thinking_enabled |
boolean | false |
no | - | Turn on extended reasoning (GPT-5 hybrid / o-series) |
reasoning_effort |
enum | medium |
no | thinking_enabled=[true] |
minimal / low / medium / high (OpenAI override adds minimal) |
api_key |
string|null | null (injected) |
no | - | auth_service.get_api_key('openai', 'default') |
(Field names are snake_case on OpenAIChatModelParams; model_config = ConfigDict(extra="ignore") drops unknown keys.)
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-model |
object | Model output (also feeds an agent's input-model handle); standard envelope payload (see below) |
Output payload
{
response: string;
thinking: string | null;
thinking_enabled: boolean;
model: string;
provider: 'openai';
finish_reason: string;
timestamp: string; // ISO 8601
input: { prompt: string; system_prompt: string };
}
Wrapped in the standard envelope: { success: true, node_id, node_type, result: <payload>, execution_time: number }.
Logic Flow
flowchart TD
A[NodeExecutor dispatch -> BaseNode.execute] --> B[ChatModelBase.chat Operation<br/>params validated by Pydantic]
B --> C[get_ai_service]
C --> D[AIService.execute_chat]
D --> E[Flatten options into flat params dict]
E --> F{api_key present?}
F -- no --> X[raise ValueError -> error envelope]
F -- yes --> G{prompt non-empty?}
G -- no --> X
G -- yes --> H[detect_ai_provider -> 'openai']
H --> I[Build NativeThinkingConfig if thinkingEnabled]
I --> J[Lookup openai_proxy credential]
J --> K[ChatUnifier.chat provider='openai']
K --> L[registry.get_provider openai + OpenAI SDK<br/>await provider.chat]
L --> M[Build response dict<br/>response / thinking / model / provider / finish_reason]
M --> N[Return success envelope]
L -- Exception --> X
Decision Logic
- Validation: missing
api_key-> ValueError; empty/whitespaceprompt(viais_valid_message_content) -> ValueError. Both produce asuccess=falseenvelope. - Provider routing:
detect_ai_provider(node_type)returns'openai'for this node; falls through the else branch inconstants.detect_ai_provider. - Native path:
ChatUnifierresolves the self-registeredopenaispec, so the nativeopenaiSDK serves both current chat and agent executions. LangChain remains isolated to eligible Temporal-history replay. - Model ID handling: strips only the UI-only
[FREE]decoration. Provider model IDs are otherwise opaque and preserved. - Thinking config: only built when
thinkingEnabledis truthy; passed through to the provider'schat()method. - System prompt: reads the schema-canonical
system_promptfield and prepends a nativeMessage(role="system")when it is non-empty. - Error path: typed SDK failures are translated by
ChatUnifierintoNodeUserErrorand re-raised toBaseNode.execute(); unexpected exceptions are logged and returned assuccess=false.
Side Effects
- Database writes: none directly in the happy path.
_track_token_usage(invoked elsewhere in the AI service when memory is attached) writesTokenUsageMetricrows; for a bare chat model node with no memory this path is typically not exercised fromexecute_chat. - Broadcasts: none from
execute_chatitself. - External API calls: the standalone chat node uses OpenAI Chat Completions through the native SDK. Native agent turns that need reasoning continuation state use the Responses API; ordinary agent turns use Chat Completions. An
openai_proxycredential can override the SDK endpoint. - File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials:
auth_service.get_api_key('openai', 'default')(API key); optionalauth_service.get_api_key('openai_proxy')for proxy URL override. - Services:
AIService(wired viaNodeExecutor.__init__),services/llm/providers/openai.py(native provider). - Python packages:
openai(native SDK). - Environment variables: none (keys are DB-stored).
Edge cases & known limits
- Reasoning-model temperature: the native provider omits
temperaturefor configured OpenAI reasoning models instead of forwarding an unsupported value. - GPT-5 hybrid reasoning:
reasoningEffort(minimal/low/medium/high) is consumed viaNativeThinkingConfig.effortand forwarded to the provider SDK. WithoutthinkingEnabled=truethe effort value is ignored. - Reasoning summary availability: the content of
thinkingfor o-series models is gated on OpenAI org verification - unverified orgs getthinking=nulleven withreasoningEffortset. maxTokensclamp: clamped to the model's actual output ceiling bynative_resolve_max_tokens. Exceeding the limit silently caps without error.- Error boundary: typed OpenAI SDK failures become user-safe
NodeUserErrorvalues inChatUnifierand are re-raised toBaseNode.execute(), which produces the standard failure envelope. Unexpected failures are logged and returned byexecute_chat. - No streaming:
execute_chatis single-shot; the full response is awaited before returning. - Pricing / token tracking: standalone chat model nodes do NOT trigger
_track_token_usage- that lives on the agent code paths. Cost attribution for bare chat-model executions is therefore not recorded.
Related
- Peer nodes (same handler):
anthropicChatModel,geminiChatModel,openrouterChatModel,groqChatModel,cerebrasChatModel,deepseekChatModel,kimiChatModel,mistralChatModel. - Architecture docs: Native LLM SDK, Credentials Encryption, Pricing Service.