# 🤖 AgentState Python SDK
**Firebase for AI Agents** - Python SDK for persistent agent state management.
[](https://pypi.org/project/agentstate/)
[](https://pypi.org/project/agentstate/)
[](https://github.com/ayushmi/agentstate/blob/main/LICENSE)
## 🚀 Quick Start
### Installation
```bash
pip install agentstate
```
### Basic Usage
```python
from agentstate import AgentStateClient
# Connect to AgentState server
client = AgentStateClient("http://localhost:8080", namespace="my-app")
# Create an agent
agent = client.create_agent(
agent_type="chatbot",
body={"name": "CustomerBot", "status": "active", "conversations": 0},
tags={"team": "support", "environment": "production"}
)
print(f"Created agent: {agent['id']}")
# Update agent state
updated = client.create_agent(
agent_type="chatbot",
body={"name": "CustomerBot", "status": "busy", "conversations": 5},
tags={"team": "support", "environment": "production"},
agent_id=agent['id'] # Update existing agent
)
# Query agents
support_agents = client.query_agents({"team": "support"})
print(f"Found {len(support_agents)} support agents")
# Get specific agent
retrieved = client.get_agent(agent['id'])
print(f"Agent status: {retrieved['body']['status']}")
```
## 📚 API Reference
### AgentStateClient
#### `__init__(base_url, namespace)`
Initialize the client.
- `base_url`: AgentState server URL (e.g., "http://localhost:8080")
- `namespace`: Namespace for organizing agents (e.g., "production", "staging")
#### `create_agent(agent_type, body, tags=None, agent_id=None)`
Create or update an agent.
- `agent_type`: Agent category (e.g., "chatbot", "workflow", "classifier")
- `body`: Agent state data (dict)
- `tags`: Key-value pairs for querying (dict, optional)
- `agent_id`: Specific ID for updates (str, optional)
Returns: Agent object with `id`, `type`, `body`, `tags`, `commit_seq`, `commit_ts`
#### `get_agent(agent_id)`
Get agent by ID.
- `agent_id`: Unique agent identifier
Returns: Agent object
#### `query_agents(tags=None)`
Query agents by tags.
- `tags`: Tag filters (e.g., `{"team": "support", "status": "active"}`)
Returns: List of matching agent objects
#### `delete_agent(agent_id)`
Delete an agent.
- `agent_id`: Unique agent identifier
#### `health_check()`
Check server health.
Returns: `True` if healthy, `False` otherwise
## 🎯 Usage Examples
### Multi-Agent System
```python
from agentstate import AgentStateClient
client = AgentStateClient("http://localhost:8080", "multi-agent-system")
# Create coordinator agent
coordinator = client.create_agent("coordinator", {
"status": "active",
"workers": [],
"tasks_queued": 50
}, {"role": "coordinator"})
# Create worker agents
workers = []
for i in range(3):
worker = client.create_agent("worker", {
"status": "idle",
"processed_today": 0,
"coordinator_id": coordinator["id"]
}, {"role": "worker", "coordinator": coordinator["id"]})
workers.append(worker)
print("Multi-agent system initialized!")
```
## 🔗 Links
- **GitHub**: https://github.com/ayushmi/agentstate
- **Documentation**: https://github.com/ayushmi/agentstate#readme
- **Issues**: https://github.com/ayushmi/agentstate/issues
Raw data
{
"_id": null,
"home_page": "https://github.com/ayushmi/agentstate",
"name": "agentstate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai agents state management firebase persistent storage real-time",
"author": "Ayush Mittal",
"author_email": "ayushsmittal@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/06/8a/29332426e1632601b41eeb90c1ec13e3f764d02b772196593dbdb44d5e56/agentstate-1.0.2.tar.gz",
"platform": null,
"description": "# \ud83e\udd16 AgentState Python SDK\n\n**Firebase for AI Agents** - Python SDK for persistent agent state management.\n\n[](https://pypi.org/project/agentstate/)\n[](https://pypi.org/project/agentstate/)\n[](https://github.com/ayushmi/agentstate/blob/main/LICENSE)\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install agentstate\n```\n\n### Basic Usage\n\n```python\nfrom agentstate import AgentStateClient\n\n# Connect to AgentState server\nclient = AgentStateClient(\"http://localhost:8080\", namespace=\"my-app\")\n\n# Create an agent\nagent = client.create_agent(\n agent_type=\"chatbot\",\n body={\"name\": \"CustomerBot\", \"status\": \"active\", \"conversations\": 0},\n tags={\"team\": \"support\", \"environment\": \"production\"}\n)\n\nprint(f\"Created agent: {agent['id']}\")\n\n# Update agent state\nupdated = client.create_agent(\n agent_type=\"chatbot\", \n body={\"name\": \"CustomerBot\", \"status\": \"busy\", \"conversations\": 5},\n tags={\"team\": \"support\", \"environment\": \"production\"},\n agent_id=agent['id'] # Update existing agent\n)\n\n# Query agents\nsupport_agents = client.query_agents({\"team\": \"support\"})\nprint(f\"Found {len(support_agents)} support agents\")\n\n# Get specific agent\nretrieved = client.get_agent(agent['id'])\nprint(f\"Agent status: {retrieved['body']['status']}\")\n```\n\n## \ud83d\udcda API Reference\n\n### AgentStateClient\n\n#### `__init__(base_url, namespace)`\n\nInitialize the client.\n\n- `base_url`: AgentState server URL (e.g., \"http://localhost:8080\")\n- `namespace`: Namespace for organizing agents (e.g., \"production\", \"staging\")\n\n#### `create_agent(agent_type, body, tags=None, agent_id=None)`\n\nCreate or update an agent.\n\n- `agent_type`: Agent category (e.g., \"chatbot\", \"workflow\", \"classifier\")\n- `body`: Agent state data (dict)\n- `tags`: Key-value pairs for querying (dict, optional)\n- `agent_id`: Specific ID for updates (str, optional)\n\nReturns: Agent object with `id`, `type`, `body`, `tags`, `commit_seq`, `commit_ts`\n\n#### `get_agent(agent_id)`\n\nGet agent by ID.\n\n- `agent_id`: Unique agent identifier\n\nReturns: Agent object\n\n#### `query_agents(tags=None)`\n\nQuery agents by tags.\n\n- `tags`: Tag filters (e.g., `{\"team\": \"support\", \"status\": \"active\"}`)\n\nReturns: List of matching agent objects\n\n#### `delete_agent(agent_id)`\n\nDelete an agent.\n\n- `agent_id`: Unique agent identifier\n\n#### `health_check()`\n\nCheck server health.\n\nReturns: `True` if healthy, `False` otherwise\n\n## \ud83c\udfaf Usage Examples\n\n### Multi-Agent System\n\n```python\nfrom agentstate import AgentStateClient\n\nclient = AgentStateClient(\"http://localhost:8080\", \"multi-agent-system\")\n\n# Create coordinator agent\ncoordinator = client.create_agent(\"coordinator\", {\n \"status\": \"active\",\n \"workers\": [],\n \"tasks_queued\": 50\n}, {\"role\": \"coordinator\"})\n\n# Create worker agents\nworkers = []\nfor i in range(3):\n worker = client.create_agent(\"worker\", {\n \"status\": \"idle\",\n \"processed_today\": 0,\n \"coordinator_id\": coordinator[\"id\"]\n }, {\"role\": \"worker\", \"coordinator\": coordinator[\"id\"]})\n workers.append(worker)\n\nprint(\"Multi-agent system initialized!\")\n```\n\n## \ud83d\udd17 Links\n\n- **GitHub**: https://github.com/ayushmi/agentstate\n- **Documentation**: https://github.com/ayushmi/agentstate#readme\n- **Issues**: https://github.com/ayushmi/agentstate/issues\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Firebase for AI Agents - Persistent state management for AI applications",
"version": "1.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/ayushmi/agentstate/issues",
"Documentation": "https://github.com/ayushmi/agentstate#readme",
"Homepage": "https://github.com/ayushmi/agentstate",
"Source Code": "https://github.com/ayushmi/agentstate"
},
"split_keywords": [
"ai",
"agents",
"state",
"management",
"firebase",
"persistent",
"storage",
"real-time"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fcf9fcd813b63645fd7108ef32741062f826c706af1a960f47564e3cdbad4eb9",
"md5": "9c541a78efdf0a8cba1871ac384537cc",
"sha256": "48375add0cfee4ecb6bb09bbb37f564d3b027e471cc635b2e354f5d32c6d3bce"
},
"downloads": -1,
"filename": "agentstate-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c541a78efdf0a8cba1871ac384537cc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6026,
"upload_time": "2025-08-22T19:22:02",
"upload_time_iso_8601": "2025-08-22T19:22:02.245441Z",
"url": "https://files.pythonhosted.org/packages/fc/f9/fcd813b63645fd7108ef32741062f826c706af1a960f47564e3cdbad4eb9/agentstate-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "068a29332426e1632601b41eeb90c1ec13e3f764d02b772196593dbdb44d5e56",
"md5": "1b76ac9abfadd25326e5c4e2361413aa",
"sha256": "2578877862efb692a4f3e467211eeca34b2a1f0a0260301c9577592c5d8c8d0d"
},
"downloads": -1,
"filename": "agentstate-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1b76ac9abfadd25326e5c4e2361413aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 5815,
"upload_time": "2025-08-22T19:22:03",
"upload_time_iso_8601": "2025-08-22T19:22:03.621675Z",
"url": "https://files.pythonhosted.org/packages/06/8a/29332426e1632601b41eeb90c1ec13e3f764d02b772196593dbdb44d5e56/agentstate-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 19:22:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ayushmi",
"github_project": "agentstate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "agentstate"
}
JSON
