Chat

A chat is one conversation with the Simba agent: an ordered transcript of user and agent messages, plus the record of the actions the agent took to answer them.

A chat is the session the agent runs in. A user opens one from anywhere in the web app, sends a message, and the agent replies over a stream, calling tools to read and write resources as it works. Every resource the agent creates or edits during the chat is attributed back to it, so the chat is the actor behind a CHT_ reference elsewhere in Perpetual: the chatId on a case timeline entry, the closedByChatId on a case the agent closed, and the createdByChatId or updatedByChatId that stands in for a user on any resource the agent authored. A chat is scoped to one Space or to all Spaces at creation, and it authors content into the changeset the user has open, so its edits stage and commit the same way a person's do.

Agent and scope

A chat runs under a named agent configuration, its agentName. The default for a user-initiated conversation is simba-chat. Other agents run in their own chats behind product features rather than the chat surface, such as case-analysis for automated case analysis and content-engineer for content work items. The agentName is the key the countByAgentNames endpoint groups by when reporting agent activity over a time window.

A chat's scope is fixed at creation by its spaceId. A chat scoped to a Space sees and acts on only that Space's resources. A chat with no spaceId is scoped to all Spaces. The scope cannot change after the chat is created. In the web app, "Auto" mode resolves the scope from the first message before the chat is created (the resolve-space-scope endpoint), returning a single Space, all Spaces, or an ambiguous set for the user to choose from.

Inputs

A chat is created with an initial message and continued by sending more messages to it. The agent's reply streams back rather than returning as a value, so create and send-message have no field-shaped output. Both take the same body.

Field	Type	Required	Description
messages	array<object>	Required	The conversation turns to run the agent against. On create, the initial user message. On send-message, the full message array with the new turn appended.
pageContext	string	Required	Where in the web app the user is, passed to the agent as context for the request.
spaceId	string	Optional	The Space to scope the chat to. Used only at creation. Omit it to scope the chat to all Spaces.
activeChangesetId	string	Optional	The changeset the user has open in the UI (draft or proposed). The agent authors content edits into it.
activeClientToolNames	array<string>	Optional	Names of the client-side tools the UI is offering the agent for this turn.
dynamicClientTools	object	Optional	Client-supplied tool definitions for this turn, keyed by tool name, each with a description, inputSchema, and outputSchema.
timeZone	string	Optional	The user's IANA time zone, so the agent resolves relative times against it.

Outputs

getById returns the chat with its full transcript. list returns the same shape without messages. Sending a message does not return the chat. The reply arrives on the message stream. The chat's id is prefixed CHT_.

Field	Type	Description
messages	array<object>	The full transcript of user and agent messages, including tool calls and their results. Returned by getById, omitted by list.

Plus the common resource fields.

Related

• The Simba agent, what runs inside a chat and how it authors content and works cases.
• Cases, which reference the chat that acted on them through closedByChatId and their timeline chatId.
• Spaces, the scope a chat is fixed to at creation.
• Changesets, where a chat's content edits stage before they commit.