Skip to content

How to Create Your First Agent

A complete step-by-step guide to creating an AI agent.

Overview

Creating an agent involves: 1. Planning your agent type 2. Preparing data 3. Configuring settings 4. Training 5. Testing

Step 1: Plan Your Agent

Ask yourself these questions:

What problem does my agent solve? - Classification: Categorize items - Regression: Predict numbers - Detection: Find objects/patterns - Generation: Create content

What data do I have? - Text, numbers, images, or mixed - How much? (100+ examples ideal) - Quality? (clean, labeled, balanced)

What's success? - What accuracy do I need? - What's the business impact?

Step 2: Create Agent Project

iovalence create-agent \
  --name my-classifier \
  --type classification \
  --framework tensorflow

This creates: 

my-classifier/
├── config.yaml
├── data/
│   ├── train.csv
│   ├── test.csv
│   └── validation.csv
├── models/
├── outputs/
└── README.md

Step 3: Configure Your Agent

Edit config.yaml:

# Agent Metadata
agent:
  name: my-classifier
  type: classification
  description: Classifies text into categories
  version: 1.0
  author: Your Name

# Data Configuration
data:
  source: data/
  train_file: train.csv
  test_file: test.csv
  validation_file: validation.csv

  # Column mappings
  features:
    - text_content
    - text_length
  target: category

  # Data processing
  preprocessing:
    - lowercase: true
    - remove_special_chars: true
    - tokenize: true
    - remove_stopwords: true

# Training Configuration
training:
  # Model architecture
  model_type: neural_network
  layers: [128, 64, 32]
  activation: relu

  # Training parameters
  epochs: 20
  batch_size: 32
  validation_split: 0.2

  # Optimization
  optimizer: adam
  learning_rate: 0.001
  loss_function: categorical_crossentropy

  # Regularization
  dropout: 0.3
  early_stopping: true
  patience: 5

# Evaluation
evaluation:
  metrics:
    - accuracy
    - precision
    - recall
    - f1_score
  threshold: 0.5

# Output
output:
  save_model: true
  save_history: true
  save_predictions: true
  output_dir: models/

Step 4: Prepare Your Data

Data Format

text_content,text_length,category
"Great product",13,positive
"Terrible experience",20,negative
"Okay quality",12,neutral

Data Checklist

  • ✅ Headers match config
  • ✅ No missing values (or handled properly)
  • ✅ Balanced classes
  • ✅ At least 100 examples
  • ✅ CSV, JSON, or supported format

File Organization

my-classifier/data/
├── train.csv      (80% of data)
├── test.csv       (20% of data)
└── validation.csv (subset of train)

Step 5: Train Your Agent

cd my-classifier
iovalence train --config config.yaml

Monitor training: 

Starting training...
Epoch 1/20: loss=0.542, acc=0.78, val_loss=0.498, val_acc=0.82
Epoch 2/20: loss=0.412, acc=0.85, val_loss=0.401, val_acc=0.87
...
Training completed!
Best model saved: models/best_model.pkl

Step 6: Evaluate Results

iovalence evaluate --model models/best_model.pkl --test data/test.csv

Results: 

=== EVALUATION METRICS ===
Accuracy:  0.91
Precision: 0.89
Recall:    0.93
F1-Score:  0.91

=== CONFUSION MATRIX ===
              Predicted
           Pos   Neg  Neutral
Actual Pos  45    3     2
       Neg   2   48     0
       Neu   1    1    46

Step 7: Make Predictions

Single Prediction

iovalence predict \
  --model models/best_model.pkl \
  --input "This is an amazing product!"

Output: 

{
  "input": "This is an amazing product!",
  "prediction": "positive",
  "confidence": 0.97,
  "scores": {
    "positive": 0.97,
    "negative": 0.02,
    "neutral": 0.01
  }
}

Batch Predictions

iovalence predict \
  --model models/best_model.pkl \
  --input-file test_data.csv \
  --output predictions.csv

Step 8: Save Your Agent

iovalence save --agent my-classifier --tag v1.0

Creates deployable package: 

my-classifier_v1.0.zip
├── model/
├── config/
├── metadata/
└── README

Configuration Tuning Guide

If Accuracy is Low

# Try:
training:
  epochs: 50          # More training
  batch_size: 16      # Smaller batches
  learning_rate: 0.01 # Higher learning rate

If Overfitting (Train good, Test bad)

# Try:
training:
  dropout: 0.5           # More dropout
  epochs: 10             # Fewer epochs
  early_stopping: true   # Stop early
  patience: 3

If Underfitting (Both poor)

# Try:
agent:
  layers: [256, 128, 64] # Larger model
training:
  epochs: 100            # More training
  learning_rate: 0.01    # Higher learning rate

Common Issues & Solutions

Issue Cause Solution
CSV parse error Wrong format Check headers and encoding
Out of memory Too large batch Reduce batch_size
Stuck training Learning rate too small Increase learning_rate
Not improving Insufficient data Add more examples
Overfitting Model too complex Add dropout, reduce layers

Next Steps

Success! You've created your first agent. What's next?