Agent reliability often fails at a small but consequential boundary: the model calls a tool, the connection drops, and nobody can tell whether the operation completed. The tempting response is to retry. That can duplicate the action.
The safer engineering rule is simple: when success is uncertain, pause and require evidence before continuing. The send-to-dot 0.3.0 preview describes exactly that behavior. Its delivery flow uses a one-time link valid for 2 minutes, and when the result is uncertain, it stops rather than sending the image again. The preview reports about 45 seconds for one image and about 20 additional seconds for each subsequent image, while its original target was 30 seconds. That is a useful lesson for an AI agent development project: correctness under ambiguity matters more than making every workflow look fast.
A small team can turn that lesson into an idempotency ledger: a Python endpoint that assigns an operation ID, records every state transition in SQLite, and exposes a hosted HTML page for inspection.
What problem should the ledger solve?
The ledger should answer one operational question: did this exact tool operation finish, fail, or become uncertain?
The market evidence points to this need from several directions. A published AI Agent engineering course describes a move from single-turn chatbots toward agents with planning, memory, collaboration, and model-controlled execution flow. It also identifies malformed tool calls, loops, oversized conversational context, missing tracing, and prompt-injection risk as production obstacles.
Those are not separate dashboard problems. They create ambiguous execution states. An agent may have emitted a valid tool request, the endpoint may have started processing it, and the response may have disappeared before the agent received it. Without a durable record, the next model step cannot distinguish “never started” from “completed but not acknowledged.”
The ledger does not need to solve every agent reliability problem. Its first useful boundary is narrower: prevent an uncertain operation from being executed again automatically.
A minimal record can include:
- `operation_id`: a unique identifier generated before the tool call;
- `tool_name`: the logical operation being attempted;
- `request_fingerprint`: a stable representation of the request inputs;
- `state`: `created`, `running`, `succeeded`, `failed`, or `unknown`;
- `created_at` and `updated_at`: timestamps for reconstruction;
- `result_reference`: a compact result or operator-provided evidence;
- `error_detail`: enough information to investigate a failure without hiding it.
The exact schema is an implementation choice, so its suitability for a particular production workload is unverified. The important property is that the operation ID and state are persisted before the external side effect begins.
Why does uncertainty deserve its own state?
`unknown` must be a first-class state because a timeout is not proof of failure. The send-to-dot preview makes the same distinction operationally: an uncertain send is stopped and must be verified with real evidence before it can be released. The preview also describes connection checks and more complete audit logs, which reinforces the value of recording what the system knew at each step.
A practical state machine can follow this rule:
- Create an operation ID and insert `created` into SQLite.
- Move the record to `running` immediately before the tool call.
- Move it to `succeeded` only after a trustworthy success response is available.
- Move it to `failed` only when the system has evidence that the operation did not complete.
- Move it to `unknown` when the request may have reached the tool but the outcome cannot be confirmed.
A retry is allowed for `created` only if no execution started. A retry is not automatic for `unknown`. An operator or a later verification tool must first attach evidence and make an explicit decision.
This design also gives the agent a smaller, safer control surface. Instead of asking the model to infer whether a timeout means “try again,” the tool response can return a precise instruction: `operation_id=...`, `state=unknown`, `retry_allowed=false`. The model can then pause, report the ambiguity, or call a separate verification operation.
The ledger will not prevent every duplicate. For example, it cannot guarantee the behavior of an external service that ignores operation IDs, and it cannot establish delivery semantics that the external tool does not expose. Those limits are unverified until tested against the actual tool. The ledger can still make uncertainty visible and block blind retries inside the workflow it controls.
How should the Python endpoint behave?
The endpoint should separate operation creation, execution, inspection, and verification so each decision is visible. VicroCode can support this shape through online Python execution, API Endpoint Hosting, in-platform tool calls, SQLite databases, and project publishing.
A small endpoint surface could look like this:
- `POST /operations`: validate the requested tool name and inputs, generate an operation ID, and persist `created`.
- `POST /operations/{id}/execute`: check that the record is eligible, set `running`, invoke the configured tool, and persist the confirmed outcome.
- `GET /operations/{id}`: return the current state and recorded evidence.
- `GET /operations`: return a filtered list for the audit page.
- `POST /operations/{id}/verify`: accept an operator or verification-tool result and transition an `unknown` record only when the evidence is sufficient.
The execution endpoint should reject a second execution when the record is `succeeded`, `running`, or `unknown`. It can return the existing result for a completed operation, which is the core idempotency behavior. For an uncertain record, the response should be explicit rather than optimistic.
SQLite is a reasonable starting point for a small tool because the ledger is structured, queryable, and easy to edit while the workflow is being tested. It is not evidence that the design is ready for high-concurrency production traffic. Locking behavior, concurrent workers, retention, backup, authentication, and access control would need separate testing; those capabilities are unverified here.
The agent-facing response should be deliberately boring. Return the operation ID, state, whether retry is allowed, and the next permitted action. Avoid returning a vague timeout message that leaves the model to improvise.
What belongs in the audit view?
The audit view should make ambiguous operations easy to find and hard to misread. A hosted HTML web app can present a table ordered by update time, with filters for `unknown`, `running`, and `failed`, plus a detail view for the request fingerprint, timestamps, tool name, result reference, and error detail.
The view should put the important decision near the state. An `unknown` row should show “verification required,” not a retry button that looks safe by default. A `succeeded` row should expose the recorded result reference and operation ID. A `failed` row should distinguish a confirmed failure from an execution that simply stopped reporting.
This is also where the “waiting for the agent” behavior becomes useful. One V2EX discussion asks what a person can do while an agent runs; replies include running eight projects in parallel. Parallel work increases the value of clear operation ownership. An operator should be able to leave one task running, inspect another task’s uncertainty, and return to the exact operation ID instead of relying on memory or a long chat transcript.
The first version should stay focused. Add search by operation ID, tool name, and state. Add a manual verification action with an evidence note. Keep the page readable without filling it with warnings and secondary labels; another market post specifically criticizes interfaces that add excessive prompts, warnings, and floating messages.
Where does VicroCode stop?
VicroCode can cover the Python endpoint, SQLite ledger, in-platform tool calls, hosted HTML audit view, and project publishing or sharing needed for this prototype. You can run Python online while iterating on the state machine, then use web app hosting for the audit page.
The proposed build does not include mobile sharing, private object storage, or ChatGPT integration. Those are part of the send-to-dot scenario, but they are outside VicroCode’s confirmed capabilities supplied for this task. The same boundary applies to any unlisted external service, deployment method, framework, or language: support is unverified unless separately confirmed.
The useful result is smaller than a complete agent platform. It is a durable decision record around tool calls. For an independent developer or operator, that is enough to test the most important behavior first: when the system cannot prove success, it stops, preserves the evidence, and gives a human or verification step a clear place to continue.
FAQ
Should an unknown operation be retried automatically?
No. An `unknown` operation should pause until a real success or failure signal is available. Blind retrying can duplicate an action that already completed.
Why store operation IDs before execution?
The operation ID creates a stable record before the external side effect begins. It lets the endpoint return the same operation state instead of treating every repeated request as new.
Can this ledger guarantee exactly-once execution?
No. Exactly-once behavior for an external tool is unverified unless that tool honors the operation ID and exposes suitable confirmation. The ledger can enforce safer retry decisions within the workflow it controls.