Firebase for AI Agents — Persistent state management for AI applications

AgentState provides a simple, scalable way to store and manage AI agent state with real-time updates, rich querying, and built-in persistence. Think Firebase for your AI agents.

🚀 Key Features:

• Zero-config setup — Docker one-liner gets you started
• Language agnostic — HTTP/gRPC APIs + Python/Node.js SDKs
• High performance — 1,400+ ops/sec with crash-safe persistence
• Real-time queries — Find agents by tags, get live updates
• Production ready — Load tested, monitored, Kubernetes friendly

• 🔄 Real-time state updates - Subscribe to agent state changes
• 🏷️ Rich querying - Query agents by tags and attributes
• 💾 Persistent storage - Crash-safe WAL + snapshots
• ⚡ High performance - 1,400+ ops/sec, ~15ms latency
• 🐳 Production ready - Docker, Kubernetes, monitoring
• 🔌 Simple API - HTTP REST + gRPC, language agnostic

Option A: Using Docker (Recommended)

# Quick start - no auth required
docker run -p 8080:8080 ayushmi/agentstate:latest

# With persistent storage
docker run -p 8080:8080 -p 9090:9090 \
  -e DATA_DIR=/data \
  -v agentstate-data:/data \
  ayushmi/agentstate:latest

# Test it works
curl http://localhost:8080/health

Option B: Using Docker Compose (Full Setup)

git clone https://github.com/ayushmi/agentstate.git
cd agentstate
docker-compose up -d

# Generate auth token for testing (optional)
export AGENTSTATE_API_KEY=$(python scripts/generate_cap_token.py \
  --kid active --secret dev-secret \
  --ns my-app --verb put --verb get --verb delete --verb query --verb lease)

Python SDK:

from agentstate import AgentStateClient

client = AgentStateClient(base_url='http://localhost:8080', namespace='my-app')

# Create agent
agent = client.create_agent(
    agent_type='chatbot',
    body={'name': 'CustomerBot', 'status': 'active'},
    tags={'team': 'customer-success'}
)
print(f"Created agent: {agent['id']}")

# Query agents  
agents = client.query_agents(tags={'team': 'customer-success'})
print(f"Found {len(agents)} customer success agents")

# Get specific agent
agent = client.get_agent(agent_id)
print(f"Agent status: {agent['body']['status']}")

Node.js SDK:

import { AgentStateClient } from 'agentstate';

const client = new AgentStateClient({
    baseUrl: 'http://localhost:8080',
    namespace: 'my-app'
});

// Create agent
const agent = await client.createAgent({
    type: 'workflow',
    body: {name: 'DataProcessor', status: 'idle'},
    tags: {capability: 'data-processing'}
});

// Update agent state
const updatedAgent = await client.updateAgent(agent.id, {
    body: {name: 'DataProcessor', status: 'processing', currentJob: 'analytics'}
});

console.log(`Agent ${agent.id} status: ${updatedAgent.body.status}`);

Raw HTTP API:

# Create agent
curl -X POST http://localhost:8080/v1/my-app/objects \
  -H "Content-Type: application/json" \
  -d '{"type": "chatbot", "body": {"name": "Bot1"}, "tags": {"env": "prod"}}'

# Query agents
curl -X POST http://localhost:8080/v1/my-app/query \
  -H "Content-Type: application/json" \
  -d '{"tags": {"env": "prod"}}'

AgentState integrates seamlessly with popular AI frameworks:

LangChain Integration:

from agentstate import AgentStateClient
from langchain.memory import BaseChatMessageHistory
from langchain.agents import AgentExecutor

# Use AgentState as LangChain memory backend
class AgentStateMemory(BaseChatMessageHistory):
    def __init__(self, agent_id: str, client: AgentStateClient):
        self.agent_id = agent_id
        self.client = client

# Full LangChain + AgentState demo available in examples/

CrewAI Integration:

from agentstate import AgentStateClient
import crewai

client = AgentStateClient(base_url='http://localhost:8080', namespace='crew')

# Store crew member states, task progress, and coordination
agent = client.create_agent(
    agent_type='crew_member',
    body={'role': 'researcher', 'current_task': 'market_analysis'},
    tags={'crew_id': 'marketing_team', 'status': 'active'}
)

Custom Agent Frameworks:

# AgentState works with any agent framework
class MyAgent:
    def __init__(self, agent_id):
        self.state = AgentStateClient(namespace='my_agents')
        self.id = agent_id
        
    def save_state(self, data):
        return self.state.create_agent(
            agent_type='custom',
            body=data,
            agent_id=self.id
        )
        
    def load_state(self):
        return self.state.get_agent(self.id)

Real-world benchmarks from our test suite:

• 🚀 Write throughput: 1,400+ ops/sec
• 🔍 Read throughput: 170+ queries/sec
• ⚡ Average latency: ~15ms
• 📈 P95 latency: ~30ms
• ✅ Reliability: 0% error rate under load

Each agent is stored with:

• id: Unique identifier (ULID)
• type: Agent category ("chatbot", "workflow", etc.)
• body: Your agent's state (any JSON)
• tags: Key-value pairs for querying
• commit_ts: Last update timestamp

Organize agents by environment/team:

• /v1/production/objects - Production agents
• /v1/staging/objects - Staging environment
• /v1/team-alpha/objects - Team-specific

# Find all active chatbots
response = requests.post("http://localhost:8080/v1/production/query", json={
    "tags": {"type": "chatbot", "status": "active"}
})

# Monitor agents by team
team_agents = requests.post("http://localhost:8080/v1/production/query", json={
    "tags": {"team": "ml-platform"}
}).json()

docker run -d --name agentstate \
  -p 8080:8080 \
  -p 9090:9090 \
  ayushmi/agentstate:latest

docker run -d --name agentstate \
  -p 8080:8080 \
  -p 9090:9090 \
  -e DATA_DIR=/data \
  -v agentstate-data:/data \
  --restart unless-stopped \
  ayushmi/agentstate:latest

version: '3.8'
services:
  agentstate:
    image: ayushmi/agentstate:latest
    ports:
      - "8080:8080"
      - "9090:9090"
    environment:
      - DATA_DIR=/data
    volumes:
      - agentstate-data:/data
    restart: unless-stopped

volumes:
  agentstate-data:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: agentstate
spec:
  replicas: 3
  selector:
    matchLabels:
      app: agentstate
  template:
    metadata:
      labels:
        app: agentstate
    spec:
      containers:
      - name: agentstate
        image: ayushmi/agentstate:latest
        ports:
        - containerPort: 8080
        - containerPort: 9090
        env:
        - name: DATA_DIR
          value: /data
        volumeMounts:
        - name: data
          mountPath: /data
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: agentstate-data
---
apiVersion: v1
kind: Service
metadata:
  name: agentstate
spec:
  selector:
    app: agentstate
  ports:
  - name: http
    port: 8080
    targetPort: 8080
  - name: grpc  
    port: 9090
    targetPort: 9090

• Rust 1.81+
• Protocol Buffers compiler

# Clone repository
git clone https://github.com/ayushmi/agentstate.git
cd agentstate

# Build server
cargo build --release -p agentstate-server

# Run server
./target/release/agentstate-server

# Or build Docker image
docker build -f docker/Dockerfile -t ayushmi/agentstate:latest .

Run the comprehensive test suite:

# Integration tests  
python integration_tests.py

# Load testing
python load_test.py

# SDK examples
python examples/quickstart/python_example.py
node examples/quickstart/nodejs_example.js

# Basic test suite
bash test_suite.sh

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

Multi-Agent AI Systems:

# Coordinate multiple specialized agents
marketing_agent = client.create_agent('marketing_specialist', {...})
research_agent = client.create_agent('research_specialist', {...})
writer_agent = client.create_agent('content_writer', {...})

# Query agents by capability when needed
available_agents = client.query_agents(tags={'status': 'idle', 'capability': 'research'})

Workflow Orchestration:

# Track workflow steps and state
workflow = client.create_agent(
    agent_type='workflow',
    body={
        'current_step': 'data_collection',
        'completed_steps': ['initialization'],
        'next_steps': ['analysis', 'reporting']
    },
    tags={'workflow_id': 'user_onboarding', 'priority': 'high'}
)

Agent Monitoring & Analytics:

# Real-time agent health monitoring
active_agents = client.query_agents(tags={'status': 'active'})
failed_agents = client.query_agents(tags={'status': 'error'})

# Build dashboards with live agent metrics
for agent in active_agents:
    print(f"Agent {agent['id']}: {agent['body']['current_task']}")

Traditional approaches to AI agent state management involve:

• Complex Redis/Postgres setups
• Custom queuing systems
• Manual state synchronization
• No built-in querying capabilities

AgentState provides:

• ✅ Simple API - Just HTTP requests, no complex SDKs
• ✅ Built-in persistence - Automatic WAL + snapshots
• ✅ Rich querying - Find agents by any tag combination
• ✅ Real-time updates - Subscribe to state changes
• ✅ Production ready - Monitoring, clustering, reliability
• ✅ Language agnostic - Works with any HTTP client

Perfect for:

• Multi-agent AI systems
• Agent monitoring dashboards
• Workflow orchestration
• Real-time agent coordination
• Production AI deployments

Ready to power your AI agents with persistent, queryable state! 🚀

1-Minute Setup:

# Start server
docker run -p 8080:8080 ayushmi/agentstate:latest

# Install SDK (Python or Node.js)
pip install agentstate
# npm install agentstate

# Create your first agent
python -c "
from agentstate import AgentStateClient
client = AgentStateClient(base_url='http://localhost:8080', namespace='demo')
agent = client.create_agent('chatbot', {'name': 'MyBot', 'status': 'active'})
print(f'Created agent: {agent[\"id\"]}')
"

Explore Examples:

Server Not Starting

# Check if port is already in use
lsof -i :8080

# Use different port if needed
docker run -p 8081:8080 ayushmi/agentstate:latest

Connection Refused

# Verify server is running
curl http://localhost:8080/health

# Should return: ok

SDK Installation Issues

# Python: Upgrade pip and reinstall
pip install --upgrade pip
pip install --upgrade agentstate

# Node.js: Clear cache and reinstall
npm cache clean --force
npm install agentstate

Performance Issues

• Default setup handles 1,400+ ops/sec
• For higher throughput, see Performance Guide
• Monitor with /metrics endpoint on port 9090

Docker Image Issues

# Pull latest image
docker pull ayushmi/agentstate:latest

# Check if image is running
docker ps

# View container logs
docker logs <container-id>

For questions and support, see our Issues page.