{"id":31284877,"url":"https://github.com/ayushmi/agentstate","last_synced_at":"2025-09-24T07:34:47.838Z","repository":{"id":311001730,"uuid":"1042081465","full_name":"ayushmi/agentstate","owner":"ayushmi","description":"Cloud-native, durable state for AI agents: WAL+snapshots, watch streams, idempotency, leases, TLS/mTLS, capability tokens, Python/TS SDKs, Helm.","archived":false,"fork":false,"pushed_at":"2025-08-25T16:23:45.000Z","size":266,"stargazers_count":50,"open_issues_count":27,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-06T12:02:00.751Z","etag":null,"topics":["ai-agents","change-data-capture","crdt","database","grafana","grpc","helm-chart","kubernetes","observability","persistence","prometheus","rust","sdk","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayushmi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-21T13:05:35.000Z","updated_at":"2025-08-30T02:15:56.000Z","dependencies_parsed_at":"2025-08-21T15:29:58.335Z","dependency_job_id":null,"html_url":"https://github.com/ayushmi/agentstate","commit_stats":null,"previous_names":["ayushmi/agentstate"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ayushmi/agentstate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushmi%2Fagentstate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushmi%2Fagentstate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushmi%2Fagentstate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushmi%2Fagentstate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayushmi","download_url":"https://codeload.github.com/ayushmi/agentstate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayushmi%2Fagentstate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276713466,"owners_count":25691389,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-24T02:00:09.776Z","response_time":97,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","change-data-capture","crdt","database","grafana","grpc","helm-chart","kubernetes","observability","persistence","prometheus","rust","sdk","vector-search"],"created_at":"2025-09-24T07:34:44.929Z","updated_at":"2025-09-24T07:34:47.825Z","avatar_url":"https://github.com/ayushmi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 AgentState v1.0.0\n**Firebase for AI Agents** — Persistent state management for AI applications\n\n[![Docker Build](https://img.shields.io/badge/docker-ready-blue)](#docker-deployment)\n[![API Status](https://img.shields.io/badge/api-stable-green)](#api-reference)  \n[![Load Tested](https://img.shields.io/badge/load%20tested-1400%20ops%2Fs-brightgreen)](#performance)\n[![Python SDK](https://img.shields.io/badge/python-pypi-blue)](https://pypi.org/project/agentstate/)\n[![Node.js SDK](https://img.shields.io/badge/nodejs-npm-green)](https://www.npmjs.com/package/agentstate)\n\nAgentState 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.\n\n**🚀 Key Features:**\n- **Zero-config setup** — Docker one-liner gets you started\n- **Language agnostic** — HTTP/gRPC APIs + Python/Node.js SDKs  \n- **High performance** — 1,400+ ops/sec with crash-safe persistence\n- **Real-time queries** — Find agents by tags, get live updates\n- **Production ready** — Load tested, monitored, Kubernetes friendly\n\n## ✨ Features\n\n- 🔄 **Real-time state updates** - Subscribe to agent state changes\n- 🏷️ **Rich querying** - Query agents by tags and attributes  \n- 💾 **Persistent storage** - Crash-safe WAL + snapshots\n- ⚡ **High performance** - 1,400+ ops/sec, ~15ms latency\n- 🐳 **Production ready** - Docker, Kubernetes, monitoring\n- 🔌 **Simple API** - HTTP REST + gRPC, language agnostic\n\n## 🚀 Quick Start\n\n### 1. Start AgentState Server\n\n**Option A: Using Docker (Recommended)**\n```bash\n# Quick start - no auth required\ndocker run -p 8080:8080 ayushmi/agentstate:latest\n\n# With persistent storage\ndocker run -p 8080:8080 -p 9090:9090 \\\n  -e DATA_DIR=/data \\\n  -v agentstate-data:/data \\\n  ayushmi/agentstate:latest\n\n# Test it works\ncurl http://localhost:8080/health\n```\n\n**Option B: Using Docker Compose (Full Setup)**\n```bash\ngit clone https://github.com/ayushmi/agentstate.git\ncd agentstate\ndocker-compose up -d\n\n# Generate auth token for testing (optional)\nexport AGENTSTATE_API_KEY=$(python scripts/generate_cap_token.py \\\n  --kid active --secret dev-secret \\\n  --ns my-app --verb put --verb get --verb delete --verb query --verb lease)\n```\n\n### 2. Use in Your Application\n\n**Python SDK:**\n```bash\npip install agentstate\n```\n```python\nfrom agentstate import AgentStateClient\n\nclient = AgentStateClient(base_url='http://localhost:8080', namespace='my-app')\n\n# Create agent\nagent = client.create_agent(\n    agent_type='chatbot',\n    body={'name': 'CustomerBot', 'status': 'active'},\n    tags={'team': 'customer-success'}\n)\nprint(f\"Created agent: {agent['id']}\")\n\n# Query agents  \nagents = client.query_agents(tags={'team': 'customer-success'})\nprint(f\"Found {len(agents)} customer success agents\")\n\n# Get specific agent\nagent = client.get_agent(agent_id)\nprint(f\"Agent status: {agent['body']['status']}\")\n```\n\n**Node.js SDK:**\n```bash\nnpm install agentstate\n```\n```javascript\nimport { AgentStateClient } from 'agentstate';\n\nconst client = new AgentStateClient({\n    baseUrl: 'http://localhost:8080',\n    namespace: 'my-app'\n});\n\n// Create agent\nconst agent = await client.createAgent({\n    type: 'workflow',\n    body: {name: 'DataProcessor', status: 'idle'},\n    tags: {capability: 'data-processing'}\n});\n\n// Update agent state\nconst updatedAgent = await client.updateAgent(agent.id, {\n    body: {name: 'DataProcessor', status: 'processing', currentJob: 'analytics'}\n});\n\nconsole.log(`Agent ${agent.id} status: ${updatedAgent.body.status}`);\n```\n\n**Raw HTTP API:**\n```bash\n# Create agent\ncurl -X POST http://localhost:8080/v1/my-app/objects \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"type\": \"chatbot\", \"body\": {\"name\": \"Bot1\"}, \"tags\": {\"env\": \"prod\"}}'\n\n# Query agents\ncurl -X POST http://localhost:8080/v1/my-app/query \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tags\": {\"env\": \"prod\"}}'\n```\n\n## 🤖 AI Framework Integration\n\nAgentState integrates seamlessly with popular AI frameworks:\n\n**LangChain Integration:**\n```python\nfrom agentstate import AgentStateClient\nfrom langchain.memory import BaseChatMessageHistory\nfrom langchain.agents import AgentExecutor\n\n# Use AgentState as LangChain memory backend\nclass AgentStateMemory(BaseChatMessageHistory):\n    def __init__(self, agent_id: str, client: AgentStateClient):\n        self.agent_id = agent_id\n        self.client = client\n\n# Full LangChain + AgentState demo available in examples/\n```\n\n**CrewAI Integration:**\n```python\nfrom agentstate import AgentStateClient\nimport crewai\n\nclient = AgentStateClient(base_url='http://localhost:8080', namespace='crew')\n\n# Store crew member states, task progress, and coordination\nagent = client.create_agent(\n    agent_type='crew_member',\n    body={'role': 'researcher', 'current_task': 'market_analysis'},\n    tags={'crew_id': 'marketing_team', 'status': 'active'}\n)\n```\n\n**Custom Agent Frameworks:**\n```python\n# AgentState works with any agent framework\nclass MyAgent:\n    def __init__(self, agent_id):\n        self.state = AgentStateClient(namespace='my_agents')\n        self.id = agent_id\n        \n    def save_state(self, data):\n        return self.state.create_agent(\n            agent_type='custom',\n            body=data,\n            agent_id=self.id\n        )\n        \n    def load_state(self):\n        return self.state.get_agent(self.id)\n```\n\n## 📊 Performance\n\nReal-world benchmarks from our test suite:\n\n- **🚀 Write throughput**: 1,400+ ops/sec\n- **🔍 Read throughput**: 170+ queries/sec  \n- **⚡ Average latency**: ~15ms\n- **📈 P95 latency**: ~30ms\n- **✅ Reliability**: 0% error rate under load\n\n## 🏗️ Core Concepts\n\n### Agents as Objects\nEach agent is stored with:\n- **`id`**: Unique identifier (ULID)\n- **`type`**: Agent category (\"chatbot\", \"workflow\", etc.)\n- **`body`**: Your agent's state (any JSON)\n- **`tags`**: Key-value pairs for querying\n- **`commit_ts`**: Last update timestamp\n\n### Namespaces\nOrganize agents by environment/team:\n- `/v1/production/objects` - Production agents\n- `/v1/staging/objects` - Staging environment\n- `/v1/team-alpha/objects` - Team-specific\n\n### Real-time Queries\n```python\n# Find all active chatbots\nresponse = requests.post(\"http://localhost:8080/v1/production/query\", json={\n    \"tags\": {\"type\": \"chatbot\", \"status\": \"active\"}\n})\n\n# Monitor agents by team\nteam_agents = requests.post(\"http://localhost:8080/v1/production/query\", json={\n    \"tags\": {\"team\": \"ml-platform\"}\n}).json()\n```\n\n## 🛠️ API Reference\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/v1/{ns}/objects` | Create/update agent |\n| `GET` | `/v1/{ns}/objects/{id}` | Get agent by ID |\n| `POST` | `/v1/{ns}/query` | Query agents by tags |\n| `DELETE` | `/v1/{ns}/objects/{id}` | Delete agent |\n| `GET` | `/health` | Health check |\n| `GET` | `/metrics` | Prometheus metrics |\n\n## 🐳 Docker Deployment\n\n### Basic Setup\n```bash\ndocker run -d --name agentstate \\\n  -p 8080:8080 \\\n  -p 9090:9090 \\\n  ayushmi/agentstate:latest\n```\n\n### Production Setup\n```bash\ndocker run -d --name agentstate \\\n  -p 8080:8080 \\\n  -p 9090:9090 \\\n  -e DATA_DIR=/data \\\n  -v agentstate-data:/data \\\n  --restart unless-stopped \\\n  ayushmi/agentstate:latest\n```\n\n### Docker Compose\n```yaml\nversion: '3.8'\nservices:\n  agentstate:\n    image: ayushmi/agentstate:latest\n    ports:\n      - \"8080:8080\"\n      - \"9090:9090\"\n    environment:\n      - DATA_DIR=/data\n    volumes:\n      - agentstate-data:/data\n    restart: unless-stopped\n\nvolumes:\n  agentstate-data:\n```\n\n## ☸️ Kubernetes Deployment\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: agentstate\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: agentstate\n  template:\n    metadata:\n      labels:\n        app: agentstate\n    spec:\n      containers:\n      - name: agentstate\n        image: ayushmi/agentstate:latest\n        ports:\n        - containerPort: 8080\n        - containerPort: 9090\n        env:\n        - name: DATA_DIR\n          value: /data\n        volumeMounts:\n        - name: data\n          mountPath: /data\n      volumes:\n      - name: data\n        persistentVolumeClaim:\n          claimName: agentstate-data\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: agentstate\nspec:\n  selector:\n    app: agentstate\n  ports:\n  - name: http\n    port: 8080\n    targetPort: 8080\n  - name: grpc  \n    port: 9090\n    targetPort: 9090\n```\n\n## 🔧 Building from Source\n\n### Prerequisites\n- Rust 1.81+\n- Protocol Buffers compiler\n\n### Build and Run\n```bash\n# Clone repository\ngit clone https://github.com/ayushmi/agentstate.git\ncd agentstate\n\n# Build server\ncargo build --release -p agentstate-server\n\n# Run server\n./target/release/agentstate-server\n\n# Or build Docker image\ndocker build -f docker/Dockerfile -t ayushmi/agentstate:latest .\n```\n\n## 📚 Documentation\n\n- **[📖 Quickstart Guide](QUICKSTART.md)** - Detailed getting started\n- **[🏗️ Architecture](docs/architecture.md)** - System design\n- **[🚀 Deployment](docs/DEPLOY.md)** - Production setup\n- **[📊 Monitoring](deploy/grafana/)** - Grafana dashboards\n- **[🔧 Configuration](docs/configuration.md)** - Settings reference\n\n## 🧪 Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Integration tests  \npython integration_tests.py\n\n# Load testing\npython load_test.py\n\n# SDK examples\npython examples/quickstart/python_example.py\nnode examples/quickstart/nodejs_example.js\n\n# Basic test suite\nbash test_suite.sh\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 💡 Use Cases\n\n**Multi-Agent AI Systems:**\n```python\n# Coordinate multiple specialized agents\nmarketing_agent = client.create_agent('marketing_specialist', {...})\nresearch_agent = client.create_agent('research_specialist', {...})\nwriter_agent = client.create_agent('content_writer', {...})\n\n# Query agents by capability when needed\navailable_agents = client.query_agents(tags={'status': 'idle', 'capability': 'research'})\n```\n\n**Workflow Orchestration:**\n```python\n# Track workflow steps and state\nworkflow = client.create_agent(\n    agent_type='workflow',\n    body={\n        'current_step': 'data_collection',\n        'completed_steps': ['initialization'],\n        'next_steps': ['analysis', 'reporting']\n    },\n    tags={'workflow_id': 'user_onboarding', 'priority': 'high'}\n)\n```\n\n**Agent Monitoring \u0026 Analytics:**\n```python\n# Real-time agent health monitoring\nactive_agents = client.query_agents(tags={'status': 'active'})\nfailed_agents = client.query_agents(tags={'status': 'error'})\n\n# Build dashboards with live agent metrics\nfor agent in active_agents:\n    print(f\"Agent {agent['id']}: {agent['body']['current_task']}\")\n```\n\n## 🌟 Why AgentState?\n\nTraditional approaches to AI agent state management involve:\n- Complex Redis/Postgres setups\n- Custom queuing systems  \n- Manual state synchronization\n- No built-in querying capabilities\n\nAgentState provides:\n- ✅ **Simple API** - Just HTTP requests, no complex SDKs\n- ✅ **Built-in persistence** - Automatic WAL + snapshots\n- ✅ **Rich querying** - Find agents by any tag combination\n- ✅ **Real-time updates** - Subscribe to state changes\n- ✅ **Production ready** - Monitoring, clustering, reliability\n- ✅ **Language agnostic** - Works with any HTTP client\n\n**Perfect for:**\n- Multi-agent AI systems\n- Agent monitoring dashboards  \n- Workflow orchestration\n- Real-time agent coordination\n- Production AI deployments\n\n---\n\n**Ready to power your AI agents with persistent, queryable state!** 🚀\n\n## 🚀 Try it Now\n\n**1-Minute Setup:**\n```bash\n# Start server\ndocker run -p 8080:8080 ayushmi/agentstate:latest\n\n# Install SDK (Python or Node.js)\npip install agentstate\n# npm install agentstate\n\n# Create your first agent\npython -c \"\nfrom agentstate import AgentStateClient\nclient = AgentStateClient(base_url='http://localhost:8080', namespace='demo')\nagent = client.create_agent('chatbot', {'name': 'MyBot', 'status': 'active'})\nprint(f'Created agent: {agent[\\\"id\\\"]}')\n\"\n```\n\n**Explore Examples:**\n- 🦜 **LangChain Integration**: [AgentStateTesting/python-tests/langchain-example/](AgentStateTesting/python-tests/langchain-example/)\n- 🤖 **CrewAI Integration**: [AgentStateTesting/python-tests/crewai-example/](AgentStateTesting/python-tests/crewai-example/)  \n- 📝 **Complete Quickstart**: [QUICKSTART.md](QUICKSTART.md)\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**Server Not Starting**\n```bash\n# Check if port is already in use\nlsof -i :8080\n\n# Use different port if needed\ndocker run -p 8081:8080 ayushmi/agentstate:latest\n```\n\n**Connection Refused**\n```bash\n# Verify server is running\ncurl http://localhost:8080/health\n\n# Should return: ok\n```\n\n**SDK Installation Issues**\n```bash\n# Python: Upgrade pip and reinstall\npip install --upgrade pip\npip install --upgrade agentstate\n\n# Node.js: Clear cache and reinstall\nnpm cache clean --force\nnpm install agentstate\n```\n\n**Performance Issues**\n- Default setup handles 1,400+ ops/sec\n- For higher throughput, see [Performance Guide](docs/perf.md)\n- Monitor with `/metrics` endpoint on port 9090\n\n**Docker Image Issues**\n```bash\n# Pull latest image\ndocker pull ayushmi/agentstate:latest\n\n# Check if image is running\ndocker ps\n\n# View container logs\ndocker logs \u003ccontainer-id\u003e\n```\n\n### Getting Help\n\n- 📖 **Documentation**: [docs/](docs/)\n- 💬 **Issues**: [GitHub Issues](https://github.com/ayushmi/agentstate/issues)\n- 🚀 **Examples**: [examples/](examples/)\n- 📧 **Contact**: Create an issue for support\n\nFor questions and support, see our [Issues](https://github.com/ayushmi/agentstate/issues) page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayushmi%2Fagentstate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayushmi%2Fagentstate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayushmi%2Fagentstate/lists"}