Skip to content

Commit ef664e1

Browse files
maninder-uipathclaude
maninder-uipath
and
claude
committed
docs: make each package README the single source for its docs page
These READMEs and the React Widgets pages on the SDK docs site were two near-complete copies of the same text, and had drifted: the multi-file-upload and pdf-viewer examples here still build the SDK inside the component body, which UiPath/uipath-typescript#770 fixed on its side. UiPath/uipath-typescript now fetches packages/<widget>/README.md at docs build time and renders it as docs/react-widgets/<widget>.md, the same way it already sources its JS Functions section from UiPath/coded-functions-js. So this brings the READMEs up to the reviewed content and adopts the conventions that build expects: - Fixed examples: the SDK is created once in a useEffect with await initialize(), and baseUrl is api.uipath.com, matching every SDK sample. - MkDocs-only syntax is written portably, since a README also has to render on npm and GitHub: `> **Note:** …` for admonitions, `<!-- tabs -->` and `<!-- details type: Title -->` for tabs and collapsibles. The fetch script translates them; npm renders a blockquote and drops the comments. - Cross-page links are absolute uipath.github.io URLs, so they resolve from an npm page too. - Development and License sit inside `<!-- docs:ignore -->`, which the fetch script strips -- contributor content stays in the README without reaching the docs site. - Validation Station gains the Vite hosting section (staging the web component into public/du-vs-wc, and why no vite.config.ts change is needed) and links to the four sample apps. docs-dispatch.yml tells the SDK repo to rebuild when a README lands on develop. It needs an SDK_DOCS_DISPATCH_TOKEN secret with contents:write on UiPath/uipath-typescript; without it the step warns and the site picks the change up on its next build. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 5ce8dfa commit ef664e1

7 files changed

Lines changed: 618 additions & 439 deletions

File tree

‎.github/workflows/docs-dispatch.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Refresh SDK Docs Site
2+
3+
# The React Widgets pages on the UiPath TypeScript SDK docs site are these
4+
# READMEs -- UiPath/uipath-typescript fetches them at docs build time rather
5+
# than keeping a second copy. Tell it to rebuild when one of them changes, so
6+
# the site does not wait for the next SDK release.
7+
on:
8+
push:
9+
branches: [develop]
10+
paths:
11+
- 'packages/*/README.md'
12+
workflow_dispatch:
13+
14+
jobs:
15+
dispatch:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- name: Trigger the docs build
19+
# A repository_dispatch to another repo needs a token with `contents:
20+
# write` there; the default GITHUB_TOKEN is scoped to this repo only.
21+
env:
22+
GH_TOKEN: ${{ secrets.SDK_DOCS_DISPATCH_TOKEN }}
23+
run: |
24+
if [ -z "${GH_TOKEN}" ]; then
25+
echo "::warning::SDK_DOCS_DISPATCH_TOKEN is not set -- the docs site will pick these READMEs up on its next build instead."
26+
exit 0
27+
fi
28+
gh api repos/UiPath/uipath-typescript/dispatches \
29+
--field event_type=react-widgets-docs-updated

‎packages/conversational-agent-chat/README.md‎

Lines changed: 60 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Conversational Agent Chat Widget
1+
# @uipath/ui-widgets-conversational-agent-chat
22

3-
A React component that provides a conversational AI chat interface powered by UiPath Conversational Agents. Built on top of UiPath Apollo React components, this widget enables seamless integration of AI-powered chat functionality into your applications.
3+
A React chat interface powered by [UiPath Conversational Agents](https://uipath.github.io/uipath-typescript/api/interfaces/ConversationalAgentServiceModel/). Built on UiPath Apollo React chat components, it drops an AI chat experience into your application with streaming, attachments and tool-call visibility.
44

55
## Features
66

@@ -10,25 +10,24 @@ A React component that provides a conversational AI chat interface powered by Ui
1010
- Conversation history management
1111
- Start new conversations or continue existing ones
1212
- Built on Apollo React chat components
13-
- Built with TypeScript for type safety
13+
- Written in TypeScript for type safety
1414

1515
## Installation
1616

1717
```bash
1818
npm install @uipath/ui-widgets-conversational-agent-chat
1919
```
2020

21-
## Peer Dependencies
22-
23-
This package requires the following peer dependencies:
21+
### Peer dependencies
2422

2523
```bash
26-
npm install react@^19.2.0 react-dom@^19.2.0 @uipath/uipath-typescript@^1.3.10
24+
npm install react@^19.2.0 react-dom@^19.2.0 @uipath/uipath-typescript@^1.5.5
2725
```
2826

2927
## Usage
3028

31-
> **Note:** Add either `light` or `dark` class to your HTML `<body>` element to enable proper theming.
29+
> **Note: Theming**
30+
> Add either a `light` or `dark` class to your HTML `<body>` element to enable proper theming.
3231
3332
```tsx
3433
import { ConversationalAgentChat } from "@uipath/ui-widgets-conversational-agent-chat";
@@ -42,10 +41,12 @@ function App() {
4241
useEffect(() => {
4342
const init = async () => {
4443
const uipath = new UiPath({
45-
baseUrl: "https://cloud.uipath.com",
44+
baseUrl: "https://api.uipath.com",
4645
orgName: "your-org",
4746
tenantName: "your-tenant",
48-
secret: "your-secret",
47+
clientId: "your-client-id",
48+
redirectUri: "http://localhost:3000/callback",
49+
scope: "OR.Execution OR.Folders OR.Users OR.Jobs ConversationalAgents Traces.Api",
4950
});
5051
await uipath.initialize();
5152
setSdk(uipath);
@@ -59,25 +60,24 @@ function App() {
5960
}
6061
```
6162

62-
## API Reference
63-
64-
### Props
63+
> **Info: Scopes for streaming**
64+
> The `ConversationalAgents` scope is what makes the real-time WebSocket session work; without it the REST calls succeed but the socket connection fails. See [OAuth Scopes](https://uipath.github.io/uipath-typescript/oauth-scopes/#conversational-agent) for the authoritative list.
6565
66-
| Prop | Type | Required | Description |
67-
| ------------------------ | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68-
| `sdk` | `UiPath` | Yes | UiPath SDK instance for API communication |
69-
| `agentId` | `number` | No | The ID of the conversational agent release. Required unless `existingConversationId` is provided. |
70-
| `folderId` | `number` | No | The folder ID the agent lives in. When omitted, the widget resolves it by listing agents and matching on `agentId` — prefer passing it when known. |
71-
| `existingConversationId` | `string` | No | Load an existing conversation by ID instead of creating a new one on first message. |
72-
| `inputSchema` | `InputSchema` | No | Agent input schema. Takes precedence over the schema derived from the resolved agent; use when the caller has the schema but the agent can't be resolved (e.g. an in-progress draft). |
73-
| `isDebugMode` | `boolean` | No | Debug flow: opens an empty conversation up front so inputs are collected in the widget, and submits update the existing conversation instead of creating a new one. |
74-
| `externalUserId` | `string` | No | External user identifier sent as `x-uipath-external-user-id` (HTTP header / WebSocket query param). Required when authenticating via an app-scoped external app; omit for standard user tokens. |
66+
## Props
7567

76-
## `ConversationalAgentPickerChat` (agent picker + chat)
68+
| Prop | Type | Required | Description |
69+
| ---- | ---- | -------- | ----------- |
70+
| `sdk` | `UiPath` | Yes | UiPath SDK instance for API communication |
71+
| `agentId` | `number` | No | The ID of the conversational agent release. Required unless `existingConversationId` is provided |
72+
| `folderId` | `number` | No | The folder ID the agent lives in. When omitted, the widget resolves it by listing agents and matching on `agentId` — prefer passing it when known |
73+
| `existingConversationId` | `string` | No | Load an existing conversation by ID instead of creating a new one on the first message |
74+
| `inputSchema` | `InputSchema` | No | Agent input schema. Takes precedence over the schema derived from the resolved agent; use when the caller has the schema but the agent can't be resolved (e.g. an in-progress draft) |
75+
| `isDebugMode` | `boolean` | No | Debug flow: opens an empty conversation up front so inputs are collected in the widget, and submits update the existing conversation instead of creating a new one |
76+
| `externalUserId` | `string` | No | External user identifier sent as `x-uipath-external-user-id` (HTTP header / WebSocket query param). Required when authenticating via an app-scoped external app; omit for standard user tokens |
7777

78-
A higher-level component that lists all conversational agents accessible to a given SDK and opens a chat with the selected one. Useful when you don't know the `agentId`/`folderId` up front and want the user to pick.
78+
## Agent picker + chat
7979

80-
### Usage
80+
`ConversationalAgentPickerChat` is a higher-level component that lists every conversational agent reachable by a given SDK instance and opens a chat with the selected one. Use it when you don't know the `agentId` / `folderId` up front and want the user to pick.
8181

8282
```tsx
8383
import { ConversationalAgentPickerChat } from "@uipath/ui-widgets-conversational-agent-chat";
@@ -91,10 +91,12 @@ function App() {
9191
useEffect(() => {
9292
const init = async () => {
9393
const uipath = new UiPath({
94-
baseUrl: "https://cloud.uipath.com",
94+
baseUrl: "https://api.uipath.com",
9595
orgName: "your-org",
9696
tenantName: "your-tenant",
97-
secret: "your-secret",
97+
clientId: "your-client-id",
98+
redirectUri: "http://localhost:3000/callback",
99+
scope: "OR.Execution OR.Folders OR.Users OR.Jobs ConversationalAgents Traces.Api",
98100
});
99101
await uipath.initialize();
100102
setSdk(uipath);
@@ -110,58 +112,60 @@ function App() {
110112

111113
### Props
112114

113-
| Prop | Type | Required | Description |
114-
| ----------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------- |
115-
| `sdk` | `UiPath` | Yes | UiPath SDK instance. Changing it refetches the list and resets the UI. |
116-
| `locale` | `Locale` | No | Passthrough to the inner chat. |
117-
| `theme` | `"light" \| "dark" \| "light-hc" \| "dark-hc"` | No | Passthrough to the inner chat. |
118-
| `readOnly` | `boolean` | No | Passthrough to the inner chat. |
119-
| `overrideLabels` | `OverrideLabels` | No | Passthrough to the inner chat. |
120-
| `onAgentSelected` | `(agent: AgentSummary) => void` | No | Fired when the user picks an agent (telemetry, routing, etc.). |
115+
| Prop | Type | Required | Description |
116+
| ---- | ---- | -------- | ----------- |
117+
| `sdk` | `UiPath` | Yes | UiPath SDK instance. Changing it refetches the list and resets the UI |
118+
| `locale` | `Locale` | No | Passthrough to the inner chat |
119+
| `theme` | `"light" \| "dark" \| "light-hc" \| "dark-hc"` | No | Passthrough to the inner chat |
120+
| `readOnly` | `boolean` | No | Passthrough to the inner chat |
121+
| `overrideLabels` | `OverrideLabels` | No | Passthrough to the inner chat |
122+
| `onAgentSelected` | `(agent: AgentSummary) => void` | No | Fired when the user picks an agent (telemetry, routing, etc.) |
121123

122124
### Behavior
123125

124-
- Calls `ConversationalAgent(sdk).getAll()` on mount → renders one row per agent (`name` + `description`).
126+
- Calls `ConversationalAgent(sdk).getAll()` on mount, then renders one row per agent (`name` + `description`).
125127
- Clicking an agent swaps to the chat view with that agent's `id` and `folderId`.
126-
- "Back" clears the selection and returns to the list (no refetch).
127-
- If the user's accessible tenants live behind your own auth/chrome, switch tenants by rebuilding the `UiPath` instance and passing the new one as `sdk` — the picker handles the rest.
128+
- **Back** clears the selection and returns to the list — no refetch.
129+
- If the user's accessible tenants live behind your own auth or chrome, switch tenants by rebuilding the `UiPath` instance and passing the new one as `sdk`; the picker handles the rest.
128130

129-
## Features in Detail
131+
## Features in detail
130132

131-
### Streaming Responses
133+
### Streaming responses
132134

133-
The component supports real-time streaming of AI responses, providing a smooth conversational experience as the agent generates its reply.
135+
Responses stream in real time, so the conversation stays fluid while the agent generates its reply.
134136

135-
### File Attachments
137+
### File attachments
136138

137-
Users can attach files to their messages via drag and drop or file picker.
139+
Users can attach files to their messages via drag and drop or the file picker.
138140

139-
### Tool Call Tracking
141+
### Tool call tracking
140142

141-
When the conversational agent uses tools, the component automatically displays:
143+
When the agent uses tools, the widget displays:
142144

143145
- Tool name and input parameters
144146
- Execution status
145147
- Output results
146148
- Error handling
147149

148-
### Session Management
150+
### Session management
149151

150-
The widget automatically handles:
151-
152-
- Conversation creation and persistence
153-
- Session initialization and maintenance
154-
- Multiple conversation support via "New Chat"
152+
The widget handles conversation creation and persistence, session initialization and maintenance, and multiple conversations via **New Chat**.
155153

156154
## Styling
157155

158-
The component comes with default styles. Import the CSS file in your application:
159-
160156
```tsx
161157
import "@uipath/ui-widgets-conversational-agent-chat/ConversationalAgentChat.css";
162158
```
163159

164-
The chat interface supports both light and dark themes through the UiPath Apollo design system.
160+
Both light and dark themes are supported through the UiPath Apollo design system.
161+
162+
## TypeScript
163+
164+
```tsx
165+
import type { ConversationalAgentChatProps } from "@uipath/ui-widgets-conversational-agent-chat";
166+
```
167+
168+
<!-- docs:ignore -->
165169

166170
## Development
167171

@@ -193,14 +197,8 @@ npm run test:ui
193197
npm run test:coverage
194198
```
195199

196-
## TypeScript Support
197-
198-
This package is written in TypeScript and includes type definitions. Import types as needed:
199-
200-
```tsx
201-
import type { ConversationalAgentChatProps } from "@uipath/ui-widgets-conversational-agent-chat";
202-
```
203-
204200
## License
205201

206202
MIT
203+
204+
<!-- /docs:ignore -->

0 commit comments

Comments
 (0)