Conversational Agent

Service for managing UiPath Conversational Agents — AI-powered chat interfaces that enable natural language interactions with UiPath automation. Discover agents, create conversations, and stream real-time responses over WebSocket. UiPath Conversational Agents Guide

Prerequisites: Initialize the SDK first - see Getting Started

How It Works

Lifecycle

graph TD
    A["Agent"] -->|conversations.create| B["Conversation"]
    B -->|startSession| C["Session"]
    B -->|exchanges.getAll| F(["History"])
    C -->|onSessionStarted| D["Ready"]
    D -->|startExchange| E["Exchange"]
    E -->|sendMessage| G["Message"]

Real-Time Event Flow

Once a session is started, events flow through a nested stream hierarchy:

graph TD
    S["SessionStream"]
    S -->|onExchangeStart| E["ExchangeStream"]
    S -->|onSessionEnd| SE(["session closed"])
    E -->|onMessageStart| M["MessageStream"]
    E -->|sendExchangeEnd| STOP(["stop response"])
    E -->|onExchangeEnd| EE(["exchange complete"])
    M -->|onContentPartStart| CP["ContentPartStream"]
    M -->|onToolCallStart| TC["ToolCallStream"]
    M -->|onInterruptStart| IR(["awaiting approval"])
    CP -->|onChunk| CH(["streaming data"])
    TC -->|onToolCallEnd| TCE(["tool result"])

Usage

import { ConversationalAgent } from '@uipath/uipath-typescript/conversational-agent';

const conversationalAgent = new ConversationalAgent(sdk);

// 1. Discover agents
const agents = await conversationalAgent.getAll();
const agent = agents[0];

// 2. Create a conversation
const conversation = await agent.conversations.create({ label: 'My Chat' });

// 3. Start real-time session and listen for responses
const session = conversation.startSession();

session.onExchangeStart((exchange) => {
  exchange.onMessageStart((message) => {
    if (message.isAssistant) {
      message.onContentPartStart((part) => {
        if (part.isMarkdown) {
          part.onChunk((chunk) => process.stdout.write(chunk.data ?? ''));
        }
      });
    }
  });
});

// 4. Wait for session to be ready, then send a message
session.onSessionStarted(() => {
  const exchange = session.startExchange();
  exchange.sendMessageWithContentPart({ data: 'Hello!' });
});

// 5. Stop a response mid-stream
// Use sendExchangeEnd() on any active exchange to stop the agent
session.onSessionStarted(() => {
  const exchange = session.startExchange();
  exchange.sendMessageWithContentPart({ data: 'Tell me a long story' });

  // Stop after 5 seconds
  setTimeout(() => exchange.sendExchangeEnd(), 5000);
});

// 6. End session when done
conversation.endSession();

// 7. Retrieve conversation history (offline)
const exchanges = await conversation.exchanges.getAll();

Properties

Property	Modifier	Type	Description
conversations	readonly	ConversationServiceModel	Service for creating and managing conversations. See ConversationServiceModel.
user	readonly	UserSettingsServiceModel	Service for reading and updating the current user's profile/context settings. See UserSettingsServiceModel.

Methods

downloadCitationSource()

downloadCitationSource(source: CitationSourceMedia): Promise<Blob>

Downloads the document behind a media citation as an authenticated Blob, fetching the source's downloadUrl with the SDK's access token. Use source.title as the file name.

The Blob type is resolved from the source mimeType, falling back to the response Content-Type then the title's file extension. HTML is returned as application/octet-stream so previewing it inline can't execute citation markup in your app's origin. The token is only sent to the tenant's configured origin; a missing, unparseable, or off-origin downloadUrl is rejected before any request is made.

Parameters

Parameter	Type	Description
source	CitationSourceMedia	A media citation source (CitationSourceMedia) with a downloadUrl

Returns

Promise<Blob>

Promise resolving to the document as a Blob

Example

import { isCitationSourceMedia } from '@uipath/uipath-typescript/conversational-agent';

if (isCitationSourceMedia(source)) {
  const blob = await conversationalAgent.downloadCitationSource(source);
  const url = URL.createObjectURL(blob);
  window.open(url, '_blank');
}

---

getAll()

getAll(folderId?: number): Promise<AgentGetResponse[]>

Gets all available conversational agents

Parameters

Parameter	Type	Description
folderId?	number	Optional folder ID to filter agents

Returns

Promise<AgentGetResponse[]>

Promise resolving to an array of agents AgentGetResponse

Examples

const agents = await conversationalAgent.getAll();
const agent = agents[0];

// Create conversation directly from agent (agentId and folderId are auto-filled)
const conversation = await agent.conversations.create({ label: 'My Chat' });

const agents = await conversationalAgent.getAll(folderId);

---

getById()

getById(id: number, folderId: number): Promise<AgentGetByIdResponse>

Gets a specific agent by ID

Parameters

Parameter	Type	Description
id	number	ID of the agent release
folderId	number	ID of the folder containing the agent

Returns

Promise<AgentGetByIdResponse>

Promise resolving to the agent AgentGetByIdResponse

Example

const agent = await conversationalAgent.getById(agentId, folderId);

// Create conversation directly from agent (agentId and folderId are auto-filled)
const conversation = await agent.conversations.create({ label: 'My Chat' });

---

onConnectionStatusChanged()

onConnectionStatusChanged(handler: (status: ConnectionStatus, error: null | Error) => void): () => void

Registers a handler that is called whenever the WebSocket connection status changes.

Parameters

Parameter	Type	Description
handler	(status: ConnectionStatus, error: null | Error) => void	Callback receiving a ConnectionStatus ('Disconnected'

Returns

Cleanup function to remove the handler

(): void

Returns

void

Example

const cleanup = conversationalAgent.onConnectionStatusChanged((status, error) => {
  console.log('Connection status:', status);
  if (error) {
    console.error('Connection error:', error.message);
  }
});

// Later, remove the handler
cleanup();