Agentic Streamer API
🚀 Live Demo
Production URL: https://agentic-streamer-api-production.up.railway.app/
Note: Currently, the service seeds and generates fake run events for demo purposes. See Future Enhancements for the planned push-based event ingestion endpoint.
Features
Real-time SSE Streaming - Stream agent execution events to multiple clients simultaneously with buffered channels to prevent blocking
Agent Monitoring - Track available agents, their runs, and detailed execution events
Watch Management - Subscribe to specific agents and receive live updates
Memory-backed Storage - In-memory state management with efficient data structures
CORS Enabled - Pre-configured CORS for development and production frontends
Health Checks - Built-in health endpoint for monitoring and deployment verification
Efficient Message Routing - Broker-based message distribution with subscription model
📋 Architecture
Core Components
Broker (
internal/platform/broker.go) - Central message distribution hub managing client subscriptions and event routingDaemon (
internal/platform/daemon.go) - Background controller managing agent lifecycle and event trackingHandler (
internal/platform/handlers.go) - HTTP request handlers for all API endpointsMemTable (
internal/memtable/memtable.go) - In-memory data structure for tracking node statusesTypes (
internal/platform/types.go) - Domain models for events, agents, and watch requestsTech Stack
Language: Go 1.23
HTTP Framework: Cloudwego Hertz - High-performance async HTTP framework
Dependency Injection: Uber FX - Application lifecycle management
Unique IDs: ULID v2 - Sortable unique identifiers
Deployment: Railway.app with NixPacks
📡 API Endpoints
All endpoints are prefixed with
/v1/agentsMetadata & Inspection
GET / - Get list of available agentsGET /:agentId/runs - Get all runs for a specific agentGET /:agentId/runs/:runId/events - Get events for a specific agent runStreaming
GET /sse?clientId=<CLIENT_ID> - Establish SSE connection for live event streamingPOST /watch - Subscribe to agent updatesDELETE /watch/:agentId?clientId=<CLIENT_ID> - Unsubscribe from agent updatesSystem Diagnostics
GET /watchers - Get current watchers and connected clientsGET /health - Health check endpoint (used by Railway for deployment validation)🔌 API Examples
Get Available Agents
Connect to Event Stream
Subscribe to Agent Updates
Get Runs for a Specific Agent
Get Events for a Specific Agent Run
Unsubscribe from Agent
🏗️ Project Structure
🛠️ Local Development
Prerequisites
Go 1.23+
Git
Testing
Installation
The API will start on
http://localhost:80 by default. You can override the port using the PORT environment variable:Testing the Local Deployment
🚀 Deployment
This project is configured for deployment on Railway.app using NixPacks.
Deployment Configuration (railway.toml)
railway.toml)Deploy to Railway
Connect your repository to Railway
Railway will automatically detect
railway.toml and build/deploy accordinglyThe service is live at: https://agentic-streamer-api-production.up.railway.app/
📊 Event Data Model
Events streamed through SSE follow this structure:
🔄 Watch Request Model
Subscribe to agent updates with:
client_id: Unique identifier for the client (used to route events)agents: List of target agents to watchlatest_only: If true, only stream events from the latest run; if false, stream all events🔐 CORS Configuration
Pre-configured CORS origins:
http://localhost:5173 (local development)https://agentic-streamer-ui-react.vercel.app (production UI)Allowed methods: GET, POST, DELETE, OPTIONS
🐛 Key Implementation Details
Buffered Channels
Client channels use a buffer size of 100 messages to prevent slow clients from blocking the broker lock:
Graceful Connection Cleanup
Automatic client removal from broker registry when handlers exit
Proper error handling for write failures with immediate connection termination
Context-based cancellation for clean shutdown
ULID Generation
Events are assigned sortable unique identifiers using ULID v2:
🤝 Integrations
This API is designed to work with:
Frontend: Agentic Streamer UI (React)
Agent Framework: LangChain, AutoGen, or custom agent implementations
Event Sources: Currently seeds demo events; push-based ingestion coming soon (see Future Enhancements)
📝 License
This project is open source and available on GitHub.
🤔 Questions or Issues?
For bugs, feature requests, or questions, please open an issue on GitHub.
🎯 Future Enhancements
Push-based Event Ingestion Endpoint - Create a dedicated endpoint for external services (LangChain, AutoGen, etc.) to push agent run events into the streamer instead of relying on seeded demo data
Improve some lock mechanisms in the AgentDaemon
Add Caching for AgentMetadata so handler can use it instead of hitting the AgentDaemon - reducing lock contention
Graceful shutdown and persistence of events upon run completion
Persistent storage backend (PostgreSQL/MongoDB)
Authentication & authorization layer
Event filtering and query capabilities
Metrics and observability (Prometheus, Grafana)
Rate limiting and backpressure handling
WebSocket support as alternative to SSE
1 like · 2 views · Jul 8, 2026
Developed a high-performance API for streaming agent updates using SSE.