Reflexion Agent
ReflexionAgentReasoningAnswers, critiques itself and improves. Each loop it drafts or refines a response, scores it out of 10, writes a reflection on what to fix, and feeds that reflection into the next revision. Reflections are kept in short and long-term memory, and the best-scoring response across all loops is returned, so a weaker late revision never replaces a stronger early one.
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 actor drafts a first response to the task.
- 2An evaluator scores the response out of 10 and explains the score.
- 3A reflector writes concrete feedback on what to fix, stored in memory.
- 4The refiner rewrites the response using that feedback, and the loop repeats up to max_loops times.
- 5It stops early once a response scores above 9/10, and returns the best-scoring response.
At a glance
ReflexionAgentPOST /v1/reasoning-agent/completionsBest for
- Writing that improves with revision: reports, explanations, emails
- Multi-step reasoning where the first draft misses cases
- Code explanations and technical answers with clear quality criteria
- Tasks where you want a self-reviewed answer without building a pipeline
Parameters
Fields that shape this agent, alongside task, agent_name and description
max_loopsNumber of draft, score, reflect and refine rounds. 1 is a single draft with a critique; 2 to 3 is where refinement pays off.memory_capacityHow many reflections the agent keeps in short-term memory. Defaults to 6.model_nameModel used by the actor, evaluator and reflector. Defaults to claude-sonnet-5.system_promptOptional instructions for the actor.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 Reflexion Agent
Send a task with swarm_type: "ReflexionAgent" to the reasoning agent endpoint.
Run Reflexion Agent
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": "reflexion-writer", "description": "Drafts, critiques and refines its own answer.", "swarm_type": "ReflexionAgent", "model_name": "gpt-5.5", "max_loops": 3, "task": "Explain how HTTPS protects data in transit to a non-technical audience in under 200 words."}'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": "reflexion-writer", "agent_type": "ReflexionAgent", "agent_id": "…", "usage": { "input_tokens": 64, "output_tokens": 1120, "total_tokens": 1184, "total_cost": 0.0213 }}Other reasoning agents
FAQ
What is the Reflexion Agent?
Answers, critiques itself and improves. Each loop it drafts or refines a response, scores it out of 10, writes a reflection on what to fix, and feeds that reflection into the next revision. Reflections are kept in short and long-term memory, and the best-scoring response across all loops is returned, so a weaker late revision never replaces a stronger early one.
How do I run the Reflexion Agent with the Swarms API?
POST to https://api.swarms.world/v1/reasoning-agent/completions with "swarm_type" set to "ReflexionAgent" and a task, authenticated with your x-api-key header.
When should I use the Reflexion Agent?
It is best for: Writing that improves with revision: reports, explanations, emails; Multi-step reasoning where the first draft misses cases; Code explanations and technical answers with clear quality criteria; Tasks where you want a self-reviewed answer without building a pipeline.
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.