Show HN: AgentState – Open-source resilience and caching proxy for AI agents
AgentState is a lightweight, self-hosted proxy that intercepts LLM and tool calls, automatically checkpoints execution state in SQLite, handles retries, and lets you pause, edit, and resume runs from any point, saving time and money.
Notifications You must be signed in to change notification settings
Fork 0
Star 1
BranchesTags
Open more actions menu
Folders and files
NameName
Last commit message
Last commit date
Latest commit
History
17 Commits
17 Commits
.agents
.agents
agentstate
agentstate
assets
assets
static
static
.gitignore
.gitignore
CONTRIBUTING.md
CONTRIBUTING.md
LICENSE
LICENSE
README.md
README.md
db.py
db.py
generate_clean_demo.py
generate_clean_demo.py
run_hitl_test.py
run_hitl_test.py
server.py
server.py
test_agent.py
test_agent.py
test_full_suite.py
test_full_suite.py
test_hitl_agent.py
test_hitl_agent.py
Repository files navigation
The Open-Source Resilience & Debugging Proxy for Autonomous 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 pause, edit, and resume runs from any point—saving you money and time.
⚡ 10-Second Quickstart
1-Line Python Integration (Recommended)
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."}] )
Framework Wrappers (LangChain & CrewAI)
LangChain
from langchain_openai import ChatOpenAI from agentstate import wrap_langchain
llm = ChatOpenAI(**wrap_langchain(session_id="session_user_9812"))
CrewAI
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") )
Standard OpenAI Client Setup (Python / Node.js)
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", # |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
Loading
💻 Quick Start & Setup
- Clone & Set Up Environment
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
- Start the Proxy Server
python server.py
Proxy endpoint: http://localhost:8080/v1
Embedded Dashboard: http://localhost:8080/dashboard
- Run Test Demos
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)
🔌 API Reference
Proxy Endpoint
POST /v1/chat/completions: OpenAI-compatible completion proxy.
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.
Management & Approval API
GET /api/sessions: List all logged sessions.
GET /api/sessions/{session_id}: Get session details and step history.
POST /api/sessions/{session_id}/reset: Rollback session to specified step.
GET /api/approvals/pending: List pending human approvals.
POST /api/approvals/{id}/action: Approve or reject pending action ({"action": "APPROVED" | "REJECTED"}).
GET /api/export/dataset: Download bulk fine-tuning .jsonl dataset.
🤝 Contributing
We welcome contributions! Please see our CONTRIBUTING.md for setup instructions and pull request guidelines.
🌟 Relevant Awesome Lists
AgentState is designed for inclusion in the following AI ecosystem resources:
Awesome AI Agents
Awesome LangChain
Awesome Python
Awesome FastAPI
📄 License
AgentState is open-source software licensed under the MIT License.
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository