Ocean Conditions Judgment Agent

A multi-agent system that checks live tide, swell, and wind data for La Jolla, CA surf spots and makes the same kind of judgment call a local surfer would — instead of applying fixed thresholds to noisy, sometimes-conflicting public data.

Built for the Kaggle "AI Agents: Intensive Vibe Coding" capstone — Freestyle track.

The problem

Surf forecast sites either dump raw numbers on you (swell height, period, direction, tide, wind — good luck synthesizing that per spot) or hide the reasoning behind a black-box "star rating." Neither approach transfers: what makes Windansea good is different from what makes La Jolla Shores good, and a threshold that works for one spot is wrong for another. That's a genuine reasoning task, not a lookup, which is exactly where an agent earns its keep over a script.

Related MCP server: Surf Forecast MCP

Why agents (not a script)

An earlier prototype (a different project) did most of its decision-making with hardcoded string/keyword matching and only called an LLM at fixed checkpoints to double-check an already-made decision. This project inverts that: the LLM is the decision-maker at both steps, and it can choose to take an action (sending an alert) rather than always following a fixed pipeline step. Concretely:

• Agent 1 (Conditions Analyst) decides how to weigh three disagreeing data feeds against each spot's specific local conditions — no if/else thresholds.

• Agent 2 (Surf Recommender) decides whether the analyst's assessment is strong enough, combined with what the user says they want, to be worth paging someone about — and it calls the alert tool itself if so.

Architecture

• Data tools (ocean_agent/tools/) — plain Python functions hitting three free, public, no-key-required government APIs: NOAA CO-OPS (tides), NDBC (buoy swell), NWS (wind). Each fails soft ({"error": ...}) instead of raising, so a bad upstream response becomes something the model can reason about rather than a crash.

• ocean_agent/agents.py — two LlmAgents built with Google ADK, composed with SequentialAgent, wired to Claude models via the LiteLlm model wrapper (so the ADK framework and its session/state machinery are real, while the actual model calls go to Anthropic).

• ocean_agent/orchestrator.py — runs the pipeline through ADK's InMemoryRunner for a single CLI/MCP invocation.

• ocean_agent/mcp_server.py — an MCP server (stdio transport) exposing the raw data tools and the full pipeline as MCP tools, so any MCP client (Claude Desktop, Claude Code, another agent) can call this system directly instead of only being usable via the CLI.

• ocean_agent/tools/alerts.py — the one tool that can take a real-world action. See Security below.

Security features

• No secrets in code. The only credential needed (ANTHROPIC_API_KEY) is read from the environment (.env, gitignored); .env.example documents the variable without a value. Everything else is a public, keyless API.

• Webhook allowlist. send_surf_alert refuses to POST to any ALERT_WEBHOOK_URL that isn't a hooks.slack.com or discord.com/api/webhooks URL — so even if that env var were ever attacker-influenced, it can't be used to exfiltrate data to an arbitrary host.

• Alert cooldown / anti-spam. A 6-hour per-spot cooldown (alert_state.json) prevents a model mistake or repeated runs from spamming the same alert.

• Fail-soft data tools. Network/parsing failures on any of the three upstream feeds return a structured error instead of raising, so a flaky government API can't crash the agent or silently corrupt its reasoning.

Setup

Requires Python 3.10+ (the mcp package requires it).

python3 -m venv venv        # use a Python 3.10+ interpreter
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env    # add your ANTHROPIC_API_KEY (console.anthropic.com)

Sanity check the data feeds (no LLM, no API key needed):

python cli.py --test-tools

Run the full agent pipeline:

python cli.py "I'm a longboarder, low crowd tolerance, willing to drive a bit further for a better spot"

Run as an MCP server (for Claude Desktop / Claude Code / another MCP client):

python -m ocean_agent.mcp_server

Point your MCP client config at this command with cwd set to this repo and ANTHROPIC_API_KEY in its environment.

Deployability

The included Dockerfile builds a runnable image with no baked-in secrets:

docker build -t ocean-conditions-agent .
docker run --rm -e ANTHROPIC_API_KEY=sk-... ocean-conditions-agent "any preference"

This is deployable as-is to Cloud Run, Fly.io, or any container host that lets you inject ANTHROPIC_API_KEY as a runtime secret/env var — no code changes needed, since the app never assumes a specific host environment.

Project structure

ocean_agent/
  config.py          # NOAA/NDBC/NWS station IDs + per-spot local surf notes
  agents.py           # the 2 LlmAgents + SequentialAgent (Google ADK)
  orchestrator.py      # ADK InMemoryRunner wrapper
  mcp_server.py         # MCP server exposing tools + pipeline
  tools/
    tide.py, buoy.py, wind.py   # public data fetchers
    alerts.py                    # rate-limited, allowlisted alert delivery
cli.py                # terminal entrypoint
Dockerfile
requirements.txt

Known limitations

• The buoy (NDBC 46225) is offshore of Torrey Pines, the closest real-time buoy to La Jolla — it's a proxy for La Jolla swell, not an exact reading.

• Per-spot notes in config.py are a fixed, hand-written knowledge base; a natural extension is an "onboarding" step where an agent derives new spots' characteristics from a description instead of a human writing them.