npm.io
6.8.0 • Published 1 week ago

@atlaskit/rovo-agent-analytics

Licence
Apache-2.0
Version
6.8.0
Deps
5
Size
104 kB
Vulns
0
Weekly
0

RovoAgentAnalytics

Rovo Agents analytics library for composing and sending typed analytics events.

Usage

import { useRovoAgentActionAnalytics } from '@atlaskit/rovo-agent-analytics/actions';

const { trackAgentEvent } = useRovoAgentActionAnalytics({});

// Full control over event properties — all fields are type-checked
trackAgentEvent({
  action: 'view',
  actionSubject: 'rovoAgent',
  attributes: { 
    agentId: 'agent-123',
    touchPoint: 'browse-agent-list',
  },
});

Detailed docs and example usage can be found here.

Examples

Basic Event Tracking

For fully-typed events with explicit action, actionSubject, and attributes:

import { useRovoAgentActionAnalytics } from '@atlaskit/rovo-agent-analytics/actions';

const { trackAgentEvent } = useRovoAgentActionAnalytics({
  agentId,
  touchPoint: 'browse-agent-list',
});

// Track a user interaction
trackAgentEvent({
  action: 'duplicate',
  actionSubject: 'rovoAgent',
  attributes: {},
});
Event Tracking with Custom Attributes
import { useRovoAgentActionAnalytics } from '@atlaskit/rovo-agent-analytics/actions';

const { trackAgentEvent } = useRovoAgentActionAnalytics({});

// Full control over event properties — all fields are type-checked
trackAgentEvent({
  action: 'created',
  actionSubject: 'batchEvaluationDataset',
  attributes: { 
    totalQuestions: 5 
  },
  objectType: 'batchEvaluationDataset',
  objectId: 'dataset-123',
});

Payload Types

Each group file in src/actions/groups/ exports a discriminated union payload type that defines all valid event shapes for that group.

File Payload Type Description
agent-interactions.ts AgentInteractionsEventPayload User-initiated interactions (view, edit, delete, duplicate, star, chat, verify…)
triggers.ts TriggerEventPayload Inline trigger views and completed frontend CRUD operations
editing.ts EditingEventPayload Agent save/mutation events (updated)
debug.ts DebugEventPayload Debug modal actions (view, copy, toggle skill info)
tools.ts ToolsEventPayload Tool execution actions (confirm, stream stop, result viewed, error)
evaluation.ts EvaluationEventPayload Batch evaluation events (dataset CRUD, job lifecycle, results viewed)
create-flow.ts CreateFlowEventPayload Create agent funnel steps
add-tools-prompt.ts AddToolsPromptEventPayload Add tools prompt modal events
value-calculator.ts ValueCalculatorEventPayload Agent Insights value calculator funnel

The combined EventPayload type (exported from types.ts) is a union of all these payload types.

Adding a New Action

To an existing payload type
  1. Open the group file (e.g. src/actions/groups/agent-interactions.ts)
  2. Add a new variant to the payload union type with a data-portal registry link:
export type AgentInteractionsEventPayload =
  | {
      // https://data-portal.internal.atlassian.com/analytics/registry/XXXXX
      actionSubject: 'rovoAgent';
      action: 'myNewAction';
      attributes: BaseAgentAnalyticsAttributes & {
        myCustomField: string;
      };
    }
  | // ... existing variants

That's it — TypeScript will enforce the correct shape when calling trackAgentEvent().

To a new group

If your action doesn't fit any existing group, create a new one:

  1. Create a new file in src/actions/groups/ following the existing template
  2. Export a discriminated union payload type (e.g. MyFeatureEventPayload)
  3. Add the new type to the EventPayload union in src/common/types.ts:
import type { MyFeatureEventPayload } from '../actions/groups/my-feature';

export type EventPayload =
  | EditingEventPayload
  | AgentInteractionsEventPayload
  // ... existing types
  | MyFeatureEventPayload;

Defining Custom Attributes

Each action variant in a payload type can have its own specific attributes:

Using BaseAgentAnalyticsAttributes

For actions that need touchPoint and agentId:

{
  actionSubject: 'rovoAgent';
  action: 'view';
  attributes: BaseAgentAnalyticsAttributes;
}
Using Custom Attributes

For actions that need additional attributes:

{
  actionSubject: 'rovoAgent';
  action: 'updated';
  attributes: BaseAgentAnalyticsAttributes & { 
    agentType: string; 
    field: string; 
  };
}

Entry Points

Entry Point Description
@atlaskit/rovo-agent-analytics/actions Main entry point — exports useRovoAgentActionAnalytics hook
@atlaskit/rovo-agent-analytics/create Create agent flow analytics — exports useRovoAgentCreateAnalytics hook and AgentCreateAction type
Create Flow Analytics

The useRovoAgentCreateAnalytics hook is used for tracking the agent creation funnel:

import { useRovoAgentCreateAnalytics } from '@atlaskit/rovo-agent-analytics/create';

const [csid, { trackCreateSession, trackCreateSessionStart }] = useRovoAgentCreateAnalytics({
  touchPoint: 'agent-studio',
});

// Track funnel steps using string literal actions
trackCreateSession('createFlowStart');
trackCreateSession('createFlowActivate', { agentType: 'custom' });