Conversation
Routes and state
Deterministic routes and conversation state machines — before the model runs.
Deterministic routes and conversation state
Add a conversation to the same definition every renderer already consumes. Routes run before the model adapter.
Flow
Loading diagram...
Definition
code
import { commandRoute, defineChat } from '@agentskit/chat'
const supportChat = defineChat({
id: 'support',
chat: { adapter },
conversation: {
initial: 'idle',
states: {
idle: { on: { start: 'collecting' }, actions: ['start'] },
collecting: { on: { finish: 'complete' }, actions: ['cancel'] },
complete: { actions: ['restart'] },
},
routes: [
commandRoute({
id: 'start',
command: '/start',
event: 'start',
response: () => 'What is your name?',
}),
commandRoute({
id: 'finish',
command: '/name Ada',
event: 'finish',
states: ['collecting'],
response: () => 'Welcome, Ada.',
}),
],
},
})Behavior
| Case | Result |
|---|---|
| Route matches + state allows event | Deterministic response; state advances |
| Unknown input | Delegates to AgentsKit adapter |
| State-disallowed route | Delegates unchanged |
| Failing matcher/response | Controller error stream; no state advance |
Conversation definitions compile to @agentskit/statechart. Chat owns routes, fallback, traces, and session decision replay — not a second statechart runtime.
Sessions and replay
createChatSession(definition) exposes derived chat config and getConversationSnapshot() (current state + allowed events/actions).
- Retry / regenerate replay the same deterministic response.
- Edit recomputes progress from retained history and drops stale decisions.
- Use
onTracefordeterministic·agentic·repaired·fallbackwithout copying prompts into telemetry.
Route identity context
Route response callbacks receive (input, context):
context.messageId— unique per turn for rendered componentscontext.sessionId— fallback when no user message exists
Never use a process-global counter for replayed route output.