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

Craft Agents configures automations through a declarative 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 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. 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 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, 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. 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:

1. Reads 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 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, enabling the agent to respond to configured events and execute defined actions.

Practical Configuration Examples

Minimal Configuration (Auto-Adds Version 2)

{
  "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

{
  "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)

{
  "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)

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 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, specifically via the AutomationsConfigSchema definition.
• The runtime loads configurations through 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. When you omit the version field in your automations.json file, the system automatically assumes version 2 according to the loading logic in packages/shared/src/resources/resource-bundle.ts.

Where should I place the automations.json file?

You must place the 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. 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, 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. The validateAutomationsConfig function exported from 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}