Swarms API Documentation - Build AI Agents & Multi-Agent Systems

Headers

x-api-key

string

required

Body

application/json

Input schema for GraphWorkflow completion requests.

name

string | null

The name of the graph workflow.

description

string | null

The description of the graph workflow.

agents

AgentSpec · object[] | null

List of agent specifications to be used as nodes in the workflow graph.

Show child attributes

agents.agent_name

string | null

required

The unique name assigned to the agent, which identifies its role and functionality within the swarm.

agents.description

string | null

A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform.

agents.system_prompt

string | null

The initial instruction or context provided to the agent, guiding its behavior and responses during execution.

agents.model_name

string | null

default:gpt-4.1

The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4o-mini, openai/o3-mini

agents.auto_generate_prompt

boolean | null

default:false

A flag indicating whether the agent should automatically create prompts based on the task requirements.

agents.max_tokens

integer | null

default:8192

The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length.

agents.temperature

number | null

default:0.5

A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses.

agents.role

string | null

default:worker

The designated role of the agent within the swarm, which influences its behavior and interaction with other agents.

agents.max_loops

integer | null

default:1

The maximum number of times the agent is allowed to repeat its task, enabling iterative processing if necessary.

agents.tools_list_dictionary

Tools List Dictionary · object[] | null

A dictionary of tools that the agent can use to complete its task.

agents.mcp_url

string | null

The URL of the MCP server that the agent can use to complete its task.

agents.streaming_on

boolean | null

default:false

A flag indicating whether the agent should stream its output.

agents.llm_args

Llm Args · object

Additional arguments to pass to the LLM such as top_p, frequency_penalty, presence_penalty, etc.

agents.dynamic_temperature_enabled

boolean | null

default:true

A flag indicating whether the agent should dynamically adjust its temperature based on the task.

agents.mcp_config

MCPConnection · object

The MCP connection to use for the agent.

Show child attributes

agents.mcp_config.type

string | null

default:mcp

The type of connection, defaults to 'mcp'

agents.mcp_config.url

string | null

default:http://localhost:8000/mcp

The URL endpoint for the MCP server

agents.mcp_config.tool_configurations

Tool Configurations · object

Dictionary containing configuration settings for MCP tools

agents.mcp_config.authorization_token

string | null

Authentication token for accessing the MCP server

agents.mcp_config.transport

string | null

default:streamable_http

The transport protocol to use for the MCP server

agents.mcp_config.headers

Headers · object

Headers to send to the MCP server

Show child attributes

agents.mcp_config.headers.{key}

string

agents.mcp_config.timeout

integer | null

default:10

Timeout for the MCP server

agents.mcp_configs

MultipleMCPConnections · object

The MCP connections to use for the agent. This is a list of MCP connections. Includes multiple MCP connections.

Show child attributes

agents.mcp_configs.connections

MCPConnection · object[]

required

List of MCP connections

Show child attributes

agents.mcp_configs.connections.type

string | null

default:mcp

The type of connection, defaults to 'mcp'

agents.mcp_configs.connections.url

string | null

default:http://localhost:8000/mcp

The URL endpoint for the MCP server

agents.mcp_configs.connections.tool_configurations

Tool Configurations · object

Dictionary containing configuration settings for MCP tools

agents.mcp_configs.connections.authorization_token

string | null

Authentication token for accessing the MCP server

agents.mcp_configs.connections.transport

string | null

default:streamable_http

The transport protocol to use for the MCP server

agents.mcp_configs.connections.headers

Headers · object

Headers to send to the MCP server

Show child attributes

agents.mcp_configs.connections.headers.{key}

string

agents.mcp_configs.connections.timeout

integer | null

default:10

Timeout for the MCP server

agents.tool_call_summary

boolean | null

default:true

A parameter enabling an agent to summarize tool calls.

agents.reasoning_effort

string | null

The effort to put into reasoning.

agents.thinking_tokens

integer | null

The number of tokens to use for thinking.

agents.reasoning_enabled

boolean | null

default:false

A parameter enabling an agent to use reasoning.

edges

(EdgeSpec · object | object)[] | null

List of edges connecting nodes. Can be EdgeSpec objects or dictionaries with 'source' and 'target' keys.

Schema for defining an edge between nodes in the workflow graph.

EdgeSpec
Option 2

Show child attributes

edges.source

string

required

The source node ID.

edges.target

string

required

The target node ID.

edges.metadata

Metadata · object

Optional metadata for the edge.

entry_points

string[] | null

List of node IDs that serve as starting points for the workflow.

end_points

string[] | null

List of node IDs that serve as ending points for the workflow.

max_loops

integer | null

default:1

The maximum number of execution loops for the workflow.

task

string | null

The task to be executed by the workflow.

img

string | null

Optional image path for vision-enabled agents.

auto_compile

boolean | null

default:true

Whether to automatically compile the workflow for optimization.

verbose

boolean | null

default:false

Whether to enable detailed logging.

Response

Successful Response

Output schema for GraphWorkflow completion responses.

job_id

string

required

The job ID of the graph workflow.

status

string

required

The status of the graph workflow.

outputs

any

required

The outputs of the graph workflow.

usage

Usage · object

required

The usage statistics of the workflow.

Show child attributes

usage.input_tokens

integer

required

The number of input tokens.

usage.output_tokens

integer

required

The number of output tokens.

usage.total_tokens

integer

required

The total number of tokens.

usage.token_cost

number

required

The cost in credits for the tokens.

usage.cost_per_agent

number

required

The cost in credits for the agents.

timestamp

string

required

The timestamp of the graph workflow execution.

name

string | null

The name of the graph workflow.

description

string | null

The description of the graph workflow.

API Reference

Agents

Auto Swarm Builder

Advanced Research

Tool Management

Marketplace

Batched Grid Workflow

Graph Workflow

Execute Graph Workflow

Headers

Body

Response