> ## 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 Configuration

> Complete guide to configuring agents with all available parameters

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

## Core Parameters

### Model Configuration

<ParamField path="model_name" type="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.

  ```python theme={null}
  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")
  ```
</ParamField>

<ParamField path="llm" type="Any" default="None">
  Pre-configured LLM instance. If not provided, will be created automatically based on `model_name`.

  ```python theme={null}
  from swarms.utils.litellm_wrapper import LiteLLM

  llm = LiteLLM(model_name="claude-sonnet-4-6", temperature=0.5)
  agent = Agent(llm=llm)
  ```
</ParamField>

<ParamField path="temperature" type="float" default="0.5">
  Controls randomness in model outputs (0.0 = deterministic, 1.0 = creative).

  ```python theme={null}
  # 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)
  ```
</ParamField>

<ParamField path="max_tokens" type="int" default="4096">
  Maximum number of tokens to generate in a single response.

  ```python theme={null}
  agent = Agent(model_name="claude-sonnet-4-6", max_tokens=8192)
  ```
</ParamField>

<ParamField path="context_length" type="int" default="Based on model">
  Maximum context window size. Automatically set based on the model.

  ```python theme={null}
  agent = Agent(model_name="claude-sonnet-4-6", context_length=128000)
  ```
</ParamField>

### Agent Identity

<ParamField path="agent_name" type="str" default="swarm-worker-01">
  Unique name for the agent. Used in multi-agent systems and logging.

  ```python theme={null}
  agent = Agent(
      agent_name="Financial-Analyst",
      model_name="claude-sonnet-4-6"
  )
  ```
</ParamField>

<ParamField path="agent_description" type="str" default="Auto-generated">
  Description of the agent's purpose and capabilities.

  ```python theme={null}
  agent = Agent(
      agent_name="Data-Analyst",
      agent_description="Expert in data analysis, visualization, and statistical modeling",
      model_name="claude-sonnet-4-6"
  )
  ```
</ParamField>

<ParamField path="system_prompt" type="str" default="Default system prompt">
  The system prompt that defines agent behavior and expertise.

  ```python theme={null}
  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"
  )
  ```
</ParamField>

### Execution Control

<ParamField path="max_loops" type="Union[int, str]" default="1">
  Number of execution loops. Set to "auto" for autonomous mode.

  ```python theme={null}
  # Single execution
  agent = Agent(max_loops=1)

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

  # Autonomous mode
  agent = Agent(max_loops="auto")
  ```
</ParamField>

<ParamField path="loop_interval" type="int" default="0">
  Delay in seconds between loops.

  ```python theme={null}
  agent = Agent(max_loops=5, loop_interval=1)  # 1 second delay
  ```
</ParamField>

<ParamField path="retry_attempts" type="int" default="3">
  Number of retry attempts for failed LLM calls.

  ```python theme={null}
  agent = Agent(retry_attempts=5)
  ```
</ParamField>

<ParamField path="retry_interval" type="int" default="1">
  Delay in seconds between retry attempts.

  ```python theme={null}
  agent = Agent(retry_attempts=3, retry_interval=2)
  ```
</ParamField>

<ParamField path="timeout" type="int" default="None">
  Timeout in seconds for agent execution.

  ```python theme={null}
  agent = Agent(timeout=300)  # 5 minute timeout
  ```
</ParamField>

### Output Configuration

<ParamField path="output_type" type="str" default="str-all-except-first">
  Format for agent output. Options: "str", "list", "json", "dict", "yaml", "xml".

  ```python theme={null}
  # String output
  agent = Agent(output_type="str")

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

  # Dictionary output
  agent = Agent(output_type="dict")
  ```
</ParamField>

<ParamField path="streaming_on" type="bool" default="False">
  Enable basic streaming with formatted panels.

  ```python theme={null}
  agent = Agent(streaming_on=True)
  ```
</ParamField>

<ParamField path="stream" type="bool" default="False">
  Enable detailed token-by-token streaming with metadata.

  ```python theme={null}
  agent = Agent(stream=True)
  response = agent.run("Tell me a story")  # Streams each token
  ```
</ParamField>

<ParamField path="streaming_callback" type="Callable" default="None">
  Callback function to receive streaming tokens in real-time.

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

  agent = Agent(streaming_callback=on_token)
  ```
</ParamField>

### 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.

```python theme={null}
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.

```python theme={null}
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())
```

<Note>
  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"`.
</Note>

<ParamField path="verbose" type="bool" default="False">
  Enable detailed logging output.

  ```python theme={null}
  agent = Agent(verbose=True)
  ```
</ParamField>

<ParamField path="print_on" type="bool" default="True">
  Enable printing of agent responses.

  ```python theme={null}
  agent = Agent(print_on=True)
  ```
</ParamField>

### Memory and History

<ParamField path="return_history" type="bool" default="False">
  Return full conversation history instead of just final response.

  ```python theme={null}
  agent = Agent(return_history=True)
  response = agent.run("Hello")  # Returns full conversation
  ```
</ParamField>

<ParamField path="user_name" type="str" default="Human">
  Name to use for user messages in conversation history.

  ```python theme={null}
  agent = Agent(user_name="John")
  ```
</ParamField>

<ParamField path="dynamic_context_window" type="bool" default="True">
  Automatically manage context window to prevent overflow.

  ```python theme={null}
  agent = Agent(dynamic_context_window=True)
  ```
</ParamField>

### Advanced Features

<ParamField path="dynamic_temperature_enabled" type="bool" default="False">
  Randomly adjust temperature between loops for varied outputs.

  ```python theme={null}
  agent = Agent(dynamic_temperature_enabled=True)
  ```
</ParamField>

<ParamField path="reasoning_prompt_on" type="bool" default="True">
  Add reasoning prompts to guide multi-step thinking.

  ```python theme={null}
  agent = Agent(max_loops=5, reasoning_prompt_on=True)
  ```
</ParamField>

<ParamField path="interactive" type="bool" default="False">
  Enable interactive mode for conversational agents.

  ```python theme={null}
  agent = Agent(interactive=True)
  ```
</ParamField>

<ParamField path="dashboard" type="bool" default="False">
  Display agent dashboard on initialization.

  ```python theme={null}
  agent = Agent(dashboard=True)
  ```
</ParamField>

### State Management

<ParamField path="autosave" type="bool" default="False">
  Automatically save agent state after each execution.

  ```python theme={null}
  agent = Agent(autosave=True)
  ```
</ParamField>

<ParamField path="saved_state_path" type="str" default="Auto-generated">
  Path to save agent state.

  ```python theme={null}
  agent = Agent(
      autosave=True,
      saved_state_path="./states/my_agent.json"
  )
  ```
</ParamField>

<ParamField path="load_state_path" type="str" default="None">
  Path to load previous agent state from.

  ```python theme={null}
  agent = Agent(load_state_path="./states/my_agent.json")
  ```
</ParamField>

### Reliability

<ParamField path="fallback_models" type="List[str]" default="None">
  List of fallback models to try if primary model fails.

  ```python theme={null}
  agent = Agent(
      fallback_models=[
          "claude-sonnet-4-6",
          "gpt-5.4",
          "gpt-3.5-turbo"
      ]
  )
  ```
</ParamField>

### Performance

<ParamField path="mode" type="str" default="standard">
  Agent execution mode. Options: "interactive", "fast", "standard".

  ```python theme={null}
  # Fast mode (no printing, minimal overhead)
  agent = Agent(mode="fast")

  # Interactive mode
  agent = Agent(mode="interactive")
  ```
</ParamField>

<ParamField path="top_p" type="float" default="0.90">
  Nucleus sampling parameter for model generation.

  ```python theme={null}
  agent = Agent(top_p=0.95)
  ```
</ParamField>

## Example Configurations

### Production Agent

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="Agent Memory" icon="database" href="/agents/agent-memory">
    Configure conversation history and memory
  </Card>

  <Card title="Agent Tools" icon="wrench" href="/agents/agent-tools">
    Add tools to extend capabilities
  </Card>
</CardGroup>

## Reference

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