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, uniquerequest_hash— hash of normalized user inputstatus— queued | running | waiting_approval | retryable | failed | completedcurrent_step— stable step name, not free textattempt— integermodel_providerandmodel_namelast_event_id— last committed eventlease_until— prevents two workers from resuming the same runpending_approval_id— relation to an approvals tablelast_error_classandlast_error_messagecreated_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_idrun_idrelationsequencetype— model_requested, model_received, tool_started, tool_finished, approval_requested, approval_decided, checkpointpayloadJSONcreated_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
- Operations queue — running, retryable, or stale leases
- Approval inbox — waiting_approval with the original input, proposed action, and evidence
- 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?