> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.world/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent
> The core Agent class for building autonomous AI agents with tools, memory, and multi-modal capabilities
## Overview
The `Agent` class is the core component of the Swarms framework, connecting LLMs with tools, long-term memory, and advanced autonomous capabilities. It provides a production-ready interface for building intelligent agents that can reason, use tools, handle multimodal inputs, and execute complex tasks. The class is designed to handle a variety of document types—including PDFs, text files, Markdown, and JSON—enabling robust document ingestion and processing.
```mermaid theme={null}
graph TD
A[Task Initiation] -->|Receives Task| B[Initial LLM Processing]
B -->|Interprets Task| C[Tool Usage]
C -->|Calls Tools| D[Function 1]
C -->|Calls Tools| E[Function 2]
D -->|Returns Data| C
E -->|Returns Data| C
C -->|Provides Data| F[Memory Interaction]
F -->|Stores and Retrieves Data| G[RAG System]
G -->|Vector Store / Retriever| H[Enhanced Data]
F -->|Provides Enhanced Data| I[Final LLM Processing]
I -->|Generates Final Response| J[Output]
C -->|No Tools Available| K[Skip Tool Usage]
K -->|Proceeds to Memory Interaction| F
F -->|No Memory Available| L[Skip Memory Interaction]
L -->|Proceeds to Final LLM Processing| I
```
| Feature | Description |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Conversational Loop** | Enables back-and-forth interaction with the model. |
| **Feedback Collection** | Allows users to provide feedback on generated responses. |
| **Stoppable Conversation** | Supports custom stopping conditions for the conversation. |
| **Retry Mechanism** | Implements a retry system for handling issues in response generation. |
| **Tool Integration** | Supports the integration of various tools for enhanced capabilities. |
| **Long-term Memory Management** | Incorporates vector databases for efficient information retrieval. |
| **Document Ingestion** | Processes various document types for information extraction. |
| **Interactive Mode** | Allows real-time communication with the agent. |
| **Sentiment Analysis** | Evaluates the sentiment of generated responses. |
| **Output Filtering and Cleaning** | Ensures generated responses meet specific criteria. |
| **Asynchronous and Concurrent Execution** | Supports efficient parallelization of tasks. |
| **Planning and Reasoning** | Implements planning functionality for enhanced decision-making. |
| **Autonomous Planning and Execution** | When `max_loops="auto"`, automatically creates plans, executes subtasks, and generates summaries. Includes built-in tools for file operations, user communication, and workspace management. |
| **Agent Handoffs and Task Delegation** | Intelligently routes tasks to specialized agents based on capabilities and task requirements. |
## Import
```python theme={null}
from swarms import Agent
```
## Key Features
* **Tool Integration**: Native support for function calling and tool execution
* **Long-term Memory**: RAG-based memory system for context retention
* **Autonomous Loops**: Dynamic execution with configurable stopping conditions
* **Multi-modal Support**: Process text, images, and other media
* **MCP Support**: Integration with Model Context Protocol servers
* **Agent Handoffs**: Delegate tasks to specialized agents
* **Streaming**: Real-time token streaming with callbacks
* **Fallback Models**: Automatic failover to backup models
* **State Management**: Autosave and state persistence
* **Telemetry**: Optional OpenTelemetry tracing of every run
## Architecture
`Agent` delegates its larger subsystems to dedicated collaborator objects, each built during `__init__` and reachable as an attribute. The agent's own methods are thin wrappers over them, so both call styles work and neither is deprecated.
| Attribute | Class | Owns |
| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `agent.llm_manager` | [`LLMManager`](/api/llm-manager) | Model selection, LiteLLM construction, invocation, streaming, fallback rotation |
| `agent.mcp_manager` | [`MCPManager`](/api/mcp-manager) | MCP server connections, tool discovery, tool-call routing |
| `agent.skills` | [`SkillsManager`](/api/skills-manager) | Agent Skills discovery and prompt rendering |
| `agent.marketplace` | [`AgentMarketplaceHandler`](/api/agent-marketplace-handler) | Fetching and publishing marketplace prompts |
```python theme={null}
agent = Agent(agent_name="Analyst", model_name="gpt-5.4-mini")
# These are equivalent
agent.get_current_model()
agent.llm_manager.get_current_model()
```
Each collaborator is independently usable and independently documented — reach for them directly when you want the behavior without an agent around it.
## Initialization
Unique identifier for the agent instance. When omitted the agent generates one via `generate_id("agent")`, of the form `agent-` followed by 32 hex characters (`secrets.token_hex(16)`) — not a UUID.
The name of the agent, used for identification and logging. Omit it and the
agent defaults to the literal `"swarm-worker-01"` — every agent that does
not set a name shares this same value.
Because the default is a shared literal rather than a generated value,
anything keyed on `agent_name` collides across unnamed agents: concurrent
result dictionaries keep one entry for the whole group, and `MEMORY.md`
folders are shared. Pass an explicit name whenever agents run
concurrently or need memory to be stable across restarts.
A description of the agent's purpose and capabilities. Shown to orchestrators when routing tasks.
The system prompt that defines the agent's behavior and personality. Defaults to the framework's general-purpose `AGENT_SYSTEM_PROMPT_3` rather than an empty prompt.
The language model instance to use. If None, a LiteLLM instance will be created
The LiteLLM-compatible model identifier (e.g. `"gpt-5.4"`, `"claude-sonnet-4-6"`, `"groq/llama-3.3-70b-versatile"`).
Extra keyword arguments forwarded to the underlying LiteLLM client.
Enable provider-side prompt caching. When `True`, ephemeral `cache_control` breakpoints are added to the stable prefix of each request (system prompt, tools, and the last message) so it is cached and re-billed at a large discount. Applies to the Anthropic model family (Claude on Anthropic / Bedrock / Vertex); providers that cache automatically (e.g. OpenAI) are left untouched. See the [Prompt Caching guide](/agents/prompt-caching).
Fine-grained prompt-caching options; only consulted when `prompt_caching=True`. All keys optional:
* `ttl` (`str`): `"5m"` (default) or `"1h"` for Anthropic's extended cache (2x write cost, survives longer gaps; the required beta header is attached automatically).
* `cache_system_prompt` (`bool`, default `True`): cache the system prefix.
* `cache_messages` (`bool`, default `True`): cache through the last message (incremental multi-turn caching).
* `cache_tools` (`bool`, default `True`): cache the tool-definitions block.
* `override` (`bool`, default `None`): force `cache_control` injection on/off regardless of the detected provider (e.g. opt Gemini/Vertex in, or a custom alias out). `None` auto-detects (Anthropic only).
* `prompt_cache_key` (`str`): OpenAI-only routing hint for higher cache hit rates.
* `prompt_cache_retention` (`str`): OpenAI-only cache TTL — `"in_memory"` or `"24h"`.
Base URL for OpenAI-compatible providers (Ollama, LM Studio, vLLM, etc.).
Override API key for the LLM provider. Falls back to environment variables when unset.
Single fallback model used when the primary model fails.
Maximum number of reasoning loops. Use "auto" for autonomous mode with dynamic planning
List of callable functions that the agent can use as tools
Temperature for LLM sampling (0.0 to 1.0)
Maximum number of tokens in the LLM response. A positive value you pass is kept and forwarded to the LLM. Leave it as `None` (or pass `0`/a negative number) and the agent resolves the model's own maximum output-token limit, falling back to `16000` when that lookup fails.
Effective context window in tokens. When `context_compression=True`, the agent compresses memory once usage crosses 90% of this limit. Leave as `None` to derive the window from the model.
Nucleus-sampling parameter. Stripped automatically for Anthropic models when extended thinking is enabled.
Allow the framework to grow/shrink the per-call context budget based on token usage signals.
When `True`, the agent runs a `ContextCompressor` that summarises long histories at 90% of `context_length` so long sessions never hit the context wall.
When `True`, read/write `MEMORY.md` under the workspace so agent state survives process restarts. Off by default: opt in explicitly for agents that should remember across runs.
Optional pre/post-processing transforms applied to the conversation history.
Enable basic streaming with formatted panels
Enable detailed token-by-token streaming with metadata (citations, tokens used, etc.)
Callback function to receive streaming tokens in real-time. Use with `agent.run_stream` / `agent.arun_stream` for generator-style consumption.
Enable interactive mode (REPL-style) — prompt the user for input between loops.
Enable verbose logging for debugging.
When `False`, suppress the agent's printed output (Rich panels, thinking panel, etc.). Token streams via `arun_stream` / `streaming_callback` are unaffected.
How the run's result is formatted. See [Output Types](#output-types) for all 17 accepted values.
Automatically save agent state during execution
Display agent dashboard on initialization
A store that is written out with agent state. The agent never queries it — only `.save(path)` is ever called on it, so this does not provide RAG. For retrieval, expose the lookup as a tool instead.
List of fallback models to try in order if the primary model fails.
Number of retry attempts for LLM calls
Token that signals the agent to stop execution
Function that returns True when the agent should stop
Alternative stopping function
Enable dynamic temperature adjustment during execution
Enable dynamic loop count adjustment (sets max\_loops="auto")
Seconds to wait between consecutive loop iterations.
Token the user can type in interactive mode to exit the loop.
When `True`, append the framework's preset stopping marker to the system prompt.
Auto-generate a system prompt from the task description when one is not provided.
Name of the user in conversation history
Path that `save()` writes to when called with no argument. When unset, falls back to an auto-generated `{api_key}_state.json` filename inside the agent workspace.
Standard operating procedure for the agent
List of standard operating procedures
Rules that govern agent behavior
Prompt for planning phase
Enable planning phase before execution
Enable multi-modal processing (images, etc.).
After every tool call, run a brief LLM summary of the tool result and add it to the conversation.
Number of times to retry a failing tool call before giving up.
Display tool inputs/outputs in the agent's printed output.
Pre-built OpenAI function-calling tool schemas. Use when you want to bypass the auto-generated schema.
Override tool schema used at runtime.
Optional post-processor applied to the agent's output before returning.
Pydantic models registered for structured-output prompting.
A single MCP server. Pass a URL string for an unauthenticated server, or an `MCPConnection`/dict to configure auth, transport, headers and timeouts.
Several MCP servers. Each entry may be a URL string, an `MCPConnection`, or a dict. Tools from every server are merged and each tool call is routed back to the server that owns it.
A single MCP server given as a connection object (or the equivalent dict).
Several MCP servers given as connection objects (or dicts).
API key applied to every MCP server that does not define its own. Sent as `Authorization: Bearer ` by default; override the header or prefix per-server with `MCPConnection(api_key_header=..., api_key_prefix=...)`. Supports `"env:MY_VAR"` / `"${MY_VAR}"` indirection so secrets stay out of code.
Bearer token applied to every MCP server that does not define its own. Equivalent to `mcp_api_key` with the default header and prefix.
OAuth 2.1 settings applied to every MCP server without its own. Supports the interactive authorization-code flow (PKCE plus dynamic client registration, tokens cached on disk), the headless `client_credentials` grant, and pre-issued access tokens.
Extra headers merged into every MCP request.
Force a transport for every MCP server. `None` auto-detects from the URL.
Request timeout in seconds for every MCP server. Falls back to the per-connection default of 30.
List of agents to enable task handoffs/delegation
Free-form list of agent capabilities used for routing and documentation.
The agent's role within a swarm (e.g. `"worker"`, `"director"`).
Tags used to filter or categorise the agent.
Structured list of intended use cases for documentation/marketplace listings.
Execution mode: `interactive` (REPL), `fast` (minimal logging/decoration), or `standard`.
UUID of a prompt from the Swarms marketplace to use as the system prompt.
When `True`, publish this agent to the Swarms marketplace on initialization.
Path to a directory of Agent Skills (Anthropic `SKILL.md` format).
Tools to enable for the autonomous looper when `max_loops="auto"`. Use `"all"`, or a list of tool names — the list filters the **entire** loop tool set, control-flow tools included, so include `create_plan` and `complete_task` unless you intend to remove them. `agent.get_all_selected_tools()` returns every valid name.
Give the autonomous looper (`max_loops="auto"`) a `think` tool for an explicit reasoning turn. Off by default: it costs a full round-trip to produce reasoning most models can emit inline alongside their actions. When `False` the system prompt is adjusted to match, so the model is never told to call a tool it does not have.
Defer tool schemas behind a `tool_search` tool instead of sending them all on every request. See [Dynamic Tool Loading](#dynamic-tool-loading) below.
Enable ReAct-style reasoning prompting.
Whether to prepend the framework's reasoning preamble to the system prompt.
Enable reasoning mode for supported models (e.g. o1, o3, Claude with extended thinking).
Effort level for reasoning models: `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"ultra"`, `"max"`, or `"none"`.
Left unset, the parameter is not sent to the provider at all.
Do not combine `reasoning_effort` with `tools` on OpenAI reasoning models such as `gpt-5.4-mini`. `/v1/chat/completions` rejects the pair with `BadRequestError: Function tools with reasoning_effort are not supported`. This is why the default is `None`: it previously defaulted to `"medium"`, which shipped on every request and made `Agent(model_name="gpt-5.4-mini", tools=[...])` fail out of the box.
Maximum extended-thinking budget for Claude reasoning models.
Prepend the framework's safety preamble to the system prompt.
Randomly select from a pool of models on each call (load-balancing/experimentation).
Not a constructor argument — any value passed here is ignored. The workspace root is read from the `WORKSPACE_DIR` environment variable; set it explicitly (e.g. via a `.env` file — `.env.example` uses `agent_workspace`). When it is unset, `agent.workspace_dir` resolves to `None` and an error is logged; the workspace manager behind `agent.workspace` then falls back to `{cwd}/agent_workspace` the first time it needs a directory. Each agent gets its own subdirectory at `{workspace}/agents/{agent-name}-{id12}/`, where `id12` is the last 12 characters of `agent.id`. Read the resolved path from `agent.workspace.dir`.
Path from which to load saved agent state on init.
## Methods
### run
Execute the agent's main loop for a given task.
```python theme={null}
def run(
task: Optional[Union[str, Any]] = None,
img: Optional[str] = None,
imgs: Optional[List[str]] = None,
correct_answer: Optional[str] = None,
streaming_callback: Optional[Callable[[str], None]] = None,
n: int = 1,
*args,
**kwargs
) -> Any
```
The task or prompt for the agent to process
Optional image path or data for vision-enabled models
Optional list of image paths for batch processing
Expected correct answer for validation with automatic retries
Callback function to receive streaming tokens in real-time
Number of times to run the task. When `n > 1`, `run` recursively calls itself `n` times and returns a list of results.
Prior conversation as typed chat turns. When given, these replace the transcript
the agent would otherwise derive from its own memory, and `task` is appended as
the new user turn. Multi-agent structures use this to hand an agent the shared
room with roles intact — the agent's own turns as `assistant`, everyone else's
as labelled `user` turns — instead of one flattened string.
```python theme={null}
agent.run(
task="What did the analyst conclude?",
messages=[
{"role": "user", "content": "Summarise the Q3 numbers."},
{"role": "assistant", "content": "Revenue rose 12%."},
{"role": "user", "content": "Analyst: margins are the risk."},
],
)
```
Agent output formatted according to output\_type configuration
**Return types based on input:**
| Scenario | Return Type | Description |
| ----------------- | ----------- | ------------------------------------------------------- |
| Single task | `str` | Returns the agent's response |
| Multiple images | `List[Any]` | Returns a list of results, one for each image |
| Answer validation | `str` | Returns the correct answer as a string |
| Streaming | `str` | Returns the complete response after streaming completes |
**Examples:**
```python theme={null}
# Basic usage
response = agent.run("Generate a report on financial performance.")
# Single image processing
response = agent.run(
task="Analyze this image and describe what you see",
img="path/to/image.jpg"
)
# Multiple image processing
response = agent.run(
task="Analyze these images and identify common patterns",
imgs=["image1.jpg", "image2.png", "image3.jpeg"]
)
# Answer validation with retries
response = agent.run(
task="What is the capital of France?",
correct_answer="Paris"
)
# Real-time streaming
def streaming_callback(token: str):
print(token, end="", flush=True)
response = agent.run(
task="Tell me a long story about space exploration",
streaming_callback=streaming_callback
)
```
### **call**
Alternative syntax for running the agent (calls `run` internally).
```python theme={null}
def __call__(
task: Optional[str] = None,
img: Optional[str] = None,
*args,
**kwargs
) -> Any
```
### arun
Async version of `run`.
```python theme={null}
async def arun(
task: Optional[str] = None,
img: Optional[str] = None,
*args,
**kwargs,
) -> Any
```
### run\_batched
Run multiple tasks **sequentially**, one after another, and collect the results. For concurrent execution use `run_concurrent_tasks` instead.
```python theme={null}
def run_batched(
tasks: List[str],
imgs: List[str] = None,
*args,
**kwargs,
) -> List[Any]
```
List of tasks to run, in order
One image per task, paired by position. Omit to run the tasks without images. A length mismatch raises `ValueError` rather than silently dropping the extras.
List of results from each task execution, in the same order as the input tasks
```python theme={null}
tasks = [
"Analyze the financial data for Q1",
"Generate a summary report for stakeholders",
"Create recommendations for Q2 planning"
]
batch_results = agent.run_batched(tasks)
for i, (task, result) in enumerate(zip(tasks, batch_results)):
print(f"Task {i+1}: {task}")
print(f"Result: {result}\n")
```
### run\_stream
Run the agent and yield response tokens one-by-one as a sync generator. The full agent loop (multi-step reasoning, tool calls, MCP, autonomous plan/execute/summary) runs in a background daemon thread; tokens are forwarded to the caller the moment the LLM emits them.
```python theme={null}
def run_stream(
task: str,
img: Optional[str] = None,
**kwargs,
) -> Iterator[str]
```
Tool-call results are fed back into the loop automatically — tokens from each subsequent LLM turn (synthesis turn, autonomous summary phase, etc.) are streamed through as well.
```python theme={null}
for token in agent.run_stream("Analyse NVDA"):
print(token, end="", flush=True)
```
### arun\_stream
Async generator version of `run_stream`. The agent loop runs in a thread executor while tokens are forwarded through an `asyncio.Queue`, so the caller's event loop is never blocked.
```python theme={null}
async def arun_stream(
task: str,
img: Optional[str] = None,
**kwargs,
) -> AsyncIterator[str]
```
```python theme={null}
import asyncio
async def main():
async for token in agent.arun_stream("Analyse NVDA"):
print(token, end="", flush=True)
asyncio.run(main())
```
Both `run_stream` and `arun_stream` work for any `max_loops` value (1, integer > 1 with tools, or `"auto"`). They stream tokens through every internal loop, including tool-call turns, synthesis turns after a tool returns, and the autonomous plan/execute/summary cycle.
### run\_concurrent\_tasks
Run a batch of tasks concurrently via a thread pool.
```python theme={null}
def run_concurrent_tasks(
tasks: List[str],
*args,
**kwargs,
) -> List[Any]
```
### bulk\_run
Generate responses for multiple input sets. Each input is a dict of kwargs forwarded to `run`.
```python theme={null}
def bulk_run(
inputs: List[Dict[str, Any]],
) -> List[str]
```
### save
Save the agent's current state to disk.
```python theme={null}
def save(
file_path: str = None
) -> None
```
### load
Load agent state from a saved file (JSON, via `SafeStateManager`). If `file_path` is omitted, falls back to `load_state_path`, then `saved_state_path`, then a path derived from `agent_name`.
```python theme={null}
def load(
file_path: str = None
) -> None
```
### save\_to\_yaml
Save the agent to a YAML file.
```python theme={null}
def save_to_yaml(
file_path: str
) -> None
```
### to\_dict
Convert agent configuration to dictionary.
```python theme={null}
def to_dict() -> Dict[str, Any]
```
### to\_json
Convert agent configuration to JSON string.
```python theme={null}
def to_json(
indent: int = 4
) -> str
```
### to\_yaml
Convert agent configuration to YAML string.
```python theme={null}
def to_yaml(
indent: int = 4
) -> str
```
### to\_toml
Convert agent configuration to TOML string.
```python theme={null}
def to_toml() -> str
```
### model\_dump\_json / model\_dump\_yaml
Save the agent model to a JSON or YAML file in the workspace directory.
```python theme={null}
def model_dump_json() -> None
def model_dump_yaml() -> None
```
### add\_tool / add\_tools
Dynamically add a tool (or list of tools) to the agent at runtime.
```python theme={null}
def add_tool(tool: Callable) -> None
def add_tools(tools: List[Callable]) -> None
```
### remove\_tool / remove\_tools
Remove a previously-registered tool (or list of tools).
```python theme={null}
def remove_tool(tool: Callable) -> None
def remove_tools(tools: List[Callable]) -> None
```
### add\_memory
Append a message to the agent's short-term memory.
```python theme={null}
def add_memory(message: str) -> None
```
### talk\_to
Initiate a conversation with another agent.
```python theme={null}
def talk_to(
agent: Any,
task: str,
img: Optional[str] = None,
*args,
**kwargs
) -> Any
```
### talk\_to\_multiple\_agents
Talk to multiple agents concurrently.
```python theme={null}
def talk_to_multiple_agents(
agents: List[Union[Any, Callable]],
task: str,
*args,
**kwargs
) -> Any
```
Returns one entry per agent, in the order the agents were given. An agent whose conversation raised contributes `None`.
### receive\_message / send\_agent\_message
`receive_message` wraps an incoming message from another agent in a short preamble and runs it through the agent's normal `run()` loop, returning the agent's response. `send_agent_message` prefixes a message with `To: {agent_name}:` and runs that through `run()`, returning the result.
```python theme={null}
def receive_message(agent_name: str, task: str, *args, **kwargs) -> Any
def send_agent_message(agent_name: str, message: str, *args, **kwargs) -> str
```
Task delegation via `handoffs` happens automatically inside `run()` — the LLM calls an internal handoff tool when it decides to delegate. There is no separate public `handle_handoffs()` method to call directly.
### reset
Drop the agent's short-term memory by setting `agent.short_memory = None`. Nothing is re-initialized in its place.
```python theme={null}
def reset() -> None
```
After `reset()` the agent cannot run again until `short_memory` is replaced with a fresh `Conversation`. Construct a new agent instead unless you intend to rebuild it yourself.
### plan
Run only the planning phase for a task without executing.
```python theme={null}
def plan(task: str, *args, **kwargs) -> None
```
### print\_dashboard
Display the agent's configuration dashboard.
```python theme={null}
def print_dashboard() -> None
```
### showcase\_config
Display the agent's configuration in a formatted table.
```python theme={null}
def showcase_config() -> None
```
### update\_system\_prompt / update\_max\_loops / update\_loop\_interval
In-place setters for runtime reconfiguration.
```python theme={null}
def update_system_prompt(system_prompt: str) -> None
def update_max_loops(max_loops: Union[int, str]) -> None
def update_loop_interval(loop_interval: int) -> None
```
### Tool Management
Methods backing dynamic tool loading and MCP tool discovery. See [Dynamic Tool Loading](#dynamic-tool-loading).
```python theme={null}
def setup_dynamic_tools(always_loaded: Optional[List[dict]] = None) -> DynamicToolLoader
def defer_tool_schemas(schemas: List[dict]) -> None
def defer_mcp_tools() -> int
def add_mcp_tools_to_memory() -> List[Dict[str, Any]]
def get_all_selected_tools() -> List[str]
```
| Method | Behaviour |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setup_dynamic_tools(always_loaded)` | Rebuild the agent's [`DynamicToolLoader`](/api/dynamic-tool-loader), deferring its tool schemas behind `tool_search`. Schemas in `always_loaded` are never deferred — control-flow tools belong there, since an agent that has to search for its own `complete_task` cannot finish. Schemas already registered (handoff tools, MCP tools) are preserved. Runs automatically during `__init__` when `dynamic_tools` applies. Returns the loader, also stored on `agent.tool_loader`. |
| `defer_tool_schemas(schemas)` | Add pre-built OpenAI function-calling schemas to the deferred catalog. No-op when no loader is active. |
| `defer_mcp_tools()` | Move this agent's MCP tool schemas into the deferred catalog and return how many were added. The fetch is a network call and runs once per agent. |
| `add_mcp_tools_to_memory()` | Fetch the tool schemas exposed by the configured MCP servers, as OpenAI function-calling definitions. Connections, authentication, and transport selection are delegated to [`MCPManager`](/api/mcp-manager). |
| `get_all_selected_tools()` | Every autonomous-loop tool name, e.g. `["create_plan", "think", "subtask_done", ...]`. Build a `selected_tools` list from this instead of hardcoding names. |
Two related properties:
| Property | Type | Value |
| ------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent.workspace` | `WorkspaceManager` | The agent's workspace manager, created on first access and rooted at `{workspace}/agents/{name}-{id12}`. Read the resolved path from `agent.workspace.dir`. |
| `agent.mcp_enabled` | `bool` | Whether at least one MCP server is configured. Backed by [`MCPManager`](/api/mcp-manager), which normalizes `mcp_url`, `mcp_urls`, `mcp_config`, and `mcp_configs` into one list of connections. |
### get\_llm\_parameters
Returns the parameters of the language model as a string (`str(vars(self.llm))`).
```python theme={null}
def get_llm_parameters() -> str
```
### Fallback Model Helpers
Methods backing the `fallback_models` / `fallback_model_name` feature. All delegate to [`LLMManager`](/api/llm-manager).
```python theme={null}
def get_available_models() -> List[str]
def get_current_model() -> str
def switch_to_next_model() -> bool
def reset_model_index() -> None
def is_fallback_available() -> bool
```
### Skills Helpers
Agent Skills loading, delegating to [`SkillsManager`](/api/skills-manager).
```python theme={null}
def handle_skills(task: Optional[str] = None) -> None # append skills to the system prompt
def load_skills_metadata(skills_dir: str = None) -> List[Dict[str, str]]
def load_full_skill(skill_name: str) -> Optional[str]
```
`agent.skills_dir` and `agent.skills_metadata` are properties that read and write through to the manager.
### Marketplace Helpers
Marketplace integration, delegating to [`AgentMarketplaceHandler`](/api/agent-marketplace-handler).
```python theme={null}
def handle_publish_to_marketplace() -> Dict[str, Any] # requires use_cases
```
Setting `marketplace_prompt_id` loads a prompt during construction; setting `publish_to_marketplace=True` publishes during construction.
### Complete Methods Reference
| Method | Description | Usage Example |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
| `run(task, img, imgs, correct_answer, streaming_callback, n, messages)` | Run the autonomous agent loop | `agent.run("Generate a report")` |
| `run_batched(tasks, imgs)` | Run multiple tasks sequentially | `agent.run_batched(["Task 1", "Task 2"])` |
| `__call__(task, img)` | Alternative way to call `run` | `agent("Generate a report")` |
| `arun(task, img)` | Async version of `run` | `await agent.arun("Task")` |
| `run_stream(task, img)` | Sync streaming generator | `for t in agent.run_stream("Task"): ...` |
| `arun_stream(task, img)` | Async streaming generator | `async for t in agent.arun_stream("Task"): ...` |
| `run_concurrent_tasks(tasks)` | Run multiple tasks concurrently | `agent.run_concurrent_tasks(["T1", "T2"])` |
| `bulk_run(inputs)` | Generate responses for multiple inputs | `agent.bulk_run([{"task": "T1"}])` |
| `tool_execution_retry(response, loop_count)` | Execute tools with retry logic | `agent.tool_execution_retry(response, 1)` |
| `add_memory(message)` | Add message to memory | `agent.add_memory("Important info")` |
| `plan(task)` | Plan task execution | `agent.plan("Analyze trends")` |
| `save(file_path)` | Save agent state to JSON | `agent.save("state.json")` |
| `load(file_path)` | Load agent state from JSON | `agent.load("state.json")` |
| `save_to_yaml(file_path)` | Save to YAML | `agent.save_to_yaml("config.yaml")` |
| `to_dict()` | Convert to dictionary | `agent.to_dict()` |
| `to_json(indent)` | Convert to JSON string | `agent.to_json()` |
| `to_yaml(indent)` | Convert to YAML string | `agent.to_yaml()` |
| `to_toml()` | Convert to TOML string | `agent.to_toml()` |
| `model_dump_json()` | Save model to JSON file | `agent.model_dump_json()` |
| `model_dump_yaml()` | Save model to YAML file | `agent.model_dump_yaml()` |
| `add_tool(tool)` | Add a tool | `agent.add_tool(my_tool)` |
| `add_tools(tools)` | Add multiple tools | `agent.add_tools([t1, t2])` |
| `remove_tool(tool)` | Remove a tool | `agent.remove_tool(my_tool)` |
| `remove_tools(tools)` | Remove multiple tools | `agent.remove_tools([t1, t2])` |
| `talk_to(agent, task)` | Talk to another agent | `agent.talk_to(other, "Collaborate")` |
| `talk_to_multiple_agents(agents, task)` | Talk to multiple agents | `agent.talk_to_multiple_agents([a1], "Task")` |
| `receive_message(agent_name, task)` | Run a message received from another agent through `run()` | `agent.receive_message("User", "Hello")` |
| `send_agent_message(agent_name, message)` | Send a message | `agent.send_agent_message("AgentX", "Done")` |
| `update_system_prompt(prompt)` | Update system prompt | `agent.update_system_prompt("New prompt")` |
| `update_max_loops(max_loops)` | Update max loops | `agent.update_max_loops(5)` |
| `reset()` | Drop short-term memory (leaves the agent unusable until rebuilt) | `agent.reset()` |
| `print_dashboard()` | Display dashboard | `agent.print_dashboard()` |
| `showcase_config()` | Display config table | `agent.showcase_config()` |
| `get_llm_parameters()` | Get LLM parameters (as a string) | `agent.get_llm_parameters()` |
| `get_available_models()` | List primary + fallback model names | `agent.get_available_models()` |
| `get_current_model()` | Get the model currently in use | `agent.get_current_model()` |
| `switch_to_next_model()` | Switch to the next fallback model | `agent.switch_to_next_model()` |
| `reset_model_index()` | Reset back to the primary model | `agent.reset_model_index()` |
| `is_fallback_available()` | Whether more than one model is configured | `agent.is_fallback_available()` |
| `check_available_tokens()` | Check available tokens | `agent.check_available_tokens()` |
| `pretty_print(response, loop_count)` | Print formatted response | `agent.pretty_print("Done", 1)` |
| `call_llm(task)` | Call the language model | `agent.call_llm("Generate text")` |
| `execute_tools(response, loop_count)` | Execute tools from response | `agent.execute_tools(response, 1)` |
| `list_output_types()` | List available output types | `agent.list_output_types()` |
| `update_loop_interval(interval)` | Update loop interval | `agent.update_loop_interval(2)` |
| `handle_tool_schema_ops()` | Handle tool schema operations | `agent.handle_tool_schema_ops()` |
| `handle_sop_ops()` | Handle SOP operations | `agent.handle_sop_ops()` |
| `mcp_tool_handling(response, current_loop)` | Handle MCP tool execution | `agent.mcp_tool_handling(response, 1)` |
| `parse_llm_output(response)` | Parse and standardize LLM output | `agent.parse_llm_output(llm_output)` |
| `check_if_no_prompt_then_autogenerate(task)` | Auto-generate prompt if none set | `agent.check_if_no_prompt_then_autogenerate("Task")` |
| `output_cleaner_op(response)` | Apply output cleaning operations | `agent.output_cleaner_op(response)` |
| `stream_response(response, delay)` | Stream response token by token | `agent.stream_response("Response", 0.001)` |
| `temp_llm_instance_for_tool_summary()` | Create temp LLM for tool summaries | `agent.temp_llm_instance_for_tool_summary()` |
| `load_skills_metadata(skills_dir)` | Load Agent Skills metadata | `agent.load_skills_metadata("./skills")` |
| `load_full_skill(skill_name)` | Load complete skill content | `agent.load_full_skill("my-skill")` |
| `setup_dynamic_tools(always_loaded)` | Defer tool schemas behind `tool_search` | `agent.setup_dynamic_tools()` |
| `defer_tool_schemas(schemas)` | Add pre-built schemas to the deferred catalog | `agent.defer_tool_schemas(schemas)` |
| `defer_mcp_tools()` | Move MCP tool schemas into the deferred catalog | `agent.defer_mcp_tools()` |
| `add_mcp_tools_to_memory()` | Fetch tool schemas from the configured MCP servers | `agent.add_mcp_tools_to_memory()` |
| `get_all_selected_tools()` | List every autonomous-loop tool name | `agent.get_all_selected_tools()` |
## Advanced Capabilities
### Tool Integration
The `Agent` class allows seamless integration of external tools by accepting a list of Python functions via the `tools` parameter. Each tool function must include type annotations and a docstring. The agent automatically converts these functions into an OpenAI-compatible function calling schema.
| Requirement | Description |
| -------------------- | -------------------------------------------------------------- |
| Function | The tool must be a Python function. |
| With types | The function must have type annotations for its parameters. |
| With doc strings | The function must include a docstring describing its behavior. |
| Must return a string | The function must return a string value. |
```python theme={null}
from swarms import Agent
import subprocess
def terminal(code: str):
"""
Run code in the terminal.
Args:
code (str): The code to run in the terminal.
Returns:
str: The output of the code.
"""
out = subprocess.run(code, shell=True, capture_output=True, text=True).stdout
return str(out)
agent = Agent(
agent_name="Terminal-Agent",
model_name="claude-sonnet-4-6",
tools=[terminal],
system_prompt="You are an agent that can execute terminal commands.",
)
response = agent.run("List the contents of the current directory")
print(response)
```
You can also provide tool schemas in OpenAI function-calling dictionary format via `tools_list_dictionary`:
```python theme={null}
from swarms import Agent
from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT
from swarms.utils.str_to_dict import str_to_dict
tools = [
{
"type": "function",
"function": {
"name": "get_stock_price",
"description": "Retrieve the current stock price for a specified company.",
"parameters": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "The stock ticker symbol, e.g. AAPL for Apple Inc.",
},
"include_history": {
"type": "boolean",
"description": "Whether to include historical price data.",
},
"time": {
"type": "string",
"format": "date-time",
"description": "Time for which stock data is requested, in ISO 8601 format.",
},
},
"required": ["ticker", "include_history", "time"],
},
},
}
]
agent = Agent(
agent_name="Financial-Analysis-Agent",
agent_description="Personal finance advisor agent",
system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
max_loops=1,
tools_list_dictionary=tools,
)
out = agent.run("What is the current stock price for Apple Inc. (AAPL)?")
print(out)
print(str_to_dict(out))
```
### Dynamic Tool Loading
`dynamic_tools=True` is the default, and it changes how tools reach the model.
Tool definitions are re-sent on every request, so a large tool set is paid for on every turn. When `dynamic_tools` is on **and** the agent has something to defer — that is, when `tools` are given, an MCP server is configured, or `max_loops="auto"` — the agent:
1. Appends a notice to the system prompt telling the model that most of its tools are **not** currently loaded.
2. Sends only a `tool_search` tool (plus anything marked always-loaded, such as the autonomous loop's control-flow tools) instead of the full schema list.
3. Loads the schemas the model asks for through `tool_search`. **They become callable on the next turn, not the one that searched.**
An agent with no tools, no MCP server, and a fixed `max_loops` has nothing to defer, so nothing changes.
```python theme={null}
from swarms import Agent
# Default: schemas are deferred behind tool_search
agent = Agent(
agent_name="Toolsmith",
model_name="gpt-5.4",
tools=[search_web, read_file, write_file],
)
# Opt out: send every schema on every request
eager_agent = Agent(
agent_name="Eager-Toolsmith",
model_name="gpt-5.4",
tools=[search_web, read_file, write_file],
dynamic_tools=False,
)
```
Deferral is a separate mechanism from `selected_tools`. `selected_tools` decides which autonomous-loop tools exist at all; `dynamic_tools` decides which of the existing schemas are sent up front.
See the [Dynamic Tools guide](/agents/dynamic-tools) and the [DynamicToolLoader reference](/api/dynamic-tool-loader) for the search behaviour, pre-warming, and the always-loaded set.
### External Knowledge and Retrieval
Swarms bundles no vector database, and `Agent` performs no retrieval of its own. To give an agent access to an external knowledge base, expose the lookup as a **tool** — the agent then decides when to query it and the result enters the conversation like any other tool output.
```python theme={null}
from swarms import Agent
def search_knowledge_base(query: str) -> str:
"""Search the company knowledge base for passages matching a query.
Args:
query: What to search for.
Returns:
The matching passages, as text.
"""
# Call whatever store you already run - Chroma, Qdrant, Pinecone, Postgres.
hits = my_vector_store.query(query, top_k=3)
return "\n\n".join(h.text for h in hits)
agent = Agent(
agent_name="Financial-Analysis-Agent",
model_name="claude-sonnet-4-6",
system_prompt="You answer using the company knowledge base.",
tools=[search_knowledge_base],
max_loops=3,
)
response = agent.run("What are the components of a startup's stock incentive equity plan?")
print(response)
```
`long_term_memory` is a constructor parameter, but the agent never queries it. The only method invoked on it is `.save(path)`, and only when agent state is written to disk. Passing a vector store here does **not** give the agent retrieval — use a tool, as above.
### Memory Persistence and Context Compression
The agent ships with two complementary memory controls that work together to manage what is remembered between runs and how the context window is managed during long sessions.
#### Persistent Memory
With `persistent_memory=True` the agent reads and writes a `MEMORY.md` file under `$WORKSPACE_DIR/agents/{agent_name}/MEMORY.md`. Every message is appended to this file, and on the next run the file is loaded back so the agent remembers prior interactions.
The default is `persistent_memory=False` — no on-disk state at all, so the agent starts from a blank slate every run. Opt in explicitly for agents that should remember across runs, and use the same `agent_name` each time, since the memory file is keyed on it.
```python theme={null}
from swarms import Agent
# Opt in: memory survives process restarts
agent = Agent(
agent_name="Persistent-Agent",
model_name="gpt-5.4",
system_prompt="You are a helpful assistant.",
persistent_memory=True,
)
agent.run("My name is Alice and I work in finance.")
# On the next run — same agent_name, persistent_memory=True again —
# the agent will still know the user's name and role.
# Default: stateless, no cross-session memory
stateless_agent = Agent(
agent_name="Stateless-Agent",
model_name="gpt-5.4",
system_prompt="You are a helpful assistant.",
# persistent_memory=False is the default
)
stateless_agent.run("Summarise the latest news.")
```
#### Context Compression
For long-running agents the conversation history can grow until it fills the context window. `context_compression=True` (the default) attaches a `ContextCompressor` that automatically summarises and collapses `MEMORY.md` whenever token usage crosses 90% of `context_length`.
```python theme={null}
from swarms import Agent
# Default: automatic summarisation when the window gets full
agent = Agent(
agent_name="Long-Session-Agent",
model_name="gpt-5.4",
system_prompt="You are a research assistant.",
max_loops=10,
context_length=8192,
# context_compression=True is the default
)
agent.run("Deep-dive analysis of transformer architecture papers.")
# If token usage passes ~7,372 tokens (90% of 8192) the compressor
# summarises MEMORY.md in place and continues without interruption.
# Disabled: keep every raw message intact
audit_agent = Agent(
agent_name="Audit-Agent",
model_name="gpt-5.4",
system_prompt="You are a compliance auditor.",
context_compression=False,
)
```
#### Combining Both Controls
```python theme={null}
from swarms import Agent
# Persistent across runs + automatic context management (production default)
production_agent = Agent(
agent_name="Production-Agent",
model_name="gpt-5.4",
system_prompt="You are a customer support assistant.",
persistent_memory=True,
context_compression=True,
context_length=16000,
)
# Stateless + no compression (CI / unit-test friendly)
test_agent = Agent(
agent_name="Test-Agent",
model_name="gpt-5.4",
system_prompt="You are a helpful assistant.",
persistent_memory=False,
context_compression=False,
print_on=False,
)
```
### Agent Handoffs and Task Delegation
The `Agent` class supports intelligent task delegation through the `handoffs` parameter. When provided with a list of specialized agents, the main agent acts as a router that analyzes incoming tasks and delegates them to the most appropriate specialized agent.
**How Handoffs Work:**
1. **Task Analysis**: When a task is received, the main agent uses a built-in "boss agent" to analyze the task requirements
2. **Agent Selection**: The boss agent evaluates all available specialized agents and selects the most suitable one(s)
3. **Task Delegation**: The selected agent(s) receive the task and process it
4. **Response Aggregation**: Results from specialized agents are collected and returned
| Feature | Description |
| -------------------------- | ------------------------------------------------------------------------------- |
| **Intelligent Routing** | Uses AI to determine the best agent for each task |
| **Multiple Agent Support** | Can delegate to multiple agents for complex tasks requiring different expertise |
| **Task Modification** | Can modify tasks to better suit the selected agent's capabilities |
| **Transparent Reasoning** | Provides clear explanations for agent selection decisions |
| **Seamless Integration** | Works transparently with the existing `run()` method |
```python theme={null}
from swarms.structs.agent import Agent
research_agent = Agent(
agent_name="ResearchAgent",
agent_description="Specializes in researching topics and providing detailed, factual information",
model_name="gpt-5.4",
max_loops=1,
system_prompt="You are a research specialist.",
)
code_agent = Agent(
agent_name="CodeExpertAgent",
agent_description="Expert in writing, reviewing, and explaining code",
model_name="gpt-5.4",
max_loops=1,
system_prompt="You are a coding expert.",
)
writing_agent = Agent(
agent_name="WritingAgent",
agent_description="Skilled in creative and technical writing",
model_name="gpt-5.4",
max_loops=1,
system_prompt="You are a writing specialist.",
)
coordinator = Agent(
agent_name="CoordinatorAgent",
agent_description="Coordinates tasks and delegates to specialized agents",
model_name="gpt-5.4",
max_loops=1,
handoffs=[research_agent, code_agent, writing_agent],
system_prompt="You are a coordinator agent. Analyze tasks and delegate them to the most appropriate specialized agent.",
output_type="all",
)
result = coordinator.run(task="Call all the agents and ask them how they are doing")
print(result)
```
### Autonomous Mode
When `max_loops="auto"` is set, the agent enables automatic planning and execution. The agent creates a structured plan with subtasks, executes them sequentially with dependency management, and generates a comprehensive summary.
#### Available Tools in Autonomous Mode
When `max_loops="auto"` and `interactive=False`, the agent has access to specialized tools:
| Tool | Description | Parameters |
| --------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_plan` | Break the task into subtasks with dependencies | `task_description` (str), `steps` (list of dicts) |
| `think` *(only when `think_tool=True`)* | Pause and reason about the current state before acting | `current_state` (str), `analysis` (str), `next_actions` (list), `confidence` (float) |
| `subtask_done` | Mark the current subtask complete and advance to the next | `task_id` (str), `summary` (str), `success` (bool) |
| `complete_task` | Mark the whole task complete and produce a final summary | `task_id` (str), `summary` (str), `success` (bool), `results` (str, optional), `lessons_learned` (str, optional) |
| `respond_to_user` | Send messages to the user | `message` (str), `message_type` (str) |
| `create_file` | Create a new file | `file_path` (str), `content` (str) |
| `update_file` | Update an existing file | `file_path` (str), `content` (str), `mode` (str) |
| `read_file` | Read file contents | `file_path` (str) |
| `list_directory` | List files and directories | `directory_path` (str) |
| `delete_file` | Delete a file (with safety checks) | `file_path` (str) |
| `run_bash` | Execute a bash command | `command` (str), `timeout_seconds` (int) |
| `grep` | Search files for a pattern, returning matching lines. Preferred over `run_bash` for searches | `pattern` (str), `path` (str), `recursive` (bool), `case_insensitive` (bool), `include_line_numbers` (bool), `file_pattern` (str), `context_lines` (int) |
| `create_sub_agent` | Create specialized sub-agents | `agents` (array of agent specs) |
| `assign_task` | Assign tasks to sub-agents | `assignments` (array), `wait_for_completion` (bool) |
| `check_sub_agent_status` | Inspect the async task status of a sub-agent via the sub-agent registry | `agent_name` (str) |
| `cancel_sub_agent_tasks` | Cancel a sub-agent's pending or running async tasks | `agent_name` (str) |
`selected_tools` filters this entire list, including the control-flow tools. Passing a list that omits `create_plan` or `complete_task` leaves the agent unable to plan or to declare itself finished — include them explicitly, or leave `selected_tools="all"`.
`think` is opt-in. It is stripped from the tool list unless the agent is constructed with `think_tool=True`, and the system prompt is adjusted to match so the model is never told to call a tool it lacks.
All file operations use the agent's workspace directory (`$WORKSPACE_DIR/agents/{agent-name}-{id12}/`, reachable as `agent.workspace.dir`).
```python theme={null}
from swarms.structs.agent import Agent
agent = Agent(
agent_name="Quantitative-Trading-Agent",
agent_description="Advanced quantitative trading and algorithmic analysis agent",
model_name="gpt-5.4",
dynamic_temperature_enabled=True,
max_loops="auto",
dynamic_context_window=True,
output_type="all",
)
out = agent.run(
"Generate a comprehensive report on the top 5 publicly traded energy stocks. "
"For each stock include company name, ticker, key financial metrics, and analysis. "
"Only create 3 subtasks in your plan."
)
print(out)
```
#### Sub-Agent Delegation
The autonomous agent can create and manage sub-agents for parallel task execution:
```python theme={null}
from swarms.structs.agent import Agent
coordinator = Agent(
agent_name="Research-Coordinator",
agent_description="Coordinates complex research by delegating to specialized sub-agents",
model_name="gpt-5.4",
max_loops="auto",
selected_tools="all",
)
task = """
Conduct comprehensive research on three emerging technology trends:
1. Artificial Intelligence in Healthcare
2. Quantum Computing Advances
3. Renewable Energy Innovations
For each topic, create a specialized sub-agent and assign research tasks.
"""
result = coordinator.run(task)
print(result)
```
| Benefit | Description |
| ----------------------- | ----------------------------------------------------------- |
| **Parallel Processing** | Multiple tasks execute simultaneously for faster completion |
| **Specialization** | Each sub-agent can focus on a specific domain or capability |
| **Scalability** | Complex tasks can be broken into manageable pieces |
| **Reusability** | Sub-agents are cached and can handle multiple assignments |
| **Fault Tolerance** | One sub-agent failure doesn't stop others from completing |
### Batch Processing
Run a list of tasks one after another with `run_batched`. It is sequential, not concurrent — reach for `run_concurrent_tasks` when the tasks are independent and you want them in parallel:
```python theme={null}
tasks = [
"Analyze the financial data for Q1",
"Generate a summary report for stakeholders",
"Create recommendations for Q2 planning"
]
batch_results = agent.run_batched(tasks)
# Batch processing with images
tasks = ["Analyze this chart", "Identify patterns", "Summarize insights"]
images = ["chart1.png", "chart2.png", "chart3.png"]
batch_results = agent.run_batched(tasks, imgs=images)
```
## Examples
### Basic Usage
```python theme={null}
from swarms import Agent
agent = Agent(
agent_name="Financial-Analyst",
model_name="claude-sonnet-4-6",
max_loops=1,
system_prompt="You are a financial analyst. Provide detailed, data-driven insights."
)
response = agent.run("Analyze the Q4 2024 revenue trends")
print(response)
```
### Minimal Configuration
```python theme={null}
from swarms import Agent
agent = Agent(
model_name="gpt-5.4",
max_loops=1,
)
response = agent.run("What is the capital of France?")
print(response)
```
### Agent with Tools
```python theme={null}
from swarms import Agent
def search_web(query: str) -> str:
"""Search the web for information."""
return f"Search results for: {query}"
def calculate(expression: str) -> float:
"""Evaluate a mathematical expression."""
return eval(expression)
agent = Agent(
agent_name="Research-Agent",
model_name="claude-sonnet-4-6",
max_loops=5,
tools=[search_web, calculate],
system_prompt="You are a research assistant with web search and calculation abilities."
)
result = agent.run("Search for the population of Tokyo and calculate its growth rate")
```
### Multi-modal Agent
```python theme={null}
agent = Agent(
agent_name="Vision-Agent",
model_name="claude-sonnet-4-6",
multi_modal=True,
max_loops=1
)
response = agent.run(
task="Describe what you see in this image and identify any objects",
img="path/to/image.jpg"
)
```
### Multi-Image Processing
```python theme={null}
image_agent = Agent(
agent_name="Image-Analysis-Agent",
system_prompt="You are an expert at analyzing images.",
multi_modal=True,
)
images = ["product1.jpg", "product2.jpg", "product3.jpg"]
analysis = image_agent.run(
task="Analyze these product images and identify design patterns",
imgs=images
)
```
### Autonomous Agent with Auto Loops
```python theme={null}
agent = Agent(
agent_name="Autonomous-Developer",
model_name="claude-sonnet-4-6",
max_loops="auto",
system_prompt="You are an autonomous software developer."
)
result = agent.run("Build a REST API for a todo application with authentication")
# Agent will:
# 1. Create a plan with subtasks
# 2. Execute each subtask using available tools
# 3. Generate a comprehensive summary
```
### Multiple Loops
```python theme={null}
from swarms import Agent
agent = Agent(
agent_name="Iterative-Reasoning-Agent",
model_name="gpt-5.4",
max_loops=3,
reasoning_prompt_on=True,
system_prompt="You are an agent that reasons through problems step by step.",
)
response = agent.run("Solve this complex problem step by step: [problem description]")
```
### Dynamic Loops
```python theme={null}
from swarms import Agent
agent = Agent(
agent_name="Dynamic-Agent",
model_name="gpt-5.4",
dynamic_loops=True,
system_prompt="You are an adaptive agent that adjusts reasoning depth based on task complexity.",
)
response = agent.run("Analyze this complex scenario and provide insights")
```
### Agent with Streaming
```python theme={null}
def on_token(token: str):
print(token, end="", flush=True)
agent = Agent(
agent_name="Streaming-Agent",
model_name="claude-sonnet-4-6",
stream=True,
streaming_callback=on_token,
max_loops=1
)
response = agent.run("Write a creative story about space exploration")
```
### Token-by-Token Streaming
```python theme={null}
from swarms import Agent
agent = Agent(
model_name="gpt-5.4",
max_loops=1,
stream=True,
)
# Each token shows metadata including token count, model info, citations, and usage
agent.run("Tell me a short story about a robot learning to paint.")
```
### Agent with Fallback Models
```python theme={null}
agent = Agent(
agent_name="Reliable-Agent",
fallback_models=["claude-sonnet-4-6", "gpt-5.4", "gpt-5.4-mini"],
max_loops=1
)
response = agent.run("Generate a market analysis report")
```
### Agent with MCP Integration
```python theme={null}
agent = Agent(
agent_name="MCP-Agent",
model_name="claude-sonnet-4-6",
mcp_url="npx -y @modelcontextprotocol/server-filesystem /path/to/directory",
max_loops=3
)
result = agent.run("Read the contents of config.json and summarize the settings")
```
### Multiple MCP Connections
```python theme={null}
from swarms import Agent
agent = Agent(
model_name="gpt-5.4",
mcp_urls=[
"http://localhost:8000",
"http://localhost:8001",
],
max_loops=1,
)
response = agent.run("Use tools from both MCP servers")
```
### MCP with Connection Config
```python theme={null}
from swarms import Agent
from swarms.schemas.mcp_schemas import MCPConnection
mcp_config = MCPConnection(
url="http://localhost:8000",
name="my_mcp_server",
)
mcp_agent = Agent(
agent_name="MCP-Enabled-Agent",
system_prompt="You are an agent with access to external tools via MCP.",
mcp_config=mcp_config,
mcp_urls=["http://localhost:8000", "http://localhost:8001"],
tool_call_summary=True
)
response = mcp_agent.run("Use the available tools to analyze system status")
```
### Agent Handoffs
```python theme={null}
researcher = Agent(
agent_name="Researcher",
model_name="claude-sonnet-4-6",
system_prompt="You are a research specialist."
)
writer = Agent(
agent_name="Writer",
model_name="claude-sonnet-4-6",
system_prompt="You are a technical writer."
)
coordinator = Agent(
agent_name="Coordinator",
model_name="claude-sonnet-4-6",
max_loops=5,
handoffs=[researcher, writer],
system_prompt="You coordinate tasks between research and writing teams."
)
result = coordinator.run("Create a comprehensive report on quantum computing")
```
### Interactive Mode
```python theme={null}
from swarms import Agent
agent = Agent(
agent_name="Interactive-Agent",
model_name="claude-sonnet-4-6",
interactive=True,
system_prompt="You are an interactive agent. Engage in a conversation with the user.",
)
agent.run("Let's start a conversation")
```
### Auto Generate Prompt
```python theme={null}
from swarms import Agent
agent = Agent(
agent_name="Financial-Analysis-Agent",
system_prompt=None,
model_name="gpt-5.4",
max_loops=1,
auto_generate_prompt=True,
)
agent.run("How can I establish a ROTH IRA to buy stocks and get a tax break?")
print(agent.system_prompt)
```
### Reasoning-Enabled Models
```python theme={null}
from swarms import Agent
agent = Agent(
model_name="o1-preview",
reasoning_enabled=True,
reasoning_effort="high",
thinking_tokens=10000,
max_loops=1
)
response = agent.run("Solve this complex mathematical problem step by step")
```
### Execution Modes
```python theme={null}
from swarms import Agent
# Fast mode - optimized for performance
fast_agent = Agent(
model_name="gpt-5.4",
mode="fast",
max_loops=1
)
# Interactive mode - for real-time conversations
interactive_agent = Agent(
model_name="gpt-5.4",
mode="interactive",
max_loops=5
)
# Standard mode - default behavior
standard_agent = Agent(
model_name="gpt-5.4",
mode="standard",
max_loops=1
)
```
### Marketplace Prompt Loading
```python theme={null}
from swarms import Agent
agent = Agent(
model_name="claude-sonnet-4-6",
marketplace_prompt_id="550e8400-e29b-41d4-a716-446655440000",
max_loops=1
)
response = agent.run("Execute the marketplace prompt task")
```
### Publishing to Marketplace
```python theme={null}
from swarms import Agent
agent = Agent(
model_name="gpt-5.4",
agent_name="Financial-Advisor",
agent_description="Expert financial advisor agent",
system_prompt="You are an expert financial advisor...",
tags=["finance", "advisor"],
capabilities=["financial_planning", "investment_advice"],
use_cases=[
{"title": "Retirement Planning", "description": "Help users plan for retirement"},
{"title": "Investment Analysis", "description": "Analyze investment opportunities"}
],
publish_to_marketplace=True,
max_loops=1
)
```
### Message Transforms for Context Management
```python theme={null}
from swarms import Agent
from swarms.structs.transforms import TransformConfig
transforms = TransformConfig(
max_tokens=8000,
strategy="truncate_oldest"
)
agent = Agent(
model_name="gpt-5.4",
transforms=transforms,
context_length=100000,
max_loops=1
)
response = agent.run("Process this very long conversation history")
```
### Agent with Capabilities
```python theme={null}
from swarms import Agent
agent = Agent(
model_name="gpt-5.4",
agent_name="Data-Analysis-Agent",
capabilities=["data_analysis", "statistics", "visualization"],
max_loops=1
)
response = agent.run("Analyze this dataset")
```
### Saving and Loading State
```python theme={null}
# Save the agent state
agent.save('saved_flow.json')
# Load the agent state
agent = Agent(model_name="gpt-5.4", max_loops=5)
agent.load('saved_flow.json')
agent.run("Continue with the task")
```
### Autosave
When `autosave=True`, the agent saves its configuration at each loop step to `{workspace}/agents/{agent-name}-{id12}/config.json` via its `WorkspaceManager`. Files are written atomically to prevent corruption.
```python theme={null}
from swarms import Agent
agent = Agent(
model_name="gpt-5.4",
agent_name="autosave-demo",
max_loops=5,
autosave=True,
verbose=True,
)
response = agent.run("Complete a complex multi-step task")
workspace = agent.workspace.dir
print(f"Files saved to: {workspace}")
```
The workspace root comes from the `WORKSPACE_DIR` environment variable. Autosave goes through `WorkspaceManager`, which falls back to `{cwd}/agent_workspace` (and sets `WORKSPACE_DIR` to it) when the variable is unset. Other readers are stricter: `agent.workspace_dir`, resolved during construction, is `None` when the variable was unset at that moment. Set `WORKSPACE_DIR` explicitly rather than relying on the fallback.
### Async and Concurrent Execution
```python theme={null}
# Run several tasks concurrently on a call-scoped thread pool
results = agent.run_concurrent_tasks(["Task A", "Task B"])
# Run multiple tasks concurrently
tasks = [
{"task": "Task 1"},
{"task": "Task 2", "img": "path/to/image.jpg"},
{"task": "Task 3"}
]
responses = agent.bulk_run(tasks)
# Run multiple tasks in batch mode
task_list = ["Analyze data", "Generate report", "Create summary"]
batch_responses = agent.run_batched(task_list)
```
### Comprehensive Agent Configuration
```python theme={null}
from swarms import Agent
agent = Agent(
agent_name="Advanced-Analysis-Agent",
agent_description="Multi-modal analysis agent with advanced capabilities",
system_prompt="You are an advanced analysis agent.",
max_loops=3,
dynamic_loops=True,
interactive=False,
dashboard=True,
context_length=100000,
dynamic_context_window=True,
auto_generate_prompt=True,
plan_enabled=True,
react_on=True,
safety_prompt_on=True,
reasoning_prompt_on=True,
tool_retry_attempts=5,
tool_call_summary=True,
show_tool_execution_output=True,
output_type="json",
model_name="gpt-5.4",
temperature=0.3,
max_tokens=8000,
top_p=0.95,
retry_attempts=3,
tags=["analysis", "multi-modal", "advanced"],
use_cases=[{"name": "Data Analysis", "description": "Process and analyze complex datasets"}],
verbose=True,
print_on=True
)
def streaming_callback(token: str):
print(token, end="", flush=True)
response = agent.run(
task="Analyze these financial charts",
imgs=["chart1.png", "chart2.png", "chart3.png"],
streaming_callback=streaming_callback
)
```
### Various Settings
```python theme={null}
print(agent.to_dict())
print(agent.to_toml())
print(agent.model_dump_json())
print(agent.model_dump_yaml())
agent.receive_message(agent_name="OtherAgent", task="message")
agent.send_agent_message(agent_name="agent_name", message="message")
agent.add_memory("Add a memory to the agent")
agent.check_available_tokens()
agent.print_dashboard()
```
## Output Types
The agent supports multiple output formats via the `output_type` parameter:
| Value | Returns |
| ---------------------------- | ----------------------------------------------------------------------------------------------- |
| `"str"`, `"string"`, `"all"` | The whole conversation as a string |
| `"str-all-except-first"` | The conversation as a string, minus the first message (default) |
| `"list"` | The conversation as a list of message dicts |
| `"list-final"` | The final message, wrapped in a list |
| `"dict"`, `"dictionary"` | The conversation as a dictionary |
| `"dict-all-except-first"` | The conversation as a dictionary, minus the first message |
| `"dict-final"` | The final message as a dictionary |
| `"final"`, `"last"` | The content of the final message |
| `"json"` | The conversation as a JSON string |
| `"yaml"` | The conversation as a YAML string |
| `"xml"` | The conversation as an XML string |
| `"basemodel"` | Accepted by the type but **not** implemented by the formatter — raises `ValueError` at runtime. |
The accepted values are the `HistoryOutputType` literal in `swarms.utils.output_types`; anything outside it raises `ValueError`.
## Error Handling
The Agent class includes comprehensive error handling:
* **AgentError**: Base class for every exception below
* **AgentInitializationError**: Raised when agent fails to initialize
* **AgentRunError**: Raised when execution fails
* **AgentLLMError**: Raised when LLM encounters issues
* **AgentLLMInitializationError**: Raised when the LLM fails to initialize
* **AgentToolExecutionError**: Raised when the agent fails to execute a tool
These live in `swarms.schemas.agent_errors` so collaborator classes can raise and catch them without importing `Agent`:
```python theme={null}
from swarms.schemas import AgentError, AgentRunError # canonical home
try:
agent.run(task)
except AgentError as e: # catches every agent exception
...
```
Only the subclasses are re-exported from `swarms.structs.agent`
(`AgentInitializationError`, `AgentLLMError`, `AgentRunError`,
`AgentToolExecutionError`). The base `AgentError` is not, so
`from swarms.structs.agent import AgentError` raises `ImportError`. Import the
base class from `swarms.schemas`.
MCP-specific failures use a separate hierarchy in `swarms.schemas.agent_mcp_errors`: `AgentMCPError`, `AgentMCPConnectionError`, `AgentMCPToolError`.
## Telemetry
`Agent.run` is instrumented with OpenTelemetry, **on by default**. Each run emits an `Agent.run` span carrying the task, the output, status, and the agent's identity — nested under the swarm run that invoked it, if any. Construction emits an `Agent.init` span carrying the full constructor configuration.
Opt out with `SWARMS_TELEMETRY_ON=false`, which reduces the cost to \~0.14 µs per call. See the [Telemetry guide](/deployment/telemetry) for what is captured and how to turn it off.
## New Features and Parameters
### Enhanced Run Method Parameters
* **`imgs`**: Process multiple images simultaneously instead of just one
* **`correct_answer`**: Validate responses against expected answers with automatic retries
* **`streaming_callback`**: Real-time token streaming for interactive applications
### MCP (Model Context Protocol) Integration
| Parameter | Description |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `mcp_url` | A single MCP server: URL string, `MCPConnection`, or dict |
| `mcp_urls` | Several MCP servers, each a URL string, `MCPConnection`, or dict |
| `mcp_config` | A single MCP server as a connection object (or dict) |
| `mcp_configs` | Several MCP servers as connection objects (or dicts) |
| `mcp_api_key` | API key applied to every server without its own; supports `env:`/`${...}` indirection |
| `mcp_authorization_token` | Bearer token applied to every server without its own |
| `mcp_oauth` | OAuth 2.1 settings (`MCPOAuthConfig` or dict) applied to every server without its own |
| `mcp_headers` | Extra headers merged into every MCP request |
| `mcp_transport` | Force `streamable_http`, `sse`, `stdio`, or `auto` for every server |
| `mcp_timeout` | Request timeout in seconds for every server |
### Advanced Reasoning and Safety
| Parameter | Description |
| --------------------- | ----------------------------------------------------------------- |
| `react_on` | Enable ReAct reasoning for complex problem-solving |
| `safety_prompt_on` | Add safety constraints to agent responses |
| `reasoning_prompt_on` | Enable multi-loop reasoning for complex tasks |
| `reasoning_enabled` | Enable reasoning capabilities for supported models (e.g., o1) |
| `reasoning_effort` | Reasoning effort level; unset by default, omit when using `tools` |
| `thinking_tokens` | Maximum number of thinking tokens for reasoning models |
### Performance and Resource Management
| Parameter | Description |
| ------------------------ | ------------------------------------------------------------- |
| `dynamic_context_window` | Automatically adjust context window based on available tokens |
| `tool_retry_attempts` | Configure retry behavior for tool execution |
### Advanced Memory and Context
| Parameter | Description |
| ---------------------- | ------------------------------------------------------------------------ |
| `auto_generate_prompt` | Automatically generate system prompts based on tasks |
| `plan_enabled` | Enable planning functionality for complex tasks |
| `context_compression` | Auto-summarize MEMORY.md once token usage crosses 90% of context\_length |
| `persistent_memory` | Off by default; set `True` to read/write MEMORY.md across sessions |
### Enhanced Tool Management
| Parameter | Description |
| ---------------------------- | -------------------------------------------- |
| `tools_list_dictionary` | Provide tool schemas in dictionary format |
| `tool_call_summary` | Enable automatic summarization of tool calls |
| `show_tool_execution_output` | Control visibility of tool execution details |
### Advanced LLM Configuration
| Parameter | Description |
| -------------- | ------------------------------------ |
| `llm_args` | Pass additional arguments to the LLM |
| `llm_base_url` | Specify custom LLM API endpoint |
| `llm_api_key` | Provide LLM API key directly |
| `top_p` | Control top-p sampling parameter |
### Execution Modes and Marketplace
| Parameter | Description |
| ------------------------ | -------------------------------------------------------- |
| `mode` | Execution mode: "interactive", "fast", or "standard" |
| `capabilities` | List of agent capabilities for documentation and routing |
| `publish_to_marketplace` | Publish agent prompt to Swarms marketplace |
| `marketplace_prompt_id` | Load prompt from Swarms marketplace by UUID |
## Best Practices
| Best Practice | Description |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `system_prompt` | Always provide a clear and concise system prompt to guide the agent's behavior. |
| `tools` | Use tools to extend the agent's capabilities for specific tasks. |
| `retry_attempts` & error handling | Implement error handling and utilize the retry\_attempts feature for robust execution. |
| `interactive` & `dashboard` | Use interactive mode for real-time conversations and dashboard for monitoring. |
| `autosave`, `save`/`load` | Utilize autosave and save/load methods for continuity across sessions. |
| `dynamic_context_window` & `check_available_tokens()` | Optimize token usage with the dynamic\_context\_window parameter and the check\_available\_tokens() method. |
| `concurrent` & `async` methods | Use concurrent and async methods for performance-critical applications. |
| `run_batched` | Leverage run\_batched to process a list of related tasks in order; use run\_concurrent\_tasks for parallelism. |
| `mcp_url` or `mcp_urls` | Use mcp\_url or mcp\_urls to extend agent capabilities with external tools. |
| `react_on` | Enable react\_on for complex reasoning tasks requiring step-by-step analysis. |
| `tool_retry_attempts` | Configure tool\_retry\_attempts for robust tool execution in production environments. |
| `handoffs` | Use handoffs to create specialized agent teams that can intelligently route tasks. |
| Set appropriate `max_loops` | Use 1 for simple tasks, higher numbers for complex reasoning, or "auto" for autonomous planning. |
| Enable `verbose` during development | Helps debug issues during development and testing. |
| Set `context_length` appropriately | Prevents token limit errors in production. |
## Related
**Agent subsystems**
* [LLMManager](/api/llm-manager) - Model selection, invocation, and fallback rotation
* [MCPManager](/api/mcp-manager) - MCP servers, tool discovery, and tool-call routing
* [SkillsManager](/api/skills-manager) - Agent Skills loading and prompt rendering
* [AgentMarketplaceHandler](/api/agent-marketplace-handler) - Marketplace fetch and publish
**Everything else**
* [Tools](/concepts/tools) - Creating and using agent tools
* [Memory](/agents/agent-memory) - Long-term memory systems
* [Telemetry](/deployment/telemetry) - Tracing agent and swarm runs