Overview
The autonomous agent mode (max_loops="auto") lets an agent plan, execute, and summarize complex multi‑step tasks without you having to manually specify the number of loops.
When max_loops="auto", the agent:
- Plans the work as a set of structured subtasks
- Executes each subtask using tools (planning, search, sub-agents, etc.)
- Summarizes the results into a clear final answer
How Autonomous Mode Works
Phase 1: Planning
- The agent analyzes the main task and calls an internal planning tool (e.g.,
create_plan) - It produces a list of subtasks with:
step_id: unique identifierdescription: what to dopriority:critical,high,medium, orlowdependencies: other steps that must complete first
Phase 2: Execution
For each subtask, the agent loops through:- Think: Optional short reasoning step (e.g., with a
thinktool) - Act: Calls tools (search, sub-agents, MCP servers, etc.)
- Observe: Reads tool outputs and updates its plan state
- Complete: Marks the subtask done when satisfied (e.g., via
subtask_done)
Phase 3: Summary
Once all subtasks are complete, the agent:- Generates a final structured summary
- Optionally calls a completion tool (e.g.,
complete_task) - Returns the final result to your application
Tool Selection
By default, autonomous agents have access to all safe built-in tools. You can restrict which tools are available using theselected_tools parameter in agent_config:
create_plan, think, subtask_done, complete_task, respond_to_user, create_sub_agent, assign_task. selected_tools also accepts a single tool name, and an unknown name returns 422.
The shell and file tools (
run_bash, create_file, update_file, read_file, list_directory, delete_file) are not available via the API for security reasons. Listing any of them in selected_tools returns 422.Complete Example: Autonomous Medical Diagnosis Agent
This example shows an autonomous agent that:- Uses the Swarms Python client to call the Agent Completions API
- Analyzes blood work results as an expert doctor
- Runs until it decides the task is complete using
max_loops="auto"
Environment Setup
Create a.env file:
Code Example
- Python
- TypeScript
- Rust
Best Practices
- Clear tasks: Give specific, outcome‑oriented instructions (what to produce, how many steps)
- Tooling: Provide tools that match the work (search, scraping, file I/O, custom APIs)
- Bounded scope: Ask for a concrete deliverable (e.g., “single markdown report”, “CSV summary”)
Key Takeaways
- Set
max_loops="auto"to let the agent decide how many reasoning/action loops are required - Combine planning, tools, and file operations to tackle complex research and analysis workflows
- Prefer clear, structured tasks so the planner can create good subtasks and dependencies
/v1/agent/completions, see “Single Agent Completion (REST)” in the examples section.