@copilotkit/angular 0.1.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,9 @@
1
1
  # CopilotKit for Angular
2
2
 
3
- Angular bindings for CopilotKit core and AG-UI agents. This package provides services, directives, and utilities for building custom, headless Copilot UIs.
3
+ First-party Angular bindings for CopilotKit core and AG-UI agents. The package
4
+ ships standalone chat, popup, and sidebar components as well as signal-based
5
+ headless APIs, tool and activity renderers, threads, memories, interrupts,
6
+ attachments, A2UI, Open Generative UI, and opt-in MCP Apps support.
4
7
 
5
8
  ## Installation
6
9
 
@@ -11,9 +14,14 @@ npm install @copilotkit/angular
11
14
 
12
15
  Peer dependencies you provide in your app:
13
16
 
14
- - `@angular/core` and `@angular/common` (19, 20, or 21)
17
+ - `@angular/core` and `@angular/common` (20, 21, or 22)
15
18
  - `@angular/cdk` (match your Angular major)
16
- - `rxjs`
19
+ - `rxjs` 7.8 or newer
20
+
21
+ The exact versions exercised by the packed-consumer release matrix are stored
22
+ in `package.json` under `copilotkit.angularSupport`. The library is compiled at
23
+ the Angular 20 support floor and installed with strict peer checking against
24
+ all three supported majors.
17
25
 
18
26
  ## Quick start
19
27
 
@@ -102,10 +110,16 @@ export interface CopilotKitConfig {
102
110
  licenseKey?: string;
103
111
  properties?: Record<string, unknown>;
104
112
  agents?: Record<string, AbstractAgent>;
113
+ selfManagedAgents?: Record<string, AbstractAgent>;
105
114
  tools?: ClientTool[];
106
115
  renderToolCalls?: RenderToolCallConfig[];
116
+ renderActivityMessages?: RenderActivityMessageConfig[];
117
+ suggestionsConfig?: SuggestionsConfig[];
107
118
  frontendTools?: FrontendToolConfig[];
108
119
  humanInTheLoop?: HumanInTheLoopConfig[];
120
+ defaultToolRendering?: boolean;
121
+ a2ui?: A2UIConfig;
122
+ openGenerativeUI?: OpenGenerativeUIConfig;
109
123
  }
110
124
  ```
111
125
 
@@ -113,10 +127,18 @@ export interface CopilotKitConfig {
113
127
  - `headers`: Default headers sent to the runtime.
114
128
  - `properties`: Arbitrary props forwarded to agent runs.
115
129
  - `agents`: Local, in-browser agents keyed by `agentId`.
130
+ - `selfManagedAgents`: AG-UI agents managed directly by the application.
116
131
  - `tools`: Tool definitions advertised to the runtime (no handler).
117
132
  - `renderToolCalls`: Components to render tool calls in the UI.
133
+ - `renderActivityMessages`: Components to render AG-UI activity messages.
134
+ - `suggestionsConfig`: Static or runtime-generated chat suggestions.
118
135
  - `frontendTools`: Client-side tools with handlers.
119
136
  - `humanInTheLoop`: Tools that pause for user input.
137
+ - `defaultToolRendering`: Opt in to the text-only renderer for unknown tools.
138
+ It is disabled by default so missing renderers remain visible integration
139
+ errors rather than silently changing the experience.
140
+ - `a2ui`: Theme, catalog, schema, loading UI, and recovery policy for A2UI.
141
+ - `openGenerativeUI`: Sandboxed UI functions and optional design guidance.
120
142
 
121
143
  ### Injection helpers
122
144
 
@@ -295,6 +317,59 @@ provideCopilotKit({
295
317
 
296
318
  `tools` are advertised to the runtime. If you include `renderer` + `parameters` on a `ClientTool`, CopilotKit will also register a renderer for tool calls.
297
319
 
320
+ ## Prebuilt UI
321
+
322
+ All UI exports are standalone Angular components. Import the component classes
323
+ directly and import `@copilotkit/angular/styles.css` once in the application's
324
+ global stylesheet.
325
+
326
+ ### Full-page chat
327
+
328
+ ```ts
329
+ import { Component } from "@angular/core";
330
+ import { CopilotChat } from "@copilotkit/angular";
331
+
332
+ @Component({
333
+ selector: "app-assistant",
334
+ imports: [CopilotChat],
335
+ template: `<copilot-chat [agentId]="'default'" />`,
336
+ })
337
+ export class AssistantComponent {}
338
+ ```
339
+
340
+ Use `CopilotPopup` for a floating dialog and `CopilotSidebar` for responsive
341
+ overlay or docked presentation. Their `open` inputs are model signals, so
342
+ `[(open)]` supports controlled application state. Both include focus trapping,
343
+ Escape handling, focus restoration, accessible dialog naming, reduced-motion
344
+ behavior, and safe-area-aware mobile layouts.
345
+
346
+ ```ts
347
+ import { Component, signal } from "@angular/core";
348
+ import { CopilotPopup, CopilotSidebar } from "@copilotkit/angular";
349
+
350
+ @Component({
351
+ imports: [CopilotPopup, CopilotSidebar],
352
+ template: `
353
+ <copilot-popup [(open)]="popupOpen" title="Support assistant" />
354
+ <copilot-sidebar
355
+ [(open)]="sidebarOpen"
356
+ mode="docked"
357
+ position="right"
358
+ title="Workspace assistant"
359
+ />
360
+ `,
361
+ })
362
+ export class AssistantSurfacesComponent {
363
+ readonly popupOpen = signal(false);
364
+ readonly sidebarOpen = signal(false);
365
+ }
366
+ ```
367
+
368
+ `CopilotChatView`, message, input, toolbar, button, attachment, and slot
369
+ components are supported public customization primitives. See
370
+ [`API.md`](./API.md) for the exhaustive export inventory; use the higher-level
371
+ components unless you are replacing part of the default composition.
372
+
298
373
  ## `RenderToolCalls` component
299
374
 
300
375
  `RenderToolCalls` renders tool call components under an assistant message based on registered render configs.
@@ -321,6 +396,71 @@ Tool arguments are parsed with `partialJSONParse`, so incomplete JSON during str
321
396
  - If you need to change runtime settings at runtime, call `CopilotKit.updateRuntime(...)`.
322
397
  - `runtimeTransport` supports `"rest"` or `"single"` (SSE single-stream transport).
323
398
 
324
- ## Not documented here
325
-
326
- This package also exports a full set of chat UI components under `src/lib/components/chat`. Those APIs are intentionally omitted from this README.
399
+ ## Activity renderers and generative UI
400
+
401
+ Register application activity renderers with `registerRenderActivityMessage`
402
+ or the `renderActivityMessages` provider option. Application registrations
403
+ take precedence over optional built-ins.
404
+
405
+ - A2UI is enabled when the runtime advertises the capability or when
406
+ `a2ui.catalog` is supplied. An explicit catalog enables its renderers and
407
+ agent context even when runtime `/info` does not advertise A2UI, matching the
408
+ React provider contract. Configure recovery exposure independently of
409
+ server-provided lifecycle content.
410
+ - Open Generative UI is enabled with `openGenerativeUI: { ... }`. Generated UI
411
+ runs in an isolated WebSandbox; expose only narrowly scoped
412
+ `sandboxFunctions` and never place credentials in browser configuration.
413
+ - MCP Apps is intentionally a secondary entry point. Add
414
+ `provideMCPApps()` to application providers and import advanced host APIs
415
+ from `@copilotkit/angular/mcp-apps`. MCP resource and tool requests travel
416
+ through the selected AG-UI agent; the browser provider does not accept a
417
+ server URL. The renderer uses the same inline `srcdoc` sandbox, sandbox
418
+ permissions, and resource-domain CSP as the React SDK.
419
+
420
+ ## Lifecycle and cleanup
421
+
422
+ Call `injectAgentStore`, `connectAgentContext`, `registerFrontendTool`,
423
+ `registerRenderToolCall`, `registerRenderActivityMessage`, `injectInterrupt`,
424
+ `injectThreads`, and `injectMemories` from an Angular injection context. The
425
+ helpers bind subscriptions, effects, timers, runtime registrations, and
426
+ observers to the owning `DestroyRef`. Changing a signal-based agent ID tears
427
+ down the previous agent subscription before connecting the replacement.
428
+
429
+ Do not create these helpers in module-level code or cache an injected
430
+ controller beyond the lifetime of its injector. `AgentStore.teardown()` is
431
+ public for advanced manually constructed stores; stores returned by
432
+ `injectAgentStore` are cleaned up automatically and should not need a manual
433
+ call.
434
+
435
+ Application-owned asynchronous work remains application-owned. Cancel fetches
436
+ or other side effects started by a frontend-tool handler when its host is
437
+ destroyed, and do not resolve an interrupt after its controller has left the
438
+ view.
439
+
440
+ ## SSR, hydration, and zoneless Angular
441
+
442
+ The package is designed for standalone, OnPush, signal-based applications and
443
+ is tested with `provideZonelessChangeDetection()`. No Zone.js dependency is
444
+ required. Keep application state in signals or Angular outputs so zoneless
445
+ change detection can observe updates.
446
+
447
+ Browser-only DOM setup is deferred to render lifecycle hooks or guarded by the
448
+ platform where the package owns it. For SSR and hydration:
449
+
450
+ - provide the same CopilotKit configuration and initial `open`/`agentId`
451
+ values on the server and first client render;
452
+ - do not access returned agents or run tools during server rendering;
453
+ - make runtime URLs absolute when the server and browser use different
454
+ origins, or proxy a same-origin `/api/copilotkit` endpoint;
455
+ - enable A2UI, Open Generative UI, audio recording, and MCP Apps in the browser;
456
+ their interactive sandboxes, custom elements, media APIs, and iframes become
457
+ active after hydration;
458
+ - avoid branching the component tree on `window` before hydration. Use Angular
459
+ platform guards and `afterNextRender` for application-owned browser work.
460
+
461
+ ## Public API contract
462
+
463
+ [`API.md`](./API.md) lists every supported export from the root and MCP Apps
464
+ entry points and identifies the single internal extension token. A package test
465
+ compares that inventory to TypeScript's resolved entry-point exports so a new
466
+ public symbol cannot be introduced without documentation.
package/dist/README.md CHANGED
@@ -1,6 +1,9 @@
1
1
  # CopilotKit for Angular
2
2
 
3
- Angular bindings for CopilotKit core and AG-UI agents. This package provides services, directives, and utilities for building custom, headless Copilot UIs.
3
+ First-party Angular bindings for CopilotKit core and AG-UI agents. The package
4
+ ships standalone chat, popup, and sidebar components as well as signal-based
5
+ headless APIs, tool and activity renderers, threads, memories, interrupts,
6
+ attachments, A2UI, Open Generative UI, and opt-in MCP Apps support.
4
7
 
5
8
  ## Installation
6
9
 
@@ -11,9 +14,14 @@ npm install @copilotkit/angular
11
14
 
12
15
  Peer dependencies you provide in your app:
13
16
 
14
- - `@angular/core` and `@angular/common` (19, 20, or 21)
17
+ - `@angular/core` and `@angular/common` (20, 21, or 22)
15
18
  - `@angular/cdk` (match your Angular major)
16
- - `rxjs`
19
+ - `rxjs` 7.8 or newer
20
+
21
+ The exact versions exercised by the packed-consumer release matrix are stored
22
+ in `package.json` under `copilotkit.angularSupport`. The library is compiled at
23
+ the Angular 20 support floor and installed with strict peer checking against
24
+ all three supported majors.
17
25
 
18
26
  ## Quick start
19
27
 
@@ -102,10 +110,16 @@ export interface CopilotKitConfig {
102
110
  licenseKey?: string;
103
111
  properties?: Record<string, unknown>;
104
112
  agents?: Record<string, AbstractAgent>;
113
+ selfManagedAgents?: Record<string, AbstractAgent>;
105
114
  tools?: ClientTool[];
106
115
  renderToolCalls?: RenderToolCallConfig[];
116
+ renderActivityMessages?: RenderActivityMessageConfig[];
117
+ suggestionsConfig?: SuggestionsConfig[];
107
118
  frontendTools?: FrontendToolConfig[];
108
119
  humanInTheLoop?: HumanInTheLoopConfig[];
120
+ defaultToolRendering?: boolean;
121
+ a2ui?: A2UIConfig;
122
+ openGenerativeUI?: OpenGenerativeUIConfig;
109
123
  }
110
124
  ```
111
125
 
@@ -113,10 +127,18 @@ export interface CopilotKitConfig {
113
127
  - `headers`: Default headers sent to the runtime.
114
128
  - `properties`: Arbitrary props forwarded to agent runs.
115
129
  - `agents`: Local, in-browser agents keyed by `agentId`.
130
+ - `selfManagedAgents`: AG-UI agents managed directly by the application.
116
131
  - `tools`: Tool definitions advertised to the runtime (no handler).
117
132
  - `renderToolCalls`: Components to render tool calls in the UI.
133
+ - `renderActivityMessages`: Components to render AG-UI activity messages.
134
+ - `suggestionsConfig`: Static or runtime-generated chat suggestions.
118
135
  - `frontendTools`: Client-side tools with handlers.
119
136
  - `humanInTheLoop`: Tools that pause for user input.
137
+ - `defaultToolRendering`: Opt in to the text-only renderer for unknown tools.
138
+ It is disabled by default so missing renderers remain visible integration
139
+ errors rather than silently changing the experience.
140
+ - `a2ui`: Theme, catalog, schema, loading UI, and recovery policy for A2UI.
141
+ - `openGenerativeUI`: Sandboxed UI functions and optional design guidance.
120
142
 
121
143
  ### Injection helpers
122
144
 
@@ -295,6 +317,59 @@ provideCopilotKit({
295
317
 
296
318
  `tools` are advertised to the runtime. If you include `renderer` + `parameters` on a `ClientTool`, CopilotKit will also register a renderer for tool calls.
297
319
 
320
+ ## Prebuilt UI
321
+
322
+ All UI exports are standalone Angular components. Import the component classes
323
+ directly and import `@copilotkit/angular/styles.css` once in the application's
324
+ global stylesheet.
325
+
326
+ ### Full-page chat
327
+
328
+ ```ts
329
+ import { Component } from "@angular/core";
330
+ import { CopilotChat } from "@copilotkit/angular";
331
+
332
+ @Component({
333
+ selector: "app-assistant",
334
+ imports: [CopilotChat],
335
+ template: `<copilot-chat [agentId]="'default'" />`,
336
+ })
337
+ export class AssistantComponent {}
338
+ ```
339
+
340
+ Use `CopilotPopup` for a floating dialog and `CopilotSidebar` for responsive
341
+ overlay or docked presentation. Their `open` inputs are model signals, so
342
+ `[(open)]` supports controlled application state. Both include focus trapping,
343
+ Escape handling, focus restoration, accessible dialog naming, reduced-motion
344
+ behavior, and safe-area-aware mobile layouts.
345
+
346
+ ```ts
347
+ import { Component, signal } from "@angular/core";
348
+ import { CopilotPopup, CopilotSidebar } from "@copilotkit/angular";
349
+
350
+ @Component({
351
+ imports: [CopilotPopup, CopilotSidebar],
352
+ template: `
353
+ <copilot-popup [(open)]="popupOpen" title="Support assistant" />
354
+ <copilot-sidebar
355
+ [(open)]="sidebarOpen"
356
+ mode="docked"
357
+ position="right"
358
+ title="Workspace assistant"
359
+ />
360
+ `,
361
+ })
362
+ export class AssistantSurfacesComponent {
363
+ readonly popupOpen = signal(false);
364
+ readonly sidebarOpen = signal(false);
365
+ }
366
+ ```
367
+
368
+ `CopilotChatView`, message, input, toolbar, button, attachment, and slot
369
+ components are supported public customization primitives. See
370
+ [`API.md`](./API.md) for the exhaustive export inventory; use the higher-level
371
+ components unless you are replacing part of the default composition.
372
+
298
373
  ## `RenderToolCalls` component
299
374
 
300
375
  `RenderToolCalls` renders tool call components under an assistant message based on registered render configs.
@@ -321,6 +396,71 @@ Tool arguments are parsed with `partialJSONParse`, so incomplete JSON during str
321
396
  - If you need to change runtime settings at runtime, call `CopilotKit.updateRuntime(...)`.
322
397
  - `runtimeTransport` supports `"rest"` or `"single"` (SSE single-stream transport).
323
398
 
324
- ## Not documented here
325
-
326
- This package also exports a full set of chat UI components under `src/lib/components/chat`. Those APIs are intentionally omitted from this README.
399
+ ## Activity renderers and generative UI
400
+
401
+ Register application activity renderers with `registerRenderActivityMessage`
402
+ or the `renderActivityMessages` provider option. Application registrations
403
+ take precedence over optional built-ins.
404
+
405
+ - A2UI is enabled when the runtime advertises the capability or when
406
+ `a2ui.catalog` is supplied. An explicit catalog enables its renderers and
407
+ agent context even when runtime `/info` does not advertise A2UI, matching the
408
+ React provider contract. Configure recovery exposure independently of
409
+ server-provided lifecycle content.
410
+ - Open Generative UI is enabled with `openGenerativeUI: { ... }`. Generated UI
411
+ runs in an isolated WebSandbox; expose only narrowly scoped
412
+ `sandboxFunctions` and never place credentials in browser configuration.
413
+ - MCP Apps is intentionally a secondary entry point. Add
414
+ `provideMCPApps()` to application providers and import advanced host APIs
415
+ from `@copilotkit/angular/mcp-apps`. MCP resource and tool requests travel
416
+ through the selected AG-UI agent; the browser provider does not accept a
417
+ server URL. The renderer uses the same inline `srcdoc` sandbox, sandbox
418
+ permissions, and resource-domain CSP as the React SDK.
419
+
420
+ ## Lifecycle and cleanup
421
+
422
+ Call `injectAgentStore`, `connectAgentContext`, `registerFrontendTool`,
423
+ `registerRenderToolCall`, `registerRenderActivityMessage`, `injectInterrupt`,
424
+ `injectThreads`, and `injectMemories` from an Angular injection context. The
425
+ helpers bind subscriptions, effects, timers, runtime registrations, and
426
+ observers to the owning `DestroyRef`. Changing a signal-based agent ID tears
427
+ down the previous agent subscription before connecting the replacement.
428
+
429
+ Do not create these helpers in module-level code or cache an injected
430
+ controller beyond the lifetime of its injector. `AgentStore.teardown()` is
431
+ public for advanced manually constructed stores; stores returned by
432
+ `injectAgentStore` are cleaned up automatically and should not need a manual
433
+ call.
434
+
435
+ Application-owned asynchronous work remains application-owned. Cancel fetches
436
+ or other side effects started by a frontend-tool handler when its host is
437
+ destroyed, and do not resolve an interrupt after its controller has left the
438
+ view.
439
+
440
+ ## SSR, hydration, and zoneless Angular
441
+
442
+ The package is designed for standalone, OnPush, signal-based applications and
443
+ is tested with `provideZonelessChangeDetection()`. No Zone.js dependency is
444
+ required. Keep application state in signals or Angular outputs so zoneless
445
+ change detection can observe updates.
446
+
447
+ Browser-only DOM setup is deferred to render lifecycle hooks or guarded by the
448
+ platform where the package owns it. For SSR and hydration:
449
+
450
+ - provide the same CopilotKit configuration and initial `open`/`agentId`
451
+ values on the server and first client render;
452
+ - do not access returned agents or run tools during server rendering;
453
+ - make runtime URLs absolute when the server and browser use different
454
+ origins, or proxy a same-origin `/api/copilotkit` endpoint;
455
+ - enable A2UI, Open Generative UI, audio recording, and MCP Apps in the browser;
456
+ their interactive sandboxes, custom elements, media APIs, and iframes become
457
+ active after hydration;
458
+ - avoid branching the component tree on `window` before hydration. Use Angular
459
+ platform guards and `afterNextRender` for application-owned browser work.
460
+
461
+ ## Public API contract
462
+
463
+ [`API.md`](./API.md) lists every supported export from the root and MCP Apps
464
+ entry points and identifies the single internal extension token. A package test
465
+ compares that inventory to TypeScript's resolved entry-point exports so a new
466
+ public symbol cannot be introduced without documentation.