ai-openai-text

ai-openai-text — Generate text using GPT-5 Chat Completion

Description

- step: ai-openai-text
  args:
    - '${PROMPT}'
    - '${REASONING_EFFORT}'  # optional
  context:
    SYSTEM_PROMPT: '${SYSTEM_PROMPT}'  # optional

The ai-openai-text step generates text using the GPT-5 Chat Completion API.

Uses the OPEN_AI_API_KEY in context for authentication.
Accepts an optional SYSTEM_PROMPT to guide the model.
Optional reasoning_effort controls the depth of reasoning: "minimal", "low", "medium", "high" (default: "low").
Output is stored in ${prev} by default or a custom context key via set_context.

Usage in a workflow YAML:

workflow:
  - step: ai-openai-text
    args:
      - "Explain quantum computing in simple terms"
      - "medium"
    context:
      SYSTEM_PROMPT: "You are a friendly, clear, and concise AI assistant."

Parameters

Parameter	Type	Description
`prompt`	`string`	The text prompt to send to GPT-5.
`reasoning_effort`	`string`	Optional. One of `"minimal"`, `"low"`, `"medium"`, `"high"`. Controls the depth of reasoning.

Context requirements:

Context Key	Type	Description
`OPEN_AI_API_KEY`	`string`	Required. OpenAI API key.
`SYSTEM_PROMPT`	`string`	Optional. System prompt to guide the model.

Return Values

Returns 0 on success, 1 on failure.
On success, context (${prev} by default, or custom via set_context) contains the generated text:

"This is the text generated by GPT-5 based on your prompt."

On failure, context contains an error message:

{
  "error": "Description of the error or API failure"
}

If no arguments are provided, usage instructions are set in context['ai-openai-text::usage'].

Behavior

Sends the prompt (and optional system prompt) to the GPT-5 Chat Completion API.
Stores the generated message content in context under ${prev} (default) or set_context.
Handles network errors, missing API key, and HTTP errors gracefully, storing errors in context.
Reasoning effort affects how detailed or computationally intensive the response is.

Examples

Example #1 — Basic text generation

workflow:
  - step: ai-openai-text
    args:
      - "Summarize the latest news in AI."

Stores the generated summary in ${prev}.

Example #2 — Specifying reasoning effort

workflow:
  - step: ai-openai-text
    args:
      - "Explain black holes for high school students."
      - "medium"

Example #3 — Using system prompt

workflow:
  - step: ai-openai-text
    args:
      - "Write a friendly reminder email."
    context:
      SYSTEM_PROMPT: "You are a polite and concise assistant."

Notes

Ensure OPEN_AI_API_KEY is set in the workflow context.
reasoning_effort defaults to "low" if not provided.
Use set_context to store output in a custom key instead of overwriting ${prev}.
Generated text is a string. If structured output is needed, parse it in a downstream step.