### Install sitecore-ai-sdk-tools and Peer Dependencies

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Install the main package and its required peer dependencies using npm.

```bash
npm install sitecore-ai-sdk-tools

# Peer dependencies
npm install @sitecore-marketplace-sdk/client @sitecore-marketplace-sdk/xmc ai zod
```

--------------------------------

### Install sitecore-ai-sdk-tools

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Install the package using npm. This package provides tools for integrating Sitecore Marketplace with the Vercel AI SDK.

```bash
npm install sitecore-ai-sdk-tools
```

--------------------------------

### Client-side Tool Execution Handling

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Handle tool calls on the client-side using the `useChat` hook and `onFinish` callback. This example demonstrates how to execute Sitecore Marketplace or Page Builder tools.

```typescript
// define sitecoreContextId
const executeTool = async (toolPart: ToolUIPart) => {
    const toolName = toolPart.type.substring('tool-'.length);
    if (!sitecoreContextId) {
      throw new Error('No sitecore context found');
    }
    try {
      let res = await executeAgentTool(
        { client, sitecoreContextId },
        { toolName, input: toolPart.input }
      );
      if (!res.success) {
        res = await executePageBuilderTool(
          { client, sitecoreContextId },
          { toolName, input: toolPart.input }
        );
      }
    } catch (error) {
      console.error('Error executing tool:', error);
    }
}

const chat = useChat({
    transport: ...,
    onFinish: async ({ message, finishReason }) => {
    // if tool was finished because of tool call
        if (finishReason !== 'tool-calls') {
            return;
        }
        for (const part of message.parts) {
            if (!part.type.startsWith('tool')) {
                continue;
            }
            const toolPart = part as ToolUIPart;
            if (toolPart.type.startsWith('tool')) {
                // if input is available - run tool
                if (toolPart.state === 'input-available') {
                    await executeTool(toolPart);
                }
            }
        }
    }
});
```

--------------------------------

### Page Builder UI Tools - `pageBuilderTools`

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Use `pageBuilderTools` to get schema-only Vercel AI SDK tools for controlling the XM Cloud Page Builder UI. These tools are client-side only and must be run via `executePageBuilderTool()`. Define tools with an optional approval gate using `needsApproval: true`.

```typescript
import { pageBuilderTools, executePageBuilderTool } from 'sitecore-ai-sdk-tools';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { ClientSDK } from '@sitecore-marketplace-sdk/client';

const client = new ClientSDK(/* config */);
const sitecoreContextId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

// Define tools with optional approval gate
const pbTools = pageBuilderTools({ needsApproval: true });

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Navigate to item a1b2c3d4-வுகளை',
  tools: pbTools,
});

// Execute the tool call returned by the model
const toolCall = result.toolCalls[0];
const execResult = await executePageBuilderTool(
  { client, sitecoreContextId },
  { toolName: toolCall.toolName, input: toolCall.input }
);
// execResult = { success: true, result: 'Navigated to item: a1b2c3d4-...' }
```

--------------------------------

### Manage Sitecore Component Datasources with SDK Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Utilize these tools for component discovery and datasource management. You can list components, get their details, search for datasources, or create new ones with specified fields and child items. A jobId is returned for new datasource creation for potential undo.

```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';

const client = new experimental_XMC({ /* config */ });
const tools = createAgentTools({
  execution: 'server',
  client,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

// List all components available in a site
const components = await tools.list_components.execute!({
  site_name: 'MySite',
});
// Returns: [{ componentId, name, datasourceTemplateId, fields, ... }, ...]

// Get full details for one component
const component = await tools.get_component.execute!({
  componentId: 'b3c4d5e6-f7a8-9012-bcde-678901234567',
});

// Find existing datasources matching a search term
const dataSources = await tools.search_component_datasources.execute!({
  componentId: 'b3c4d5e6-f7a8-9012-bcde-678901234567',
  term: 'hero',
});

// Create a new datasource for a component (with child items)
const newDs = await tools.create_component_datasource.execute!({
  componentId: 'b3c4d5e6-f7a8-9012-bcde-678901234567',
  siteName: 'MySite',
  language: 'en',
  dataFields: {
    Heading: 'Welcome to our platform',
    SubHeading: 'Discover XM Cloud',
  },
  children: [
    { Title: 'Feature 1', Icon: 'star' },
    { Title: 'Feature 2', Icon: 'rocket' },
  ],
});
console.log(newDs.jobId); // For undo if needed

```

--------------------------------

### Client-side Agent Tools Configuration

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Configure agent tools for client-side execution. This is the default mode and requires no additional authentication setup.

```typescript
import { createAgentTools, executeAgentTool } from "sitecore-ai-sdk-tools";
import { generateText } from "ai";

const tools = createAgentTools({ execution: "client" });

const result = await generateText({
  model: yourModel,
  prompt: "List all sites",
  tools,
});
```

--------------------------------

### Create Agent Tools for Server-Side Execution

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Demonstrates creating agent tools for server-side execution using an `experimental_XMC` client. Requires authentication configuration and optionally enforces approval for mutations.

```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

// --- Server-side mode ---
const xmcClient = new experimental_XMC({ /* auth config */ });

const serverTools = createAgentTools({
  execution: 'server',
  client: xmcClient,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  // Optional: require approval only for write operations
  needsApproval: true,
  needsApprovalFor: 'mutations',
});

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'List all sites, then get the first page of the main site in English.',
  tools: serverTools,
  maxSteps: 5,
});
console.log(result.text);
```

--------------------------------

### Initialize Page Builder Tools

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Initialize page builder tools for client-side interaction with the XM Cloud Page Builder UI. Ensure the `sitecore-ai-sdk-tools` library is imported.

```typescript
import { pageBuilderTools } from "sitecore-ai-sdk-tools";

const tools = pageBuilderTools();
```

--------------------------------

### createAgentTools - Available Tools

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Lists all available XM Cloud tools grouped by domain when using `createAgentTools`.

```APIDOC
## createAgentTools - Available Tools

### Description
Returns all XM Cloud tools grouped by domain.

### Tools by Group

**Assets**
- `get_asset_information`
- `search_assets`
- `update_asset`
- `upload_asset`

**Pages**
- `get_page`
- `create_page`
- `get_page_template_by_id`
- `get_allowed_components_by_placeholder`
- `get_components_on_page`
- `add_component_on_page`
- `set_component_datasource`
- `add_language_to_page`
- `search_site`
- `get_page_path_by_live_url`
- `get_page_screenshot`
- `get_page_html`
- `get_page_preview_url`

**Sites**
- `get_sites_list`
- `get_site_details`
- `get_all_pages_by_site`
- `get_site_id_from_item`

**Content**
- `create_content_item`
- `delete_content`
- `get_content_item_by_id`
- `update_content`
- `get_content_item_by_path`
- `list_available_insert_options`

**Components**
- `create_component_datasource`
- `search_component_datasources`
- `list_components`
- `get_component`

**Personalization**
- `create_personalization_version`
- `get_personalization_versions_by_page`
- `get_condition_templates`
- `get_condition_template_by_id`

**Jobs**
- `revert_job`
- `get_job`
- `list_operations`

**Environment**
- `list_languages`
```

--------------------------------

### createAgentTools(options)

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

The primary entry point to create all Vercel AI SDK `tool()` definitions for Sitecore XM Cloud Agent APIs. It supports both server-side execution with a live client and client-side schema-only definitions.

```APIDOC
## createAgentTools(options)

### Description
Creates a flat object of all Vercel AI SDK `tool()` definitions, grouped by domain, for interacting with Sitecore XM Cloud Agent APIs. It supports two execution modes: 'server' for direct execution in a Node.js environment using an `experimental_XMC` client, and 'client' for schema-only definitions to be executed later.

### Parameters

#### `options` (object) - Required
Configuration object for creating the tools.

- **`execution`** (string) - Required - Specifies the execution mode. Must be either `'server'` or `'client'`.
- **`client`** (`experimental_XMC`) - Required if `execution` is `'server'`. An instance of the Sitecore XM Cloud client.
- **`sitecoreContextId`** (string) - Required - The ID of the Sitecore context to use.
- **`needsApproval`** (boolean) - Optional - If `true`, operations may require explicit approval.
- **`needsApprovalFor`** (string) - Optional - Specifies when approval is needed. Can be `'mutations'` (default) or `'all'`.

### Server-side Example
```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const xmcClient = new experimental_XMC({ /* auth config */ });

const serverTools = createAgentTools({
  execution: 'server',
  client: xmcClient,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  needsApproval: true,
  needsApprovalFor: 'mutations',
});

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'List all sites, then get the first page of the main site in English.',
  tools: serverTools,
  maxSteps: 5,
});
console.log(result.text);
```

### Client-side Example (Schema-only)
```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const clientTools = createAgentTools({ execution: 'client' });

const clientResult = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Get a list of all sites.',
  tools: clientTools,
});
// Tool calls must be executed separately via executeAgentTool()
```
```

--------------------------------

### Manage Sitecore Sites with SDK Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

These tools allow for enumerating sites, fetching site configuration, listing all routes within a site, and determining which site an item belongs to by checking its ancestors.

```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';

const client = new experimental_XMC({ /* config */ });
const tools = createAgentTools({
  execution: 'server',
  client,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

// List all available sites
const sites = await tools.get_sites_list.execute!({});
// Returns: [{ siteId, siteName, languages, ... }, ...]

// Get full configuration for one site
const details = await tools.get_site_details.execute!({
  siteId: 'e1f2a3b4-c5d6-7890-ef01-345678901234',
});

// Get a flat list of all routes in a site
const allPages = await tools.get_all_pages_by_site.execute!({
  siteName: 'MySite',
  language: 'en',
});
// Returns: [{ id: 'uuid', path: '/en/home' }, { id: 'uuid', path: '/en/about' }, ...]

// Determine which site root an item belongs to
const siteRoot = await tools.get_site_id_from_item.execute!({
  itemId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
});
// Returns: { siteId: 'e1f2a3b4-c5d6-7890-ef01-345678901234' }
```

--------------------------------

### createAgentTools - Default Approval

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Initializes agent tools with default approval settings, requiring approval for all tools.

```APIDOC
## createAgentTools

### Description
Initializes agent tools with default approval settings, requiring approval for all tools.

### Method
`createAgentTools`

### Parameters
- `execution` (string) - Required - Specifies the execution environment ('server' or 'client').
- `client` (object) - Required - The client instance to use for operations.
- `sitecoreContextId` (string) - Required - The Sitecore context ID.
- `needsApproval` (boolean) - Optional - If true, requires approval for tool execution. Defaults to true.

### Request Example
```typescript
const tools = createAgentTools({
  execution: "server",
  client: xmcClient,
  sitecoreContextId: "your-context-id",
  needsApproval: true
});
```
```

--------------------------------

### createAgentTools - Mutation Approval

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Initializes agent tools with specific approval settings, requiring approval only for mutation tools.

```APIDOC
## createAgentTools

### Description
Initializes agent tools with specific approval settings, requiring approval only for mutation tools.

### Method
`createAgentTools`

### Parameters
- `execution` (string) - Required - Specifies the execution environment ('server' or 'client').
- `client` (object) - Required - The client instance to use for operations.
- `sitecoreContextId` (string) - Required - The Sitecore context ID.
- `needsApproval` (boolean) - Optional - If true, requires approval for tool execution. Defaults to true.
- `needsApprovalFor` (string) - Optional - Specifies which tools require approval. Can be 'mutations' or undefined (all tools).

### Request Example
```typescript
const tools = createAgentTools({
  execution: "server",
  client: xmcClient,
  sitecoreContextId: "your-context-id",
  needsApproval: true,
  needsApprovalFor: "mutations"
});
```

### Mutation Tools
Mutation tools include: `update_asset`, `upload_asset`, `create_personalization_version`, `revert_job`, `create_page`, `add_component_on_page`, `set_component_datasource`, `add_language_to_page`, `create_content_item`, `delete_content`, `update_content`, `create_component_datasource`.
```

--------------------------------

### Manage Sitecore Pages with SDK Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Use these tools to manage the full page lifecycle, including reading layout and component data, creating pages from templates, managing components and placeholders, adding language versions, searching content, resolving live URLs, and capturing screenshots or HTML snapshots.

```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';

const client = new experimental_XMC({ /* config */ });
const tools = createAgentTools({
  execution: 'server',
  client,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

// Get full page details (layout, components, placeholders)
const page = await tools.get_page.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  language: 'en',
});

// Create a new page under a parent
const newPage = await tools.create_page.execute!({
  templateId: 'c1d2e3f4-a5b6-7890-cdef-123456789012',
  name: 'About Us',
  parentId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  language: 'en',
  fields: [{ Title: 'About Us', MetaDescription: 'Learn about our company' }],
});
console.log(newPage.jobId); // Available for revert

// Check what components can go in a placeholder
const allowed = await tools.get_allowed_components_by_placeholder.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  placeholderName: 'jss-main',
  language: 'en',
});

// Add a component to a page
const addResult = await tools.add_component_on_page.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  componentId: 'd1e2f3a4-b5c6-7890-def0-234567890123',
  placeholderPath: '/jss-main/jss-content',
  componentItemName: 'HeroBanner',
  language: 'en',
  fields: { Title: 'Welcome', Subtitle: 'Explore our platform' },
});

// Resolve a live URL to its Sitecore item path
const pathInfo = await tools.get_page_path_by_live_url.execute!({
  live_url: 'https://www.mysite.com/en/about-us',
});

// Add a French language version
await tools.add_language_to_page.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  language: 'fr-FR',
});

// Search all pages in a site
const searchResults = await tools.search_site.execute!({
  search_query: 'contact form',
  site_name: 'MySite',
  language: 'en',
});

// Get a screenshot (returns image data)
const screenshot = await tools.get_page_screenshot.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  version: 1,
  language: 'en',
  width: 1280,
  height: 720,
});
```

--------------------------------

### Manage Personalization Versions with Sitecore AI SDK

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Use these tools to fetch condition templates, create personalization versions with specific variants and audience definitions, and view existing versions on a page. Ensure you have the necessary client configuration and site context ID.

```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';

const client = new experimental_XMC({ /* config */ });
const tools = createAgentTools({
  execution: 'server',
  client,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

// Step 1: List all condition templates
const templates = await tools.get_condition_templates.execute!({});

// Step 2: Get details for a specific template to see required params
const template = await tools.get_condition_template_by_id.execute!({
  templateId: 'c4d5e6f7-a8b9-0123-cdef-789012345678',
});
// Returns: { templateId, name, parameters: [{ name, type, required }, ...] }

// Step 3: Create a personalization version on a page
const personalization = await tools.create_personalization_version.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  name: 'New Visitor Campaign',
  variant_name: 'New Visitor Variant',
  audience_name: 'New Visitors',
  condition_template_id: 'c4d5e6f7-a8b9-0123-cdef-789012345678',
  condition_params: { maxVisitCount: 1, operator: 'lessThan' },
  language: 'en',
});
console.log(personalization.jobId);

// Step 4: View all personalization versions on a page
const versions = await tools.get_personalization_versions_by_page.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
});
```

--------------------------------

### Configure Agent Tools with Approval Settings

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Configure agent tools to require approval for all operations or only for mutation operations. Ensure `client` and `sitecoreContextId` are provided.

```typescript
const tools = createAgentTools({
  execution: "server",
  client: xmcClient,
  sitecoreContextId: "your-context-id",
  needsApproval: true,
});
```

```typescript
const tools = createAgentTools({
  execution: "server",
  client: xmcClient,
  sitecoreContextId: "your-context-id",
  needsApproval: true,
  needsApprovalFor: "mutations",
});
```

--------------------------------

### Page Builder UI Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Provides tools for controlling the XM Cloud Page Builder UI. These tools are client-side only and must be executed via `executePageBuilderTool()`.

```APIDOC
## `pageBuilderTools(options)` — Page Builder UI tools

Returns schema-only Vercel AI SDK tools for controlling the XM Cloud Page Builder UI. These tools are client-side only (no `execute`) and must be run via `executePageBuilderTool()`. Exposes `get_current_page_context`, `reload_current_page`, and `navigate_to_another_page`.

```typescript
import { pageBuilderTools, executePageBuilderTool } from 'sitecore-ai-sdk-tools';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { ClientSDK } from '@sitecore-marketplace-sdk/client';

const client = new ClientSDK(/* config */);
const sitecoreContextId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

// Define tools with optional approval gate
const pbTools = pageBuilderTools({ needsApproval: true });

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Navigate to item a1b2c3d4-வுகளை',
  tools: pbTools,
});

// Execute the tool call returned by the model
const toolCall = result.toolCalls[0];
const execResult = await executePageBuilderTool(
  { client, sitecoreContextId },
  { toolName: toolCall.toolName, input: toolCall.input }
);
// execResult = { success: true, result: 'Navigated to item: a1b2c3d4-...' }
```
```

--------------------------------

### Environment Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Retrieves all languages configured in the Sitecore XM Cloud environment, which can be used as valid `language` values in other tool calls.

```APIDOC
## Environment Tools — `list_languages`

### Description
Retrieves all languages configured in the Sitecore XM Cloud environment, which can then be used as valid `language` values in any other tool call.

### Usage
```typescript
const languages = await tools.list_languages.execute!({});
// Returns: [{ name: 'en', nativeName: 'English' }, { name: 'fr-FR', nativeName: 'Français' }, ...]

// Use discovered languages to drive further tool calls
for (const lang of languages) {
  const pages = await tools.get_all_pages_by_site.execute!({
    siteName: 'MySite',
    language: lang.name,
  });
  console.log(`${lang.name}: ${pages.length} pages`);
}
```
```

--------------------------------

### Create Agent Tools for Client-Side Mode (Schema-Only)

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Creates agent tools for client-side usage, providing only schema definitions without execution functions. Tool calls must be handled separately.

```typescript
// --- Client-side mode (schema-only, no execute) ---
const clientTools = createAgentTools({ execution: 'client' });

const clientResult = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Get a list of all sites.',
  tools: clientTools,
});
// Tool calls must be executed separately via executeAgentTool()
```

--------------------------------

### Site Management Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Tools for enumerating sites, fetching site configuration, listing all routes in a site, and resolving which site an item belongs to.

```APIDOC
## Site Management Tools

### Description
Provides tools for interacting with Sitecore sites, including listing sites, retrieving site details, and managing pages within a site.

### Tools
- `get_sites_list`: Retrieve a list of all available sites.
- `get_site_details`: Get the full configuration for a specific site.
- `get_all_pages_by_site`: Get a flat list of all routes (pages) within a site.
- `get_site_id_from_item`: Determine which site root an item belongs to.

### Example Usage (TypeScript)
```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';

const client = new experimental_XMC({ /* config */ });
const tools = createAgentTools({
  execution: 'server',
  client,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

// List all sites
const sites = await tools.get_sites_list.execute!({});
// Returns: [{ siteId, siteName, languages, ... }, ...]

// Get site details
const details = await tools.get_site_details.execute!({
  siteId: 'e1f2a3b4-c5d6-7890-ef01-345678901234',
});

// Get all pages in a site
const allPages = await tools.get_all_pages_by_site.execute!({
  siteName: 'MySite',
  language: 'en',
});
// Returns: [{ id: 'uuid', path: '/en/home' }, { id: 'uuid', path: '/en/about' }, ...]

// Get site ID from item
const siteRoot = await tools.get_site_id_from_item.execute!({
  itemId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
});
// Returns: { siteId: 'e1f2a3b4-c5d6-7890-ef01-345678901234' }
```
```

--------------------------------

### Components Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Tools for component discovery and datasource management. Agents can list all available components for a site, inspect their schemas, search for existing datasources, or create new datasource items with field values and child records.

```APIDOC
## Components Tools

Tools for component discovery and datasource management. Agents can list all available components for a site, inspect their schemas, search for existing datasources, or create new datasource items with field values and child records.

### `list_components`

Lists all components available in a site.

#### Parameters
- **site_name** (string) - Required - The name of the site.

#### Response
- Returns an array of component objects, each containing `componentId`, `name`, `datasourceTemplateId`, `fields`, etc.

### `get_component`

Gets full details for a specific component.

#### Parameters
- **componentId** (string) - Required - The ID of the component.

### `search_component_datasources`

Finds existing datasources matching a search term for a given component.

#### Parameters
- **componentId** (string) - Required - The ID of the component.
- **term** (string) - Required - The search term.

### `create_component_datasource`

Creates a new datasource for a component, optionally with child items.

#### Parameters
- **componentId** (string) - Required - The ID of the component.
- **siteName** (string) - Required - The name of the site.
- **language** (string) - Required - The language of the datasource.
- **dataFields** (object) - Optional - An object containing the data fields for the datasource.
- **children** (array) - Optional - An array of child items to create under the datasource.

#### Response
- **jobId** (string) - The ID of the job created for this operation, used for undo support.
```

--------------------------------

### Server-side Agent Tools Configuration

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Configure agent tools for server-side execution in a Node.js environment. Requires an initialized `experimental_XMC` client and a Sitecore context ID.

```typescript
import { createAgentTools } from "sitecore-ai-sdk-tools";
import { experimental_XMC } from "@sitecore-marketplace-sdk/xmc";
import { generateText } from "ai";

const xmcClient = new experimental_XMC({
  /* your config */
});

const tools = createAgentTools({
  execution: "server",
  client: xmcClient,
  sitecoreContextId: "your-context-id",
});

const result = await generateText({
  model: yourModel,
  prompt: "Get the list of sites",
  tools,
});
```

--------------------------------

### List Languages in Sitecore Environment with SDK

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Retrieve all configured languages in the Sitecore XM Cloud environment. These language codes can then be used in other tool calls. Ensure the client and site context ID are properly set up.

```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';

const client = new experimental_XMC({ /* config */ });
const tools = createAgentTools({
  execution: 'server',
  client,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

const languages = await tools.list_languages.execute!({});
// Returns: [{ name: 'en', nativeName: 'English' }, { name: 'fr-FR', nativeName: 'Français' }, ...]

// Use discovered languages to drive further tool calls
for (const lang of languages) {
  const pages = await tools.get_all_pages_by_site.execute!({
    siteName: 'MySite',
    language: lang.name,
  });
  console.log(`${lang.name}: ${pages.length} pages`);
}
```

--------------------------------

### Tool Approval Configuration

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Configure which tools require human approval before execution using the `needsApproval` and `needsApprovalFor` options.

```APIDOC
## Tool Approval — `needsApproval` / `needsApprovalFor`

Controls which tools require human approval before execution (Vercel AI SDK `needsApproval` feature). Default is `'all'` (every tool requires approval). Set `needsApprovalFor: 'mutations'` to restrict approval gates to write operations only. Works identically for both `createAgentTools` and `pageBuilderTools`.

```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';

const xmcClient = new experimental_XMC({ /* config */ });
const ctx = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

// Approve only mutation tools (create/update/delete/upload/revert)
// Read tools like get_page, search_assets, list_languages run freely
const tools = createAgentTools({
  execution: 'server',
  client: xmcClient,
  sitecoreContextId: ctx,
  needsApproval: async ({ toolName }) => {
    console.log(`Requesting approval for: ${toolName}`);
    return true; // or implement custom approval UI logic
  },
  needsApprovalFor: 'mutations',
});

// Mutation tools (require approval with needsApprovalFor: 'mutations'):
// update_asset, upload_asset, create_personalization_version, revert_job,
// create_page, add_component_on_page, set_component_datasource,
// add_language_to_page, create_content_item, delete_content,
// update_content, create_component_datasource
```
```

--------------------------------

### pageBuilderTools

Source: https://github.com/izharikov/sitecore-ai-sdk-tools/blob/master/readme.md

Provides tools for navigating and controlling the XM Cloud Page Builder UI. These are only available client-side.

```APIDOC
## pageBuilderTools

### Description
Provides tools for navigating and controlling the XM Cloud Page Builder UI. These are only available client-side.

### Method
`pageBuilderTools()`

### Usage
```typescript
import { pageBuilderTools } from "sitecore-ai-sdk-tools";

const tools = pageBuilderTools();
```

### Available Tools

| Tool | Description |
|---|---|
| `get_current_page_context` | Returns info about the currently open page |
| `get_current_site_context` | Returns info about the currently active site |
| `reload_current_page` | Reloads the Page Builder canvas |
| `navigate_to_another_page` | Navigates to a different page by item ID |
```

--------------------------------

### Execute Client-Side Agent and Page Builder Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Dispatches tool calls to the `ClientSDK` for client-side execution. It first attempts to execute agent tools and falls back to page builder tools if necessary. Input validation is performed using Zod schemas.

```typescript
import { executeAgentTool, executePageBuilderTool } from 'sitecore-ai-sdk-tools';
import { ClientSDK } from '@sitecore-marketplace-sdk/client';
import { useChat } from 'ai/react';
import type { ToolUIPart } from 'ai';

const client = new ClientSDK(/* config */);
const sitecoreContextId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

const executeTool = async (toolPart: ToolUIPart) => {
  const toolName = toolPart.type.substring('tool-'.length);
  try {
    // Try agent tools first, fall back to page builder tools
    let res = await executeAgentTool(
      { client, sitecoreContextId },
      { toolName, input: toolPart.input }
    );
    if (!res.success) {
      res = await executePageBuilderTool(
        { client, sitecoreContextId },
        { toolName, input: toolPart.input }
      );
    }
    if (!res.success) {
      console.error('Tool not found:', toolName);
    }
  } catch (error) {
    console.error('Tool execution failed:', error);
  }
};

const chat = useChat({
  transport: myTransport,
  onFinish: async ({ message, finishReason }) => {
    if (finishReason !== 'tool-calls') return;
    for (const part of message.parts) {
      if (part.type.startsWith('tool') && (part as ToolUIPart).state === 'input-available') {
        await executeTool(part as ToolUIPart);
      }
    }
  },
});
```

--------------------------------

### Asset Tools - `createAgentTools` for DAM operations

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Use `createAgentTools` to access tools for retrieving asset metadata, searching the DAM library, updating asset fields, and uploading new files. Mutation tools like `update_asset` and `upload_asset` automatically generate an `x-sc-job-id` header for later undo via `revert_job`.

```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const client = new experimental_XMC({ /* config */ });
const tools = createAgentTools({
  execution: 'server',
  client,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

// Search for banner images
const searchResult = await tools.search_assets.execute!({
  query: 'hero banner',
  language: 'en',
  type: 'image',
});
// Returns: [{ assetId, name, fileUrl, altText, ... }, ...]

// Get details of a specific asset
const assetInfo = await tools.get_asset_information.execute!({
  assetId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
});

// Update asset metadata (returns jobId for undo)
const updateResult = await tools.update_asset.execute!({
  assetId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'Hero Banner Updated',
  altText: 'A vibrant hero banner for the homepage',
  language: 'en',
  fields: { title: 'Summer Campaign' },
});
console.log(updateResult.jobId); // UUID for revert_job

// Upload a new asset from a URL
const uploadResult = await tools.upload_asset.execute!({
  fileUrl: 'https://example.com/new-banner.jpg',
  name: 'Summer Banner',
  itemPath: '/sitecore/media library/Project/MySite/Images',
  language: 'en',
  extension: 'jpg',
  siteName: 'MySite',
});
console.log(uploadResult.jobId); // Available for revert if needed
```

--------------------------------

### Personalization Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Enables agents to read and create personalization rules on pages. The workflow involves fetching condition templates, selecting a template with its parameters, and then creating a personalization version with variant and audience definitions.

```APIDOC
## Personalization Tools — `create_personalization_version`, `get_personalization_versions_by_page`, `get_condition_templates`, `get_condition_template_by_id`

### Description
Enables agents to read and create personalization rules on pages. The workflow is: fetch condition templates → pick a template and its required parameters → create a personalization version with variant and audience definitions.

### Usage
```typescript
// Step 1: List all condition templates
const templates = await tools.get_condition_templates.execute!({});

// Step 2: Get details for a specific template to see required params
const template = await tools.get_condition_template_by_id.execute!({
  templateId: 'c4d5e6f7-a8b9-0123-cdef-789012345678',
});
// Returns: { templateId, name, parameters: [{ name, type, required }, ...] }

// Step 3: Create a personalization version on a page
const personalization = await tools.create_personalization_version.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  name: 'New Visitor Campaign',
  variant_name: 'New Visitor Variant',
  audience_name: 'New Visitors',
  condition_template_id: 'c4d5e6f7-a8b9-0123-cdef-789012345678',
  condition_params: { maxVisitCount: 1, operator: 'lessThan' },
  language: 'en',
});
console.log(personalization.jobId);

// Step 4: View all personalization versions on a page
const versions = await tools.get_personalization_versions_by_page.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
});
```
```

--------------------------------

### Page Management Tools

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Tools for managing the full page lifecycle, including reading layout and component data, creating pages, managing components and placeholders, adding language versions, searching content, resolving live URLs, and capturing screenshots or HTML snapshots.

```APIDOC
## Page Management Tools

### Description
Provides a comprehensive set of tools for managing Sitecore pages throughout their lifecycle.

### Tools
- `get_page`: Retrieve full page details (layout, components, placeholders).
- `create_page`: Create a new page from a template.
- `get_page_template_by_id`: Get details of a page template.
- `get_allowed_components_by_placeholder`: Check which components can be added to a specific placeholder.
- `get_components_on_page`: Retrieve components currently on a page.
- `add_component_on_page`: Add a new component to a page.
- `set_component_datasource`: Set the data source for a component.
- `add_language_to_page`: Add a new language version to an existing page.
- `search_site`: Search for pages within a site.
- `get_page_path_by_live_url`: Resolve a live URL to its Sitecore item path.
- `get_page_screenshot`: Capture a screenshot of a page.
- `get_page_html`: Get the HTML content of a page.
- `get_page_preview_url`: Get the preview URL for a page.

### Example Usage (TypeScript)
```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';

const client = new experimental_XMC({ /* config */ });
const tools = createAgentTools({
  execution: 'server',
  client,
  sitecoreContextId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

// Get full page details
const page = await tools.get_page.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  language: 'en',
});

// Create a new page
const newPage = await tools.create_page.execute!({
  templateId: 'c1d2e3f4-a5b6-7890-cdef-123456789012',
  name: 'About Us',
  parentId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  language: 'en',
  fields: [{ Title: 'About Us', MetaDescription: 'Learn about our company' }],
});
console.log(newPage.jobId);

// Check allowed components for a placeholder
const allowed = await tools.get_allowed_components_by_placeholder.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  placeholderName: 'jss-main',
  language: 'en',
});

// Add a component to a page
const addResult = await tools.add_component_on_page.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  componentId: 'd1e2f3a4-b5c6-7890-def0-234567890123',
  placeholderPath: '/jss-main/jss-content',
  componentItemName: 'HeroBanner',
  language: 'en',
  fields: { Title: 'Welcome', Subtitle: 'Explore our platform' },
});

// Resolve live URL to item path
const pathInfo = await tools.get_page_path_by_live_url.execute!({
  live_url: 'https://www.mysite.com/en/about-us',
});

// Add a language version
await tools.add_language_to_page.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  language: 'fr-FR',
});

// Search pages
const searchResults = await tools.search_site.execute!({
  search_query: 'contact form',
  site_name: 'MySite',
  language: 'en',
});

// Get page screenshot
const screenshot = await tools.get_page_screenshot.execute!({
  pageId: 'b1c2d3e4-f5a6-7890-bcde-f12345678901',
  version: 1,
  language: 'en',
  width: 1280,
  height: 720,
});
```
```

--------------------------------

### Tool Approval - `needsApproval` / `needsApprovalFor`

Source: https://context7.com/izharikov/sitecore-ai-sdk-tools/llms.txt

Control which tools require human approval using `needsApproval` and `needsApprovalFor`. Default is `'all'`. Set `needsApprovalFor: 'mutations'` to restrict approval gates to write operations only. This works for both `createAgentTools` and `pageBuilderTools`.

```typescript
import { createAgentTools } from 'sitecore-ai-sdk-tools';
import { experimental_XMC } from '@sitecore-marketplace-sdk/xmc';

const xmcClient = new experimental_XMC({ /* config */ });
const ctx = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

// Approve only mutation tools (create/update/delete/upload/revert)
// Read tools like get_page, search_assets, list_languages run freely
const tools = createAgentTools({
  execution: 'server',
  client: xmcClient,
  sitecoreContextId: ctx,
  needsApproval: async ({ toolName }) => {
    console.log(`Requesting approval for: ${toolName}`);
    return true; // or implement custom approval UI logic
  },
  needsApprovalFor: 'mutations',
});

// Mutation tools (require approval with needsApprovalFor: 'mutations'):
// update_asset, upload_asset, create_personalization_version, revert_job,
// create_page, add_component_on_page, set_component_datasource,
// add_language_to_page, create_content_item, delete_content,
// update_content, create_component_datasource
```