Part 3 of 15 • 🟢 Easy (Beginner) • ⏱️ 60 minutes

Processing User Files & Spreadsheets in watsonx Orchestrate: Building an Automated Data Analyst Agent

Handling multi-modal file uploads, inspecting Excel spreadsheets with pandas, and generating summary analytics.

---

Step 1: Write Tool Logic (file_processor.py)

from ibm_watsonx_orchestrate import tool
import pandas as pd
import os

@tool
def analyze_employee_data(file_path: str) -> str:
    """
    Analyze employee data from an uploaded Excel spreadsheet.

    Args:
        file_path: Absolute filesystem path to the uploaded Excel file.

    Returns:
        Structured summary statistics and department breakdown.
    """
    try:
        if not os.path.exists(file_path):
            return f"❌ File not found at path: {file_path}"

        df = pd.read_excel(file_path)
        total_records = len(df)
        columns = ", ".join(df.columns.tolist())
        
        dept_counts = df['Department'].value_counts().to_dict() if 'Department' in df.columns else {}
        avg_salary = f"${df['Salary'].mean():,.2f}" if 'Salary' in df.columns else "N/A"

        return f"""
📊 Spreadsheet Analytics Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Headcount:    {total_records}
Detected Columns:   {columns}
Average Base Pay:   {avg_salary}

Department Breakdown:
{chr(10).join([f"  • {dept}: {count}" for dept, count in dept_counts.items()])}
"""
    except Exception as e:
        return f"❌ Error processing Excel file: {str(e)}"

Step 2: Dependencies (requirements.txt)

ibm-watsonx-orchestrate>=2.9.0
pandas>=2.0.0
openpyxl>=3.1.0

Step 3: Agent Manifest (agent.yaml)

spec_version: v1
kind: native
name: hr_data_analyst
title: "HR Data Analyst"
description: "Ingests user-uploaded spreadsheets to extract headcount and department statistics."
model: ibm/granite-3-8b-instruct
instructions: |
  You are an HR analytics assistant. When a user uploads or references an Excel file,
  call `analyze_employee_data` passing the file path, and summarize the key findings.
tools:
  - analyze_employee_data

Step 4: Live Execution

orchestrate chat ask -n hr_data_analyst "Analyze this spreadsheet: /tmp/sample_employees.xlsx"

╭─ 🤖 hr_data_analyst ───────────────────────────────────────────────────╮
│                                                                        │
│  📊 Spreadsheet Analytics Summary                                      │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                                     │
│  Total Headcount:    3                                                 │
│  Detected Columns:   Employee_ID, Name, Department, Salary             │
│  Average Base Pay:   $78,333.33                                        │
│                                                                        │
│  Department Breakdown:                                                 │
│    • Engineering: 1                                                    │
│    • Sales: 1                                                          │
│    • HR: 1                                                             │
╰────────────────────────────────────────────────────────────────────────╯

---

💡 Pro Tips & Architecture Insights

---