{"id":46228432,"url":"https://github.com/DiTo97/deepagents-backends","last_synced_at":"2026-03-17T10:01:04.489Z","repository":{"id":332413528,"uuid":"1129669896","full_name":"DiTo97/deepagents-backends","owner":"DiTo97","description":"S3 and PostgreSQL remote storage backends for LangChain Deep Agents, enabling persistent and distributed agent file systems.","archived":false,"fork":false,"pushed_at":"2026-01-07T23:34:27.000Z","size":159,"stargazers_count":71,"open_issues_count":0,"forks_count":11,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-16T00:25:28.886Z","etag":null,"topics":["deepagents","langchain","postgresql","remote-storage","s3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DiTo97.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-07T12:17:21.000Z","updated_at":"2026-02-15T13:09:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DiTo97/deepagents-backends","commit_stats":null,"previous_names":["dito97/deepagents-backends"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/DiTo97/deepagents-backends","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiTo97%2Fdeepagents-backends","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiTo97%2Fdeepagents-backends/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiTo97%2Fdeepagents-backends/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiTo97%2Fdeepagents-backends/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DiTo97","download_url":"https://codeload.github.com/DiTo97/deepagents-backends/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiTo97%2Fdeepagents-backends/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30622074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T08:10:05.930Z","status":"ssl_error","status_checked_at":"2026-03-17T08:10:04.972Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["deepagents","langchain","postgresql","remote-storage","s3"],"created_at":"2026-03-03T17:00:31.150Z","updated_at":"2026-03-17T10:01:04.468Z","avatar_url":"https://github.com/DiTo97.png","language":"Python","funding_links":[],"categories":["🛠️ Developer Tools"],"sub_categories":["🟩 Development Tools 🛠️"],"readme":"# 🗄️ Deep Agents Remote Backends\n\n**deepagents-backends** provides production-ready implementations of the [LangChain Deep Agents](https://github.com/langchain-ai/deepagents)' `BackendProtocol` for remote file storage, allowing your agents to maintain state across restarts and share files in distributed environments.\n\nStore agent files in **S3** or **PostgreSQL** instead of ephemeral state, enabling persistent storage, distributed execution, and multi-agent file sharing.\n\n## 🚀 Quickstart\n\n```bash\npip install deepagents-backends\n```\n\n### S3 Backend\n\nStore agent files in AWS S3 or any S3-compatible storage (MinIO, DigitalOcean Spaces, etc.):\n\n```python\nfrom deepagents import create_deep_agent\nfrom deepagents_backends import S3Backend, S3Config\n\n# Configure S3 (or MinIO for local development)\nconfig = S3Config(\n    bucket=\"my-agent-bucket\",\n    prefix=\"agent-workspace\",\n    endpoint_url=\"http://localhost:9000\",  # Remove for AWS S3\n    access_key_id=\"minioadmin\",\n    secret_access_key=\"minioadmin\",\n    use_ssl=False,\n)\n\n# Create agent with S3 backend\nagent = create_deep_agent(\n    backend=S3Backend(config),\n    system_prompt=\"You are a helpful assistant. Files persist in S3.\",\n)\n\n# Run the agent - all file operations use S3\nresult = agent.invoke({\n    \"messages\": [{\"role\": \"user\", \"content\": \"Create a Python calculator module in /src/\"}]\n})\n```\n\n### PostgreSQL Backend\n\nStore agent files in PostgreSQL with connection pooling for high-performance scenarios:\n\n```python\nimport asyncio\nfrom deepagents import create_deep_agent\nfrom deepagents_backends import PostgresBackend, PostgresConfig\n\nasync def main():\n    config = PostgresConfig(\n        host=\"localhost\",\n        port=5432,\n        database=\"deepagents\",\n        user=\"postgres\",\n        password=\"postgres\",\n        table=\"agent_files\",\n    )\n\n    backend = PostgresBackend(config)\n    await backend.initialize()  # Creates table + indexes\n\n    try:\n        agent = create_deep_agent(\n            backend=backend,\n            system_prompt=\"You are a data analyst. Files persist in PostgreSQL.\",\n        )\n\n        result = await agent.ainvoke({\n            \"messages\": [{\"role\": \"user\", \"content\": \"Create a data analysis project in /analysis/\"}]\n        })\n    finally:\n        await backend.close()  # Always close the connection pool\n\nasyncio.run(main())\n```\n\n## 🔀 Composite Backend (Hybrid Storage)\n\nRoute different paths to different backends for optimal storage:\n\n```python\nfrom deepagents import create_deep_agent\nfrom deepagents.backends import CompositeBackend, StateBackend\nfrom deepagents_backends import S3Backend, S3Config, PostgresBackend, PostgresConfig\n\n# S3 for large files, PostgreSQL for structured data\ns3_backend = S3Backend(S3Config(bucket=\"assets\", ...))\npg_backend = PostgresBackend(PostgresConfig(...))\nawait pg_backend.initialize()\n\nagent = create_deep_agent(\n    backend=CompositeBackend(\n        default=StateBackend(),  # Ephemeral working files\n        routes={\n            \"/assets/\": s3_backend,    # Large files → S3\n            \"/data/\": pg_backend,      # Structured data → PostgreSQL\n            \"/memories/\": pg_backend,  # Long-term memory → PostgreSQL\n        },\n    ),\n)\n```\n\n## 📚 Examples\n\nSee the [examples/](examples/) directory for complete, runnable examples:\n\n| Example | Description |\n|---------|-------------|\n| [s3_deep_agent.py](examples/s3_deep_agent.py) | Full S3 backend with streaming and custom tools |\n| [postgres_deep_agent.py](examples/postgres_deep_agent.py) | PostgreSQL with multi-agent and sub-agent workflows |\n| [composite_backend.py](examples/composite_backend.py) | Hybrid S3 + PostgreSQL storage with routing |\n| [basic_usage.py](examples/basic_usage.py) | Low-level backend API operations |\n\n### Running Examples Locally\n\n```bash\n# Start MinIO and PostgreSQL\ndocker-compose up -d\n\n# Run an example\npython examples/s3_deep_agent.py\n```\n\n## ⚙️ Configuration\n\n### S3Config\n\n```python\nS3Config(\n    bucket=\"my-bucket\",              # Required: S3 bucket name\n    prefix=\"agent-files\",            # Key prefix for all files\n    region=\"us-west-2\",              # AWS region (default: us-east-1)\n    endpoint_url=None,               # Custom endpoint (MinIO, etc.)\n    access_key_id=None,              # AWS credentials (or use IAM role)\n    secret_access_key=None,\n    use_ssl=True,                    # Use HTTPS\n    max_pool_connections=50,         # Connection pool size\n    connect_timeout=5.0,             # Connection timeout (seconds)\n    read_timeout=30.0,               # Read timeout (seconds)\n    max_retries=3,                   # Retry attempts\n)\n```\n\n### PostgresConfig\n\n```python\nPostgresConfig(\n    host=\"localhost\",                # PostgreSQL host\n    port=5432,                       # PostgreSQL port\n    database=\"deepagents\",           # Database name\n    user=\"postgres\",                 # Username\n    password=\"postgres\",             # Password\n    table=\"agent_files\",             # Table name for file storage\n    min_pool_size=2,                 # Minimum connections in pool\n    max_pool_size=10,                # Maximum connections in pool\n    sslmode=\"prefer\",                # SSL mode (use \"require\" in production)\n)\n```\n\n## 🔧 Backend Protocol\n\nBoth backends implement the full `BackendProtocol` with sync and async methods:\n\n| Method | Description |\n|--------|-------------|\n| `read` / `aread` | Read file content (supports offset/limit pagination) |\n| `write` / `awrite` | Create new file (fails if exists) |\n| `edit` / `aedit` | Edit file with string replacement |\n| `ls_info` / `als_info` | List directory contents |\n| `glob_info` / `aglob_info` | Find files matching glob pattern |\n| `grep_raw` / `agrep_raw` | Search files with line-numbered results |\n| `upload_files` / `aupload_files` | Batch upload raw bytes |\n| `download_files` / `adownload_files` | Batch download as bytes |\n\n### File Storage Format\n\nFiles are stored as JSON with line arrays for efficient line-based operations:\n\n```json\n{\n  \"content\": [\"line 1\", \"line 2\", \"line 3\"],\n  \"created_at\": \"2025-01-07T12:00:00Z\",\n  \"modified_at\": \"2025-01-07T12:30:00Z\"\n}\n```\n\n## 🧪 Development\n\n```bash\n# Install dev dependencies\nuv sync\n\n# Unit tests (mocked, no Docker)\nuv run pytest -m unit\n\n# Integration tests (Docker services started automatically via pytest-docker)\nuv run pytest -m integration\n\n# All tests\nuv run pytest\n```\n\n### Docker Services\n\n| Service | Port | Credentials |\n|---------|------|-------------|\n| MinIO (S3) | 9000 | `minioadmin` / `minioadmin` |\n| MinIO Console | 9001 | `minioadmin` / `minioadmin` |\n| PostgreSQL | 5432 | `postgres` / `postgres` |\n\n## 🔒 Security\n\n- **Credentials**: Use environment variables or IAM roles, never commit secrets\n- **PostgreSQL**: Use `sslmode=\"require\"` in production\n- **S3**: Use `use_ssl=True` in production\n- **Connection pooling**: PostgresBackend maintains a connection pool—always call `close()`\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDiTo97%2Fdeepagents-backends","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDiTo97%2Fdeepagents-backends","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDiTo97%2Fdeepagents-backends/lists"}