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

# Operations Analyst

> A two-task autonomous pipeline that analyzes shipment data, computes delivery KPIs, and generates matplotlib charts, all from workspace-defined behavior.

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.

<iframe src="https://www.youtube.com/embed/vRhzl_yx26o" title="YouTube video player" frameborder="0" className="w-full aspect-video rounded-xl" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Overview

The setup has two parts:

1. **AutonomousAgent** with a workspace directory, no custom tools, no system prompt
2. **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

```bash theme={null}
ANTHROPIC_API_KEY=your-api-key
```

## Installation

```bash theme={null}
cd examples/autonomous_agents/operations_analyst
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
```

## Usage

```bash theme={null}
python main.py
```

The agent will:

1. Read the shipment CSV (80 rows of delivery records)
2. Compute KPIs: on-time rate, carrier performance, route delays, cost efficiency
3. Write `workspace/KPI_REPORT.md` with tables, breakdowns, and commentary
4. 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

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

## Complete Implementation

### main.py

```python theme={null}
"""
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](https://github.com/Upsonic/Examples/tree/master/examples/autonomous_agents/operations_analyst)