Execution Model
Agents is a governed runtime for Craft integrations.
Trust boundary
- Production actions execute through scoped API routes and policy controls.
- Runtime behavior is deterministic: request validation, stable error codes, auditable records.
- The plugin does not execute agent-provided shell commands as part of production action handling.
- CLI commands (
craft agents/*) are operator/developer tools for diagnostics and workflow support.
Surface stability matrix
| Surface | Status | Notes |
|---|---|---|
Read/sync API (/health, /readiness, /auth/whoami, /products, /variants*, /subscriptions*, /transfers*, /donations*, /orders*, /entries*, /assets*, /categories*, /tags*, /global-sets*, /addresses*, /content-blocks*, /users*, /changes, /sections) | Production stable | Token/scopes + deterministic error contract. |
Integration state API (/sync-state/lag, /sync-state/checkpoint, /schema) | Production stable | Sync-state checkpoint/lag and machine-readable schema contracts. |
Discovery descriptors (/capabilities, /openapi.json, root aliases) | Production stable | Canonical machine contract discovery. |
Webhook delivery + DLQ replay (/webhooks/dlq, /webhooks/dlq/replay) | Production stable | Signed payloads, retries, dead-letter replay. |
| Credential controls (scopes, targeted webhook subscriptions, TTL/reminders, IP allowlists) | Production stable | Managed in CP, enforced at runtime. |
CLI (craft agents/*) | Production stable (ops tooling) | Operator/dev workflows; not runtime control plane. |
Discovery docs (/llms.txt, /llms-full.txt, /commerce.txt) | Optional stable feature | Public discovery docs, not the core trust boundary. |
Control-plane execution (/control/*, governed-write workflows) | Experimental | Enabled only by PLUGIN_AGENTS_WRITES_EXPERIMENTAL=true. |
Why this model
- Keeps production behavior auditable and policy-constrained.
- Avoids broad shell-execution risk in multi-tenant/production environments.
- Preserves CLI velocity for operators without making CLI the runtime trust boundary.
See Compatibility & Deprecations for upgrade and contract-change policy.