Agentic Streamer API Development by Khalid ElokielyAgentic Streamer API Development by Khalid Elokiely

Agentic Streamer API Development

Portfolio project
Khalid Elokiely

Agentic Streamer API

A high-performance REST API backend for live agentic updates powered by Go and server-sent events (SSE). Built with Hertz and Uber FX, this service enables real-time streaming of agent execution events to multiple clients simultaneously.

🚀 Live Demo

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 routing
Daemon (internal/platform/daemon.go) - Background controller managing agent lifecycle and event tracking
Handler (internal/platform/handlers.go) - HTTP request handlers for all API endpoints
MemTable (internal/memtable/memtable.go) - In-memory data structure for tracking node statuses
Types (internal/platform/types.go) - Domain models for events, agents, and watch requests

Tech 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/agents

Metadata & Inspection

GET / - Get list of available agents
GET /:agentId/runs - Get all runs for a specific agent
GET /:agentId/runs/:runId/events - Get events for a specific agent run

Streaming

GET /sse?clientId=<CLIENT_ID> - Establish SSE connection for live event streaming
POST /watch - Subscribe to agent updates
DELETE /watch/:agentId?clientId=<CLIENT_ID> - Unsubscribe from agent updates

System Diagnostics

GET /watchers - Get current watchers and connected clients
GET /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)


Deploy to Railway

Connect your repository to Railway
Railway will automatically detect railway.toml and build/deploy accordingly

📊 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 watch
latest_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.

Tags