> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Learn how to build agentic experiences with Anvil2 AI Kit and the Carto theme.

Anvil2 AI Kit provides guidance, patterns, and components for building agentic product experiences. Carto is the visual theme AI Kit uses to give agentic surfaces a consistent identity across web and mobile.
Use this guide to understand when to use AI Kit, how it relates to the rest of Anvil2, and how to get started.

## What is "agentic"?

An agentic experience uses AI to act on your behalf, not just to advise you. Four things define it:

* **Context**: the system understands what's relevant.
* **Reasoning**: it makes thoughtful, adaptive decisions.
* **Conversation**: it explains what it's doing.
* **Action**: it takes meaningful steps for you, not just suggestions you have to act on yourself.

Compare that to non-agentic AI, which stays advisory: it surfaces insights and recommendations, but a person still has to do the work.

## Overview

AI Kit is part of Anvil2. It extends the Anvil2 ecosystem with design guidance and building blocks for agentic experiences, including chat, generative UI, panels, action surfaces, and agent-mediated flows.
Carto provides the visual layer for AI Kit through its typography, iconography, semantic tokens, component tokens, and component styling. Core Anvil2 continues to support standard product surfaces, while AI Kit applies Carto to agentic surfaces within AgentOS.

### When do I use AI Kit?

Use AI Kit when building an agentic surface within AgentOS.
Do not apply the Carto theme to an entire screen solely because it contains an AI-powered feature. When an agentic element appears within a core Anvil2 surface, use the defined integration patterns for that element instead of applying AI Kit components or the Carto theme to the surrounding product UI.

### How does AI Kit relate to Anvil2?

AI Kit belongs to the Anvil2 design system and specializes it for agentic product experiences. Use core Anvil2 components and guidance for standard product UI. Use AI Kit when a surface requires agentic interaction patterns, AI-specific components, or the Carto visual treatment.
The Carto theme gives agentic surfaces a distinct visual identity while keeping their implementation within the Anvil2 ecosystem.

<Note>
  Beyond the Carto theme, AI Kit uses agent-friendly APIs to improve
  consistency. Its components favor prop-driven interfaces over compositions of
  subcomponents, limit reliance on open-ended `children` props, and use a
  tighter token system to keep web and mobile libraries aligned automatically.
  Over time, these API improvements will be incorporated into the core Anvil2
  library.
</Note>

### How is this different from Atlas v1?

Atlas v1 was the previous iteration of ServiceTitan's agentic chat experience. It was built with [`ext-atlas`](/docs/kits/atlas), Anvil2's extended Atlas component library, and focused on chat-based interactions.
Atlas today uses AI Kit and the Carto theme to support agentic experiences beyond chat. `ext-atlas` supports existing Atlas v1 integrations and is deprecated for new Atlas experiences.

## How do I start?

### Design assets

1. Get familiar with what's covered above: when to use AI Kit, how it relates to Anvil2, and how Carto styles agentic surfaces.
2. Explore the component libraries in Figma:
   * [Web Components](https://www.figma.com/design/QEIsArLktLeJAaFvcpw3PO/Carto-Web-Components?m=auto\&node-id=505-2597\&t=95kmwGT5HM0WAnlp-1)
   * [React Native Components](https://www.figma.com/design/gjGWnAOnI1kukfzjsUQ6dP/Mobile-Agentic-Component-Library?m=auto\&node-id=1-20524\&t=TomzmvO7I642gBup-1)
   * [Design Tokens and Iconography](https://www.figma.com/design/6WeJz8JMm1in6Wb4g0wLP5/Carto-Design-Tokens?m=auto\&node-id=105-264\&t=aYAxxbtkRw4ttuUB-1)
3. Explore the [AI Kit component Storybook](https://design-platform-docs.vercel.app/carto/react-kit/).
4. Have questions on agentic patterns? Ask in [#support-agentic-design](https://servicetitan.enterprise.slack.com/archives/C08PPU97WJG). Have questions about components or implementation? Ask in [#ask-designsystem](https://servicetitan.enterprise.slack.com/archives/CBSRGHTRS). Since the system and its conventions are still forming, a quick check-in helps you avoid rework as things solidify.

### Engineering assets

Use `@servicetitan/carto-react-kit` to implement AI Kit experiences on the web. It provides chat shells, prompts, artifacts, supporting primitives, and the Carto theme through a consistent React API.

Peer requirements: `react@>=18 <20`, `react-dom@>=18 <20`.

#### Storybook

<Card title="AI Kit component Storybook" icon="book-open" href="https://design-platform-docs.vercel.app/carto/react-kit/">
  Explore API documentation and interactive component examples.
</Card>

<Info>AI Kit API documentation will move to this site soon.</Info>

#### Install

```bash theme={null}
pnpm add @servicetitan/carto-react-kit
```

Or with npm:

```bash theme={null}
npm install --save @servicetitan/carto-react-kit
```

#### Styles

Import the CSS bundle once at your application entry point so vanilla-extract styles load:

```tsx theme={null}
import "@servicetitan/carto-react-kit/styles.css";
```

#### Theme

Wrap your AI Kit tree in `CartoTheme` so Carto design tokens inherit to every descendant, including components rendered inside MFE shadow roots:

```tsx theme={null}
import { CartoTheme } from "@servicetitan/carto-react-kit";

export function Root({ children }) {
  return <CartoTheme appearance="auto">{children}</CartoTheme>;
}
```

Overlays from React Aria (Tooltip, Popover, Menu, Modal, Toast) portal into a sibling inside the theme wrapper rather than `document.body`, so token context stays intact.

#### Fonts

AgentOS pairs Sofia Pro for headers with Inter for body copy. This differs from the existing setup in Web, which pairs Sofia Pro with Nunito Sans.

Prefetch Inter in your document `<head>` for the fastest first paint. The kit also injects this link at module load as a safety net.

```html theme={null}
<link rel="preconnect" href="https://fonts.googleapis.com" crossorigin />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css?family=Inter:400,400i,500,500i,700,700i&display=optional"
/>
```

Sofia Pro requires no additional setup: the kit reuses the same Sofia Pro already loaded by your host application, the same font Web relies on for headers.

#### Quick start

```tsx theme={null}
import { Button, CartoTheme, Text } from "@servicetitan/carto-react-kit";
import { IconPencil } from "@servicetitan/carto-react-kit/icons";
import "@servicetitan/carto-react-kit/styles.css";

export function App() {
  return (
    <CartoTheme>
      <Text variant="headline" size="regular" text="AI Kit" />
      <Button label="Edit" icon={<IconPencil />} onPress={() => {}} />
    </CartoTheme>
  );
}
```

#### Icons

AI Kit uses [Lucide](https://lucide.dev/) icons (`lucide-react`) along with a small number of custom Carto SVGs. Import icons from the kit subpath, not directly from `lucide-react`:

```tsx theme={null}
import { IconPencil, IconPlus } from "@servicetitan/carto-react-kit/icons";
```

The icon allowlist is owned by VizD and curated inside the kit. Consumers cannot extend it from outside.

#### Internationalization

`CartoIntlProvider` is optional. Without it, components render English. Mount it inside `CartoTheme` to switch locale or override strings without colliding with your app’s react-intl context:

```tsx theme={null}
import { CartoTheme, CartoIntlProvider } from "@servicetitan/carto-react-kit";

export function Root({ children }) {
  return (
    <CartoTheme appearance="auto">
      <CartoIntlProvider locale="fr-FR">{children}</CartoIntlProvider>
    </CartoTheme>
  );
}
```

### Resources

<Columns cols={2}>
  <Card title="AI Kit overview" icon="sparkles" href="/docs/kits/ai-kit">
    Learn what AI Kit covers and how its documentation is organized.
  </Card>

  <Card title="Terminology" icon="book" href="/docs/kits/ai-kit/terminology">
    Explore core terms used across AI experiences and ServiceTitan.
  </Card>

  <Card title="Visual Foundations" icon="block-brick" href="/docs/kits/ai-kit/foundations/overview">
    Explore the visual foundations of AI Kit and the Carto theme.
  </Card>

  <Card title="Components" icon="shapes" href="/docs/kits/ai-kit/components/overview">
    Browse reusable AI Kit building blocks.
  </Card>

  <Card title="AI UX" icon="sparkles" href="/docs/kits/ai-kit/ai-ux/overview">
    Read guidance for agentic product experiences.
  </Card>
</Columns>