> ## 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 backbone 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. ## 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 ## Initialization Unique identifier for the agent instance The name of the agent, used for identification and logging 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 The language model instance to use. If None, a LiteLLM instance will be created The LiteLLM-compatible model identifier (e.g. `"gpt-4.1"`, `"claude-sonnet-4-6"`, `"groq/llama-3.3-70b-versatile"`). Extra keyword arguments forwarded to the underlying LiteLLM client. 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 Effective context window in tokens. When `context_compression=True`, the agent compresses memory once usage crosses 90% of this limit. 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. Set `False` for stateless tasks. 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. Output format: 'str', 'string', 'list', 'json', 'dict', 'yaml', 'xml' Automatically save agent state during execution Display agent dashboard on initialization Long-term memory backend (e.g. vector database) for RAG. List of fallback models to try in order if the primary model fails. Number of retry attempts for LLM calls Interval in seconds between retry attempts 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 to save agent state 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.). When multiple images are provided, summarise them into a single context entry before invoking the LLM. 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. URL or connection object for a single MCP server. List of MCP server URLs for connecting to multiple servers. Single MCP connection configuration object. 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. 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: `"low"`, `"medium"`, or `"high"`. 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). Optional tokenizer instance used for local token counting. 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, *args, **kwargs ) -> Any ``` The task or prompt for the agent to process Optional image path or data for vision-enabled models Agent output formatted according to output\_type configuration ### **call** Alternative syntax for running the agent (calls `run` internally). ```python theme={null} def __call__( task: str, *args, **kwargs ) -> str ``` ### arun Async version of `run`. ```python theme={null} async def arun( task: Optional[Union[str, Any]] = None, img: Optional[str] = None, *args, **kwargs, ) -> Any ``` ### run\_concurrent Run a single task concurrently using the agent's internal executor. Returns the awaited result. ```python theme={null} async def run_concurrent( task: str, *args, **kwargs, ) -> Any ``` ### 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. ```python theme={null} def load( file_path: str ) -> Agent ``` ### 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 ``` ### 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 ``` ### reset Reset the agent's memory and state. ```python theme={null} def reset() -> None ``` ### print\_dashboard Display the agent's configuration dashboard. ```python theme={null} def print_dashboard() -> None ``` ### update\_system\_prompt / update\_max\_loops / update\_loop\_interval / update\_retry\_attempts / update\_retry\_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 def update_retry_attempts(retry_attempts: int) -> None def update_retry_interval(retry_interval: int) -> None ``` ### plan Run only the planning phase for a task without executing. ```python theme={null} def plan(task: str, *args, **kwargs) -> None ``` ### add\_memory Append a message to the agent's short-term memory. ```python theme={null} def add_memory(message: str) -> None ``` ### enable\_autosave / disable\_autosave / cleanup Control the agent's background autosave loop. ```python theme={null} def enable_autosave(interval: int = 300) -> None def disable_autosave() -> None def cleanup() -> None ``` ### 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. ## Examples ### Basic Usage ```python theme={null} from swarms import Agent # Create a simple 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." ) # Run a task response = agent.run("Analyze the Q4 2024 revenue trends") print(response) ``` ### Agent with Tools ```python theme={null} from swarms import Agent def search_web(query: str) -> str: """Search the web for information.""" # Implementation 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" ) ``` ### Autonomous Agent with Auto Loops ```python theme={null} agent = Agent( agent_name="Autonomous-Developer", model_name="claude-sonnet-4-6", max_loops="auto", # Enables autonomous planning and execution 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 ``` ### 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") ``` ### Agent with Fallback Models ```python theme={null} agent = Agent( agent_name="Reliable-Agent", fallback_models=["claude-sonnet-4-6", "gpt-5.4", "gpt-3.5-turbo"], max_loops=1 ) # Will try gpt-4o first, then gpt-4o-mini, then gpt-3.5-turbo if each fails 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") ``` ### Agent Handoffs ```python theme={null} # Create specialized agents 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." ) # Create coordinator with handoffs 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") # Coordinator can delegate research to researcher and writing to writer ``` ### Marketplace Prompt Loading ```python theme={null} # Load a prompt from Swarms marketplace in one line 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") # Agent automatically loads system prompt from marketplace ``` ## Output Types The agent supports multiple output formats via the `output_type` parameter: * `"str"` or `"string"`: Returns the last response as a string * `"str-all-except-first"`: Returns all responses except system prompt as string (default) * `"list"`: Returns conversation as a list of messages * `"json"`: Returns conversation as JSON string * `"dict"`: Returns conversation as dictionary * `"yaml"`: Returns conversation as YAML string * `"xml"`: Returns conversation as XML string ## Error Handling The Agent class includes comprehensive error handling: * **AgentInitializationError**: Raised when agent fails to initialize * **AgentRunError**: Raised when execution fails * **AgentLLMError**: Raised when LLM encounters issues * **AgentToolError**: Raised when tool execution fails * **AgentMemoryError**: Raised for memory-related issues ## Best Practices 1. **Set appropriate max\_loops**: Use 1 for simple tasks, higher numbers for complex reasoning, or "auto" for autonomous planning 2. **Use tools wisely**: Provide well-documented tools with clear function signatures and docstrings 3. **Enable autosave for long-running tasks**: Prevents data loss on interruption 4. **Configure fallback models**: Ensures reliability in production 5. **Use streaming for real-time feedback**: Better user experience for long-running tasks 6. **Set context\_length appropriately**: Prevents token limit errors 7. **Enable verbose mode during development**: Helps debug issues 8. **Use agent handoffs for complex workflows**: Delegate subtasks to specialized agents ## Related * [BaseSwarm](/api/base-swarm) - Base class for multi-agent systems * [BaseStructure](/api/base-structure) - Foundation for swarm structures * [Tools](/concepts/tools) - Creating and using agent tools * [Memory](/agents/agent-memory) - Long-term memory systems