Inspiration

StateGuard started with a problem I kept running into while working on my trading bot. After restarts and updates, the bot’s saved state could get out of sync with trades that were still open. Before letting it continue, I had to check what the bot believed against what was actually happening on the exchange. That made me think about the same problem in other automations. What happens when an agent resumes with an incomplete picture of an action it already took? I wanted a way to catch that disagreement before it causes another mistake.

What it does

StateGuard checks whether an automation’s internal state agrees with evidence from the system it is working with. When the evidence is uncertain, it holds the next action. When it finds a conflict, it investigates, explains what it found, and asks for approval before reconciling the state. The trading-bot problem inspired the project. For the working demonstration, we used email delivery so we could test the same failure pattern without placing real trades: an action succeeds, its acknowledgment is lost, and the worker considers trying again.

How we built it

We built StateGuard in Python using FastAPI, SQLite, and a JavaScript dashboard. A Strands agent reads the saved attempt and checks fresh provider evidence through tools. It produces a structured explanation that the user can inspect alongside the actual tool calls. The model handles the investigation. Application code handles the action restrictions and approval checks. An explanation from the agent cannot authorize a resend. We also built a sandbox to exercise different outcomes, including confirmed delivery, pending confirmation, and an unavailable provider.

Challenges we ran into

The hardest part was deciding what the system should do when it could not tell whether an action had succeeded. Automatically retrying can create a duplicate, but stopping everything indefinitely is not useful either. We had to make uncertainty an explicit state and keep the workflow paused until there was enough evidence to make a decision. We also ran into practical integration problems. Bedrock inference was blocked by account quotas, so we used OpenAI through Strands for the live demo. Testing with a real provider also exposed assumptions that worked in the sandbox but needed more careful handling outside it.

Accomplishments that we're proud of

We turned a recurring problem from my own trading bot into a working recovery flow. StateGuard now stores attempts, checks external evidence, runs a real agent investigation, and requires a current approval before reconciling state. We demonstrated that flow against a real email provider without sending another message during recovery. We also have 37 passing tests, including checks for concurrent retries, stale approvals, missing evidence, and ambiguous results.

What we learned

A restart does not reset the outside world. Open trades, sent messages, and other actions can still exist even when an automation has lost track of them. We learned that saving state is only part of the problem. The system also needs a way to check that state before continuing. We also found that giving an agent useful tools does not mean giving it control over every action. It can investigate and explain while the application keeps clear limits on what can happen next.

What's next for StateGuard

I want StateGuard to become something people can rely on whenever their automations restart, lose connection, or pick up unfinished work. They shouldn’t have to manually check every open trade, sent message, or pending action before trusting the system to continue. We’ll start by returning to the trading-bot problem that inspired it, then expand to other workflows where losing track of an action has real consequences. The long-term goal is for an automation to recover with a clear account of what happened, what is still uncertain, and what needs a person’s decision.

Built With

• css3
• fastapi
• google-gmail-oauth
• html5
• javascript
• openai
• pydantic
• pytest
• python
• sqlite