Agent Configuration

The Agent class provides extensive configuration options to customize behavior, performance, and capabilities.

Core Parameters

Model Configuration

str

default:"gpt-5.4"

The name of the language model to use. Supports any model from OpenAI, Anthropic, Groq, Cohere, and more via LiteLLM.

agent = Agent(model_name="claude-sonnet-4-6")
agent = Agent(model_name="claude-sonnet-4-5")
agent = Agent(model_name="groq/llama-3.1-70b")

Any

default:"None"

Pre-configured LLM instance. If not provided, will be created automatically based on model_name.

from swarms.utils.litellm_wrapper import LiteLLM

llm = LiteLLM(model_name="claude-sonnet-4-6", temperature=0.5)
agent = Agent(llm=llm)

float

default:"0.5"

Controls randomness in model outputs (0.0 = deterministic, 1.0 = creative).

# Deterministic for code generation
agent = Agent(model_name="claude-sonnet-4-6", temperature=0.1)

# Creative for writing
agent = Agent(model_name="claude-sonnet-4-6", temperature=0.9)

int

default:"4096"

Maximum number of tokens to generate in a single response.

agent = Agent(model_name="claude-sonnet-4-6", max_tokens=8192)

int

default:"Based on model"

Maximum context window size. Automatically set based on the model.

agent = Agent(model_name="claude-sonnet-4-6", context_length=128000)

bool

default:"False"

Enable provider-side prompt caching. When True, the stable prefix of each request (system prompt, tools, and last message) is cached and re-billed at a large discount. Applies to the Anthropic model family (Claude on Anthropic / Bedrock / Vertex); OpenAI and other auto-caching providers are left untouched. See the full Prompt Caching guide.

agent = Agent(model_name="claude-opus-4-8", prompt_caching=True, temperature=None)

dict

default:"None"

Fine-grained prompt-caching options; only consulted when prompt_caching=True. Keys (all optional): ttl ("5m" | "1h"), cache_system_prompt (bool), cache_messages (bool), cache_tools (bool), override (bool | None — force injection on/off), and OpenAI-only prompt_cache_key / prompt_cache_retention ("in_memory" | "24h").

agent = Agent(
    model_name="claude-opus-4-8",
    prompt_caching=True,
    cache_config={"ttl": "1h", "cache_tools": True},
    temperature=None,
)

Agent Identity

str

default:"swarm-worker-01"

Unique name for the agent. Used in multi-agent systems and logging.

agent = Agent(
    agent_name="Financial-Analyst",
    model_name="claude-sonnet-4-6"
)

str

default:"Auto-generated"

Description of the agent’s purpose and capabilities.

agent = Agent(
    agent_name="Data-Analyst",
    agent_description="Expert in data analysis, visualization, and statistical modeling",
    model_name="claude-sonnet-4-6"
)

str

default:"Default system prompt"

The system prompt that defines agent behavior and expertise.

SYSTEM_PROMPT = """
You are a senior software engineer specializing in:
- Clean code architecture
- Test-driven development
- Code review best practices

Provide detailed, well-documented code solutions.
"""

agent = Agent(
    system_prompt=SYSTEM_PROMPT,
    model_name="claude-sonnet-4-6"
)

Execution Control

Union[int, str]

default:"1"

Number of execution loops. Set to “auto” for autonomous mode.

# Single execution
agent = Agent(max_loops=1)

# Multi-step reasoning
agent = Agent(max_loops=5)

# Autonomous mode
agent = Agent(max_loops="auto")

int

default:"0"

Delay in seconds between loops.

agent = Agent(max_loops=5, loop_interval=1)  # 1 second delay

int

default:"3"

Number of retry attempts for failed LLM calls.

agent = Agent(retry_attempts=5)

int

default:"1"

Delay in seconds between retry attempts.

agent = Agent(retry_attempts=3, retry_interval=2)

int

default:"None"

Timeout in seconds for agent execution.

agent = Agent(timeout=300)  # 5 minute timeout

Output Configuration

str

default:"str-all-except-first"

Format for agent output. Options: “str”, “list”, “json”, “dict”, “yaml”, “xml”.

# String output
agent = Agent(output_type="str")

# JSON output
agent = Agent(output_type="json")

# Dictionary output
agent = Agent(output_type="dict")

bool

default:"False"

Enable basic streaming with formatted panels.

agent = Agent(streaming_on=True)

bool

default:"False"

Enable detailed token-by-token streaming with metadata.

agent = Agent(stream=True)
response = agent.run("Tell me a story")  # Streams each token

Callable

default:"None"

Callback function to receive streaming tokens in real-time.

def on_token(token: str):
    print(f"Token: {token}", end="", flush=True)

agent = Agent(streaming_callback=on_token)

Streaming Methods

In addition to the streaming flags above, the Agent exposes two streaming methods that yield tokens as a generator. They are real LLM streaming — tokens are forwarded the moment LiteLLM emits them, across every loop of the agent (tool-call turns, synthesis turns, autonomous plan/execute/summary phases).

`agent.run_stream(task) -> Iterator[str]`

Sync generator that yields tokens. The agent runs in a background thread; tokens are pushed onto a queue and yielded to the caller in order.

from swarms import Agent

agent = Agent(
    agent_name="Writer",
    model_name="gpt-4.1-mini",
    max_loops=3,
)

for token in agent.run_stream("Write a short poem about distributed systems."):
    print(token, end="", flush=True)

`agent.arun_stream(task) -> AsyncIterator[str]`

Async generator. Same semantics as run_stream, but 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.

import asyncio
from swarms import Agent

agent = Agent(
    agent_name="Writer",
    model_name="gpt-4.1-mini",
    max_loops=1,
)

async def main():
    async for token in agent.arun_stream("Explain async/await in two sentences."):
        print(token, end="", flush=True)

asyncio.run(main())

Both methods stream tokens through every internal loop, including tool calls, synthesis turns after a tool returns, and the autonomous plan/execute/summary cycle when max_loops="auto".

bool

default:"False"

Enable detailed logging output.

agent = Agent(verbose=True)

bool

default:"True"

Enable printing of agent responses.

agent = Agent(print_on=True)

Memory and History

bool

default:"False"

Return full conversation history instead of just final response.

agent = Agent(return_history=True)
response = agent.run("Hello")  # Returns full conversation

str

default:"Human"

Name to use for user messages in conversation history.

agent = Agent(user_name="John")

bool

default:"True"

Automatically manage context window to prevent overflow.

agent = Agent(dynamic_context_window=True)

Advanced Features

bool

default:"False"

Randomly adjust temperature between loops for varied outputs.

agent = Agent(dynamic_temperature_enabled=True)

bool

default:"True"

Add reasoning prompts to guide multi-step thinking.

agent = Agent(max_loops=5, reasoning_prompt_on=True)

bool

default:"False"

Enable interactive mode for conversational agents.

agent = Agent(interactive=True)

bool

default:"False"

Display agent dashboard on initialization.

agent = Agent(dashboard=True)

State Management

bool

default:"False"

Automatically save agent state after each execution.

agent = Agent(autosave=True)

str

default:"Auto-generated"

Path to save agent state.

agent = Agent(
    autosave=True,
    saved_state_path="./states/my_agent.json"
)

str

default:"None"

Path to load previous agent state from.

agent = Agent(load_state_path="./states/my_agent.json")

Reliability

List[str]

default:"None"

List of fallback models to try if primary model fails.

agent = Agent(
    fallback_models=[
        "claude-sonnet-4-6",
        "gpt-5.4",
        "gpt-3.5-turbo"
    ]
)

Performance

str

default:"standard"

Agent execution mode. Options: “interactive”, “fast”, “standard”.

# Fast mode (no printing, minimal overhead)
agent = Agent(mode="fast")

# Interactive mode
agent = Agent(mode="interactive")

float

default:"0.90"

Nucleus sampling parameter for model generation.

agent = Agent(top_p=0.95)

Example Configurations

Production Agent

production_agent = Agent(
    agent_name="Production-Agent",
    agent_description="Production-ready agent with reliability features",
    model_name="claude-sonnet-4-6",
    fallback_models=["claude-sonnet-4-6", "gpt-5.4"],
    max_loops=1,
    temperature=0.3,
    max_tokens=4096,
    retry_attempts=5,
    retry_interval=2,
    timeout=300,
    autosave=True,
    verbose=True,
    dynamic_context_window=True,
)

Research Agent

research_agent = Agent(
    agent_name="Research-Agent",
    system_prompt="Expert researcher providing detailed analysis",
    model_name="claude-sonnet-4-6",
    max_loops=3,
    temperature=0.5,
    reasoning_prompt_on=True,
    verbose=True,
    return_history=True,
)

Fast Batch Processing Agent

batch_agent = Agent(
    agent_name="Batch-Processor",
    model_name="gpt-5.4",
    max_loops=1,
    mode="fast",  # Disable printing for performance
    temperature=0.2,
    print_on=False,
    verbose=False,
)

Next Steps

Agent Memory

Configure conversation history and memory

Agent Tools

Add tools to extend capabilities

Reference

Location in source: swarms/structs/agent.py:352-454

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

Agent Configuration

Core Parameters

Model Configuration

Agent Identity

Execution Control

Output Configuration

Streaming Methods

`agent.run_stream(task) -> Iterator[str]`

`agent.arun_stream(task) -> AsyncIterator[str]`

Memory and History

Advanced Features

State Management

Reliability

Performance

Example Configurations

Production Agent

Research Agent

Fast Batch Processing Agent

Next Steps

Agent Memory

Agent Tools

Reference

​Core Parameters

​Model Configuration

​Agent Identity

​Execution Control

​Output Configuration

​Streaming Methods

​agent.run_stream(task) -> Iterator[str]

​agent.arun_stream(task) -> AsyncIterator[str]

​Memory and History

​Advanced Features

​State Management

​Reliability

​Performance

​Example Configurations

​Production Agent

​Research Agent

​Fast Batch Processing Agent

​Next Steps

Agent Memory

Agent Tools

​Reference

Core Parameters

Model Configuration

Agent Identity

Execution Control

Output Configuration

Streaming Methods

`agent.run_stream(task) -> Iterator[str]`

`agent.arun_stream(task) -> AsyncIterator[str]`

Memory and History

Advanced Features

State Management

Reliability

Performance

Example Configurations

Production Agent

Research Agent

Fast Batch Processing Agent

Next Steps

Reference