# How to Configure Automations in Craft Agents: Understanding the automations.json Schema Version

> Learn how to configure automations.json in Craft Agents using schema version 2. This guide explains setting up your workspace for efficient automation management.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Craft Agents configures automations through a declarative [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) file located in the workspace root, which follows schema version 2 (the default when the version field is omitted) and is validated against the Zod-based `AutomationsConfigSchema` defined in the source code.**

Craft Agents OSS enables you to define automated behaviors declaratively using a JSON configuration file. This article explores how automations are configured in Craft Agents, the specific schema version requirements, and the validation logic implemented in the codebase.

## The automations.json File Location and Structure

### File Location

The automation configuration resides in a file named [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) placed in the root of your workspace. The exact filename is defined by the **`AUTOMATIONS_CONFIG_FILE`** constant in [`packages/shared/src/automations/constants.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/constants.ts). When the runtime initializes, it searches for this specific file to load your automation rules.

### Schema Version Declaration

The top-level object in [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) may contain a **`version`** field. If omitted, the system assumes **`version: 2`**, which is the current canonical schema. This default behavior is hardcoded in the resource import logic found in [`packages/shared/src/resources/resource-bundle.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/resources/resource-bundle.ts), ensuring backward compatibility while encouraging explicit version declarations.

## Understanding the Automations Config Schema

The schema is enforced by a Zod definition located in [`packages/shared/src/automations/schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts). This definition validates the structure and normalizes deprecated fields during the loading process.

### Top-Level Structure

The root object contains:

- **`version`**: A number indicating the schema version (optional, defaults to 2)
- **`automations`**: A record mapping event names to arrays of **AutomationMatcher** objects

The `automations` field is a `record<string, AutomationMatcher[]>` where each key represents an event name (canonical event or deprecated alias) and the value defines the matchers for that event.

### Automation Matchers

Each matcher follows the **`AutomationMatcherSchema`** and supports optional fields including:

- `id`: Unique identifier
- `name`: Human-readable name
- `matcher`: Matching criteria
- `cron`: Cron expression for scheduled events
- `timezone`: Timezone for cron scheduling
- `permissionMode`: Permission configuration
- `labels`: Label filters
- `enabled`: Boolean toggle
- `conditions`: Array of condition objects
- `telegramTopic`: Telegram-specific configuration
- `actions`: Array of action definitions

### Actions and Conditions

The **`actions`** array supports two built-in types defined in the same schema file:

- **`prompt`**: Defined by `PromptActionSchema`, triggers an AI prompt
- **`webhook`**: Defined by `WebhookActionSchema`, triggers HTTP requests

The optional **`conditions`** array accepts objects validated by `AutomationConditionSchema`, supporting `time`, `state`, or logical combinators (`and`, `or`, `not`).

## How the Runtime Loads and Validates Automations

### Resource Bundle Import Process

When the system loads the configuration, it follows a strict process in [`packages/shared/src/resources/resource-bundle.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/resources/resource-bundle.ts):

1. Reads [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) from the workspace root
2. Parses the JSON and validates it against `AutomationsConfigSchema`
3. Normalizes deprecated event names using `DEPRECATED_EVENT_ALIASES`
4. If the file is missing or malformed, creates a fresh config with `version: 2` (in overwrite mode) or aborts (in skip mode)

### Validation Layer

The **`validateAutomationsConfig`** function in [`packages/shared/src/automations/validation.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/validation.ts) provides programmatic access to the validation logic. It runs the Zod schema against raw JSON objects and returns typed results.

### Runtime Attachment

Once validated, the automation system attaches to the agent runtime through [`packages/shared/src/agent/base-agent.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/agent/base-agent.ts), enabling the agent to respond to configured events and execute defined actions.

## Practical Configuration Examples

### Minimal Configuration (Auto-Adds Version 2)

```json
{
  "automations": {
    "UserPromptSubmit": [
      {
        "name": "WelcomePrompt",
        "actions": [
          {
            "type": "prompt",
            "prompt": "Hello! How can I help you today?"
          }
        ]
      }
    ]
  }
}

```

The loader treats this as having `"version": 2` implicitly.

### Cron-Based Automation with Webhook

```json
{
  "version": 2,
  "automations": {
    "schedule": [
      {
        "name": "DailyReport",
        "cron": "0 9 * * *",
        "timezone": "UTC",
        "enabled": true,
        "actions": [
          {
            "type": "webhook",
            "url": "https://example.com/report",
            "method": "POST",
            "headers": { "Content-Type": "application/json" },
            "body": { "reportDate": "$TODAY" },
            "captureResponse": true
          }
        ]
      }
    ]
  }
}

```

### Conditional Execution (Weekdays Only)

```json
{
  "version": 2,
  "automations": {
    "UserPromptSubmit": [
      {
        "name": "WorkdayGreeting",
        "conditions": [
          {
            "condition": "time",
            "weekday": ["mon","tue","wed","thu","fri"]
          }
        ],
        "actions": [
          {
            "type": "prompt",
            "prompt": "Good morning! How can I assist you today?",
            "thinkingLevel": "high"
          }
        ]
      }
    ]
  }
}

```

### Programmatic Validation (Node.js/TypeScript)

```typescript
import { join } from 'node:path';
import { readFileSync } from 'node:fs';
import { validateAutomationsConfig } from '@craft/shared/automations/validation';

const configPath = join(workspaceRoot, 'automations.json');
const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
const validation = validateAutomationsConfig(raw);

if (validation.valid && validation.config) {
  console.log('Loaded automations version:', validation.config.version ?? 2);
}

```

## Summary

- **Craft Agents** uses a declarative [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) file placed in the workspace root to define automated behaviors.
- The current **schema version is 2**, which is the default when the `version` field is omitted from the configuration.
- Schema validation occurs through **Zod** in [`packages/shared/src/automations/schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts), specifically via the `AutomationsConfigSchema` definition.
- The runtime loads configurations through [`packages/shared/src/resources/resource-bundle.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/resources/resource-bundle.ts), normalizing deprecated fields and applying version defaults.
- Two primary action types are supported: **`prompt`** for AI interactions and **`webhook`** for HTTP requests.
- Conditions support time-based, state-based, and logical combinator expressions for complex execution rules.

## Frequently Asked Questions

### What is the current schema version for Craft Agents automations?

The current canonical schema version is **2**. This is defined in the `AutomationsConfigSchema` in [`packages/shared/src/automations/schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts). When you omit the version field in your [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) file, the system automatically assumes version 2 according to the loading logic in [`packages/shared/src/resources/resource-bundle.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/resources/resource-bundle.ts).

### Where should I place the automations.json file?

You must place the [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) file in the **root of your workspace**. The exact filename is defined by the `AUTOMATIONS_CONFIG_FILE` constant in [`packages/shared/src/automations/constants.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/constants.ts). The runtime searches for this specific location during the resource bundle import process.

### What happens if I omit the version field in automations.json?

If the version field is missing, the loader defaults to **version 2**. This behavior is implemented in the resource import logic within [`packages/shared/src/resources/resource-bundle.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/resources/resource-bundle.ts), where the system either creates a fresh config with `version: 2` or normalizes the existing configuration to assume the current schema during validation.

### How are automation schemas validated in Craft Agents?

Validation occurs through **Zod** schemas defined in [`packages/shared/src/automations/schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts). The `validateAutomationsConfig` function exported from [`packages/shared/src/automations/validation.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/validation.ts) parses the raw JSON and validates it against `AutomationsConfigSchema`, normalizing deprecated event names via `DEPRECATED_EVENT_ALIASES` and ensuring the structure matches the expected version 2 format before runtime attachment.