Hugging Face details Shippy agent architecture and hosting platform

Allen Institute for AI (AI2) described the architecture and engineering lessons behind Shippy, a maritime AI agent built for high-stakes operational decisions where incorrect outputs carry real-world consequences.

Shippy’s design centers on reliability rather than model capability alone, with a focus on verifiable correctness against live data streams and continuous satellite and vessel signals rather than static snapshots.

The team decomposed the agent into three components: a soul (system prompt defining persona and behavioral boundaries), skills (versioned markdown files specifying how to handle requests), and config (runtime settings including the agent harness and model choice). Skills follow the same agent-skills specification used by coding agents like Claude Code and Codex.

Shippy currently relies on Claude Opus 4.6 as its LLM and uses OpenClaw, an open-source agent framework, as its runtime harness. The model and framework are configured at runtime via config changes rather than rebuilds, enabling swaps without altering the core agent artifact.

To constrain nondeterminism, Shippy interacts with the Skylight API through a purpose-built CLI that wraps complex API inputs—filter objects, pagination cursors, and geometry—into predictable commands. The CLI self-documents with extensive help text and writes outputs to local JSON files to avoid shell buffer limits and downstream tool breakage.

Under the CLI sits a standardized API layer exposing multiple resource types (events, vessels, regions, imagery, tracks) through typed schemas and common operations like search and aggregate. This layering allows each component—API, CLI, and skills—to be tested independently.

For multi-tenant safety, every user session runs in an ephemeral, isolated Kubernetes deployment via Mothership, AI2’s agent hosting platform. User-specific Skylight JWTs are injected at provision time, ensuring API calls and conversation history remain scoped to the individual analyst and never cross user boundaries.

The system prompt explicitly forbids legal determinations and speculation beyond supported data, making boundaries auditable and revisable without fine-tuning. Shippy can chain multiple skills in a single turn, such as combining Skylight data queries with partner databases like ProtectedSeas for marine protected area boundaries and Global Fishing Watch for vessel metadata.