Manage a conversation

Create one session per conversation, not per question. It keeps state on the server and remains pinned to the domain version published when the session was created.

The SDK lifecycle

Moment	Python	TypeScript	Result
Start	`client.start_session()`	`client.startSession()`	A session handle.
First question	`session.next()`	`session.next()`	A decision and its candidates.
Answer received	`session.answer(...)`	`session.answer(...)`	The answer recorded and the next decision.
External information	`session.apply_events(...)`	`session.applyEvents(...)`	Updated state and pending decision, without a new turn.
Read again	`session.refresh()`	`session.refresh()`	Latest state and pending decision.
Business outcome known	`session.submit_feedback(...)`	`session.submitFeedback(...)`	Recorded outcome.

TypeScript calls use await. Python also offers AsyncZelinqaClient with async with and await. See the complete quickstart.

Resume after an interruption

Persist session.id in your backend when the session is created. These examples assume a configured client and a saved_session_id or savedSessionId variable read from your storage.

Python
TypeScript

session = client.resume_session(saved_session_id)
pending = session.pending_decision
if pending is not None:
    print(pending.candidates[0].text)

const session = await client.resumeSession(savedSessionId);
const pending = session.pendingDecision;
if (pending !== null) {
  console.log(pending.candidates[0]?.text);
}

Present the pending question before sending a new answer. After a network interruption, check whether the previous answer was already recorded; do not replay it blindly. The SDK tracks state_version, decision_id, and question_id for business calls. The state version advances with the session: it is not the domain’s published version.

Use one handle sequentially. Concurrent writes to the same session may conflict; read state and reconcile the answer. SDKs do not hide business conflicts.

Continue or finish

action: "ask": a question is available.
warnings may contain objective_achieved: your application decides whether to conclude or continue.
action: "stop": the turn limit is reached (stop_reason: "max_turns_reached") or no question is available (no_question_available); do not expect a candidate.

Calculated progress is not the same as a real-world result. Record success feedback only when the business outcome has actually occurred.

Python
TypeScript

receipt = session.submit_feedback(result="success", label="appointment_booked")

const receipt = await session.submitFeedback({
  result: "success",
  label: "appointment_booked",
});

With MCP, the same stages use the conversation tools. The API reference covers concurrency and idempotency for direct HTTP integrations.

Get started

Guides

References

Resources

Manage a conversation

The SDK lifecycle

Resume after an interruption

Continue or finish