Skip to main content

What This Example Shows

  • One real, hard analytical problem solved end-to-end with POST /v1/reasoning-agent/completions
  • Why a normal agent call hallucinates on this and how swarm_type: "self-consistency" fixes it
  • How to tune num_samples and max_loops for the depth-vs-cost tradeoff on a single high-stakes question
  • How to read the structured outputs payload (returned in dict-all-except-first format) to extract the answer programmatically
  • A direct side-by-side: same task, plain agent vs. reasoning agent, real failure modes
The Reasoning Agent endpoint (POST /v1/reasoning-agent/completions) is a premium-only feature available on Pro, Ultra, and Premium plans. Free tier keys receive a 403. Upgrade your account to unlock self-consistency, iterative refinement, and multi-sample deliberation.

Why This Matters

Some questions look like they should be a one-shot LLM call but aren’t. A multi-step accrual reconciliation. A cross-jurisdiction tax allocation. A logic puzzle with five interlocking constraints. An algorithm correctness proof. These are problems where a wrong-looking-but-confident answer is worse than no answer, because nobody downstream has the time to re-derive the calculation by hand. A plain gpt-4 call will produce a single deterministic chain of thought and confidently miscount the deferred revenue. A reasoning agent samples multiple chains, votes on the convergent answer, and surfaces the disagreement when the chains don’t converge — which is exactly the signal you need to escalate a question to a human. The job done isn’t “smarter LLM,” it’s calibrated confidence on hard analytical work.

Step 1: Setup

Step 2: The Problem

This is the kind of problem a controller would hand to a senior associate. It is solvable in closed form, but every step compounds the next, so a single dropped assumption produces a confidently wrong number.
The trick step is question 3. The $240k cash collected in Oct 2024 covers months 1-12 of the contract, but the transaction price is allocated over the full 24 months at $19,500/month (not $20,000/month), so YTD recognition through Dec 31, 2024 is 3 months × $19,500 = $58,500, not $60,000. The remainder of the $240k cash sits as deferred revenue. A plain LLM call will frequently compute $20,000/month and miss the discount allocation.

Step 3: First — Try It With a Plain Agent (for Comparison)

Run the exact same problem through the standard agent completion endpoint. Keep this number — you’ll compare against the reasoning agent’s answer.
In practice on this problem the plain agent will produce a confident but wrong allocation roughly 40-60% of the time — most often by computing $20,000/month for the first year (ignoring that the $12,000 discount must be allocated across all 24 months under ASC 606).

Step 4: Now Solve It With a Reasoning Agent

Switch to /v1/reasoning-agent/completions with swarm_type: "self-consistency". The agent runs num_samples independent reasoning chains and votes on the convergent answer.
The response (result above) is a ReasoningAgentCompletionOutput object with these top-level fields: outputs is where the reasoning content lives. The API returns it in dict-all-except-first format (the output_type default) — a conversation-style structure of role/content entries covering every reasoning step after the initial prompt, ending with the convergent final answer that Step 5 below extracts.

Step 5: Extract the Answer

With the default output_type (dict-all-except-first), outputs contains the per-sample reasoning chains with the convergent final answer last. The convergent answer is the one to trust; the per-sample chains are the audit trail.
$468,000 transaction price = $480,000 contract value − $12,000 discount, allocated ratably over 24 months = $19,500/month. Three months in fiscal 2024 = $58,500 recognized; the rest of the first $240,000 cash collected sits as a contract liability.

Step 6: Tuning the Depth Knob

num_samples is the deliberation budget. Use this table to pick a setting: The right read on convergence: if all 5 samples produce the same final JSON, ship the answer. If 4-of-5 agree, ship with a flag. If 3-of-5 or worse, the problem is genuinely ambiguous and you need a human in the loop — that signal is what you’re paying for, not just the answer.

Picking the Right swarm_type

For accrual accounting, legal interpretation, and financial calculation work, self-consistency is the right default — the failure mode is “confidently wrong on one chain,” and voting across chains is the specific antidote.
The full list of supported values is returned by GET /v1/reasoning-agent/types: reasoning-duo, self-consistency, ire, reasoning-agent, consistency-agent, ire-agent, ReflexionAgent, GKPAgent, AgentJudge. For the ire / ire-agent types, the iteration count is controlled by num_samples rather than max_loops.

Cost vs. Hiring a Senior Associate

Concrete numbers for a high-stakes analytical question (the accrual problem above): Use the reasoning agent for the questions where being wrong is expensive — accruals that hit a 10-K, tax allocations on a large deal, contract interpretations, complex underwriting. Use a plain agent for everything else. The reasoning agent is ~250x cheaper than the associate and gives you a convergence signal the associate can’t, because a single human only has one chain of thought.
A reasoning agent producing 5-of-5 convergence is strong evidence the answer is correct under the given assumptions. It is not evidence the assumptions are correct. For anything that hits a regulated filing, the calculated answer goes to a licensed human reviewer who validates the inputs.

Next Steps