Axon concepts
Axon is the Mach5 workflow layer for approved action. It lets apps, analysts, and AI agents call external systems, run automations, and perform side effects through one controlled path.
Use Axon when work needs action. Use SQL for read-only analysis. Use ingest pipelines for durable collection.
Core model
An Axon workflow is a versioned program with typed input, typed output, local state, control flow, and effects.
| Concept | Meaning |
|---|---|
| Workflow | A versioned unit of work, for example NotifyFinding@v1. |
| Input | The JSON-compatible value passed to a workflow at start. |
| Output | The value returned by the workflow. |
| Step | A statement in the workflow body. |
| Effect | A call to something outside pure local evaluation. |
| Connector effect | An effect that invokes a Mach5 connector operation. |
| Policy | A with { ... } object attached to a step or effect to guide approval, retry, timeout, or execution behavior. |
| Run | One execution of a workflow. |
Effects
Effects are the boundary between workflow logic and the outside world. Axon supports built-in effects such as sleep, HTTP, events, child workflows, LLM calls, and connector operations.
The connector effect is the main integration surface:
let result = effect connector {
connection: "slack-prod",
operation: "post_message",
input: {
channel: input.channel,
text: input.text
}
}
The connection name resolves to a configured connector connection. The operation must be exposed with the Axon facet by that connector.
Axon, SQL, and ingest pipelines
Many integrations support more than one surface.
| Surface | Use it for | Side effects allowed? |
|---|---|---|
| Axon | Workflow actions, approvals, enrichment calls, and controlled external writes. | Yes, if the operation exposes an Axon effect. |
| SQL | Read-only lookup, search, inventory, and analysis. | No. |
| Ingest pipelines | Durable collection from source operations. | No. |
A common data app flow is:
- ingest events from GitHub, Okta, Slack, email, or object storage
- analyze and enrich with SQL
- investigate with AI
- use Axon to post a Slack update, open an issue, send email, or perform an approved response
Safety classes
Every connector operation carries safety metadata.
| Safety class | Meaning | Examples |
|---|---|---|
| Read-only safe | Bounded metadata read or validation. | validate connection, lookup user, get repository |
| Read-only expensive | Read that may require pagination or external API cost. | list users, search messages, list audit events |
| Side-effecting low | Reversible or low-risk write. | post message, add label, create comment |
| Side-effecting high | Higher-impact write. | create repository, update policy, rerun workflow |
| Destructive | Removes, disables, deletes, archives, or revokes something. | delete file, deactivate account, revoke session |
Side-effecting and destructive operations should be protected by approval policy in production workflows.
Idempotency
Retries are normal in distributed workflows. Axon effects expose idempotency expectations so an action can be retried without accidentally duplicating external writes.
Read-only effects do not require idempotency. Side-effecting effects may require a caller-provided key. Use stable keys derived from the run, target, and intent.
let issue = effect connector {
connection: "github-prod",
operation: "create_issue",
input: {
owner: "acme",
repo: "platform",
title: input.title,
body: input.body
}
} with {
idempotency_key: `{{ input.finding_id }}:create_issue`
}
Outcomes
An Axon connector effect returns one of four outcomes.
| Outcome | Meaning |
|---|---|
success | The operation completed and returned output. |
pending | The operation is waiting on external progress and returns a resume token. |
retryable_error | The operation failed temporarily and can be retried, optionally after a delay. |
fatal_error | The operation failed permanently and should not be retried without changing input or configuration. |
Agents and approvals
AI agents should use Axon for actions. This gives agents the same controlled path as humans: explicit operations, safety metadata, approvals, idempotency, and a run record.
For syntax and full examples, see Axon syntax.