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_samplesandmax_loopsfor the depth-vs-cost tradeoff on a single high-stakes question - How to read the structured
outputspayload (returned indict-all-except-firstformat) to extract the answer programmatically - A direct side-by-side: same task, plain agent vs. reasoning agent, real failure modes
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 plaingpt-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.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.
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 defaultoutput_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.
Next Steps
- Graph Workflows for Production Pipelines — embed a reasoning agent as one node in a larger production DAG
- Reasoning Agent Types — full catalog of
swarm_typeoptions and their tradeoffs