> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# CopilotHandler

- Package: [@gooddata/sdk-ui-gen-ai](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/index.md)
- Kind: class
- Stability: alpha
- Source: https://github.com/gooddata/gooddata-ui-sdk/blob/rel/11.68/libs/sdk-ui-gen-ai/src/copilot/CopilotHandler.ts

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Isolated headless workflow owner backed by pure transitions and immutable snapshots.

**Signature:**

```typescript
export declare class CopilotHandler<TBuild extends string = CopilotBuildType> 
```

## Remarks

Create one instance per mounted editor/runtime and dispose it on teardown. Host callbacks run after subscribers observe the committed state; application callbacks require an explicit success or interruption acknowledgement. No application store or React setup is required.

## Properties

| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [cancelGeneration](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlercancelgeneration) |  | (type: TBuild) =&gt; void | **_(ALPHA)_** Clear a matching foreground generation intent or build. |
| [definitionApplicationInterrupted](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerdefinitionapplicationinterrupted) |  | (applicationId: string) =&gt; void | **_(ALPHA)_** Release an interrupted application without cancelling a still-running response. |
| [definitionApplicationStarted](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerdefinitionapplicationstarted) |  | (source: [ICopilotApplicationSource](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.icopilotapplicationsource/index.md)&lt;TBuild&gt;) =&gt; string | **_(ALPHA)_** Track a host-initiated application, including an explicit draft-link open. Returns its correlation ID, or an empty string after disposal. |
| [definitionApplied](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerdefinitionapplied) |  | (applicationId: string, target: [ICopilotTarget](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.icopilottarget/index.md)&lt;TBuild&gt;) =&gt; void | **_(ALPHA)_** Acknowledge installation, using the final applied object identifier. Stale IDs are ignored. |
| [dispose](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerdispose) |  | () =&gt; void | **_(ALPHA)_** Permanently stop processing and release all listeners. Idempotent. |
| [getAppliedSource](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlergetappliedsource) |  | (target: [ICopilotTarget](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.icopilottarget/index.md)&lt;TBuild&gt;) =&gt; [ICopilotSource](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.icopilotsource/index.md) \| undefined | **_(ALPHA)_** Read the origin associated with the applied object, not the selected chat. |
| [getReasoningTitle](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlergetreasoningtitle) |  | () =&gt; string \| undefined | **_(ALPHA)_** Read the foreground reasoning heading. |
| [getSnapshot](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlergetsnapshot) |  | () =&gt; [ICopilotSnapshot](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.icopilotsnapshot/index.md)&lt;TBuild&gt; | **_(ALPHA)_** Read the stable, recursively frozen snapshot. |
| [getStatus](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlergetstatus) |  | (scope: [ICopilotScope](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.icopilotscope/index.md)&lt;TBuild&gt;) =&gt; [CopilotStatus](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilotstatus/index.md) | **_(ALPHA)_** Query the same pure scoped progress selector used by headless consumers. |
| [handleEvent](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerhandleevent) |  | (event: [ChatEvent](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.chatevent/index.md)) =&gt; void | **_(ALPHA)_** Consume one existing chat event. Ignored after disposal. |
| [hasDefinition](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerhasdefinition) |  | (target: [ICopilotTarget](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.icopilottarget/index.md)&lt;TBuild&gt;) =&gt; boolean | **_(ALPHA)_** Whether this exact workflow target has a pending or applied definition, regardless of chat selection. |
| [isGenerationPending](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerisgenerationpending) |  | (type: TBuild) =&gt; boolean | **_(ALPHA)_** Whether a creation intent or skill-activated creation is still pending. |
| [resetInteraction](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerresetinteraction) |  | () =&gt; void | **_(ALPHA)_** Clear foreground chat progress, preserving background requests and generation intent. |
| [resetTarget](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerresettarget) |  | (target: [ICopilotTarget](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.icopilottarget/index.md)&lt;TBuild&gt;) =&gt; void | **_(ALPHA)_** Apply a host navigation/reset boundary, preserving applications in progress. |
| [setContext](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlersetcontext) |  | (context: [ICopilotContext](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.icopilotcontext/index.md)&lt;TBuild&gt;) =&gt; void | **_(ALPHA)_** Update host facts without reading routes or application state. |
| [startGeneration](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlerstartgeneration) |  | (type: TBuild) =&gt; void | **_(ALPHA)_** Record an explicit creation intent before seeding the chat. |
| [subscribe](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-gen-ai/sdk-ui-gen-ai.copilothandler/index.md#copilothandlersubscribe) |  | (listener: () =&gt; void) =&gt; (() =&gt; void) | **_(ALPHA)_** Subscribe directly to changes. The returned function removes this subscription. |

## Property details

### CopilotHandler.cancelGeneration

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Clear a matching foreground generation intent or build.

**Signature:**

```typescript
cancelGeneration: (type: TBuild) => void;
```

### CopilotHandler.definitionApplicationInterrupted

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Release an interrupted application without cancelling a still-running response.

**Signature:**

```typescript
definitionApplicationInterrupted: (applicationId: string) => void;
```

### CopilotHandler.definitionApplicationStarted

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Track a host-initiated application, including an explicit draft-link open. Returns its correlation ID, or an empty string after disposal.

**Signature:**

```typescript
definitionApplicationStarted: (source: ICopilotApplicationSource<TBuild>) => string;
```

### CopilotHandler.definitionApplied

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Acknowledge installation, using the final applied object identifier. Stale IDs are ignored.

**Signature:**

```typescript
definitionApplied: (applicationId: string, target: ICopilotTarget<TBuild>) => void;
```

### CopilotHandler.dispose

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Permanently stop processing and release all listeners. Idempotent.

**Signature:**

```typescript
dispose: () => void;
```

### CopilotHandler.getAppliedSource

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Read the origin associated with the applied object, not the selected chat.

**Signature:**

```typescript
getAppliedSource: (target: ICopilotTarget<TBuild>) => ICopilotSource | undefined;
```

### CopilotHandler.getReasoningTitle

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Read the foreground reasoning heading.

**Signature:**

```typescript
getReasoningTitle: () => string | undefined;
```

### CopilotHandler.getSnapshot

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Read the stable, recursively frozen snapshot.

**Signature:**

```typescript
getSnapshot: () => ICopilotSnapshot<TBuild>;
```

### CopilotHandler.getStatus

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Query the same pure scoped progress selector used by headless consumers.

**Signature:**

```typescript
getStatus: (scope: ICopilotScope<TBuild>) => CopilotStatus;
```

### CopilotHandler.handleEvent

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Consume one existing chat event. Ignored after disposal.

**Signature:**

```typescript
handleEvent: (event: ChatEvent) => void;
```

### CopilotHandler.hasDefinition

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Whether this exact workflow target has a pending or applied definition, regardless of chat selection.

**Signature:**

```typescript
hasDefinition: (target: ICopilotTarget<TBuild>) => boolean;
```

### CopilotHandler.isGenerationPending

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Whether a creation intent or skill-activated creation is still pending.

**Signature:**

```typescript
isGenerationPending: (type: TBuild) => boolean;
```

### CopilotHandler.resetInteraction

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Clear foreground chat progress, preserving background requests and generation intent.

**Signature:**

```typescript
resetInteraction: () => void;
```

### CopilotHandler.resetTarget

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Apply a host navigation/reset boundary, preserving applications in progress.

**Signature:**

```typescript
resetTarget: (target: ICopilotTarget<TBuild>) => void;
```

### CopilotHandler.setContext

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Update host facts without reading routes or application state.

**Signature:**

```typescript
setContext: (context: ICopilotContext<TBuild>) => void;
```

### CopilotHandler.startGeneration

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Record an explicit creation intent before seeding the chat.

**Signature:**

```typescript
startGeneration: (type: TBuild) => void;
```

### CopilotHandler.subscribe

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Subscribe directly to changes. The returned function removes this subscription.

**Signature:**

```typescript
subscribe: (listener: () => void) => (() => void);
```
