imokokok

Posted on Sep 26

An AI Agent Paused. What Should Your Code Do Next?

#ai #web3

An automated trading workflow can pause because it detected a risk, lacked sufficient evidence, or encountered a service failure.

These conditions need different recovery paths. If your application collapses them into one failed state, operators and retry logic lose information they need.

While building Insight, I have been working on making these distinctions visible through coverage, freshness, and assessment diagnostics.

1. Preserve the reason for stopping

Consider a hypothetical ETH → USDC swap.

Several quotes agree, but one source is too old and another has no known update timestamp. The application may lack enough eligible evidence to evaluate the trade under its configured policy.

That is a different situation from detecting significant disagreement between valid sources.

I would preserve three categories in the application's workflow record:

Risk detected: an evaluated condition crossed a policy threshold.
Evidence incomplete: required sources or assessment dimensions were unavailable.
Service failure: the application could not obtain or process the assessment.

These are application design categories, not Insight SDK enum values.

A service failure should retain request and error information. It should not be rewritten as zero market coverage.

2. Inspect coverage and freshness explicitly

Here is an assessment-only TypeScript example using the Insight SDK:

import { InsightGuard } from 'oracle-insight-guard';

const apiKey = process.env.INSIGHT_API_KEY;
if (!apiKey) throw new Error('INSIGHT_API_KEY is required');

const guard = new InsightGuard({
  apiKey,
  freshness: {
    maxSourceAgeSeconds: 300,
    maxAssessmentAgeSeconds: 60,
    minimumRemainingValiditySeconds: 15,
  },
});

const coverage = await guard.client.coverage({
  asset: 'USDC',
  chainId: 1,
  probe: true,
  maxSourceAgeSeconds: 300,
});

const assessment = await guard.assessSwap({
  source: {
    asset: 'ETH',
    destinationAsset: 'USDC',
    chainId: 1,
    action: 'swap',
    tradeAmountUsd: 1_000,
  },
  destination: {
    asset: 'USDC',
    destinationAsset: 'ETH',
    chainId: 1,
    action: 'swap',
    tradeAmountUsd: 1_000,
  },
  receipt: {
    settlementChainId: 1,
    maxSlippageBps: 50,
  },
});

console.log(JSON.stringify({
  coverage,
  diagnostics: assessment.diagnostics,
  freshness: assessment.freshness,
}, null, 2));

Install the package with npm install oracle-insight-guard. Run the example in a trusted server or agent runtime with an Insight API key. It makes metered API requests; it does not sign or broadcast a transaction.

The freshness thresholds above are example application settings, not universal requirements for every asset or strategy.

Important distinctions:

Retrieval time and source update time are separate.
Unknown source age cannot satisfy a configured age requirement.
Coverage must match the requested evidence chain.
Unsigned coverage diagnostics do not replace a signed assessment or authorize execution.
A requested but unavailable assessment dimension has not passed its check.

3. Make recovery conditional

A useful recovery policy can specify:

Risk detected: obtain a new assessment or require human review.
Evidence incomplete: obtain the missing evidence, then evaluate the policy again.
Service failure: resolve or retry the operation, then complete the assessment.

A successful retry establishes that the operation succeeded. The application still needs to evaluate the returned evidence.

Refreshing an assessment also creates a new evidence commitment. If the previous authorization bound the old commitment, obtain a new authorization before proceeding.

4. Recheck at the actual execution boundary

Evidence continues to age while a transaction is prepared and signed.

An earlier freshness check cannot account for every later delay. The executor should validate the applicable deadlines at actual dispatch, including delays inside its own submission callback.

Insight supplies assessment evidence and diagnostics. The application owns its execution policy. When using PriorSeal, authorization and observed execution can be linked to the relevant evidence through an exact-call workflow.

What I would record

For each paused workflow, preserve:

Workflow and request identifiers.
Asset and evidence-chain scope.
Policy version and freshness requirements.
Available and unavailable assessment dimensions.
Excluded sources and their reasons.
Evidence references and relevant timestamps.
The recovery condition and subsequent decision.

Keep credentials and private keys out of these records.

The goal is to give the application enough information to decide what recovery requires—and give a reviewer enough information to understand that decision.

How does your agent distinguish an assessed risk from an incomplete assessment?

DEV Community