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

# Agent Train

> Active iterative training with human or LLM feedback to improve agent behavior

Agent Train enables active improvement of agent behavior through iterative feedback loops. Unlike [Agent Learn](/docs/concepts/agent-learn) which captures patterns passively, training uses explicit human or LLM feedback to refine responses.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Agent Training Flow"
        I[📋 Scenario] --> A[🤖 Agent]
        A --> O[📝 Output]
        O --> G{Grader}
        G -->|Score + Feedback| R[🔄 Improve]
        R --> A
    end
    
    subgraph "Grading Modes"
        H[👤 Human Feedback]
        L[🧠 LLM-as-Judge]
    end
    
    G --> H
    G --> L
    
    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    
    class I input
    class A,O,G,R process
    class H,L output
```

## Quick Start

<Steps>
  <Step title="Simple CLI Training">
    Train an agent with a single input:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai train agents --input "What is Python?"
    ```
  </Step>

  <Step title="Human-in-the-Loop">
    Get human feedback instead of automated grading:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai train agents --input "Explain machine learning" --human
    ```
  </Step>

  <Step title="Multiple Iterations">
    Run multiple training iterations:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai train agents --input "Write a poem" --iterations 5
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant AgentTrainer
    participant Agent
    participant Grader
    participant Storage

    User->>AgentTrainer: Add scenario
    AgentTrainer->>Agent: Run with input
    Agent->>AgentTrainer: Output response
    AgentTrainer->>Grader: Grade output
    Grader->>AgentTrainer: Score + feedback
    AgentTrainer->>AgentTrainer: Build improvement prompt
    AgentTrainer->>Agent: Run improved (iteration 2)
    AgentTrainer->>Storage: Save training report
    AgentTrainer->>User: Final report
```

### Detailed Control Flow

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant AgentTrainer
    participant TrainingStorage
    participant TrainingGrader

    User->>AgentTrainer: praisonai train agents --input "Hello"
    AgentTrainer->>TrainingStorage: add_scenario()
    
    loop For each iteration
        AgentTrainer->>AgentTrainer: _get_agent_output(prompt)
        
        alt LLM Mode (default)
            AgentTrainer->>TrainingGrader: grade(input, output)
            TrainingGrader-->>AgentTrainer: GradeResult (score, feedback)
        else Human Mode (--human)
            AgentTrainer->>User: Print output, ask for score
            User-->>AgentTrainer: Score + feedback
        end
        
        AgentTrainer->>TrainingStorage: save_iteration()
        AgentTrainer->>AgentTrainer: _build_improvement_prompt
    end
    
    AgentTrainer->>TrainingStorage: save_report()
    AgentTrainer-->>User: TrainingReport
```

| Phase | Description |
| - | - |
| **Scenario** | Define input and expected output |
| **Execute** | Run agent and capture response |
| **Grade** | Score output (human or LLM) |
| **Improve** | Build enhanced prompt from feedback |
| **Iterate** | Repeat for N iterations |
| **Report** | Generate training summary |

***

## SDK Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.train.agents import AgentTrainer, TrainingScenario
from praisonaiagents import Agent

# Create agent
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant"
)

# Create trainer
trainer = AgentTrainer(
    agent=agent,
    iterations=3,
    human_mode=False  # Use LLM grading
)

# Add training scenario
trainer.add_scenario(TrainingScenario(
    id="greeting",
    input_text="Hello, how are you?",
    expected_output="A friendly greeting response"
))

# Run training
report = trainer.run()

print(f"Final score: {report.avg_score}/10")
print(f"Improvement: {report.improvement:+.1f}")
```

***

## Applying Training at Runtime

After training, apply the learned improvements to your agent using `apply_training()`:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.train.agents import apply_training
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")

# Apply best iteration from a session
apply_training(agent, session_id="train-abc123")

# Now the agent uses learned improvements
response = agent.start("Hello!")
```

### Select Specific Iteration

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Apply iteration #2 specifically (not just the best)
apply_training(agent, session_id="train-abc123", iteration=2)
```

### Inspect Before Applying

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.train.agents import get_training_profile

# Preview the profile first
profile = get_training_profile("train-abc123")
print(f"Score: {profile.quality_score}/10")
print(f"Suggestions: {profile.suggestions}")

# Then apply if it looks good
apply_training(agent, profile=profile)
```

### Remove Training

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.train.agents import remove_training

# Remove training hook from agent
remove_training(agent)
```

<Note>
  Training is applied via hooks - it doesn't modify the agent permanently. You can remove it anytime.
</Note>

***

## CLI Commands

### Train Agents

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai train agents [OPTIONS] [AGENT_FILE]
```

| Option | Description | Default |
| - | - | - |
| `--input`, `-i` | Single input text | - |
| `--expected`, `-e` | Expected output | - |
| `--iterations`, `-n` | Number of iterations | `3` |
| `--human`, `-h` | Use human feedback | `false` |
| `--scenarios`, `-s` | Scenarios JSON file | - |
| `--model`, `-m` | LLM for grading | `gpt-4o-mini` |
| `--storage-backend` | `file`, `sqlite`, `redis://` | `file` |

### List Sessions

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai train list
```

### Show Session Details

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai train show <session_id> --iterations
```

The `--iterations` flag shows detailed suggestions for each iteration.

### Apply Training

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai train apply <session_id> [OPTIONS]
```

| Option | Description | Default |
| - | - | - |
| `--iteration`, `-n` | Specific iteration number | best |
| `--run`, `-r` | Run agent with this prompt | - |
| `--agent`, `-a` | Path to agent YAML file | - |

Example:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai train apply train-abc123 --iteration 2 --run "Hello"
```

***

## Grading Modes

<Tabs>
  <Tab title="LLM-as-Judge (Default)">
    Automated grading using an LLM to evaluate responses:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai train agents --input "Explain AI" --model gpt-4o
    ```

    The LLM grades based on:

    * Relevance to input
    * Accuracy of information
    * Clarity and completeness
    * Match to expected output (if provided)
  </Tab>

  <Tab title="Human Feedback">
    Interactive mode where you score and provide feedback:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai train agents --input "Write a haiku" --human
    ```

    You'll be prompted to:

    1. Review the agent's output
    2. Provide a score (1-10)
    3. Enter improvement suggestions
  </Tab>
</Tabs>

***

## Storage Backends

Training data persists across sessions:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# File storage (default)
praisonai train agents --input "Hello" --storage-backend file

# SQLite (recommended for production)
praisonai train agents --input "Hello" --storage-backend sqlite

# Redis (distributed systems)
praisonai train agents --input "Hello" --storage-backend redis://localhost:6379
```

Training data is stored as JSON (not pickle), making it:

* ✅ Human-readable
* ✅ Git-friendly
* ✅ Secure (no pickle vulnerabilities)
* ✅ Cross-platform compatible

***

## Scenarios File

For batch training, use a scenarios file:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
[
  {
    "id": "greeting",
    "input_text": "Hello, how are you?",
    "expected_output": "A friendly response"
  },
  {
    "id": "coding",
    "input_text": "Write a Python hello world",
    "expected_output": "print('Hello, World!')"
  }
]
```

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai train agents --scenarios scenarios.json --iterations 5
```

***

## Learn vs Train

| Aspect | Agent Learn | Agent Training |
| - | - | - |
| **Purpose** | Passive learning during interactions | Active iterative improvement |
| **Trigger** | Automatic during `agent.start()` | Explicit CLI/SDK call |
| **Feedback** | Implicit (patterns, insights) | Explicit (score, suggestions) |
| **Storage** | Persona, insights, patterns stores | Scenarios, iterations, reports |
| **Use Case** | Remember user preferences | Improve agent behavior |

<Tip>
  Agent Learn and Agent Training are **complementary**. Use Learn for continuous adaptation and Training for focused improvement sessions.
</Tip>

See [Learn vs Train Comparison](/docs/concepts/learn-vs-train) for detailed differences.

***

## Related

<CardGroup cols={2}>
  <Card title="Agent Learn" icon="graduation-cap" href="/docs/concepts/agent-learn">
    Passive continuous learning
  </Card>

  <Card title="Learn vs Train" icon="scale-balanced" href="/docs/concepts/learn-vs-train">
    Detailed comparison
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.