#712 Agentic Bot Demo - Conference Presentation

## Overview Implement a full agentic conversational bot demo for conference presentation, showcasing Highway's capabilities as equivalent to Temporal for AI agent workflows. **Reference:** Temporal AI Agent demo screenshot in usecases/web/agentic-bot/ --- ## CRITICAL: Demo App Architecture **The demo app is COMPLETELY INDEPENDENT and uses ONLY public APIs.** ### Configuration (2 values only) ``` API_URL=https://highway.rodmena.app/api/v1 API_TOKEN=<6-month token for demo tenant> ``` ### What the Demo App Can Do (via API only) - Submit workflows - Start/pause/resume/cancel workflows - Send signals (updates) to workflows - Receive events from workflows (SSE stream) - Query workflow status and history ### What the Demo App CANNOT Do - NO direct database access - NO access to engine internals - NO special privileges - NO container access **This proves Highway works as a black-box API service - exactly how a real customer would use it.** --- ## Engine Capability Assessment (Completed) ### EXISTING PRIMITIVES (No Changes Needed) | Primitive | Method | Purpose | |-----------|--------|---------| | Wait for input | ctx.wait_for_event() | Durable wait for external events | | Send output | ctx.emit_event() | Emit events to external listeners | | Persist state | ctx.set_variable() | Store conversation history durably | | Retrieve state | ctx.get_variable() | Restore state on replay/restart | | Checkpoint execution | ctx.step() | Deterministic replay of LLM calls | | Send to workflow | POST /workflows/{id}/updates | API to inject user messages | | Get events | GET /workflows/{id}/events | Query workflow event history | | LISTEN/NOTIFY | UpdateService | PostgreSQL pub/sub for real-time | ### EXISTING INFRASTRUCTURE - LLM Tool: tools.llm.call with Ollama, multi-provider support - Agent Framework: engine/tools/agent.py with reflexive loop - Event Gateway: Webhooks, approvals, event injection - Audit Trail: absurd_event_log with full history - Multi-tenancy: All layers support tenant isolation --- ## GAPS TO IMPLEMENT (2 Items) ### Gap 1: LLM Function/Tool Calling **File:** engine/tools/llm.py **Current State:** LLM tool supports text completion but NOT function/tool calling. **Required Enhancement:** Add tools and tool_choice parameters to call_llm(). When LLM decides to call a tool, response includes tool_calls array with function name and arguments. **Implementation:** 1. Add tools and tool_choice parameters to call_llm() 2. Add messages parameter (list format vs single prompt) 3. Update _call_ollama() for tool payload 4. Parse tool_calls from Ollama response 5. Return structured response with tool_calls when present --- ### Gap 2: SSE Event Stream Endpoint **File:** api/blueprints/v1/workflows.py (new endpoint) **Current State:** Events can be queried but no real-time streaming. **Required Enhancement:** GET /api/v1/workflows/{workflow_run_id}/events/stream Accept: text/event-stream **Implementation:** 1. Create async generator that yields SSE events 2. Use PostgreSQL LISTEN on highway_events_{workflow_run_id} channel 3. Emit heartbeat every 15s 4. Support Last-Event-ID header for reconnection 5. Filter events by type (optional query param) --- ## Demo Application **Location:** usecases/web/agentic-bot/ ### Architecture: Standalone Client ``` +--------------------------------------------------+ | Demo Flask App | | (Standalone - NO engine access) | | | | Config: | | API_URL = https://highway.rodmena.app/api/v1 | | API_TOKEN = hw_demo_xxx... | +--------------------------------------------------+ | | HTTPS (public API only) v +--------------------------------------------------+ | Highway API (Black Box) | | | | POST /workflows - Submit workflow | | POST /workflows/{id}/updates - Send message | | GET /workflows/{id}/events/stream - SSE | | GET /workflows/{id} - Get status | | POST /workflows/{id}/cancel - Cancel | +--------------------------------------------------+ ``` ### Components 1. **Flask App** (app.py) - Chat interface (left panel) - Workflow timeline visualization (right panel) - Uses requests library + EventSource for SSE - Reads API_URL and API_TOKEN from environment 2. **Agentic Workflow Definition** (workflows/travel_agent.json) - Submitted via API as workflow_definition - Multi-turn conversation loop using wait_for_event/emit_event - Tool definitions: FindEvents, SearchFlights, BookTicket 3. **No Mock Tools Needed** - Tools are defined IN the workflow - LLM function calling triggers ctx.step() executions - Results returned to LLM for next turn ### Setup Before Demo 1. Create demo tenant (one-time) 2. Generate 6-month API token for demo tenant 3. Register workflow definition (or submit inline) 4. Configure Flask app with API_URL + TOKEN --- ## Pre-Demo Setup Task Generate long-lived token for demo tenant: ```bash docker compose exec api hwe rbac generate-token \ --tenant-id demo \ --email demo@highway.rodmena.app \ --expiry-days 180 ``` --- ## Implementation Plan ### Phase 1: LLM Function Calling (1.5 days) - Add tools, tool_choice, messages params to call_llm() - Update _call_ollama() for tool payload - Parse tool_calls response - Add unit tests - Test with deepseek-r1 model ### Phase 2: SSE Streaming (1.5 days) - Create /workflows/{id}/events/stream endpoint - Implement PostgreSQL LISTEN subscription - Add heartbeat mechanism - Add reconnection support - Add integration tests ### Phase 3: Demo Application (2 days) - Flask app with chat UI + timeline - API client using requests + SSE - Agentic workflow definition - Docker compose for standalone demo - Environment config for API_URL/TOKEN ### Phase 4: Polish and Testing (1 day) - End-to-end testing via public API only - Error handling - Demo script for conference - README with setup **Total Estimate: ~6 days** --- ## Success Criteria 1. Demo app works with ONLY API_URL and TOKEN (no engine access) 2. Agent decides which tool to use based on conversation 3. Bot responses appear in real-time via SSE 4. Conversation survives worker restart 5. Timeline shows execution like Temporal UI 6. Can demo: submit, pause, resume, cancel, send signals --- ## Technical Notes - Use deepseek-r1:671b via Ollama (supports function calling) - SSE uses existing LISTEN/NOTIFY infrastructure - No domain-specific APIs - uses generic workflow APIs - Demo proves Highway is a true API-first platform