/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-keyheader) - Rate Limiting: Subject to tier-based rate limits
Request Schema
AgentCompletion Object
| Field | Type | Required | Description |
|---|---|---|---|
agent_config | AgentSpec | Yes | The configuration of the agent to be completed |
task | string | No | The task to be completed by the agent |
history | Union[Dict, List[Dict]] | No | The history of the agent’s previous tasks and responses. Can be either a dictionary or a list of message objects |
img | string | No | A base64 encoded image for the agent to process. Encode your image file to base64 and pass it here |
imgs | List[string] | No | A list of base64 encoded images for the agent to process. Encode your image files to base64 and pass them here |
tools_enabled | List[string] | No | A list of tools that the agent should use to complete its task |
AgentSpec Object
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
agent_name | string | No | - | The unique name assigned to the agent, which identifies its role and functionality within the swarm |
description | string | No | - | A detailed explanation of the agent’s purpose, capabilities, and any specific tasks it is designed to perform |
system_prompt | string | No | - | The initial instruction or context provided to the agent, guiding its behavior and responses during execution |
marketplace_prompt_id | string | No | - | 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 | string | No | "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_prompt | boolean | No | false | A flag indicating whether the agent should automatically create prompts based on the task requirements |
max_tokens | integer | No | 8192 | The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length |
temperature | float | No | 0.5 | A parameter that controls the randomness of the agent’s output; lower values result in more deterministic responses |
role | string | No | "worker" | The designated role of the agent within the swarm, which influences its behavior and interaction with other agents |
max_loops | Union[int, string] | No | 1 | Maximum 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_dictionary | List[Dict] | No | - | A dictionary of tools that the agent can use to complete its task |
mcp_url | string | No | - | The URL of the MCP server that the agent can use to complete its task |
streaming_on | boolean | No | false | A flag indicating whether the agent should stream its output |
llm_args | Dict | No | - | Additional arguments to pass to the LLM such as top_p, frequency_penalty, presence_penalty, etc. |
dynamic_temperature_enabled | boolean | No | true | A flag indicating whether the agent should dynamically adjust its temperature based on the task |
mcp_config | MCPConnection | No | - | The MCP connection to use for the agent |
mcp_configs | MultipleMCPConnections | No | - | The MCP connections to use for the agent. This is a list of MCP connections. Includes multiple MCP connections |
tool_call_summary | boolean | No | true | A parameter enabling an agent to summarize tool calls |
reasoning_effort | string | No | - | The effort to put into reasoning |
thinking_tokens | integer | No | - | The number of tokens to use for thinking |
reasoning_enabled | boolean | No | false | A parameter enabling an agent to use reasoning |
publish_to_marketplace | boolean | No | false | A flag indicating whether to publish this agent to the Swarms marketplace |
use_cases | List[Dict[str, str]] | No | - | A list of use case dictionaries with ‘title’ and ‘description’ keys. Required when publish_to_marketplace is True |
tags | List[string] | No | - | A list of searchable tags/keywords for the marketplace (e.g., [‘finance’, ‘analysis’]) |
capabilities | List[string] | No | - | A list of agent capabilities or features (e.g., [‘trend-analysis’, ‘risk-assessment’]) |
category | string | No | - | The marketplace category for the agent (e.g., ‘research’, ‘content’, ‘coding’, ‘finance’, ‘healthcare’, ‘education’, ‘legal’) |
is_free | boolean | No | true | A flag indicating whether the agent is free to use in the marketplace |
price_usd | float | No | - | The price in USD for using this agent in the marketplace (if not free) |
handoffs | List[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
| Field | Type | Description |
|---|---|---|
job_id | string | Unique identifier for the completion job |
success | boolean | Indicates successful execution |
name | string | Name of the executed agent |
description | string | Agent description |
temperature | float | Temperature setting used |
outputs | any | Generated output from the agent |
usage | Dict | Token usage and cost information |
timestamp | string | ISO timestamp of completion |
Usage Information
The response includes detailed usage metrics: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
imgparameter - Multiple image analysis via
imgsparameter - 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_enabledparameter - 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.- Python
- TypeScript
- Rust
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.- Python
- TypeScript
- Rust
Agent with Search Capabilities
Enable web search functionality for your agent by including search tools in thetools_enabled parameter. This allows the agent to search the web for real-time information to complete tasks.
- Python
- TypeScript
- Rust
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.- Python
- TypeScript
- Rust
Agent with Custom LLM Arguments
Customize advanced LLM parameters such astop_p, frequency_penalty, and presence_penalty to fine-tune the model’s behavior. This is useful for controlling creativity, repetition, and topic diversity.
- Python
- TypeScript
- Rust
Agent with Max Loops
Control the number of execution iterations your agent performs using themax_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.
- Python
- TypeScript
- Rust
Agent with Marketplace Prompt
Use pre-built prompts from the Swarms marketplace by specifying themarketplace_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.
- Python
- TypeScript
- Rust
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./v1/agent/batch/completions
Request: Array of AgentCompletion objects (max 10 per batch)
- Python
- TypeScript
- Rust
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
- Agent Naming: Use descriptive, unique names for agents
- System Prompts: Provide clear, specific instructions for consistent behavior
- Temperature Settings: Use lower values (0.1-0.3) for analytical tasks, higher values (0.7-0.9) for creative tasks
- Token Limits: Set appropriate max_tokens based on expected response length
- History Management: Keep conversation history concise to manage token costs
- Error Handling: Implement proper error handling for production applications
- 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
JavaScript/Node.js Integration
Integrate the Swarms API into your JavaScript or Node.js applications using nativefetch or any HTTP client library. This example demonstrates a basic implementation using the Fetch API.
- TypeScript
- Rust
Support and Resources
- API Keys: https://swarms.world/platform/api-keys
- Technical Support: https://cal.com/swarms/swarms-technical-support
- Community: Discord
Further Examples
For end‑to‑end, copy‑pasteable examples built on top of this endpoint:- Single Agent Completion (REST) – minimal
requestsexample using the newagent_configformat:
/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