Agent Developer Guide

Overview

Freight Rate Intelligence is designed for AI-first consumption. Every skill is available as:

1. REST API — Standard HTTP endpoints at /v1/*
2. MCP Tools — Model Context Protocol tools at /mcp/tools
3. Agent Invoke — Unified agent endpoint at /v1/agent/invoke/:skill_name

Agent Registration

Get Agent API Key

Sign up for a Starter plan or above. Generate an API key from Dashboard → Settings → API Keys. API keys use the fri_ prefix (e.g. fri_abc123...).

Discover Available Skills

GET /v1/agent/skills
Authorization: Bearer fri_YOUR_KEY

Available skills:

• rate-lookup — Cost-basis rate estimate (Explorer tier)
• diesel-trend — PADD regional diesel price trends (Explorer tier)
• fuel-surcharge — ATA/DOE surcharge calculation (Explorer tier)
• market-analysis — Macro freight intelligence (Starter tier)
• lane-comparison — Side-by-side lane comparison (Starter tier)
• rate-alerts — Threshold monitoring (Starter tier)
• carrier-capacity — Regional capacity pressure (Starter tier)
• audit-report — Receipt-chain provenance (Professional tier)
• rate-forecast — Forward projections (Professional tier)

Constitutional Commerce

Every agent invocation goes through:

1. Gate — Tier check + rate limit enforcement
2. Handler — Skill execution with real data
3. Receipt — Hash-chained receipt for the query
4. Attribution — AUTH.OBJ linking all data sources
5. Royalty — ECON.ROY event for metered billing
6. Relay — AGENT.RELAY record for agent-to-agent tracing

Best Practices

1. Cache wisely — Response data includes factor_versions with timestamps. Use these to decide when to refresh.
2. Store receipts — Keep receipt_id from every call for audit compliance.
3. Handle 403s — Some skills require higher tiers. Check the tier_required field in skill discovery.
4. Use bulk discounts — High-volume agents get per-request discounts on Enterprise tier.
5. Set alerts — Use rate-alerts skill to monitor lanes instead of polling.