Chat Sessions
Chat sessions let a deployed App (or TeamApp) continue a conversation across
messages. When you call app.chat(message), the SDK stores the returned sessionId
and sends it with the next message automatically — you do not manage the ID yourself.
Send a message
const response = await app.chat("My name is Alex.");
console.log(response?.response);
console.log(response?.sessionId);
app.chat() resolves to a ChatResponse, or null in interactive mode.
| Field | Description |
|---|---|
response | The reply text. |
sessionId | The current session identifier, or null. |
retrievedContexts | Data source chunks used for the response. |
messages | Conversation messages returned by the API. |
selectedAgent, handoffPath, contributingAgents | Agent-team routing detail. |
rawPayload | The unmodified API response. |
Continue a conversation
Call chat() again on the same instance:
await app.chat("My name is Alex.");
const reply = await app.chat("What is my name?");
console.log(reply?.response); // knows it's Alex
Inspect the session
console.log(app.sessionId); // null before the first message
Reset the session
app.resetSession();
const reply = await app.chat("What is my name?"); // starts fresh — won't know
ChatSession helper
app.session() returns a small helper whose .ask() always resolves to a
ChatResponse (it throws instead of returning null):
const session = app.session();
const reply = await session.ask("Summarize the uploaded handbook.");
console.log(reply.response);
Interactive terminal chat
Call .chat() with no argument to start a REPL. Requires a Node.js TTY; in other
environments it throws CustodianError — pass a message instead.
await app.chat();
// Type "exit" or "quit" to end.
Notes
- Session state lives on the
App/TeamAppinstance. A new instance starts with no session. TeamAppbehaves identically.
Next steps
- Data Sources and RAG — understand
retrievedContexts. - Error Handling.