Self-Consistency
self-consistencyReasoningRuns the same task num_samples times, independently and in parallel, then hands every answer to an aggregator agent that compares them and returns the answer most of them agree on. Disagreement between samples is a signal that the question is hard or ambiguous; agreement makes the final answer far more reliable than a single run. This is the default reasoning agent type.
Reasoning agents need a Pro or Premium plan. Requests from a free-tier key return 403. See plans
Architecture
How one run moves through the agent
- 1The task is sent to num_samples independent runs of the same model, all at once.
- 2Each run reasons through the problem on its own, with no view of the others.
- 3An aggregator agent reads every answer and runs a majority vote over them.
- 4The response contains the individual samples and the aggregated final answer.
At a glance
self-consistency (alias: consistency-agent)POST /v1/reasoning-agent/completionsBest for
- Math, logic and word problems with one correct answer
- Factual questions where a single run might hallucinate
- Classification and labeling that needs a stable result
- Decisions where you want a measure of agreement, not one opinion
Parameters
Fields that shape this agent, alongside task, agent_name and description
num_samplesHow many independent answers to generate. 3 to 5 is a good start; each sample is a separate model call.model_nameModel used for every sample. Defaults to claude-sonnet-5.system_promptOptional instructions for each sample.max_loopsLoops per sample. Leave at 1 for most tasks.Quick start
Get a key, list the reasoning agent types, then run this one. Code examples in cURL, Python, TypeScript, Go and JSON.
Get your Swarms API key
Create a key, then export it as SWARMS_API_KEY in your environment.
List the reasoning agent types
Returns every supported swarm_type.
List reasoning agent types
curl -X GET 'https://api.swarms.world/v1/reasoning-agent/types' \ -H 'x-api-key: '"$SWARMS_API_KEY"Run the Self-Consistency
Send a task with swarm_type: "self-consistency" to the reasoning agent endpoint.
Run Self-Consistency
curl -X POST 'https://api.swarms.world/v1/reasoning-agent/completions' \ -H 'x-api-key: '"$SWARMS_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "agent_name": "consistency-solver", "description": "Answers by majority vote over independent samples.", "swarm_type": "self-consistency", "model_name": "gpt-5.5", "num_samples": 5, "max_loops": 1, "task": "If 5 machines take 5 minutes to make 5 widgets, how long would 100 machines take to make 100 widgets? Show your reasoning."}'Read the response
outputs holds the agent's result, and usage reports tokens and the cost of the run.
{ "job_id": "reasoning-agent-…", "status": "success", "outputs": "…", "timestamp": "2026-09-25T12:00:00+00:00", "agent_name": "consistency-solver", "agent_type": "self-consistency", "agent_id": "…", "usage": { "input_tokens": 64, "output_tokens": 1120, "total_tokens": 1184, "total_cost": 0.0213 }}Other reasoning agents
FAQ
What is the Self-Consistency?
Runs the same task num_samples times, independently and in parallel, then hands every answer to an aggregator agent that compares them and returns the answer most of them agree on. Disagreement between samples is a signal that the question is hard or ambiguous; agreement makes the final answer far more reliable than a single run. This is the default reasoning agent type.
How do I run the Self-Consistency with the Swarms API?
POST to https://api.swarms.world/v1/reasoning-agent/completions with "swarm_type" set to "self-consistency" and a task, authenticated with your x-api-key header. "consistency-agent" runs the same agent.
When should I use the Self-Consistency?
It is best for: Math, logic and word problems with one correct answer; Factual questions where a single run might hallucinate; Classification and labeling that needs a stable result; Decisions where you want a measure of agreement, not one opinion.
Which plans can use reasoning agents?
Reasoning agents are a premium endpoint: they need a Pro or Premium plan. A request from a free-tier key returns 403.
How is a reasoning agent run billed?
By tokens, like any other completion. Every sample, loop and evaluation step is a model call, so raising num_samples or max_loops raises the cost. The response reports input, output and total tokens and the total cost.