AI agents and conversations

Use jet.agent(agentUid) to prompt a configured agent and manage its conversations. These methods use the agent API; they are distinct from editing a database collection named assistant_conversation.

Create a conversation and send a prompt

import { Jet } from '@jet-admin/jet-sdk';

async function startConversation(jet: Jet, prompt: string) {
  const agent = jet.agent('YOUR_AGENT_UID');
  const conversation = await agent.createConversation();
  const result = await agent.prompt({ conversation: conversation.id, prompt });
  return {
    conversationId: conversation.id,
    completed: result.result,
    messages: result.messagesCreated,
  };
}

Retain conversation.id and send it with later prompts to continue the same conversation. prompt() resolves to AgentPromptResult with result: boolean, messagesCreated: AgentMessage[], and conversationName: string. It does not expose a conversation ID, so explicitly creating a conversation is useful when you need to retain it.

Prompt options

Both prompt(options?) and promptSse(options?) accept:

Option	Type	Purpose
conversation	string	Conversation identifier
prompt	string	User's prompt
params	Record<string, unknown>	Parameters supported by the configured agent
promptImageBase64	string[]	Base64 image values; accepted encoding details depend on the API
promptImageURLs	string[]	Image URLs
promptDocumentURLs	string[]	Document URLs
confirmMessage	string	Confirmation message value expected by the agent flow
confirmContext	Record<string, unknown>	Context expected by that confirmation flow

All options are optional in the SDK types; the server determines valid combinations. The SDK forwards confirmation values without defining their payload contract. Obtain these values from your agent's confirmation flow rather than inventing them.

Stream agent events

import {
  Jet, AgentMessage, AgentPromptRequest, AgentPromptResult,
} from '@jet-admin/jet-sdk';

async function streamReply(jet: Jet, conversationId: string, prompt: string) {
  const agent = jet.agent('YOUR_AGENT_UID');
  for await (const event of agent.promptSse({ conversation: conversationId, prompt })) {
    if (event instanceof AgentMessage) {
      console.log('New message', event.id, event.content);
    } else if (event instanceof AgentPromptRequest) {
      console.log('Request', event.request);
    } else if (event instanceof AgentPromptResult) {
      console.log('Result', event.result, event.messagesCreated);
    }
  }
}

promptSse() reads Server-Sent Events through fetch and yields class instances:

Server event	Yielded value
message_created	AgentMessage
request	AgentPromptRequest with request: string
result	AgentPromptResult
error	Throws JetRequestError

Other event types are ignored. The SDK has no dedicated token-delta event contract, automatic reconnection, or AbortSignal option. Exiting the loop cancels the response reader; it does not guarantee cancellation of the agent's server-side work. See streaming limitations.

Read conversation history

import { Jet } from '@jet-admin/jet-sdk';

async function loadHistory(jet: Jet, conversationId: string) {
  const agent = jet.agent('YOUR_AGENT_UID');
  const page = await agent.getMessages({ conversationId, page: 1 });
  return { messages: page.results, hasMore: page.hasMore };
}

Method	Arguments	Resolved value
getConversations(options?)	{ search?: string, page?: number }	results: AgentConversation[], hasMore
getConversation(id)	Conversation ID	AgentConversation
createConversation()	None	AgentConversation
renameConversation(id, name)	ID and new name	AgentConversation
archiveConversation(id)	ID	{ result, otherConversation }; replacement conversation is populated only if returned
getMessages(options?)	{ page?: number, conversationId?: string }	results: AgentMessage[], hasMore, and conversation when returned
getConversationFiles(id, options?)	ID and { page?: number, perPage?: number }	results: StorageObject[], hasMore, perPage

For listing methods, request the next page while the server returns hasMore: true. Pagination is manual. getConversationFiles() sends the page-size query parameter as perPage in this version; confirm compatibility with your endpoint if it ignores the page size.

Conversations include id, name, objectType, objectId, params, dateAdd, filesCount, and optional lastMessage. Messages include id, type, content, params, dateAdd, and parentId, with user/local ID data when returned.

Display message content

message.content is an array of AgentContentBlock, not a single text string. Text is available through block.markdown?.content, block.plainText?.content, or block.html?.content. Other parsed payloads include images, files, calls, confirmations, follow-ups, and questions.

Render only supported block types in your UI, handle unknown types gracefully, and sanitize HTML or rendered Markdown before inserting it into the DOM. The SDK parses data; it does not provide a chat UI or sanitize content. Some enum values have no dedicated payload parser in this version.