Show HN: AgentState – Open-source resilience and caching proxy for AI agents

AgentState, an open-source resilience and caching proxy for AI agents, automatically checkpoints execution state in SQLite, handles retries, and enables pause, edit, and resume of runs from any point, saving tokens and time. In benchmark tests simulating complex 50-step autonomous agent runs with forced crashes, AgentState achieved crash recovery in ~0.015 seconds (7,360x faster than standard agents) and 100% token cost savings on retries via cache hits.

Stop wasting tokens when AI agents crash. When an agent fails on step 87 out of 100, you typically lose the entire execution history and have to restart from step 0. AgentState is a lightweight, self-hosted proxy that intercepts your LLM and tool calls, automatically checkpoints their execution state in SQLite, handles retries, and lets you pause, edit, and resume runs from any point—saving you money and time. python from agentstate import AgentStateOpenAI Automatically routes all completions through AgentState proxy client = AgentStateOpenAI session id="session user 9812", step number=0 response = client.chat.completions.create model="gpt-4o", messages= {"role": "user", "content": "Analyze system performance metrics."} python from langchain openai import ChatOpenAI from agentstate import wrap langchain llm = ChatOpenAI wrap langchain session id="session user 9812" python from crewai import Agent from agentstate import wrap crewai agent = Agent role="Research Analyst", goal="Analyze market data", llm config=wrap crewai session id="session user 9812" No SDKs required. Just point your LLM client's baseURL to the AgentState proxy: python from openai import OpenAI client = OpenAI api key="your-api-key", base url="http://localhost:8080/v1", <-- Route through AgentState default headers={"x-agent-session-id": "session user 9812", "x-agent-step-number": "0"} 🔌 1-Line Integration: Native AgentStateOpenAI wrapper or simple baseURL swapping for OpenAI, LangChain, and CrewAI. 💾 Automatic Checkpointing: Every prompt, response, and tool invocation is saved to a local SQLite database. ⚡ Instant Cache Recovery: Replay steps in ~15ms $0.00 token cost on retries. ✋ Human-in-the-Loop Gateway: Intercept sensitive tool calls send email , execute command , stripe charge and pause execution until approved via dashboard or API. 🔀 Multi-Model Fallback: Transparently reroutes requests to fallback models e.g. gpt-3.5-turbo , Claude, Ollama if the primary provider hits rate limits 429 or server errors 500 . 📥 Fine-Tuning Dataset Exporter: Export production agent trajectories as OpenAI-compatible .jsonl fine-tuning datasets in a single click. 🔔 Webhook Alerts: Real-time Slack/Discord webhooks when agent runs fail or require human approval. 🎛️ Session Replay & Rollback: Visual dashboard to inspect agent trajectories. Rollback to any step and resume execution cleanly. In benchmark tests simulating complex 50-step autonomous agent runs with forced crashes: | Metric | Standard Agent No Proxy | AgentState Proxy | Improvement | |---|---|---|---| Crash Recovery Time Step 45 | ~110.4 seconds | ~0.015 seconds | 7,360x faster 🚀 | Token Cost on Retry | $2.45 per failed retry | $0.00 100% Cache Hit | 100% Savings 💰 | Resilience to Consecutive Failures | Crashes run after 1 error | Recovered from 5+ consecutive crashes | 100% Execution Completion | Rogue Action Risk | Unmonitored | 100% Intercepted by HITL Gateway | Zero Unapproved Actions | php graph TD A AI Agent / Application -- |1. LLM / Tool Request| B AgentState Proxy B -- |2. Checkpoint State| C SQLite Database B -- |3. Forward Request| D OpenAI / Claude / Local LLM D -- |4. Return Response| B B -- |5. Update Cache & Log| C B -- |6. Return to Agent| A git clone https://github.com/aleenz1102/AgentState.git cd agentstate python -m venv venv On Windows PowerShell : .\venv\Scripts\activate On macOS/Linux: source venv/bin/activate pip install fastapi uvicorn httpx openai playwright Pillow imageio python server.py - Proxy endpoint: http://localhost:8080/v1 - Embedded Dashboard: http://localhost:8080/dashboard - Resilience & Caching Demo: python test agent.py Simulates an agent crash on Step 2, then recovers instantly on retry via cache - Human-in-the-Loop Gateway Demo: python test hitl agent.py Pauses terminal agent execution when a sensitive action is attempted until approved on dashboard - Comprehensive Feature Suite: python test full suite.py Tests 1-Line wrappers, fallback models, dataset exporter, and webhooks : OpenAI-compatible completion proxy. POST /v1/chat/completions Headers: x-agent-session-id Required : Unique session tracking ID. x-agent-step-number Optional : Step index of execution loop. x-agent-require-approval Optional : Trigger HITL approval gateway. x-agent-fallback-model Optional : Reroute model if primary provider fails. : List all logged sessions. GET /api/sessions : Get session details and step history. GET /api/sessions/{session id} : Rollback session to specified step. POST /api/sessions/{session id}/reset : List pending human approvals. GET /api/approvals/pending : Approve or reject pending action POST /api/approvals/{id}/action {"action": "APPROVED" | "REJECTED"} .: Download bulk fine-tuning GET /api/export/dataset .jsonl dataset. We welcome contributions Please see our CONTRIBUTING.md /aleenz1102/AgentState/blob/main/CONTRIBUTING.md for setup instructions and pull request guidelines. AgentState is designed for inclusion in the following AI ecosystem resources: AgentState is open-source software licensed under the MIT License /aleenz1102/AgentState/blob/main/LICENSE .