# Green-Agent PRD



Oct 7, 2026 · @Donna

## Overview

Green-Agent lets a shipper pick a freight carrier on cost and carbon at once, instead of defaulting to the cheapest quote. A buyer agent broadcasts each shipment request over Agentverse, carrier agents reply with price, ETA, and CO2e bids, and a scoring engine ranks them using weights the shipper sets. An LLM explains why the top carrier won, and the shipper approves the choice before it is booked.

The system is built in Python with Fetch.ai uAgents, a React dashboard, and the Spring LLM API.

## Problem

Shippers choose carriers mostly on price, because emissions data is scattered and hard to compare across quotes. Even when a shipper wants to cut emissions, weighing a cheaper quote against a lower-carbon one is a manual judgment call made shipment by shipment.

Three gaps make this hard:

- **No common format.** Carriers report price, delivery time, and emissions in different ways, so quotes can't be compared side by side.
- **No consistent tradeoff.** Without a scoring rule, the same shipper makes different cost-versus-carbon calls from one day to the next.
- **No visible impact.** Shippers can't see how much CO2e their choices actually saved, so sustainability goals are hard to track or report.

## Goals and non-goals

The MVP proves that agents can collect comparable bids and that a transparent score can trade cost against carbon.

**Goals**

- Collect price, ETA, and CO2e bids from multiple carrier agents for every shipment request.
- Rank bids with one scoring rule whose cost/carbon weights the shipper can change at runtime.
- Explain every recommendation in plain language before the shipper approves it.
- Show CO2e saved against a cheapest-option baseline for each shipment and in total.

**Non-goals**

- Real carrier integrations or live freight booking. Carriers are simulated agents in the MVP.
- Certified emissions accounting. CO2e figures are carrier-reported estimates, not audited values.
- Payments, contracts, or invoicing.
- Fully autonomous booking. A person approves every selection.

## Users and user stories

The primary user is a logistics coordinator at a small or mid-sized shipper with a sustainability target. A secondary user is the sustainability lead who reports on emissions.

|   |   |   |
|---|---|---|
|As a…|I want to…|So that…|
|Logistics coordinator|Send one shipment request and get bids from several carriers|I don't have to collect quotes by hand|
|Logistics coordinator|Set how much I care about cost versus carbon|Rankings reflect my company's priorities|
|Logistics coordinator|Read why a carrier was recommended|I can trust the choice and explain it to my manager|
|Logistics coordinator|Approve or reject the recommendation|Nothing is booked without my sign-off|
|Sustainability lead|See CO2e saved versus the cheapest option|I can report progress toward our emissions goal|

## Functional requirements

P0 items are required for the MVP; P1 items follow once the core loop works.

|   |   |   |
|---|---|---|
|ID|Requirement|Priority|
|FR-1|The buyer agent broadcasts a shipment request (origin, destination, weight, deadline) over Agentverse|P0|
|FR-2|Each carrier agent returns a bid with price, ETA, and CO2e within a set timeout|P0|
|FR-3|Bids that arrive after the timeout or are missing a field are excluded and logged|P0|
|FR-4|The scoring engine ranks all valid bids using min-max normalization and the current weights|P0|
|FR-5|The shipper can change cost/carbon weights from the dashboard without restarting any agent|P0|
|FR-6|The LLM generates a plain-language rationale for the top-ranked carrier|P0|
|FR-7|The dashboard shows the rationale beside a bid comparison table, with Approve and Reject actions|P0|
|FR-8|Approved shipments move to the live shipments view; rejected ones return to pending|P0|
|FR-9|The dashboard shows CO2e saved per shipment and in total versus the cheapest-option baseline|P0|
|FR-10|If the LLM call fails, the dashboard still shows the ranking with a fallback message|P1|
|FR-11|The shipper can save weight presets (for example "Cost-first" and "Green-first")|P1|
|FR-12|Completed shipments can be exported as a CSV emissions report|P1|

## System architecture

![[Screenshot 2026-10-07 at 2.40.02 PM.png]]

The dashboard sends a request with the current weights to the buyer agent, which broadcasts it to the carrier agents through Agentverse. Valid bids go to the scoring engine, and the LLM explains the top-ranked result before it returns to the dashboard for approval.

## Scoring algorithm

Each bid gets a single score from 0 to 1, and the lowest score wins. Price and CO2e are first rescaled within the current bid set, so a $50 difference and a 10 kg difference become comparable.

![[Screenshot 2026-10-07 at 2.40.30 PM.png]]
Rules:

- Normalization runs per bid set, so scores compare bids for the same shipment, never across shipments.
- If every bid has the same value for a field, that field's normalized value is 0 for all bids, which avoids dividing by zero.
- Weights are read at scoring time, not at agent startup, so a change on the dashboard applies to the next request without a restart.
- ETA is a hard filter, not a weight: bids that miss the shipment deadline are excluded before scoring.

## Success metrics

The MVP succeeds if the full request-to-approval loop runs reliably and shows measurable CO2e savings. Targets below are proposed starting points to confirm.

|   |   |   |
|---|---|---|
|Metric|Target|How it's measured|
|Bid collection rate|100% of carrier agents respond before the timeout in demo runs|Count of valid bids per request|
|Time to recommendation|Under 10 seconds from request to ranked result with rationale|Timestamp from broadcast to dashboard render|
|CO2e saved|Positive average savings versus cheapest option at a balanced weight|Dashboard total across demo shipments|
|Approval rate|Shippers approve most recommendations without overriding|Approved ÷ total recommendations|
|Weight-change latency|New weights apply on the very next request|Manual test: change weights, send request, check ranking|

## Risks and open questions

The biggest risk is trust: if CO2e numbers or LLM explanations look wrong, shippers will fall back to picking the cheapest bid.

|   |   |
|---|---|
|Risk|Mitigation|
|Carrier CO2e figures are unverified estimates|Label them as carrier-reported and show the source on each bid|
|The LLM rationale states something the data doesn't support|Pass only the bid table and weights into the prompt, and show the table beside the text|
|A slow or offline carrier agent stalls the request|Enforce a bid timeout and score whatever bids arrived|
|Min-max scores mislead with only 2 or 3 bids|Show raw price and CO2e next to every score|

**Open questions**

- Should ETA be a hard deadline filter (as drafted above) or a third weighted factor?
- Where do carrier CO2e figures come from beyond the simulated agents?
- What weights should the dashboard default to?
- Does the MVP need user accounts, or is a single shipper workspace enough?
- How many carrier agents should the demo run beyond the current 3?
