> ## Documentation Index > Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt > Use this file to discover all available pages before exploring further. # Generate Agent Configurations From a Task > Generate a roster of agent configurations for a task. A single builder agent designs the team and returns ready-to-post AgentSpec entries — the generated agents are not executed by this endpoint. ## OpenAPI ````yaml https://api.swarms.world/openapi.json post /v1/auto-agent-builder/completions openapi: 3.1.0 info: title: Swarms API description: >- The Swarms API delivers a high-performance, enterprise-grade platform for orchestrating advanced multi-agent systems. Built on a Rust-powered agent runtime, it enables scalable, robust, and secure agent collaboration, supporting complex workflows and dynamic agent communication. The API exposes a comprehensive suite of RESTful endpoints for the management, execution, and monitoring of agents, swarms, and related resources, empowering organizations to automate and optimize mission-critical processes. To access the API, obtain your API key from the [Swarms API Keys page](https://swarms.world/platform/api-keys). For detailed integration guides, best practices, and reference material, consult the [Swarms API Documentation](https://docs.swarms.ai). version: 1.0.0 servers: - url: https://api.swarms.world description: Swarms Production API security: [] paths: /v1/auto-agent-builder/completions: post: tags: - Auto Agent Builder summary: Generate Agent Configurations From a Task description: >- Generate a roster of agent configurations for a task. A single builder agent designs the team and returns ready-to-post AgentSpec entries — the generated agents are not executed by this endpoint. operationId: run_auto_agent_builder_v1_auto_agent_builder_completions_post parameters: - name: x-api-key in: header required: true schema: type: string title: X-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AutoAgentBuilderInput' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AutoAgentBuilderOutput' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: AutoAgentBuilderInput: properties: task: type: string minLength: 1 title: Task description: >- The task the generated team should be able to handle. This is the only required field. name: anyOf: - type: string - type: 'null' title: Name description: The name of this auto agent builder run. description: anyOf: - type: string - type: 'null' title: Description description: The description of this auto agent builder run. model_name: anyOf: - type: string - type: 'null' title: Model Name description: >- The model backing the builder agent itself — not the models given to the generated agents; the builder chooses those per agent. Defaults to the framework's builder default. max_agents: anyOf: - type: integer maximum: 100 minimum: 1 - type: 'null' title: Max Agents description: >- Upper bound on roster size. This is a ceiling, not a target — the builder prefers the smallest roster that covers the task. default: 5 num_agents: anyOf: - type: integer maximum: 100 minimum: 1 - type: 'null' title: Num Agents description: >- Exact number of agents to generate. When set, this overrides max_agents and the builder's prefer-fewer guidance. system_prompt: anyOf: - type: string - type: 'null' title: System Prompt description: >- Custom instructions for the builder agent. Defaults to the framework's builder system prompt. agent_kwargs: anyOf: - additionalProperties: true type: object - type: 'null' title: Agent Kwargs description: >- Extra keyword arguments carried on every generated agent, e.g. max_loops or streaming_on. Keys that collide with the fields the builder generates (agent_name, description, system_prompt, model_name) are ignored. type: object required: - task title: AutoAgentBuilderInput AutoAgentBuilderOutput: properties: job_id: type: string title: Job Id description: The job ID of the auto agent builder run. name: type: string title: Name description: The name of the auto agent builder run. description: type: string title: Description description: The description of the auto agent builder run. status: type: string title: Status description: The status of the auto agent builder run. agents: items: $ref: '#/components/schemas/AgentSpec-Output' description: The configuration of the agent to be completed. type: array title: Agents description: >- The generated roster. Each entry is a complete AgentSpec that can be posted unmodified to /v1/swarm/completions or the other multi-agent endpoints. usage: $ref: '#/components/schemas/api__auto_agent_builder__Usage' description: The usage of the auto agent builder run. timestamp: type: string title: Timestamp description: The timestamp of the auto agent builder run. type: object required: - job_id - name - description - status - agents - usage - timestamp title: AutoAgentBuilderOutput HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AgentSpec-Output: properties: agent_name: anyOf: - type: string - type: 'null' title: Agent Name description: >- The unique name assigned to the agent, which identifies its role and functionality within the swarm. description: anyOf: - type: string - type: 'null' title: Description description: >- A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform. system_prompt: anyOf: - type: string - type: 'null' title: System Prompt description: >- The initial instruction or context provided to the agent, guiding its behavior and responses during execution. marketplace_prompt_id: anyOf: - type: string - type: 'null' title: Marketplace Prompt Id description: >- The ID of a prompt from the Swarms marketplace to use as the system prompt. If provided, the prompt will be automatically retrieved from the marketplace. model_name: anyOf: - type: string - type: 'null' title: Model Name description: >- The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4.1, openai/o3-mini default: claude-sonnet-5 fallback_models: anyOf: - items: type: string type: array - type: 'null' title: Fallback Models description: >- An ordered list of models to try if the primary model errors: the request is retried with the next model on failure. If set while model_name is omitted, the first entry becomes the primary model. Example: ['gpt-4.1', 'gpt-5.4']. fallback_model_name: anyOf: - type: string - type: 'null' title: Fallback Model Name description: >- A single fallback model to try if the primary model fails, tried after any `fallback_models`. Example: 'gpt-4.1'. auto_generate_prompt: anyOf: - type: boolean - type: 'null' title: Auto Generate Prompt description: >- A flag indicating whether the agent should automatically create prompts based on the task requirements. default: false max_tokens: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Tokens description: >- The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length. Must be at least 1. default: 16000 temperature: anyOf: - type: number maximum: 2 minimum: 0 - type: 'null' title: Temperature description: >- A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses. Accepted range: 0 to 2. If omitted, no temperature is sent to the model (the provider's own default applies). role: anyOf: - type: string - type: 'null' title: Role description: >- The designated role of the agent within the swarm, which influences its behavior and interaction with other agents. default: worker max_loops: anyOf: - type: integer - type: string - type: 'null' title: Max Loops description: >- Maximum number of iterations the agent can perform for its task. Accepts an integer of 1 or greater for a fixed count, or 'auto' to allow the system to determine the necessary number based on the task's complexity. default: 1 tools_list_dictionary: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Tools List Dictionary description: A dictionary of tools that the agent can use to complete its task. selected_tools: anyOf: - type: string - items: type: string type: array - type: 'null' title: Selected Tools description: >- Tools to enable for the autonomous looper when max_loops='auto'. Pass a list of tool names to restrict which tools the agent can use, or omit to allow all safe defaults. Available tools: create_plan, think, subtask_done, complete_task, respond_to_user, create_file, update_file, read_file, list_directory, delete_file, create_sub_agent, assign_task. Note: run_bash is not permitted. mcp_url: anyOf: - type: string - type: 'null' title: Mcp Url description: >- The URL of the MCP server that the agent can use to complete its task. streaming_on: anyOf: - type: boolean - type: 'null' title: Streaming On description: A flag indicating whether the agent should stream its output. default: false llm_args: anyOf: - additionalProperties: true type: object - type: 'null' title: Llm Args description: >- Additional arguments to pass to the LLM such as top_p, frequency_penalty, presence_penalty, etc. top_p: anyOf: - type: number - type: 'null' title: Top P description: The top_p parameter to pass to the LLM. dynamic_temperature_enabled: anyOf: - type: boolean - type: 'null' title: Dynamic Temperature Enabled description: >- A flag indicating whether the agent should dynamically adjust its temperature based on the task. default: false mcp_config: anyOf: - $ref: '#/components/schemas/MCPConnection' - type: 'null' description: The MCP connection to use for the agent. mcp_configs: anyOf: - $ref: '#/components/schemas/MultipleMCPConnections' - type: 'null' description: >- The MCP connections to use for the agent. This is a list of MCP connections. Includes multiple MCP connections. tool_call_summary: anyOf: - type: boolean - type: 'null' title: Tool Call Summary description: A parameter enabling an agent to summarize tool calls. default: true reasoning_effort: anyOf: - type: string enum: - minimal - low - medium - high - none - xhigh - ultra - max - type: 'null' title: Reasoning Effort description: >- How much effort the agent puts into reasoning. Accepted values, tracking the reasoning levels the installed litellm advertises: 'minimal', 'low', 'medium', 'high', 'none', 'xhigh', 'ultra', 'max'. 'max' is the top tier (deepest reasoning) and no beta header is required. At 'xhigh' and above, pair with a large max_tokens so the model has room to think and answer. thinking_tokens: anyOf: - type: integer - type: 'null' title: Thinking Tokens description: The number of tokens to use for thinking. reasoning_enabled: anyOf: - type: boolean - type: 'null' title: Reasoning Enabled description: A parameter enabling an agent to use reasoning. default: false publish_to_marketplace: anyOf: - type: boolean - type: 'null' title: Publish To Marketplace description: >- A flag indicating whether to publish this agent to the Swarms marketplace. default: false use_cases: anyOf: - items: additionalProperties: type: string type: object type: array - type: 'null' title: Use Cases description: >- A list of use case dictionaries with 'title' and 'description' keys. Required when publish_to_marketplace is True. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: >- A list of searchable tags/keywords for the marketplace (e.g., ['finance', 'analysis']). capabilities: anyOf: - items: type: string type: array - type: 'null' title: Capabilities description: >- A list of agent capabilities or features (e.g., ['trend-analysis', 'risk-assessment']). category: anyOf: - type: string - type: 'null' title: Category description: >- The marketplace category for the agent (e.g., 'research', 'content', 'coding', 'finance', 'healthcare', 'education', 'legal'). is_free: anyOf: - type: boolean - type: 'null' title: Is Free description: >- A flag indicating whether the agent is free to use in the marketplace. default: true price_usd: anyOf: - type: number - type: 'null' title: Price Usd description: >- The price in USD for using this agent in the marketplace (if not free). handoffs: anyOf: - items: $ref: '#/components/schemas/AgentSpec-Output' type: array - type: 'null' title: Handoffs description: >- A list of agent specifications that this agent can hand off tasks to. These agents will be created and passed to the agent's handoffs parameter. type: object title: AgentSpec api__auto_agent_builder__Usage: properties: input_tokens: type: integer title: Input Tokens description: The number of input tokens. output_tokens: type: integer title: Output Tokens description: The number of output tokens. total_tokens: type: integer title: Total Tokens description: The total number of tokens. token_cost: type: number title: Token Cost description: The cost in credits for the tokens. cost_per_agent: type: number title: Cost Per Agent description: >- The cost in credits for the single builder agent that designs the roster. The generated agents are not run by this endpoint. type: object required: - input_tokens - output_tokens - total_tokens - token_cost - cost_per_agent title: Usage ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError MCPConnection: properties: type: anyOf: - type: string - type: 'null' title: Type description: The type of connection, defaults to 'mcp' default: mcp url: anyOf: - type: string - type: 'null' title: Url description: The URL endpoint for the MCP server default: http://localhost:8000/mcp name: anyOf: - type: string - type: 'null' title: Name description: Human readable name for the server, used in logs and tool routing tool_configurations: anyOf: - additionalProperties: true type: object - type: 'null' title: Tool Configurations description: Dictionary containing configuration settings for MCP tools authorization_token: anyOf: - type: string - type: 'null' title: Authorization Token description: Bearer token for accessing the MCP server api_key: anyOf: - type: string - type: 'null' title: Api Key description: >- API key for the MCP server. Sent using api_key_header/api_key_prefix. api_key_header: type: string title: Api Key Header description: >- Header used to send the API key, e.g. 'Authorization' or 'X-API-Key'. default: Authorization api_key_prefix: anyOf: - type: string - type: 'null' title: Api Key Prefix description: Prefix prepended to the API key value. Set to None/'' for raw keys. default: Bearer auth_type: anyOf: - type: string enum: - none - api_key - bearer - oauth - custom - type: 'null' title: Auth Type description: Explicit auth mode. Inferred from the other fields when omitted. oauth: anyOf: - $ref: '#/components/schemas/MCPOAuthConfig' - type: 'null' description: OAuth 2.1 configuration for this server. transport: anyOf: - type: string - type: 'null' title: Transport description: 'Transport protocol: ''streamable_http'', ''sse'', ''stdio'', or ''auto''' default: streamable_http headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Headers description: Headers to send to the MCP server timeout: anyOf: - type: integer - type: 'null' title: Timeout description: Request timeout for the MCP server default: 30 sse_read_timeout: anyOf: - type: integer - type: 'null' title: Sse Read Timeout description: How long to wait for streamed events before giving up default: 300 tool_timeout: anyOf: - type: integer - type: 'null' title: Tool Timeout description: >- How long a single tool call may run before timing out. Separate from `timeout`, which bounds HTTP requests. default: 120 command: anyOf: - type: string - type: 'null' title: Command description: Executable to launch for the 'stdio' transport args: anyOf: - items: type: string type: array - type: 'null' title: Args description: Arguments passed to the 'stdio' command env: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Env description: Environment variables for the 'stdio' command additionalProperties: true type: object title: MCPConnection MultipleMCPConnections: properties: connections: items: $ref: '#/components/schemas/MCPConnection' type: array title: Connections description: List of MCP connections type: object required: - connections title: MultipleMCPConnections MCPOAuthConfig: properties: grant_type: type: string enum: - authorization_code - client_credentials title: Grant Type description: OAuth grant to use when no static access_token is supplied. default: authorization_code client_id: anyOf: - type: string - type: 'null' title: Client Id description: >- OAuth client id. Optional for authorization_code when the server supports dynamic client registration. client_secret: anyOf: - type: string - type: 'null' title: Client Secret description: OAuth client secret. Required for client_credentials. scopes: anyOf: - items: type: string type: array - type: 'null' title: Scopes description: Scopes to request, e.g. ['mcp:tools', 'offline_access']. redirect_uri: type: string title: Redirect Uri description: Loopback redirect URI used to capture the authorization code. default: http://127.0.0.1:8765/callback client_name: type: string title: Client Name description: Client name sent during dynamic client registration. default: Swarms Agent client_uri: anyOf: - type: string - type: 'null' title: Client Uri description: Client homepage sent during dynamic client registration. authorization_url: anyOf: - type: string - type: 'null' title: Authorization Url description: >- Explicit authorization endpoint. Discovered automatically when omitted. token_url: anyOf: - type: string - type: 'null' title: Token Url description: Explicit token endpoint. Discovered automatically when omitted. access_token: anyOf: - type: string - type: 'null' title: Access Token description: Pre-obtained access token. When set, no OAuth flow is performed. refresh_token: anyOf: - type: string - type: 'null' title: Refresh Token description: Pre-obtained refresh token, paired with access_token. token_storage_path: anyOf: - type: string - type: 'null' title: Token Storage Path description: >- File used to cache OAuth tokens. Defaults to ~/.swarms/mcp_auth/.json. use_token_cache: type: boolean title: Use Token Cache description: Persist tokens to disk so the browser flow is only run once. default: true open_browser: type: boolean title: Open Browser description: >- Open the system browser for the authorization step. When False the URL is logged instead. default: true callback_timeout: type: integer title: Callback Timeout description: Seconds to wait for the user to complete the browser flow. default: 300 additionalProperties: true type: object title: MCPOAuthConfig description: >- OAuth 2.1 configuration for an MCP server. Three flavours are supported: 1. ``grant_type="authorization_code"`` (default) — the interactive browser flow described by the MCP authorization spec. PKCE and RFC 7591 dynamic client registration are handled by the MCP SDK, so ``client_id`` is optional. Tokens are cached on disk so the browser prompt only happens once. 2. ``grant_type="client_credentials"`` — a headless machine-to-machine flow. Requires ``client_id``/``client_secret``. The token endpoint is discovered from the server's ``/.well-known/oauth-authorization-server`` metadata unless ``token_url`` is given. 3. ``access_token=...`` — a token you already obtained elsewhere. No flow is run; the token is simply sent as a bearer credential. Any string field may use ``"env:MY_VAR"`` or ``"${MY_VAR}"`` to read the value from the environment instead of hardcoding a secret. ````