---
title: "Run Agent"
method: POST
path: "/v1/agent/completions"
---

# Run Agent

`POST /v1/agent/completions`

Run an agent with the specified task. Supports streaming when stream=True.

## Headers

- `x-api-key` string, required

## Request body

- AgentCompletion
  - `agent_config` AgentSpec
    - `agent_name` string, nullable, required — The unique name assigned to the agent, which identifies its role and functionality within the swarm.
    - `description` string, nullable — A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform.
    - `system_prompt` string, nullable — The initial instruction or context provided to the agent, guiding its behavior and responses during execution.
    - `model_name` string, nullable — 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
    - `auto_generate_prompt` boolean, nullable — A flag indicating whether the agent should automatically create prompts based on the task requirements.
    - `max_tokens` integer, nullable — The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length.
    - `temperature` number, nullable — A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses.
    - `role` string, nullable — The designated role of the agent within the swarm, which influences its behavior and interaction with other agents.
    - `max_loops` integer, nullable — The maximum number of times the agent is allowed to repeat its task, enabling iterative processing if necessary.
    - `tools_list_dictionary` object[], nullable — A dictionary of tools that the agent can use to complete its task.
    - `mcp_url` string, nullable — The URL of the MCP server that the agent can use to complete its task.
    - `streaming_on` boolean, nullable — A flag indicating whether the agent should stream its output.
    - `llm_args` object, nullable — Additional arguments to pass to the LLM such as top_p, frequency_penalty, presence_penalty, etc.
    - `dynamic_temperature_enabled` boolean, nullable — A flag indicating whether the agent should dynamically adjust its temperature based on the task.
    - `mcp_config` MCPConnection
      - `type` string, nullable — The type of connection, defaults to 'mcp'
      - `url` string, nullable — The URL endpoint for the MCP server
      - `tool_configurations` object, nullable — Dictionary containing configuration settings for MCP tools
      - `authorization_token` string, nullable — Authentication token for accessing the MCP server
      - `transport` string, nullable — The transport protocol to use for the MCP server
      - `headers` object, nullable — Headers to send to the MCP server
      - `timeout` integer, nullable — Timeout for the MCP server
    - `mcp_configs` MultipleMCPConnections
      - `connections` MCPConnection[], required — List of MCP connections
        - `type` string, nullable — The type of connection, defaults to 'mcp'
        - `url` string, nullable — The URL endpoint for the MCP server
        - `tool_configurations` object, nullable — Dictionary containing configuration settings for MCP tools
        - `authorization_token` string, nullable — Authentication token for accessing the MCP server
        - `transport` string, nullable — The transport protocol to use for the MCP server
        - `headers` object, nullable — Headers to send to the MCP server
        - `timeout` integer, nullable — Timeout for the MCP server
    - `tool_call_summary` boolean, nullable — A parameter enabling an agent to summarize tool calls.
    - `reasoning_effort` string, nullable — The effort to put into reasoning.
    - `thinking_tokens` integer, nullable — The number of tokens to use for thinking.
    - `reasoning_enabled` boolean, nullable — A parameter enabling an agent to use reasoning.
  - `task` string, nullable — The task to be completed by the agent.
  - `history` union — The history of the agent's previous tasks and responses. Can be either a dictionary or a list of message objects.
    - object
    - object[]
  - `img` string, nullable — An optional image URL that may be associated with the agent's task or representation.
  - `imgs` string[], nullable — A list of image URLs that may be associated with the agent's task or representation.
  - `tools_enabled` string[], nullable — A list of tools that the agent should use to complete its task.

## Response `200`

Successful Response

- AgentCompletionOutput
  - `job_id` string, nullable — The unique identifier for the agent completion.
  - `success` boolean, nullable — Indicates whether the agent completion was successful.
  - `name` string, nullable — The name of the agent.
  - `description` string, nullable — A description of the agent or completion.
  - `temperature` number, nullable — The temperature setting used for the agent's response generation.
  - `outputs` unknown
  - `usage` object, nullable — Usage statistics or metadata for the agent completion.
  - `timestamp` string, nullable — The timestamp when the agent completion was created.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/the-swarm-corporation/apis/swarms-api.md) · [All operations](https://skmtc.net/the-swarm-corporation/apis/swarms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/the-swarm-corporation/swarms-api/revisions/7618ad18b40e/schema)