Framework guide

Monitor and control Vercel AI SDK agents in production

The Vercel AI SDK gives you one API for many model providers and makes tool-calling agents short to write. In production you also need cost per agent, alerts, and a way to pause or change an agent without a deploy. This guide adds that with Agent Control Panel around a generateText call with tools. The code was run against the real ai package before we published it.

By the Agent Control Panel teamPublished 4 min read

On this page
  1. What you get
  2. Set up
  3. Wrap each generateText call
  4. Answer users while the agent is paused
  5. How we tested this code
  6. Frequently asked questions

What you get

  • Every run, with cost. Status, duration, tokens of every model call in the run, the model, the question and the answer, per agent.
  • Pause and stop. From the dashboard, or automatically when an alert rule fires on daily spend, error rate, a spend anomaly or a lost heartbeat.
  • Model swaps without a redeploy. Pick another model in the dashboard; the next run uses it.
  • Approved prompt changes. An owner or admin approves a new prompt; the next run uses it.
  • Liveness. A heartbeat every 30 seconds, so a crashed worker shows up as lost, not as quiet.

Model calls still go from your app to the provider with your own keys. If Agent Control Panel is unreachable, your agent keeps working: see fail-open vs in-path.

Set up

  1. Create an app in Agent Control Panel and copy its API key, agent ID and webhook secret. New apps start in monitor scope; allow the control scope when you are ready to pause and swap models.
  2. Install the SDK next to the AI SDK: npm install agent-control-panel ai @ai-sdk/openai zod.
  3. Create the client once at startup and call start(), as in the quickstart.

Wrap each generateText call

Agent Control Panel’s SDK reads the AI SDK’s result directly, so the call goes into the wrapper unchanged. Only the system prompt and the model id come from Agent Control Panel, each with your own default.

import { generateText, stepCountIs, tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import { acp } from "./acp"; // createClient(...) + acp.start(), see the quickstart

const DEFAULT_PROMPT = "You are a helpful support assistant."; // used when ACP has no prompt or cannot be reached

const tools = {
  orderStatus: tool({
    description: "Look up an order",
    inputSchema: z.object({ id: z.string() }),
    execute: async ({ id }) => getOrderStatus(id), // your code
  }),
};

export async function answer(question: string) {
  const system = (await acp.fetchPrompt()) || DEFAULT_PROMPT;              // the approved prompt
  const modelId = acp.getEffectiveModel("gpt-4.1-mini") ?? "gpt-4.1-mini"; // a model swap from ACP, or your default

  // ACP reads the answer from result.text and the tokens from result.usage, which in AI SDK 7 covers every step.
  return acp.wrapAgentRun(
    () => generateText({ model: openai(modelId), system, prompt: question, tools, stopWhen: stepCountIs(5) }),
    { userInput: question, modelUsed: modelId },
  );
}

The wrapper returns the AI SDK’s result as it is, so result.text, tool results and steps work as before. To move an agent to another provider, choose the provider from the model id, for example anthropic(modelId) for Claude models. A pushed prompt applies at once when your app receives Agent Control Panel’s signed webhook; without a public webhook URL it applies within 60 seconds, and model swaps and pauses within one 30-second heartbeat.

Answer users while the agent is paused

While the agent is paused or stopped, the wrapper throws AgentPausedError before your agent runs, so no model is called and no tokens are spent. Catch it where you answer the user:

Node.js

import { AgentPausedError } from "agent-control-panel";

try {
  reply = await answer(question);
} catch (err) {
  if (!(err instanceof AgentPausedError)) throw err;
  reply = "The assistant is paused right now. Please try again later.";
}

After a restart, the first run waits up to three seconds for Agent Control Panel’s answer, so a pause holds across deploys. If no answer comes in time the run goes ahead.

How we tested this code

On November 10, 2026 we ran this example against ai 7.0.166 with the AI SDK’s own mock language model and a stand-in Agent Control Panel server, so the test needed no API keys. The agent called the tool and then answered, and we checked that:

  • the run was reported once, as a success, with the tokens of both steps, the model, the question and the answer;
  • a model swap and a pushed prompt were used on the next run;
  • after a pause, the next call threw AgentPausedError and the model was not called.

In AI SDK 7, usage on the result adds up every step; that is what the SDK reports. Agent Control Panel records each run as one record, not a step-by-step trace. Streaming with streamText is not covered here; report those runs with reportRun when the stream ends.

Frequently asked questions

Does Agent Control Panel work with the Vercel AI SDK?

Yes. The Node.js SDK reads the answer text and token usage from AI SDK results, so a generateText call can be wrapped unchanged.

Does it work with any provider the AI SDK supports?

Yes. Your app still calls the provider through the AI SDK with your own keys. To swap across providers from the dashboard, choose the provider function from the model id in your code.

Are tool-calling steps counted?

Yes. In AI SDK 7 the result’s usage adds up every step, so a run that calls a tool and then answers is reported with the tokens of both steps.

What about streamText?

This guide covers generateText. For streaming, report the run with reportRun when the stream finishes, including the tokens from the final usage.