OpenRouter Analytics API: Build a Per-Agent Cost and Usage Ledger

Vercel AI SDK 7 is more than a version bump. Its WorkflowAgent, Skills, MCP Apps, durable runs, and observability features change where an agent stores state and how a team reviews failures. My migration rule is to move workflow state deliberately, keep provider credentials behind a gateway, and test resume behavior before production traffic changes.

Key takeaway

• Treat WorkflowAgent as orchestration, not model routing.
• Skills and MCP Apps improve reuse; permissions still belong to your app.
• Durable runs need idempotent steps and replay tests.
• Pin the SDK and document every experimental feature.

Figure 1. The release page is the primary evidence for the SDK surface.

What changes in a migration

A chat loop can hide state in memory. A durable workflow cannot. Each tool step needs stable input, bounded retries, and a record saying whether its side effect already happened. Capture fixtures for the old loop and compare tool calls, not only final text.

Figure 2. Keep model/API access separate from workflow orchestration.

Where SandBase fits

SandBase can provide a shared gateway for language, image, video, embedding, and third-party APIs while the SDK owns workflow state. Keep the key server-side and attach a request ID to every run. Record provider, model, latency, and spend so a migration becomes an evidence-backed comparison.

Figure 3. A gateway centralizes credentials, routing, and budget controls.

Migration checklist

Pin the SDK, make durable steps idempotent, test pause/resume/retry, separate approval from discovery, and compare cost per successful workflow. The trade-off is operational complexity: durable runs buy recoverability but add storage, replay, and schema work.

Sources: Vercel AI SDK 7, SandBase Docs.

The decision I would make first

The first implementation decision is not a framework choice. It is the boundary around a side effect. A model response can be retried; a payment, repository write, notification, or data export cannot be treated as an ordinary retry. Give each side effect an idempotency key, persist the approval decision, and make the retry outcome visible to the operator.

A practical run record contains a stable run ID, the actor, the requested goal, model and provider, tool name, validated arguments, approval state, start and end timestamps, token or usage fields, and final status. Keep the raw payload separate from the searchable index so retention and redaction policies remain possible. This is also where a shared SandBase gateway helps: the application can attach one request identity to language, image, video, embedding, and external API calls without exposing credentials in browser code.

Failure cases worth simulating

Do not stop at the happy path. Simulate a provider timeout after the tool has accepted the request, a duplicate webhook, a malformed tool argument, a revoked permission, a partial stream, and a budget limit reached halfway through a run. For each case, write down the expected user message, operator alert, persisted state, and safe retry behavior. If the team cannot answer those four questions, the workflow is not ready for a larger audience.

A useful review is to replay the same fixture twice. The second run should either produce the same read-only result or clearly refuse to repeat the side effect. Compare traces and ledger rows, not only the final prose. The exact behavior depends on the provider, SDK version, endpoint, and deployment configuration; the examples here are a design checklist, not a benchmark or a claim of universal support.

When another option is better

A managed workflow surface is attractive when the team needs resumability, scheduling, or shared observability. A small custom loop is often better for one short request with no side effects. A provider-native API may be preferable when a feature is newly released and the gateway has not exposed the required parameter. The right choice is the smallest surface that makes the failure mode explicit.

A release note template

Record the source date, package version, enabled flags, supported endpoints, known limitations, rollback commit, and one example trace. Ask a second engineer to reproduce the setup from that note. This catches a common publishing and operations mistake: describing a capability that exists in an announcement but is not enabled in the exact route the reader will call.

Final checklist

• Source claim and retrieval date recorded.
• Reader task answered in the first section.
• At least one failure path and one trade-off explained.
• Screenshot is interpreted as evidence in nearby text.
• API key remains server-side.
• EN and ZH versions are native rewrites, not copied paragraphs.