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="gpt-5.4-mini")
agent = Agent(model_name="groq/llama-3.3-70b-versatile")

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

default:"None"

Controls randomness in model outputs (0.0 = deterministic, 1.0 = creative). When left as None, no temperature is sent and the provider’s own default applies. This keeps models that reject any temperature value working without extra configuration. Set it only when you need it.

Two settings override this value. dynamic_temperature_enabled=True sets a random temperature between 0.0 and 1.0 on each loop. On Anthropic models, reasoning_effort or reasoning_enabled=True forces temperature=1 and drops top_p, because extended thinking requires it.

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

Maximum number of tokens to generate in a single response.

When left unset (or set to 0 or less), max_tokens resolves during __init__ to the model’s own maximum output tokens from LiteLLM’s model registry, falling back to 16000 only if that lookup fails. Pass max_tokens explicitly to override the resolved value. For OpenAI’s o1/o3/o4 and gpt-5/gpt-6 families the value is sent as max_completion_tokens, the key those models accept.

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-sonnet-4-6", prompt_caching=True)

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-sonnet-4-6",
    prompt_caching=True,
    cache_config={"ttl": "1h", "cache_tools": True},
)

Reasoning

str | None

default:"None"

Reasoning effort for reasoning models, forwarded to the provider as reasoning_effort. Accepted values: "none", "minimal", "low", "medium", "high", "xhigh", "ultra", "max". Which values a model accepts is up to the provider. When None, nothing is sent. On Anthropic models, setting it also forces temperature=1, drops top_p and raises max_tokens to at least 16000.

agent = Agent(model_name="o3", reasoning_effort="high")

bool

default:"False"

Turn on extended thinking. When True, each request carries a thinking block with a budget of thinking_tokens. On Anthropic models, temperature is forced to 1, top_p is dropped, and max_tokens is raised above the budget when needed.

int

default:"1024"

Thinking budget sent with each request when reasoning_enabled=True. It has no effect otherwise.

agent = Agent(
    model_name="claude-sonnet-4-6",
    reasoning_enabled=True,
    thinking_tokens=4096,
)

Reasoning tokens a provider reports show up in agent.usage["reasoning_tokens"]. See Token usage.

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"

How run() formats the conversation it returns. Options: "str-all-except-first", "final", "last", "str", "string", "all", "list", "list-final", "dict", "dictionary", "dict-all-except-first", "dict-final", "json", "yaml". The "xml" type was removed. See Structured Outputs for what each one returns.

# Just the last message
agent = Agent(output_type="final")

# The whole conversation as a JSON string
agent = Agent(output_type="json")

# The whole conversation as a list of message dicts
agent = Agent(output_type="list")

bool

default:"False"

Stream each LLM call. With print_on=True tokens render in a live panel; with print_on=False the stream is collected silently. Required for streaming_callback to receive tokens.

agent = Agent(streaming_on=True)

bool

default:"False"

Detailed streaming. Each token is printed with its metadata (model, finish reason, logprobs, citations, usage), and streaming_callback receives a dict per token whose "token" key holds the text.

agent = Agent(stream=True)
response = agent.run("Tell me a story")

Callable

default:"None"

Function that receives each streamed token as a string. It only fires on streamed calls, so pair it with streaming_on=True. On its own it is never called. You can also pass it per call: agent.run(task, streaming_callback=fn).

def on_token(token: str):
    print(token, end="", flush=True)

agent = Agent(streaming_on=True, 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". Streamed calls are counted in agent.usage once the stream has been consumed.

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)

List[dict]

default:"None"

Prior turns in chat format, such as {"role": "user", "content": "..."}. They seed the agent’s conversation at construction and are sent as context on every run. run() takes the same argument per call: those turns are added to the conversation and sent as the context that call continues from.

agent = Agent(
    agent_name="Support-Agent",
    model_name="gpt-5.4",
    messages=[
        {"role": "user", "content": "My order number is 4417."},
        {"role": "assistant", "content": "Thanks, I have order 4417."},
    ],
)
agent.run("What is my order number?")

bool

default:"False"

Read and append to {workspace}/agents/{agent_name}/MEMORY.md so context survives process restarts. Off by default. See Agent Memory.

bool

default:"True"

Summarize the conversation when it crosses 90% of context_length. Applies to integer max_loops and "auto" alike. See Agent Memory.

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)

bool

default:"False"

Hide tool schemas behind a single tool_search tool and load them on demand. Off by default. When True, it applies only if the agent has tools, an MCP server, or max_loops="auto". See Dynamic Tool Loading.

agent = Agent(model_name="gpt-5.4", max_loops="auto", dynamic_tools=True)

str | List[str]

default:"None"

One directory, or a list of directories, of SKILL.md skills. With a list, directories are read in order and a later directory’s skill replaces an earlier one with the same name. See Agent Skills.

agent = Agent(skills_dir=["./team_skills", "./my_skills"])

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"

Models to try in order. When set, the first entry is the primary model and model_name is not used. If a run fails after retry_attempts, the agent switches to the next model and runs the task again.

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". Only "fast" changes behavior: it sets print_on=False and verbose=False at the end of construction. "interactive" does not turn on interactive mode; use interactive=True for that.

# No printing and no verbose logging
agent = Agent(mode="fast")

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:306-412 (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

Reasoning

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

​Reasoning

​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

Reasoning

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