Shipping Assistant

1. What the Shipping Assistant does

The SHIP marketplace agent helps logistics and distribution SMEs run fulfillment with less manual tracking and fewer “Where is my order?” tickets.

• ▸ ShipStation · UPS · FedEx · USPS — ShipStation is the hub; carriers flow through it
• ▸ Full order-to-delivery flow — from awaiting shipment to delivered / exception

2. Starting from the Matrixly.AI landing page

1. Open the marketplace

   Open agents.html (nav: Agents or Browse Agents).

2. Find the SHIP card

   Shipping Assistant — Live · ShipStation · UPS · FedEx · USPS · Full order-to-delivery flow.

3. Choose an action

   • Deploy Now → opens the deploy page (shipping-assistant.html)
   • See full logistics flow → homepage multi-agent logistics section
   • This User Guide → step-by-step usage (you are here)

4. Optional: Integrations

   On integrations.html, search ship or filter Logistics. ShipStation is marked popular and links to the Shipping Agent.

3. Install and run the demo (no API keys)

You can try the full agent flow immediately with sample data. No ShipStation account required.

Windows PowerShell

cd C:\Users\anwar\projects\matrix-six\agents\shipping-assistant
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m src.cli demo

What demo shows:

• Sample shipments (UPS, FedEx, USPS)
• Exception scan (e.g. delivery exception, delayed in transit)

Confirm mode with python -m src.cli status — you should see Mode: demo until API keys are set.

4. Connect live ShipStation

1. Create API credentials

   In ShipStation: Settings → Account → API Settings → generate API Key and API Secret. Docs: shipstation.com

2. Create local env file

   cd C:\Users\anwar\projects\matrix-six\agents\shipping-assistant
   copy .env.example .env

3. Add secrets (never commit or paste into chat)

   SHIPSTATION_API_KEY=your_key_here
   SHIPSTATION_API_SECRET=your_secret_here

4. Verify live mode

   python -m src.cli status
   python -m src.cli list

   Status should show Mode: live and list real orders/shipments.

5. Recommended daily ops workflow

1. Morning exception scan

   python -m src.cli exceptions

   Review high-severity items first (exceptions, past ETA).

2. Draft stakeholder + customer updates

   python -m src.cli notify-drafts

   Internal draft → your ops email. Customer draft → review, then send from Gmail/Thunderbird (or Email Assistant).

3. Answer a specific WISMO

   python -m src.cli wismo --order YOUR-ORDER-NUMBER

   Copy the draft into your mail client. Agent does not auto-email the customer.

4. Track one package

   python -m src.cli track --order MB-10421
   python -m src.cli track --tracking 1Z999AA10123456784

5. Export a snapshot for audit / sharing

   python -m src.cli export

   Writes JSON under agents/shipping-assistant/data/output/.

6. Command reference

Add --json to most commands for machine-readable output.

7. WISMO and stakeholder notifications

WISMO = “Where Is My Order?” The agent drafts a clear status email with tracking and ETA when available.

# Demo sample exception order
python -m src.cli wismo --order MB-10418

Pair with the Email Assistant to triage inbound WISMO mail, then paste the draft reply (still human-approved to send).

notify-drafts prepares:

• Internal — ops alert for your notify address
• Customer — polite status update (draft only)

8. Human-in-the-loop (HITL) approvals

Safe by default: tracking and drafts never need approval. Destructive shipping ops do.

python -m src.cli propose-cancel --order MB-10418
python -m src.cli pending
python -m src.cli approve --id shp_xxxxxxxx
# or
python -m src.cli reject --id shp_xxxxxxxx

Live ShipStation mutations run only after approval and when API credentials + action handlers are enabled.

9. Using Hermes

The agent is registered as Hermes skill shipping-assistant.

hermes -s shipping-assistant -z "Scan shipping exceptions and draft WISMO for the worst order"

Hermes can run CLI tools under agents/shipping-assistant. Prefer explicit commands for production ops; use natural language for exploration.

10. Full order-to-delivery flow

How the SHIP agent maps to Matrixly’s logistics story on the homepage:

1. Order capture — orders land in ShipStation from your stores/channels.
2. Rate & label — carriers UPS / FedEx / USPS via ShipStation; label actions need HITL.
3. In transit — list / track / exceptions.
4. Delivery & WISMO — confirm delivered; draft customer updates when delayed or excepted.

Open multi-agent logistics flow on the homepage →

11. Troubleshooting

12. FAQ