Why did my agent run fail?

When an agent run doesn't do what you expected, open the run and read its message and audit trail first — the run records every model call and tool call, so the failure point is almost always visible there. A run.finished row with empty unit counts — no model call at all — is the biggest clue: it means a guard fired before the agent could think. See Audit trail for how to read a run's records.

No runtime model

An agent needs a runtime model to think with. If the agent has no model pinned, or the pinned model isn't allowed on your account, the run stops before any model call. Fix it by pinning an allowed model — see Choosing a model.

Missing platform key

The model the agent uses needs a provider key behind it. If the platform key for that provider isn't configured, the dispatcher short-circuits and the run finishes without a model call. Read the run's first message — it names the guard that fired.

Out of credits

Credit-burning actions refuse when the wallet is empty. A run that needs a paid model call or a paid tool (like web_fetch) stops with an insufficient_credits signal. A run can also be blocked by a spend cap (a run.budget_blocked row). Top up at /a/<slug>/billing/credits — see Credits and pricing — or raise the cap, then re-run.

Connector or credential problem

If the agent tried to read a connector and the underlying credential is missing or expired, the tool call fails. Re-check the connector with connector.list and refresh or re-authorize the source.

Still stuck?

Compare a failing run to a successful one on the same agent. The audit trail diff usually points straight at the tool call or model call that changed.