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

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 , edit, and resume runs from any point—saving you money and time.

from agentstate import AgentStateOpenAI

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:

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: NativeAgentStateOpenAI

wrapper or simplebaseURL

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 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:

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
.\venv\Scripts\activate
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

(s 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-tuningGET /api/export/dataset

.jsonl

dataset.

We welcome contributions! Please see our 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.