> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naga.ac/llms.txt
> Use this file to discover all available pages before exploring further.

# Reasoning

> Understand reasoning-related output in the Responses API.

`Responses API` exposes a public `reasoning` request field and can return reasoning as its own typed output items. That is one reason the response is item-based instead of a single assistant message string.

Use reasoning when you want to trade more latency and token usage for harder planning, decomposition, or tool selection.

## Request Controls

Use the public `reasoning` field to request additional reasoning budget on models that support it.

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.naga.ac/v1",
      api_key="YOUR_API_KEY",
  )

  response = client.responses.create(
      model="gpt-5",
      input="Explain the likely root cause of a slow PostgreSQL query and suggest the first two checks.",
      reasoning={"effort": "medium"},
  )

  print(response.output)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.naga.ac/v1',
    apiKey: 'YOUR_API_KEY',
  });

  const response = await client.responses.create({
    model: 'gpt-5',
    input: 'Explain the likely root cause of a slow PostgreSQL query and suggest the first two checks.',
    reasoning: { effort: 'medium' },
  });

  console.log(response.output);
  ```

  ```bash cURL theme={null}
  curl https://api.naga.ac/v1/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5",
      "input": "Explain the likely root cause of a slow PostgreSQL query and suggest the first two checks.",
      "reasoning": {
        "effort": "medium"
      }
    }'
  ```
</CodeGroup>

Supported effort values on this surface are:

* `none`
* `minimal`
* `low`
* `medium`
* `high`
* `xhigh`

Start low and raise the effort only if the extra quality is worth the latency and cost.

## Response Items

Reasoning can appear in the `output` array before, after, or between message and tool items.

```json theme={null}
[
  {
    "type": "reasoning",
    "id": "rs_123",
    "status": "completed",
    "summary": [
      {
        "type": "summary_text",
        "text": "The model compared likely causes before answering."
      }
    ]
  },
  {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "Start by checking the query plan and index usage.",
        "annotations": [],
        "logprobs": []
      }
    ]
  }
]
```

Depending on the model, a `reasoning` item can include:

* `summary` with `summary_text` parts
* `content` with `reasoning_text` parts
* `encrypted_content`

Not every reasoning-capable model exposes visible reasoning items.

## Streaming Behavior

When streaming, reasoning-related events can arrive before the final message text.

* `response.reasoning_summary_text.delta` streams reasoning summary text
* `response.reasoning_text.delta` or `response.reasoning.delta` streams reasoning text
* `response.output_item.done` can finalize a reasoning item with `encrypted_content`
* `response.completed` closes the final snapshot

## Preserve Reasoning Across Tool Turns

This gateway is stateless. If you want the model to continue from the same reasoning state after a tool call, replay the earlier `reasoning` item unchanged in the next `input[]` request together with the earlier `function_call` and the new `function_call_output`.

```json theme={null}
{
  "model": "gpt-5",
  "tools": [
    {
      "type": "function",
      "name": "lookup_weather",
      "description": "Look up current weather for a city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string" }
        },
        "required": ["city"]
      }
    }
  ],
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What is the weather in Prague and should I bring a coat?"
        }
      ]
    },
    {
      "type": "reasoning",
      "summary": [
        {
          "type": "summary_text",
          "text": "Need live weather data before answering."
        }
      ],
      "encrypted_content": "enc_123"
    },
    {
      "type": "function_call",
      "call_id": "call_1",
      "name": "lookup_weather",
      "arguments": "{\"city\":\"Prague\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "call_1",
      "output": "{\"temperature_c\":7,\"raining\":true}"
    }
  ]
}
```

Treat the replayed `reasoning` item as model output. Do not edit, reorder, or partially copy it if you want continuity.

## Caveats

* not every reasoning-capable model exposes visible reasoning items
* output order matters; do not assume the first item is the final answer
* reasoning can coexist with `function_call` items and later `function_call_output` items in the same workflow

## Common mistakes

* turning reasoning effort up by default without measuring the cost and latency impact
* dropping reasoning items when continuing a tool workflow that depends on continuity
* assuming visible reasoning is guaranteed on every supported model

## Related Docs

* [Responses API](/api/responses)
* [Responses Streaming](/api/responses/streaming)
* [Capability-level Reasoning](/build/reasoning)
* [Responses Tool Calling](/api/responses/tool-calling)