When a Lesson Starts Talking Back

OpenMAIC's shared Action contract becomes meaningful only when something decides which agent speaks, when an action runs, and what happens when the learner interrupts. This chapter follows that live path through two connected mechanisms: a bounded director graph that routes one classroom turn, and a playback engine that owns time, pause, discussion, and resume. The result is not an unconstrained autonomous conversation. It is a state machine in which agents can contribute, but the classroom and the learner still control the transitions.

Routing one turn without an open-ended loop

The stateless discussion path begins with a director. The director does not generate the whole conversation. It decides whether the next step should be an agent response, a user cue, or the end of the current request. Once an agent is selected, the agent-generation node streams text and actions, records a compact summary, and returns control to the graph. The graph then ends. A longer discussion comes from the client sending another request with the updated conversation state, not from the server entering a loop that can continue indefinitely.

That topology is the first important boundary. It gives the platform a clear unit of work: one director decision followed, at most, by one agent turn. There is no need for a hidden maximum-turn counter to stop the graph, because the graph itself contains no edge from agent generation back to the director within the same request. The client can still create a sustained roundtable by serializing requests, but each server operation has a visible beginning and end.

The director's decision path depends on how many agents are available. With one agent, the first turn can be dispatched by ordinary code. After that agent responds, the director cues the user rather than inventing another speaker. This avoids spending a model call to answer a routing question whose answer is already determined. With multiple agents, the first turn can use a configured trigger agent as a fast path. Later decisions use an LLM-informed director prompt that includes the available agents, a summary of the conversation, prior agent responses, discussion context, and the current whiteboard state.

The LLM is therefore used for a narrow judgment: who should speak next, or whether the round should end. It does not receive permission to name an arbitrary agent and have the graph accept it blindly. The decision is parsed, checked against the available agent set, and treated as an ending if it cannot be understood or points to an unknown agent. A decision that says the user should speak becomes a user cue. A decision that cannot be safely mapped to a known agent does not create a new route.

The director's input also changes after each turn. The graph records a short response preview, the number of actions, and any whiteboard contributions, then supplies that state to the next decision. The summary is not meant to replace the conversation transcript; it is a routing view.