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:"16000"

Maximum number of tokens to generate in a single response.

The constructor default is actually None. When left unset, self.max_tokens resolves during __init__ to the model’s real max-output-tokens (via _default_max_tokens()), falling back to 16000 only if that lookup fails. Pass max_tokens explicitly to override the resolved value.

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

int

default:"None"

Maximum context window size, used as the denominator for the ContextCompressor threshold check (see Agent Memory).

The value you pass is respected: self.context_length is only replaced by a model-derived default when you leave it as None. (An earlier release did overwrite it unconditionally; that is fixed.)

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. Omitted, it defaults to the literal string "swarm-worker-01" — the same value for every agent that doesn’t set one.

Because MEMORY.md is keyed on agent_name, every agent left at the default name reads and writes the same memory folder. Always give long-running or persistent-memory agents a unique agent_name.

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)

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-5.4-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-5.4-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

To get the full conversation history instead of just the final response, use the output_type parameter (e.g. output_type="list" or output_type="dict") rather than a dedicated history flag — see Structured Outputs.

agent = Agent(output_type="list")
response = agent.run("Hello")  # Returns full conversation as a list of messages

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. save() writes here when called with no argument.

Earlier releases accepted this argument and then overwrote self.saved_state_path during initialization with an auto-generated {api_key}_state.json filename, so a custom path had no effect. It is now honoured; omit it to keep the auto-generated name.

Pass a file path, not a directory. The value is used as a filename, so a trailing slash such as "./agent_states/" resolves to ./agent_states/.json — a hidden file. While the argument was ignored this was harmless; now that it is honoured it is not.

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-5.4-mini"
    ]
)

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:"None"

Nucleus sampling parameter for model generation. When left as None, no top_p value is sent in the request and the provider’s own default applies.

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,
    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,
)

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:309-411 (the Agent.__init__ signature)

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