On this page
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
- 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.
- Install the SDK next to the Agents SDK:
npm install agent-control-panel @openai/agents zod, orpip install agent-control-panel openai-agents. - Create the client once at startup and call
start(), as in the quickstart.
Wrap each agent run
Three things change in your code: the instructions come from Agent Control Panel (with your own default), the model comes from it (with your own default), and the run goes through the wrapper. agent-control-panel reads the run result as it is (npm 0.3.4 and PyPI 0.1.4 or later): the final output and the usage of every model call in the run, so no adapter code is needed.
Node.js (TypeScript)
import { Agent, run, tool } from "@openai/agents";
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 orderStatus = tool({
name: "order_status",
description: "Look up an order",
parameters: z.object({ id: z.string() }),
execute: async ({ id }) => getOrderStatus(id), // your code
});
export async function answer(question: string) {
const instructions = (await acp.fetchPrompt()) || DEFAULT_PROMPT; // the approved prompt
const model = acp.getEffectiveModel("gpt-4.1-mini") ?? "gpt-4.1-mini"; // a model swap from ACP, or your default
const agent = new Agent({ name: "Support", instructions, model, tools: [orderStatus] });
// The SDK reads the run result as it is: the answer from finalOutput, the tokens of every model call in the run
// from its usage (agent-control-panel 0.3.4 or later).
const result = await acp.wrapAgentRun(() => run(agent, question), { userInput: question, modelUsed: model });
return String(result.finalOutput ?? "");
}
Python
import asyncio
from agents import Agent, Runner, function_tool
from acp_setup import acp # create_client(...) + acp.start(), see the quickstart
DEFAULT_PROMPT = "You are a helpful support assistant." # used when ACP has no prompt or cannot be reached
@function_tool
def order_status(order_id: str) -> str:
"""Look up an order."""
return get_order_status(order_id) # your code
async def answer(question: str) -> str:
instructions = await asyncio.to_thread(acp.fetch_prompt) or DEFAULT_PROMPT # the approved prompt
model = acp.get_effective_model("gpt-4.1-mini") # a model swap from ACP, or your default
agent = Agent(name="Support", instructions=instructions, model=model, tools=[order_status])
# The SDK reads the run result as it is: the answer from final_output, the tokens of every model call in the
# run from its usage (agent-control-panel 0.1.4 or later).
result = await acp.wrap_agent_run_async(lambda: Runner.run(agent, question),
user_input=question, model_used=model)
return str(result.final_output)
Creating the Agent on each call is cheap and means a model swap or a new prompt applies on the very next run. 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.";
}
Python
from agent_control_panel import AgentPausedError
try:
reply = await answer(question)
except AgentPausedError:
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 both examples against @openai/agents 0.21.0 and openai-agents 0.24.0 for Python, with a stand-in model and a stand-in Agent Control Panel server, so the test needed no API keys. On November 11 and 12, 2026 we ran both examples as shown, with no adapter, on agent-control-panel 0.1.4 (PyPI) and 0.3.4 (npm). In each language 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 model calls, 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 raised
AgentPausedErrorand the model was not called.
What it does not do: Agent Control Panel records each run as one record, not a step-by-step trace of tool calls and handoffs. The Agents SDK’s own tracing keeps working alongside it. Streaming runs are not covered here; report them with reportRun when the stream ends.
Frequently asked questions
Does this work with the Python and the TypeScript Agents SDK?
Yes. The guide shows both. In Python, use wrap_agent_run_async around Runner.run; in TypeScript, wrapAgentRun around run. The SDK reads the run result as it is (npm 0.3.4 and PyPI 0.1.4 or later).
Does Agent Control Panel replace the Agents SDK’s tracing?
No. Tracing shows each step of a run for debugging. Agent Control Panel records each run with its cost and lets you pause, stop or change the agent in production. They work side by side.
Do my OpenAI calls go through Agent Control Panel?
No. The Agents SDK calls OpenAI directly with your key. Agent Control Panel only receives the run report and sends signed commands back.
How are tokens counted for runs with tool calls?
The run’s usage from the Agents SDK adds up every model call in the run, so a run that calls a tool and then answers is reported with the tokens of both calls.