> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Agent Defaults

> Chat-optimised defaults for YAML agents behind the gateway

Gateway agents use chat-optimised defaults to ensure fast response times for interactive chat applications.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Gateway Agent Flow"
        User[👤 User] --> Chat[💬 Chat App]
        Chat --> Gateway[🌐 Gateway]
        Gateway --> Agent[🤖 Agent<br/>reflection=false]
        Agent --> Reply[⚡ Fast Reply<br/>~1.6s]
    end
    
    classDef user fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef chat fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef gateway fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef reply fill:#10B981,stroke:#7C90A0,color:#fff
    
    class User user
    class Chat chat
    class Gateway gateway
    class Agent agent
    class Reply reply
```

## Quick Start

<Steps>
  <Step title="Fast by default">
    Create a minimal `bot.yaml` with fast defaults:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agents:
      assistant:
        instructions: "You are a helpful AI assistant."
        model: gpt-4o-mini
    ```

    Response latency: \~1.6 seconds on short prompts.
  </Step>

  <Step title="Opt in to reflection">
    Add reflection for higher quality responses:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agents:
      assistant:
        instructions: "You are a helpful AI assistant."
        model: gpt-4o-mini
        reflection: true   # opt-in: enables self-critique
    ```

    Response latency: \~12.3 seconds (8x slower for better quality).
  </Step>
</Steps>

***

## How It Works

Gateway agents optimize for chat channel performance with different flow patterns:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Gateway
    participant Agent
    
    rect rgb(245, 158, 11, 0.1)
        Note over User, Agent: Default: Fast Response
        User->>Gateway: Message
        Gateway->>Agent: Process (reflection=false)
        Agent-->>Gateway: Direct Answer
        Gateway-->>User: ~1.6s response
    end
    
    rect rgb(139, 0, 0, 0.1)
        Note over User, Agent: Opt-in: High Quality
        User->>Gateway: Message
        Gateway->>Agent: Process (reflection=true)
        Agent->>Agent: Self-critique loop
        Agent-->>Gateway: Refined Answer
        Gateway-->>User: ~12.3s response
    end
```

| Mode                 | Reflection | Latency | Quality                 |
| -------------------- | ---------- | ------- | ----------------------- |
| **Fast** (default)   | `false`    | \~1.6s  | Direct response         |
| **Quality** (opt-in) | `true`     | \~12.3s | Self-critiqued response |

***

## Configuration Options

Gateway agents loaded from YAML use chat-optimised defaults:

| YAML key           | Gateway default | SDK default   | Why different                         |
| ------------------ | --------------- | ------------- | ------------------------------------- |
| `reflection`       | `false`         | `false`       | Chat channels need sub-second replies |
| `tool_choice`      | `null` (auto)   | `null` (auto) | Let LLM decide when to call tools     |
| `allow_delegation` | `false`         | `false`       | Prevents routing unless opted in      |

***

## Common Patterns

### Plain Chat Assistant

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
  assistant:
    instructions: "You are a helpful AI assistant."
    model: gpt-4o-mini
    # reflection defaults to false - fast responses
```

### High-Quality Q\&A Bot

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
  expert:
    instructions: "You are an expert consultant. Think carefully before answering."
    model: gpt-4o
    reflection: true  # opt-in for quality over speed
```

### Mixed Agent Configuration

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
  quickhelp:
    instructions: "Handle basic questions quickly."
    model: gpt-4o-mini
    # reflection=false (default) - fast responses
    
  research:
    instructions: "Conduct thorough research and analysis."
    model: gpt-4o
    reflection: true  # enable self-critique for research
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Default is fast — only enable reflection when quality matters more than latency">
    Gateway agents default to `reflection: false` because chat applications prioritize response speed. Enable reflection only for agents handling complex analysis or research tasks.
  </Accordion>

  <Accordion title="Measure before opting in: reflection adds 1..max_reflect=3 extra LLM round-trips per message">
    Each reflection cycle requires additional API calls. For `gpt-4o-mini`, this increases latency from \~1.6s to \~12.3s. Test your specific use case to validate the quality improvement justifies the speed tradeoff.
  </Accordion>

  <Accordion title="Use reflection selectively per agent, not globally">
    Configure reflection per agent based on their role. Quick support agents should stay fast, while research or analysis agents benefit from reflection.
  </Accordion>

  <Accordion title="For background / long-form tasks use the Python SDK directly — it has different defaults suited to that use case">
    Gateway defaults optimize for interactive chat. For batch processing, long-running tasks, or non-interactive workflows, use the Python SDK directly where different performance characteristics apply.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Gateway" icon="gateway" href="/docs/gateway">
    Gateway configuration and deployment
  </Card>

  <Card title="Reflection" icon="rotate" href="/docs/concepts/reflection">
    Understanding reflection and self-critique
  </Card>

  <Card title="Bot OS" icon="robot" href="/docs/concepts/bot-os">
    Bot operating system concepts
  </Card>

  <Card title="Messaging Bots" icon="message-square" href="/docs/features/messaging-bots">
    Chat platform integrations
  </Card>
</CardGroup>