Run an OpenAI chat completion
openai_chat_completionSend a saved conversation to an OpenAI model and get the next assistant reply. Use this for structured chat history where you need verbatim continuation with controls like stop, temperature, or JSON.
Instructions
Send an explicit list of chat messages to an OpenAI model through the Chat Completions API.
Use this when you already hold a structured conversation history (system/user/assistant turns) and want it sent verbatim. For new single-prompt generations prefer openai_generate_text.
Args:
messages (array, required): [{ role: 'system'|'user'|'assistant'|'developer', content: string }], 1-200 entries
model (string): model ID, defaults to OPENAI_DEFAULT_TEXT_MODEL
max_completion_tokens (number): 1-200000
temperature (number): 0-2
top_p (number): 0-1
stop (string[]): up to 4 stop sequences
response_format ('markdown'|'json'): default 'markdown'
Returns (JSON format): { "id": string, // completion ID "model": string, // model that served the request "finish_reason": string | null, // "stop", "length", "content_filter", ... "content": string, // assistant reply text "refusal": string | null, // set when the model declined "usage": { "input_tokens": number|null, "output_tokens": number|null, "total_tokens": number|null } }
Examples:
Use when: replaying a saved conversation with a new final user turn
Use when: you need a stop sequence to cut generation at a delimiter
Don't use when: chaining stored responses (use openai_generate_text with previous_response_id)
Error Handling:
"Error: OpenAI rejected the request as invalid" often means an unsupported parameter for that model, e.g. temperature on a reasoning-only model
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| stop | No | Up to 4 strings that stop generation when produced | |
| model | No | Model ID. Defaults to OPENAI_DEFAULT_TEXT_MODEL. | |
| top_p | No | Nucleus sampling cutoff | |
| messages | Yes | Conversation history in chronological order | |
| temperature | No | Sampling temperature | |
| response_format | No | Output format: 'markdown' for a readable summary, 'json' for the full structured payload | markdown |
| max_completion_tokens | No | Upper bound on generated tokens |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| model | Yes | ||
| usage | Yes | ||
| content | Yes | ||
| refusal | Yes | ||
| finish_reason | Yes |