Agentic Trading
Decisions

ADR-0002: Agent runtime is Vercel AI SDK v6, routed via Vercel AI Gateway

Every Skill is, at its core, a structured call to an LLM with tools. We need an SDK that:

  • Status: accepted (SDK choice); superseded for the gateway portion by ADR-0010
  • Date: 2026-05-27

Context

Every Skill is, at its core, a structured call to an LLM with tools. We need an SDK that:

  • Supports multiple model providers so Skill authors can pick (Claude / GPT / Gemini) per Skill
  • Has first-class tool calling with type-safe schemas
  • Supports MCP so we can integrate the open ecosystem of trading-related tools
  • Has streaming primitives that work cleanly with Next.js for the chat agent
  • Runs in both Vercel Functions (sim, chat) and a Node service (live runner on Fly) without code branching

We considered Vercel AI SDK, OpenAI Agents SDK, Anthropic Claude Agent SDK, LangGraph, and Mastra. Detailed comparison in conversation history; key discriminators:

  • Per-Skill model swap: rules out single-provider SDKs (Claude Agent SDK, OpenAI Agents SDK natively)
  • Web streaming: AI SDK's toUIMessageStreamResponse is purpose-built
  • Lightweight: rules out LangGraph for what we need
  • Maturity: Mastra is too new to bet on

For the gateway, we considered Vercel AI Gateway, OpenRouter, Portkey, LiteLLM, and Cloudflare AI Gateway. Key factors: zero markup, BYOK support, observability, Vercel-platform integration.

Decision

Agent runtime: Vercel AI SDK v6. Model routing: Vercel AI Gateway, with BYOK support for users who bring their own provider keys.

All model calls — from the trading agent (Fly), simulator (Vercel/Fly), and chat agent (Vercel Function) — go through AI Gateway. We do not import provider SDKs directly anywhere in the codebase.

Alternatives considered

Alt A — OpenAI Agents SDK

  • Excellent multi-agent handoffs, guardrails, tracing
  • Other providers only via LiteLLM shim
  • Not picked: per-Skill model swap is a core product feature; fighting an SDK that assumes OpenAI is friction we don't need. Handoffs and guardrails are nice but not required for our single-agent trading loop; the Execution Engine is our real guardrail.

Alt B — Claude Agent SDK

  • Best-in-class for Claude-specific features (extended thinking, cache_control)
  • Claude-only
  • Not picked: same reason — model swap is core. Also optimized for agent loops with shell/file/MCP, more than we need.

Alt C — LangGraph

  • Most mature open-source agent framework, multi-provider
  • Graph orchestration is powerful but verbose for a single-agent decision loop
  • Not picked: too much abstraction for what we need; AI SDK is much lighter for the same outcome.

Alt D — Direct provider SDKs + own routing

  • Maximum control
  • Not picked: rewriting model routing, observability, BYOK handling = months of work we don't need to spend.

Alt E — OpenRouter as gateway

  • Largest model catalog, ~5.5% markup or BYOK
  • Not picked: we're on Vercel already; AI Gateway has zero markup, native integration, $5/mo free dev credits. OpenRouter remains a fallback for any future model not in Vercel's catalog.

Consequences

Positive

  • One-line model swap per Skill (skill.model = "anthropic/claude-sonnet-4.6" → "openai/gpt-5")
  • Provider abstraction we don't have to maintain
  • Streaming primitives we don't have to invent
  • MCP, prompt caching, structured outputs — all first-class
  • Same code path works on Vercel and Fly
  • AI Gateway gives us observability, cost tracking, fallback routing without integration work
  • BYOK path: users who hit cost limits can plug in their own Anthropic/OpenAI key with no fee

Negative / trade-offs

  • Coupling to Vercel as a platform (AI SDK is OSS, but Gateway is Vercel-hosted)
  • AI Gateway pricing model could change in future (currently 0% markup; if that ends, BYOK is our hedge)
  • If we ever want a feature only one provider offers and AI SDK lags exposing it, we're blocked until they ship support

Things we'll need to revisit

  • If we ever decide to commit to one model exclusively for cost / latency reasons, revisit whether the abstraction overhead of AI SDK is still worth it
  • If Vercel AI Gateway pricing changes materially, evaluate self-hosting LiteLLM in front of providers + BYOK

References

ADR-0001: MVP exchange is Hyperliquid

Previous Page

ADR-0003: Database is Supabase (Postgres + pgvector + Auth)

We need a primary data store. Requirements:

On this page

ContextDecisionAlternatives consideredAlt A — OpenAI Agents SDKAlt B — Claude Agent SDKAlt C — LangGraphAlt D — Direct provider SDKs + own routingAlt E — OpenRouter as gatewayConsequencesPositiveNegative / trade-offsThings we'll need to revisitReferences