{"id":30172910,"url":"https://github.com/ibbybuilds/agent-protocol-server","last_synced_at":"2025-08-11T23:18:20.034Z","repository":{"id":306752048,"uuid":"1023243010","full_name":"ibbybuilds/agent-protocol-server","owner":"ibbybuilds","description":"Self-hosted LangGraph-compatible agent backend. Run, store, and stream agents with FastAPI + Postgres. No lock-in. Just control.","archived":false,"fork":false,"pushed_at":"2025-08-10T14:56:05.000Z","size":604,"stargazers_count":27,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-10T16:24:06.694Z","etag":null,"topics":["fastapi","langchain","langggraph","langgraph-agents","postgres","python"],"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/ibbybuilds.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}},"created_at":"2025-07-20T20:31:23.000Z","updated_at":"2025-08-10T14:56:08.000Z","dependencies_parsed_at":"2025-07-27T12:32:32.890Z","dependency_job_id":"4416bf8a-97e4-47c6-992f-32b84936b2a1","html_url":"https://github.com/ibbybuilds/agent-protocol-server","commit_stats":null,"previous_names":["ibbybuilds/langgraph-agent-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ibbybuilds/agent-protocol-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibbybuilds%2Fagent-protocol-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibbybuilds%2Fagent-protocol-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibbybuilds%2Fagent-protocol-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibbybuilds%2Fagent-protocol-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ibbybuilds","download_url":"https://codeload.github.com/ibbybuilds/agent-protocol-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibbybuilds%2Fagent-protocol-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269970136,"owners_count":24505477,"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-08-11T02:00:10.019Z","response_time":75,"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":["fastapi","langchain","langggraph","langgraph-agents","postgres","python"],"created_at":"2025-08-11T23:18:13.841Z","updated_at":"2025-08-11T23:18:20.023Z","avatar_url":"https://github.com/ibbybuilds.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Protocol Server\n\n\u003e **Replace LangGraph Platform with your own backend – zero vendor lock-in, full control.**\n\nAn open-source, production-ready backend for running, persisting, and streaming AI agents with LangGraph compatibility. Built with FastAPI and PostgreSQL for developers who demand control over their agent orchestration.\n\nBased on the [Agent Protocol specification](https://github.com/langchain-ai/agent-protocol), with modifications to maintain backward compatibility with the LangGraph Client SDK.\n\n**Status**: Work in progress — actively improving DX, protocol coverage, and production hardening. Contributors welcome!\n\n## ✨ Why This Exists\n\n- **Zero Vendor Lock-in**: Own your agent infrastructure completely\n- **Drop-in Replacement**: Compatible with LangGraph Client SDK\n- **Production Ready**: PostgreSQL persistence, streaming, auth\n- **Developer First**: Clean OSS implementation that's easy to run and evolve\n\n## 🚀 Quick Start (5 minutes)\n\n### Prerequisites\n\n- Python 3.11+\n- PostgreSQL 15+\n- uv (Python package manager)\n- Docker (for local Postgres)\n\n### Get Running\n\n```bash\n# Clone and setup\ngit clone https://github.com/ibbybuilds/agent-protocol-server.git\ncd agent-protocol-server\nuv install\n\nsource .venv/bin/activate (for mac/linux)\nOR\n/.venv/Scripts/activate (for windows)\n\n# Start database\ndocker-compose up -d postgres\n\n# Launch server\npython run_server.py\n```\n\n### Verify It Works\n\n```bash\ncurl http://localhost:8000/health\nopen http://localhost:8000/docs  # Interactive API docs\n```\n\n## 🏗️ Architecture\n\n```\nClient → FastAPI → LangGraph SDK → PostgreSQL\n         ↓           ↓              ↓\n   Agent Protocol  Auth/Graph   Checkpoints\n   Endpoints       Execution     Metadata\n```\n\n- **FastAPI**: HTTP layer with Agent Protocol compliance\n- **LangGraph**: State management and graph execution\n- **PostgreSQL**: Durable state and metadata storage\n- **Config-driven**: `langgraph.json` maps graphs to endpoints\n\n## 📁 Project Structure\n\n```\nagent-protocol-server/\n├── langgraph.json              # Graph configuration\n├── auth.py                     # Authentication setup\n├── graphs/                     # Agent definitions\n│   └── react_agent/            # Example agent\n├── src/agent_server/           # FastAPI application\n│   ├── main.py                 # App entrypoint\n│   ├── core/                   # Database \u0026 infrastructure\n│   ├── models/                 # Pydantic schemas\n│   ├── services/               # Business logic\n│   └── utils/                  # Helpers\n└── tests/                      # Test suite\n```\n\n## ⚙️ Configuration\n\n### Environment Variables (.env)\n\n```bash\n# Database\nDATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/agent_protocol_server\n\n# Authentication\nAUTH_TYPE=noop  # noop, custom\n\n# Server\nHOST=0.0.0.0\nPORT=8000\nDEBUG=true\n\nOPENAI_API_KEY=sk-...\n```\n\n### Graph Configuration (langgraph.json)\n\n```json\n{\n  \"$schema\": \"https://raw.githubusercontent.com/langchain-ai/langgraph/refs/heads/main/libs/cli/schemas/schema.json\",\n  \"dependencies\": [\".\"],\n  \"graphs\": {\n    \"agent\": \"./graphs/react_agent/graph.py:graph\"\n  },\n  \"env\": \".env\",\n  \"auth\": {\n    \"path\": \"./auth.py:auth\"\n  }\n}\n```\n\n## 🧪 Try the Example Agent (Client SDK)\n\n```python\nimport asyncio\nfrom langgraph_sdk import get_client\n\nasync def main():\n    client = get_client(url=\"http://localhost:8000\")\n\n    # 1) Create (or reuse) an assistant for your graph\n    assistant = await client.assistants.create(\n        graph_id=\"agent\",\n        if_exists=\"do_nothing\",\n        config={},\n    )\n    assistant_id = assistant[\"assistant_id\"]\n\n    # 2) Create a thread\n    thread = await client.threads.create()\n    thread_id = thread[\"thread_id\"]\n\n    # 3) Create + stream a run and log events\n    stream = client.runs.stream(\n        thread_id=thread_id,\n        assistant_id=assistant_id,                 # can also pass \"agent\" directly\n        input={\n            \"messages\": [\n                {\"type\": \"human\", \"content\": [{\"type\": \"text\", \"text\": \"hello\"}]}\n            ]\n        },\n        stream_mode=[\"values\", \"messages-tuple\", \"custom\"],\n        on_disconnect=\"cancel\",\n        # checkpoint={\"checkpoint_id\": \"...\", \"checkpoint_ns\": \"\"},\n    )\n\n    async for chunk in stream:\n        print(\"event:\", getattr(chunk, \"event\", None), \"data:\", getattr(chunk, \"data\", None))\n\nasyncio.run(main())\n```\n\n## 🎯 What You Get\n\n- ✅ **Agent Protocol-compliant REST endpoints**\n- ✅ **Persistent conversations with database-backed checkpoints**\n- ✅ **Config-driven agent graphs**\n- ✅ **Pluggable authentication (JWT, OAuth, custom)**\n- ✅ **Streaming responses with network drop resilience**\n- ✅ **Backward compatible with LangGraph Client SDK** (uses \"assistant\" naming in schemas for compatibility)\n- ✅ **Production-ready with Docker, monitoring, CI/CD**\n\n## 📊 Development Status\n\n### ✅ Phase 1: Foundation (Complete)\n\n- Project structure and dependencies\n- FastAPI application with LangGraph integration\n- Database setup with PostgreSQL\n- Basic authentication framework\n- Health checks and development environment\n\n### 🔄 Phase 2: Agent Protocol API (In Progress)\n\n- Assistant management endpoints\n- Thread creation and management\n- Run execution with streaming\n- Store operations (key-value + vector)\n\n### 📋 Phase 3: Production Features (Planned)\n\n- Comprehensive authentication backends\n- Multi-tenant isolation\n- Monitoring and metrics\n- Deployment configurations\n\n## 🛣️ Roadmap\n\n- **Human-in-the-loop interrupts** (pause/resume, manual decisions)\n- **Redis-backed streaming buffers** for resilience and scale\n- **Langfuse integration** for tracing\n- **Assistant management endpoints** and improved UX\n- **Store operations** (kv + vector)\n- **Multi-tenant isolation** and auth backends\n- **Deployment recipes** (Docker/K8s)\n\n## 🚀 Production Deployment\n\n- Run with multiple workers behind a reverse proxy\n- Use managed PostgreSQL with backups and monitoring\n- Configure proper auth (JWT/OIDC) and CORS\n- Export metrics/logs to your observability stack\n\n## 🤝 Contributing\n\nWe're looking for contributors to:\n\n- Improve spec alignment and API ergonomics\n- Harden streaming/resume semantics\n- Add auth backends and deployment guides\n- Expand examples and tests\n\n**Open issues/PRs** - run tests and follow style guidelines.\n\n## 📄 License\n\nMIT License — see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibbybuilds%2Fagent-protocol-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibbybuilds%2Fagent-protocol-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibbybuilds%2Fagent-protocol-server/lists"}