Reasoning

Reasoning is useful for tasks that require multistep analysis, complex constraints, mathematical derivation, code planning, or tool coordination. Reasoning models often let applications control reasoning effort and can return reasoning summaries, Thinking Blocks, or related Usage; the exact form depends on the model and protocol.

For simple classification, format conversion, or short question answering, higher reasoning effort does not necessarily produce a better business result and can increase latency and Token usage.

When to use reasoning

First confirm the models, protocols, and capability labels available to the current account in the Model marketplace. Replace MODEL_ID in the examples with a model from the current account that supports the corresponding reasoning configuration.

Configure reasoning effort with Responses

Responses places reasoning configuration in the reasoning object:

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "input": "Compare two database migration approaches and explain which one to choose.",
    "reasoning": {
      "effort": "medium",
      "summary": "auto"
    }
  }'

effort controls reasoning effort, while summary requests a reasoning summary that the protocol allows to be exposed. Available values and whether they take effect depend on the model; see Responses Reference for the complete definition.

How protocols represent reasoning

{
  "model": "MODEL_ID",
  "messages": [
    {"role": "user", "content": "Analyze the main risks of this deployment plan."}
  ],
  "reasoning_effort": "medium"
}

The example values only illustrate field locations and do not mean every model accepts the same levels or budgets. See the Chat Completions, Anthropic Messages, and Gemini Generate Content references.

Read the final answer and visible reasoning information

Applications usually need to handle the following content separately:

1. Final answer: the content actually shown to the user or passed to downstream business logic.
2. Reasoning summary or Thinking Block: read it only when the protocol and model explicitly return it, and do not assume it is the model's complete internal chain of thought.
3. Usage: record input, visible output, and reasoning Tokens; field locations vary by protocol.
4. Stopped or incomplete state: determine whether the response was incomplete because of the output budget, content policy, cancellation, or an error.

If the business needs only the final conclusion, visible reasoning content does not need to be persisted. Before storing this content, also evaluate privacy, logging scope, and data retention policies.

Streaming and tool calls

• A streaming response can return reasoning deltas and final-text deltas separately; use independent buffers.
• Protocol state or Thinking Blocks can appear before and after a tool call; do not preserve only the final text.
• Tool execution still follows the argument validation, permission, and idempotency requirements in Tool Calling.
• When continuing a conversation, send back only the history structure required by the target protocol; do not rewrite signatures, call IDs, or opaque state.

See Streaming for complete streaming handling.

Design the output budget

Reasoning Tokens and the visible answer can share the output budget. If the budget is too small, the model can finish its analysis without enough room to provide a complete final answer.

Production applications should observe all of the following:

• Whether the final answer is complete;
• Stop reasons or incomplete reasons;
• Usage for reasoning and visible output;
• Quality, latency, and cost at different effort levels;
• Whether the tool loop completes within the allowed rounds and total time limit.

Pre-production checklist

• The current account supports the target model, and the reasoning endpoint and request fields have been confirmed.
• The application sends only reasoning fields accepted by the target protocol.
• The final answer, visible reasoning information, and Usage are handled separately.
• Streaming, multi-turn, and tool-calling workflows preserve the required protocol state.
• Insufficient output budget, refusals, timeouts, and incomplete responses each have an explicit branch.
• Reasoning effort, summaries, or visible Thinking are not described as a correctness guarantee.

If a request fails, see Errors and troubleshooting. Before switching models or protocols, see Choose a protocol.