Sign in
Reasoning Agents

Execute Reasoning Agent Completion

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

post/v1/reasoning-agent/completions

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 nullable

The number of samples to generate for the reasoning agent.

output_type'list' | 'dict' | 'dictionary' | 'string' | 'str' | 'final' | 'last' | 'json' | 'all' | 'yaml' | 'xml' | '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.

{"stackTrail":"components:schemas:ReasoningAgentCompletionOutput:properties:outputs","oasType":"schema","type":"unknown","title":"Outputs","description":"The output generated by the reasoning agent. Shape varies by reasoning type."}
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

Changed in 3 of the 80 revisions of this API.336

  • 7bb777a831f3216See the full diff
    • ▲

      request property was restricted to a list of enum values

      request-property-became-enum

    • ▲

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

      request-property-list-of-types-narrowed

    • ●

      removed the request property

      request-property-removed

    • ○

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

      request-property-default-value-changed

    • ○

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

      request-property-default-value-changed

    • ○

      added the new AgentJudge enum value to the request property

      request-property-enum-value-added

    • ○

      added the new ReflexionAgent enum value to the request property

      request-property-enum-value-added

    • ○

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

      request-property-enum-value-added

    • ○

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

      request-property-enum-value-added

  • b7b92eb482fe11See the full diff
    • ▲

      the / request property's max was decreased to 50.00

      request-property-max-decreased

    • ●

      the / request property's min was set to 1.00

      request-property-min-set

  • 35f4c5ec5bfd1See the full diff
    • ●

      the / request property's max was set to 100.00

      request-property-max-set