Building Reliable AI Agents: Key Architecture Lessons From the Shippy Maritime Assistant
AllenAI's Skylight team shares their architecture for Shippy, a high-stakes maritime AI agent built on Claude Opus 4.6. By structuring agents into "soul, skills, and config" and wrapping complex APIs in a deterministic CLI, they eliminated non-deterministic agent errors and API failures.
Impact: High
Why it matters
You can apply their three-part architecture (soul, skills, config) and CLI-wrapper pattern to make your own agentic workflows deterministic and highly reliable.
TL;DR
- 01Wrap complex, nested APIs in a typed, self-documenting CLI to eliminate malformed agent queries.
- 02Structure agents into distinct layers: "soul" (system rules), "skills" (markdown tasks), and "config" (runtime).
- 03To isolate user data, spin up ephemeral, network-restricted Kubernetes pods per session rather than sharing environments.
Key facts
- Active Model
- Claude Opus 4.6
- Agent Framework
- OpenClaw
- Configuration Format
- Markdown with YAML frontmatter
- Session Isolation
- Kubernetes Pods
The Three-Part Agent Specification
The Skylight team structures Shippy into three distinct, versioned components:
- Soul: The system prompt defining the agent's persona, boundaries, and explicit limitations (e.g., forbidding legal determinations). This is managed in prompts rather than fine-tuning to keep it auditable.
- Skills: Plain Markdown files with YAML frontmatter containing instructions, matching the specifications used by agent tools like Claude Code and Codex.
- Config: Runtime configurations specifying the agent harness (such as the open-source
OpenClawframework), the active model (currently Claude Opus 4.6), and secrets/keys injected at launch.
Collapsing API Complexity with a CLI Wrapper
Early versions of Shippy suffered from silent data drops and geometry errors when allowed to construct raw HTTP API queries. To solve this, developers built a deterministic Command Line Interface (CLI) helper. Instead of calling endpoints, Shippy runs local CLI commands like:
skylight events search --filter-flagsThe CLI handles schema validation, authentication, and output formatting. To avoid pipe buffer limits (especially with large datasets), the CLI writes the structured output to local JSON files on disk, which the agent reads programmatically in subsequent steps.
Dynamic Kubernetes Sandboxing
To guarantee enterprise-grade data isolation across over 70 countries, the team built Mothership, a session-hosting platform. For every chat session, Mothership provisions: 1. A dedicated Kubernetes deployment running the agent runtime, its skills, and the CLI. 2. Runtime injection of the user's JSON Web Token (JWT) to scope all API commands to their authorized data. 3. Strict network-level boundaries limiting outbound connections.
Try it in 2 minutes
---
title: query_events
description: "Query vessel events in an Exclusive Economic Zone"
tools:
- skylight_cli
---
# Skill Instructions
1. Resolve region name using regions API
2. Call `skylight events search --zone <polygon>`yaml
✓ When to use
- Building production AI agents interacting with complex, nested APIs.
- Designing high-stakes enterprise workflows where agent hallucination must be strictly bounded.
- Orchestrating agent runtimes with strict session-level data isolation.
✕ When NOT to use
- Simple chatbot wrappers that do not execute multi-step external tools.
- Prototype apps where setting up isolated Kubernetes pods is over-engineering.
What to do today
- Define agent system prompt boundaries (the "soul") separately from logic to simplify audit processes.
- Adopt the markdown-with-frontmatter schema for orchestrating custom tool instructions.
- Store large tool outputs to temporary local JSON files instead of piping them directly through shell scripts.
Sources