airforms-starter is a minimal demo app that shows how to integrate:
@airforms/orchestratorover HTTP (POST /turn)@airforms/renderer-reactfor renderingui_frame@airforms/ui-schemafor shared turn/message typing
It is both:
- A runnable demo
- A reference implementation document for developers
This starter uses a single-page React chat UI.
Flow:
- User sends text in the starter chat.
- Starter posts that as
llm_resultto orchestrator (representing client-side LLM output handoff). - Orchestrator returns assistant messages and optional
ui_frame. - App renders assistant messages in transcript and embeds
ui_frameinline inside the assistant bubble. - Renderer submit triggers
ui_submitturn back to orchestrator. - App updates transcript and repeats.
Conversation scope is one conversationId per browser session (stored in sessionStorage).
The orchestrator now calls OpenAI Responses API for dynamic turn generation.
Set this before starting airforms-orchestrator:
OPENAI_API_KEY=your_key_hereOptional model override:
OPENAI_MODEL=gpt-4.1-miniIf OPENAI_API_KEY is missing, orchestrator requests return an error.
Starter demonstrates a host-chat integration where the host can pass client-LLM output to the orchestrator (llm_result).
Supported turn message types now include:
user_textllm_resultui_submit
- Plan finalized for starter architecture and flow
- Starter package scaffolded (React + Vite + TypeScript)
- Orchestrator API client implemented (
POST /turn) - Minimal chat UI implemented
- Renderer integration implemented (
ChatUIRenderer) - Tests added (unit + integration)
- Optional live smoke test command wiring
- Remote publish mode docs (post-local demo)
From each package folder:
- Build schema package
cd ../airforms-ui-schema
npm install
npm run build- Build renderer package
cd ../airforms-renderer
npm install
npm run build- Start orchestrator
cd ../airforms-orchestrator
npm install
npm run dev- Run starter app
cd ../airforms-starter
npm install
npm run devDefault orchestrator URL: http://localhost:3000
Override with env var:
VITE_ORCHESTRATOR_URL=http://localhost:3000npm run dev– run starter appnpm run build– type-check + production buildnpm run test– run tests oncenpm run test:watch– watch mode tests
Initialize this folder as its own git repository:
git init
git add .
git commit -m "Initialize airforms-starter demo"Then add your remote and push:
git remote add origin <your-remote-url>
git branch -M main
git push -u origin main