A resumable AI agent run table in NocoBase: schema and retry rules

Long-running AI agents fail in a different way from normal CRUD requests: a model call may succeed, a tool may partially complete, and the process may restart before the final response is saved. A larger context window does not solve that. The workflow needs durable, inspectable state.

Here is a NocoBase pattern I would use for an agent_runs collection.

1. Core fields

  • run_id — UUID, unique
  • request_hash — hash of normalized user input
  • status — queued | running | waiting_approval | retryable | failed | completed
  • current_step — stable step name, not free text
  • attempt — integer
  • model_provider and model_name
  • last_event_id — last committed event
  • lease_until — prevents two workers from resuming the same run
  • pending_approval_id — relation to an approvals table
  • last_error_class and last_error_message
  • created_at, updated_at, completed_at

Keep large prompts, tool payloads, and receipts in related collections instead of one growing JSON field.

2. Add an append-only event table

Create agent_run_events with:

  • event_id
  • run_id relation
  • sequence
  • type — model_requested, model_received, tool_started, tool_finished, approval_requested, approval_decided, checkpoint
  • payload JSON
  • created_at

Add a unique constraint on (run_id, sequence). This gives you an audit trail and lets a worker rebuild the last safe state.

3. Use an idempotency key for every external action

For email, billing, ticket creation, or any other side effect, generate:

idempotency_key = run_id + step_name + logical_action_id

Store the external receipt before moving to the next step. A retry should first look for that receipt. If it exists, do not repeat the side effect.

4. Separate retryable and terminal errors

Retryable examples:

  • 429 or temporary 5xx
  • network timeout with no confirmed side effect
  • short provider outage

Terminal or review-required examples:

  • schema validation failure after the retry budget
  • ambiguous tool result
  • denied approval
  • a request that violates a business rule

A single generic retry flag makes production incidents much harder to reason about.

5. Resume with a lease

A worker may resume a run only if lease_until < now. It updates the lease atomically, reads the latest checkpoint and event, then continues from the next uncommitted step. Renew the lease during long tool calls.

6. Build three NocoBase views

  1. Operations queue — running, retryable, or stale leases
  2. Approval inbox — waiting_approval with the original input, proposed action, and evidence
  3. Failure review — grouped by error class, model, and workflow version

These views are more useful than a single “agent logs” page because each supports a concrete operator decision.

7. Make model routing replaceable

Keep the run contract stable when testing a different model. A unified API layer such as Tokatlas can help compare candidate models without rewriting the NocoBase schema or workflow: https://app.tokatlas.com

The important metric is not “API call succeeded.” It is “the run reached an accepted terminal state without duplicate side effects.”

How are people representing resumable agent state in NocoBase today: one run table, an event table, or both?