Your AI Agent Can Now Call Tools. That Does Not Mean It Is Ready for Production
A production checklist for agent APIs covering permissions, state, retries, observability, human approval, and the failure modes hidden by demos.
The demo skips the expensive part
An agent demo usually shows a clean request, a few successful tool calls, and a polished final answer. Production is the same workflow surrounded by stale records, partial outages, duplicate events, hostile input, ambiguous authorization, and users who change their minds halfway through. A capable model can make decisions across tools; that capability increases the number of places where a product can fail.
The current shift is visible in official platform announcements. OpenAI's Agents API describes a public-beta surface for building and running cloud agents. Similar product direction across the industry makes it easier to connect a model to browsers, code, files, and business systems. Teams can ship a prototype quickly, but the existence of a managed agent runtime does not transfer responsibility for what the agent is allowed to do.
Before launch, define the agent's job in terms of permitted outcomes. “Handle refunds” is dangerously broad. “Look up an order, summarize the applicable policy, and prepare a refund request for a human to approve” is bounded. The distinction is not cosmetic: it decides whether a model can move money or only prepare a reversible proposal.
Put the action boundary in code
Treat every tool as an API with a security boundary. Give each agent the smallest set of tools needed for its task. Prefer read-only access by default. Separate proposing an action from executing it, and make the execution step require explicit authorization when the action changes money, access, customer data, or production state. Do not rely on a prompt saying “be careful” to enforce a permission.
For every tool, document:
- accepted arguments and strict validation rules
- the identity and scope used when calling the underlying service
- whether the operation is read-only, reversible, or irreversible
- timeout, retry, and rate-limit behavior
- what the user sees before an action is committed
- how the action is audited and undone
Validate tool arguments in ordinary application code. An agent that proposes a customer ID must not gain access to that customer merely because the ID is syntactically valid. Re-check authorization at execution time, because permissions can change after the model formed its plan. Use idempotency keys for retried mutations so a network timeout does not create two refunds or two tickets.
Model the run as a state machine
Long-running agents need explicit states such as received, planning, waiting for approval, executing, completed, failed, and cancelled. Persist the run ID, tool-call IDs, relevant input references, and a bounded event history. If the process restarts, it should resume from a known state or stop safely; it should not guess whether a previous action succeeded.
Set limits on steps, wall-clock time, token use, and repeated calls to the same tool. A model can loop between search and retrieval while appearing busy. A hard budget turns an accidental loop into a visible failure instead of an uncapped bill. Classify tool errors: retry a transient 503 with backoff, do not retry an invalid argument unchanged, and ask for human input when a required decision is missing.
Cancellation deserves first-class design. When a user cancels, stop scheduling new work, signal in-flight tools where possible, and report which actions already completed. A cancellation that merely hides a spinner while the agent continues sending messages is not cancellation.
Design approval around risk
Human approval should appear at the point where the reviewer has enough information to decide. Show the proposed action, target, relevant source evidence, expected effect, and a clear decline path. Do not ask users to approve a vague “continue?” after the model has already made several hidden changes. For low-risk read-only steps, approval can be unnecessary; for high-impact changes, require it even if the model is highly confident.
Test the approval path with stale data, a modified proposal, repeated clicks, and an approver who lacks permission. Bind approval to the exact action payload so an agent cannot ask for approval on one change and execute a different one afterward. Log the approver and the approved payload, while applying your organization's retention and privacy rules.
Instrument outcomes, not just tokens
Log model version, prompt version, tool name, duration, retry count, approval state, and final outcome. Redact secrets and minimize personal data. Use trace IDs to connect the agent run to application and vendor logs. Monitor completion rate, human correction, unsafe-action attempts, abandonment, p95 latency, and cost per completed task. A cheaper run is not a win if it creates more support escalations.
Build an evaluation set from real task patterns and adversarial cases. Include prompt injection in retrieved pages, tool outages, malformed outputs, duplicate webhooks, authorization changes, and a task that has no safe answer. Verify that the agent stops or asks for help in each case. Run the set after model, prompt, tool, or policy changes.
Launch in shadow mode first: produce recommendations without executing them, then compare them with human decisions. Move to a small canary only after the system demonstrates stable behavior. Keep a kill switch that disables mutations while leaving read-only assistance available. An agent is production-ready when its authority, failure behavior, and recovery path are as clear as its happy-path demo.