THthe-swarm-corporation
Reasoning Agents

Execute Reasoning Agent Completion

Changed on

Execute a reasoning agent with advanced cognitive capabilities for complex problem-solving tasks. This is a premium-only feature.

post/v1/reasoning-agent/completions

Request

  • Base URL
    https://api.swarms.world
  • URL
    https://api.swarms.world/v1/reasoning-agent/completions
  • Auth
    none declared. Required headers: x-api-key

Headers

x-api-keystring required

Request body

agent_namestring nullable

The unique name assigned to the reasoning agent.

descriptionstring nullable

A detailed explanation of the reasoning agent's purpose and capabilities.

model_namestring nullable

The name of the AI model that the reasoning agent will utilize.

system_promptstring nullable

The initial instruction or context provided to the reasoning agent.

max_loopsinteger nullable

The maximum number of times the reasoning agent is allowed to repeat its task. At most 50.

swarm_type'AgentJudge' | 'ReflexionAgent' | 'self-consistency' | 'consistency-agent'

The type of reasoning agent to run: AgentJudge, ReflexionAgent, self-consistency or consistency-agent.

num_samplesinteger

How many independent answers self-consistency and consistency-agent generate before aggregating; each one sends the prompt again and is billed for it. Between 1 and 2000.

output_type'list' | 'dict' | 'dictionary' | 'string' | 'str' | 'final' | 'last' | 'json' | 'all' | 'yaml' | 'dict-all-except-first' | 'str-all-except-first' | 'basemodel' | 'dict-final' | 'list-final' nullable

The type of output format for the reasoning agent.

memory_capacityinteger nullable

The memory capacity for a ReflexionAgent.

taskstring nullable

The task to be completed by the reasoning agent.

Response

Successful Response

job_idstring required

Unique identifier for the reasoning agent run.

statusstring

Status of the reasoning agent run.

outputsunknown required
timestampstring required

ISO-formatted timestamp of when the run was executed.

agent_namestring required

Name of the agent.

agent_typestring required

Type of the agent (swarm type).

agent_idstring required

Unique identifier for the agent instance.

usageobject required

Usage statistics: input, output and total tokens plus the run's total_cost (a float, so this cannot be Dict[str, int]).

Changes

  • 3e13975ede3dRevision changes
    • breaking

      request property list-of-types was narrowed by removing types null from media type application/json

    • warning

      the request property's max was set to 2000.00

    • warning

      the request property's min was set to 1.00

  • 500c79520e41Revision changes
    • breaking

      request property was restricted to a list of enum values

    • breaking

      removed the enum value xml of the request property /

    • breaking

      request property list-of-types was narrowed by removing types null from media type application/json

    • warning

      the / request property's max was set to 50.00

    • warning

      the / request property's min was set to 1.00

    • warning

      removed the request property

    • info

      api tag Reasoning Agents added

    • info

      the request property default value changed from claude-sonnet-4-20250514 to claude-sonnet-5

    • info

      the request property default value changed from reasoning_duo to self-consistency

    • info

      added the new AgentJudge enum value to the request property

    • info

      added the new ReflexionAgent enum value to the request property

    • info

      added the new consistency-agent enum value to the request property

    • info

      added the new self-consistency enum value to the request property

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status