Get Started

Agents is the governed machine-access layer for Craft CMS and Craft Commerce. Start by installing the plugin, configuring machine credentials, and validating the API and control-plane posture before connecting an external runtime.

In these docs, an external runtime can be:

• an agent
• an orchestrator
• a worker
• a script

You set the boundary. External runtimes work inside it.

Requirements

• PHP ^8.2
• Craft CMS ^5.0
• Craft Commerce recommended for full commerce endpoints

Install

composer require klick/agents:^0.25.3
php craft plugin/install agents

Verify

• Open CP: admin/agents/status
• Confirm service state and readiness score
• Hit GET /agents/v1/health
• Hit GET /agents/v1/schema with a token that has schema:read
• Hit GET /agents/v1/capabilities to inspect the discovered contract and auth posture

First Worker

If you want one practical end-to-end bootstrap before building a fuller integration, start with a managed account plus the public Node worker example.

A worker is the simplest first external runtime because it makes scheduling, retries, and deterministic fetch/proof behavior easy to understand.

The product does not require every integration to use a separate worker process, but it is the calmest first path:

• create a read-only managed account with health:read, readiness:read, and auth:read
• place the one-time token into examples/workers/node-bootstrap/.env
• run the worker once, then schedule it

Next

• Set environment variables in .env / config/agents.php
• Configure API credentials (scopes + optional TTL/IP allowlists)
• Treat credentials as machine identities with the minimum scopes each integration needs
• Use starter packs for copy/paste integration bootstrap (/api/starter-packs)
• Review webhook scopes and delivery posture before production

See:

• Installation & Setup
• Configuration
• First Worker
• External Runtimes
• Agents vs Element API
• Job Guides
• Agent Bootstrap
• Starter Packs