Skip to main content
The Agent Completions endpoint (/v1/agent/completions) enables you to execute individual AI agents with specific tasks, configurations, and capabilities. This endpoint provides a flexible way to run single agents with various models, tools, and configurations.

Endpoint Information

  • URL: /v1/agent/completions
  • Method: POST
  • Authentication: Required (x-api-key header)
  • Rate Limiting: Subject to tier-based rate limits

Request Schema

AgentCompletion Object

FieldTypeRequiredDescription
agent_configAgentSpecYesThe configuration of the agent to be completed
taskstringNoThe task to be completed by the agent
historyUnion[Dict, List[Dict]]NoThe history of the agent’s previous tasks and responses. Can be either a dictionary or a list of message objects
imgstringNoA base64 encoded image for the agent to process. Encode your image file to base64 and pass it here
imgsList[string]NoA list of base64 encoded images for the agent to process. Encode your image files to base64 and pass them here
tools_enabledList[string]NoA list of tools that the agent should use to complete its task

AgentSpec Object

FieldTypeRequiredDefaultDescription
agent_namestringNo-The unique name assigned to the agent, which identifies its role and functionality within the swarm
descriptionstringNo-A detailed explanation of the agent’s purpose, capabilities, and any specific tasks it is designed to perform
system_promptstringNo-The initial instruction or context provided to the agent, guiding its behavior and responses during execution
marketplace_prompt_idstringNo-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_namestringNo"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-4.1, openai/o3-mini
auto_generate_promptbooleanNofalseA flag indicating whether the agent should automatically create prompts based on the task requirements
max_tokensintegerNo8192The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length
temperaturefloatNo0.5A parameter that controls the randomness of the agent’s output; lower values result in more deterministic responses
rolestringNo"worker"The designated role of the agent within the swarm, which influences its behavior and interaction with other agents
max_loopsUnion[int, string]No1Maximum number of iterations the agent can perform for its task. Accepts an integer for a fixed count, or ‘auto’ to allow the system to determine the necessary number based on the task’s complexity
tools_list_dictionaryList[Dict]No-A dictionary of tools that the agent can use to complete its task
mcp_urlstringNo-The URL of the MCP server that the agent can use to complete its task
streaming_onbooleanNofalseA flag indicating whether the agent should stream its output
llm_argsDictNo-Additional arguments to pass to the LLM such as top_p, frequency_penalty, presence_penalty, etc.
dynamic_temperature_enabledbooleanNotrueA flag indicating whether the agent should dynamically adjust its temperature based on the task
mcp_configMCPConnectionNo-The MCP connection to use for the agent
mcp_configsMultipleMCPConnectionsNo-The MCP connections to use for the agent. This is a list of MCP connections. Includes multiple MCP connections
tool_call_summarybooleanNotrueA parameter enabling an agent to summarize tool calls
reasoning_effortstringNo-The effort to put into reasoning
thinking_tokensintegerNo-The number of tokens to use for thinking
reasoning_enabledbooleanNofalseA parameter enabling an agent to use reasoning
publish_to_marketplacebooleanNofalseA flag indicating whether to publish this agent to the Swarms marketplace
use_casesList[Dict[str, str]]No-A list of use case dictionaries with ‘title’ and ‘description’ keys. Required when publish_to_marketplace is True
tagsList[string]No-A list of searchable tags/keywords for the marketplace (e.g., [‘finance’, ‘analysis’])
capabilitiesList[string]No-A list of agent capabilities or features (e.g., [‘trend-analysis’, ‘risk-assessment’])
categorystringNo-The marketplace category for the agent (e.g., ‘research’, ‘content’, ‘coding’, ‘finance’, ‘healthcare’, ‘education’, ‘legal’)
is_freebooleanNotrueA flag indicating whether the agent is free to use in the marketplace
price_usdfloatNo-The price in USD for using this agent in the marketplace (if not free)
handoffsList[AgentSpec]No-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

Response Schema

AgentCompletionOutput Object

FieldTypeDescription
job_idstringUnique identifier for the completion job
successbooleanIndicates successful execution
namestringName of the executed agent
descriptionstringAgent description
temperaturefloatTemperature setting used
outputsanyGenerated output from the agent
usageDictToken usage and cost information
timestampstringISO timestamp of completion

Usage Information

The response includes detailed usage metrics:
{
  "usage": {
    "input_tokens": 150,
    "output_tokens": 300,
    "total_tokens": 450,
    "img_cost": 0.25,
    "total_cost": 0.0056
  }
}

Features and Capabilities

1. Multi-Model Support

  • OpenAI Models: gpt-4o, gpt-4o-mini, gpt-4.1
  • Anthropic Models: claude-sonnet-4-20250514-20240620
  • Custom Models: Any model supported by LiteLLM
  • Vision Models: Support for image analysis with gpt-4o and compatible models

2. Vision Capabilities

  • Single image analysis via img parameter
  • Multiple image analysis via imgs parameter
  • Automatic image token counting and cost calculation

3. Conversation History

  • Maintain context across multiple interactions
  • Support for both dictionary and list-based history formats
  • Automatic history formatting and token counting

4. Tool Integration

  • Enable specific tools via tools_enabled parameter
  • MCP (Model Context Protocol) server integration
  • Custom tool dictionaries via tools_list_dictionary
  • Tool call summarization

5. Advanced Configuration

  • Dynamic temperature adjustment
  • Custom LLM arguments (top_p, frequency_penalty, presence_penalty)
  • Streaming output support
  • Auto-prompt generation

Examples

Basic Agent Execution

A simple example demonstrating how to execute a single agent with basic configuration. This example shows the minimum required fields to run an agent completion.
import requests

payload = {
    "agent_config": {
        "agent_name": "Research Analyst",
        "description": "Expert in analyzing and synthesizing research data",
        "system_prompt": "You are a Research Analyst with expertise in data analysis and synthesis.",
        "model_name": "gpt-4o-mini",
        "max_tokens": 8192,
        "temperature": 0.7
    },
    "task": "Analyze the impact of artificial intelligence on healthcare"
}

response = requests.post(
    "https://api.swarms.world/v1/agent/completions",
    headers={"x-api-key": "your-api-key"},
    json=payload
)

Agent with Conversation History

This example demonstrates how to provide conversation history to maintain context across multiple interactions. The history can be provided as a dictionary or list format.
payload = {
    "agent_config": {
        "agent_name": "Medical Assistant",
        "system_prompt": "You are a medical information assistant.",
        "model_name": "gpt-4o-mini",
        "max_tokens": 4096
    },
    "task": "What are the symptoms of diabetes?",
    "history": {
        "message1": {
            "role": "user",
            "content": "Tell me about diabetes"
        },
        "message2": {
            "role": "assistant", 
            "content": "Diabetes is a chronic condition affecting blood sugar levels."
        }
    }
}

Agent with Search Capabilities

Enable web search functionality for your agent by including search tools in the tools_enabled parameter. This allows the agent to search the web for real-time information to complete tasks.
payload = {
    "agent_config": {
        "agent_name": "Research Assistant",
        "description": "Research assistant with web search capabilities",
        "system_prompt": "You are a research assistant that can search the web.",
        "model_name": "gpt-4o-mini",
        "max_tokens": 8192
    },
    "task": "Find the latest developments in quantum computing",
    "tools_enabled": ["search"]
}

Agent with MCP Integration

Integrate Model Context Protocol (MCP) servers to extend your agent’s capabilities. This example shows how to connect an agent to an MCP server for additional tools and resources.
payload = {
    "agent_config": {
        "agent_name": "Data Analyst",
        "description": "Data analyst with database access",
        "system_prompt": "You are a data analyst with access to databases.",
        "model_name": "gpt-4o-mini",
        "max_tokens": 8192,
        "mcp_url": "http://github.com/mcp"
    },
    "task": "Query the customer database for recent orders"
}

Agent with Custom LLM Arguments

Customize advanced LLM parameters such as top_p, frequency_penalty, and presence_penalty to fine-tune the model’s behavior. This is useful for controlling creativity, repetition, and topic diversity.
payload = {
    "agent_config": {
        "agent_name": "Creative Writer",
        "description": "Creative writing specialist",
        "system_prompt": "You are a creative writing expert.",
        "model_name": "gpt-4o",
        "max_tokens": 2048,
        "temperature": 0.9,
        "llm_args": {
            "top_p": 0.9,
            "frequency_penalty": 0.1,
            "presence_penalty": 0.1
        }
    },
    "task": "Write a creative story about time travel"
}

Agent with Max Loops

Control the number of execution iterations your agent performs using the max_loops parameter. This is useful for tasks that require multiple reasoning steps or iterative problem-solving. Set max_loops to a higher value (e.g., 3-5) for complex tasks that need multiple passes, or use "auto" for fully autonomous agents that decide when to stop.
payload = {
    "agent_config": {
        "agent_name": "Problem Solver",
        "description": "Agent that performs iterative problem-solving",
        "system_prompt": "You are a problem-solving agent that breaks down complex tasks into steps and iteratively refines solutions.",
        "model_name": "gpt-4o",
        "max_loops": 3,
        "max_tokens": 4096,
        "temperature": 0.7
    },
    "task": "Solve this multi-step problem: First, research the current state of renewable energy. Then, identify the top 3 challenges. Finally, propose solutions for each challenge."
}

response = requests.post(
    "https://api.swarms.world/v1/agent/completions",
    headers={"x-api-key": "your-api-key"},
    json=payload
)

Agent with Marketplace Prompt

Use pre-built prompts from the Swarms marketplace by specifying the marketplace_prompt_id. When using a marketplace prompt, you don’t need to provide agent_name, description, or system_prompt - the system will automatically retrieve and use the prompt configuration from the marketplace, including the agent’s name, description, and system prompt.
payload = {
    "agent_config": {
        "marketplace_prompt_id": "1191250b-9fb3-42e0-b0e9-25ec83260ab2",
        "model_name": "gpt-4o-mini",
        "max_tokens": 8192
    },
    "task": "Your task here"
}

response = requests.post(
    "https://api.swarms.world/v1/agent/completions",
    headers={"x-api-key": "your-api-key"},
    json=payload
)
Note: When marketplace_prompt_id is provided, the system automatically fetches the agent’s name, description, and system prompt from the marketplace. You can find marketplace prompts using the Query Prompts API.

Batch Processing

Process multiple agent completions simultaneously using the batch endpoint. This is useful for parallel processing of multiple tasks or running the same task with different configurations.
Premium Tier Required: The /v1/agent/batch/completions endpoint is available only on Pro, Ultra, and Premium plans. Upgrade your account to access batch processing capabilities.
For processing multiple agents simultaneously, use the batch endpoint: Endpoint: /v1/agent/batch/completions Request: Array of AgentCompletion objects (max 10 per batch)
payloads = [
    {
        "agent_config": {
            "agent_name": "Analyst 1",
            "system_prompt": "You are a financial analyst.",
            "model_name": "gpt-4o-mini"
        },
        "task": "Analyze Q1 financial results"
    },
    {
        "agent_config": {
            "agent_name": "Analyst 2", 
            "system_prompt": "You are a market analyst.",
            "model_name": "gpt-4o-mini"
        },
        "task": "Evaluate market trends"
    }
]

response = requests.post(
    "https://api.swarms.world/v1/agent/batch/completions",
    headers={"x-api-key": "your-api-key"},
    json=payloads
)

Error Handling

The API returns appropriate HTTP status codes and error messages:
  • 400 Bad Request: Invalid input parameters or validation failures
  • 401 Unauthorized: Missing or invalid API key
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server-side processing errors

Rate Limits

Rate limits are tier-based:
  • Free Tier: 100 requests/minute, 50 requests/hour, 50*24 requests/day
  • Premium Tier: 2000 requests/minute, 10000 requests/hour, 100000 requests/day

Cost Calculation

For detailed pricing information, see the Pricing page.

Best Practices

  1. Agent Naming: Use descriptive, unique names for agents
  2. System Prompts: Provide clear, specific instructions for consistent behavior
  3. Temperature Settings: Use lower values (0.1-0.3) for analytical tasks, higher values (0.7-0.9) for creative tasks
  4. Token Limits: Set appropriate max_tokens based on expected response length
  5. History Management: Keep conversation history concise to manage token costs
  6. Error Handling: Implement proper error handling for production applications
  7. Rate Limiting: Monitor usage and implement backoff strategies for rate limit handling

Integration Examples

Python SDK Usage

Use the official Python SDK for a more convenient way to interact with the Swarms API. The SDK handles authentication, request formatting, and response parsing automatically.
  • pip3 install -U swarms-client
  • Put your SWARMS_API_KEY
import os
from swarms_client import SwarmsClient
from dotenv import load_dotenv
import json

load_dotenv()

client = SwarmsClient(
    api_key=os.getenv("SWARMS_API_KEY"),
)


result = client.agent.run(
    agent_config={
        "agent_name": "Bloodwork Diagnosis Expert",
        "description": "An expert doctor specializing in interpreting and diagnosing blood work results.",
        "system_prompt": (
            "You are an expert medical doctor specializing in the interpretation and diagnosis of blood work. "
            "Your expertise includes analyzing laboratory results, identifying abnormal values, "
            "explaining their clinical significance, and recommending next diagnostic or treatment steps. "
            "Provide clear, evidence-based explanations and consider differential diagnoses based on blood test findings."
        ),
        "model_name": "gpt-4.1",
        "max_loops": 1,
        "max_tokens": 1000,
        "temperature": 0.5,
    },
    task=(
        "A patient presents with the following blood work results: "
        "Hemoglobin: 10.2 g/dL (low), WBC: 13,000 /µL (high), Platelets: 180,000 /µL (normal), "
        "ALT: 65 U/L (high), AST: 70 U/L (high). "
        "Please provide a detailed interpretation, possible diagnoses, and recommended next steps."
    ),
)

print(json.dumps(result, indent=4))

JavaScript/Node.js Integration

Integrate the Swarms API into your JavaScript or Node.js applications using native fetch or any HTTP client library. This example demonstrates a basic implementation using the Fetch API.
const response = await fetch('https://api.swarms.world/v1/agent/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your-api-key'
    },
    body: JSON.stringify({
        agent_config: {
            agent_name: "TypeScript Agent",
            system_prompt: "You are a helpful assistant.",
            model_name: "gpt-4o-mini"
        },
        task: "Explain TypeScript promises"
    })
});

const result = await response.json();

Support and Resources

Further Examples

For end‑to‑end, copy‑pasteable examples built on top of this endpoint:
  • Single Agent Completion (REST) – minimal requests example using the new agent_config format:
    /docs/examples/api_examples/agent_completion_single_agent
  • Autonomous Agents with max_loops="auto" – tutorial for fully autonomous, tool‑using agents:
    /docs/examples/api_examples/autonomous_agent_tutorial