Operations Analyst - Upsonic AI

An autonomous agent built with Upsonic’s AutonomousAgent that reads raw shipment data, decides which KPIs matter, writes a structured report, and produces matplotlib charts. The agent runs two tasks in sequence (analyst then visualizer) with all behavior defined in AGENTS.md, not in code.

Overview

The setup has two parts:

AutonomousAgent with a workspace directory, no custom tools, no system prompt
Two Task objects sent sequentially to the same agent

The agent uses its built-in tools (read/write files, run_python) to explore data, compute metrics, write a report, and generate charts autonomously.

Project Structure

operations_analyst/
├── main.py                         # Two-task pipeline (~40 lines)
├── requirements.txt                # upsonic, anthropic, matplotlib, pandas
└── workspace/
    ├── AGENTS.md                   # Agent behavior: task definitions, rules, memory
    ├── SOUL.md                     # Agent identity and personality
    ├── shipment_data.csv           # Input data (80 shipment records)
    └── memory/                     # Agent writes session logs here

After running, the workspace will also contain:

workspace/
├── KPI_REPORT.md                   # Generated report with tables and commentary
├── charts/                         # Generated PNG charts (one per metric)
│   ├── ontime_performance.png
│   ├── carrier_comparison.png
│   └── ...
└── memory/
    └── YYYY-MM-DD.md

Environment Variables

ANTHROPIC_API_KEY=your-api-key

Installation

cd examples/autonomous_agents/operations_analyst
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt

Usage

python main.py

The agent will:

Read the shipment CSV (80 rows of delivery records)
Compute KPIs: on-time rate, carrier performance, route delays, cost efficiency
Write workspace/KPI_REPORT.md with tables, breakdowns, and commentary
Generate one chart per metric and save them to workspace/charts/

How It Works

Component	Role
AutonomousAgent	Reads workspace files, runs Python, manages all logic
Task 1 (Analyst)	Reads CSV → computes KPIs → writes `KPI_REPORT.md`
Task 2 (Visualizer)	Reads report → runs matplotlib via `run_python` → saves PNGs
AGENTS.md	Task definitions, workspace layout, memory rules, safety rules
SOUL.md	Agent identity and analysis style

Flow

Agent reads AGENTS.md and SOUL.md from the workspace on startup
Task 1: Agent reads shipment_data.csv, decides which metrics matter, computes them, and writes KPI_REPORT.md
Task 2: Agent reads the report, writes matplotlib code, executes it via run_python, and saves charts to charts/
Agent logs the session in memory/

Complete Implementation

main.py

"""
Operations Analysis — Upsonic AutonomousAgent (two-task pipeline)

Task 1 (Analyst):    reads shipment_data.csv → decides KPIs → writes KPI_REPORT.md
Task 2 (Visualizer): reads KPI_REPORT.md → runs matplotlib code directly via run_python → produces charts

One agent. Two shots. Fully autonomous.
"""

import os
from upsonic import AutonomousAgent, Task

WORKSPACE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "workspace")

print(f"Workspace: {WORKSPACE}")

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace=WORKSPACE,
)

analyst_task = Task(
    "Read shipment_data.csv. Identify the KPIs that matter most for delivery operations — "
    "on-time rate, carrier performance, route delays, cost efficiency. Compute each from the raw data. "
    "Write KPI_REPORT.md with a summary table, per-carrier breakdown, and a "
    "## Agent Commentary section with your analysis and recommendations."
)

visualizer_task = Task(
    "Read KPI_REPORT.md and shipment_data.csv. Based on the KPIs in the report, use run_python "
    "to execute matplotlib code that creates one chart per key metric. "
    "Use a white background with dark text for readability. Save all charts as PNGs to the charts/ directory. "
    "Do not write a .py file — run the code directly."
)

if __name__ == "__main__":
    print("\n── Task 1: Analyst ────────────────────────────")
    agent.print_do(analyst_task)

    print("\n── Task 2: Visualizer ─────────────────────────")
    agent.print_do(visualizer_task)

No system prompt, no custom tools. The agent reads everything from its workspace and uses run_python to execute generated code.

Workspace: AGENTS.md

The key to this example. Instead of hardcoding analysis steps in Python, the agent reads its instructions from AGENTS.md:

Two-task pipeline: Task 1 analyzes data and writes a report, Task 2 reads the report and produces charts
Memory: Daily logs in memory/YYYY-MM-DD.md for continuity between tasks and sessions
Workspace layout: Which files are inputs, which are outputs, who owns what
Rules: Never delete source data, no exfiltration, trash over rm
Tools: Task 2 writes its own visualization script from scratch based on what Task 1 found

Change the task descriptions or edit AGENTS.md to analyze different metrics. The agent adapts without touching code.

Sample Data

The included shipment_data.csv contains 80 shipment records with:

3 Carriers: FastCargo (reliable), SpeedLine (mixed), EcoShip (cheap but slow on long routes)
8 Destinations: Western cities are fast, eastern cities (Erzurum, Diyarbakir, Trabzon) have delays
4 Categories: Electronics, Furniture, Food & Beverage, Clothing
Date range: Jan-Mar 2025

Swap it with your own data to analyze different operations.

Repository

View the full example: Operations Analyst

​Overview

​Project Structure

​Environment Variables

​Installation

​Usage

​How It Works

​Flow

​Complete Implementation

​main.py

​Workspace: AGENTS.md

​Sample Data

​Repository