Actions

Calling an Automate.ax action registers durable work and immediately returns a Signal for its eventual output.

const message = gmail.getMessage({ messageId: email.messageId })

gmail.archiveMessages({ messageIds: message.messageId })

Automate.ax resolves and validates the inputs, runs the action, validates its output, and makes the result available to dependent work.

Attach each action to one context

Every action must resolve to exactly one least context boundary: the closest boundary that contains its complete signal dependency chain. A trigger starts a root, while coordinators such as correlate, collect, each, window, funnel, and race create boundaries as they combine or split occurrences. When an automation has one initiating trigger, Automate.ax assigns an action with no signal dependencies to that trigger:

onSchedule({ schedule: "0 9 * * 1-5" })

gmail.sendEmail({
  to: "team@example.com",
  subject: "Daily update",
  text: "The scheduled update is ready.",
})

With more than one possible root, an action with no signal dependencies is ambiguous. Attach it to the intended root with withPrerequisites, or pass a signal from that root as an input:

const requested = onInvocation("request")
const cancelled = onInvocation("cancel")

withPrerequisites(requested, () => {
  gmail.sendEmail({
    to: "team@example.com",
    subject: "Request received",
    text: "We are processing your request.",
  })
})

This rule includes roots declared inside built-in or package compositions. delay, timeout, firecrawl.crawlWebsite, codex.runCloudTask, and codex.waitForCloudTask use hidden triggers so work can resume without holding an action open. Scope their literal starter actions to the initiating signal. Planning fails before deployment when an action has no unique closest boundary. The error identifies the action and the competing boundaries so you can add a signal input or withPrerequisites.

Call actions by service

Import the named service namespace from an integration entry point, then call its provider-free action name, such as gmail.sendEmail or linear.createIssue. These entry points also retain fully qualified callable exports such as sendGmailEmail for direct per-action imports. Built-in actions use platform terms without a provider, such as respondToHttpRequest.

Pass literal and signal inputs

An action accepts a direct input object, a compatible signal for the complete object, or signals at any nested array or object property:

gmail.sendEmail({
  to: "person@example.com",
  subject: email.subject,
  text: "We received your message.",
})

Here, to and text are literal values. subject is a signal, so the action waits for the incoming email before executing. You can also supply a complete nested object or the entire input with one signal:

const reply = email.transform((message) => ({
  subject: `Re: ${message.subject}`,
  text: "We received your message.",
  to: message.from,
}))

gmail.sendEmail(reply)

When every input property is optional, you can omit the input object entirely. Automate.ax recursively resolves signals through arrays and plain objects before validating the reconstructed input. Dates, files, URLs, maps, sets, and other class instances remain single values.

Use action outputs as signals

An action always returns a signal, whether its eventual output is an object, array, primitive, or void.

const draft = gmail.draftEmail({
  to: "person@example.com",
  subject: "Status update",
  text: "Processing finished.",
})

gmail.sendDraft({ draftId: draft.draftId })

Property access records the dependency.

Control action order

Actions become ready when all their signal inputs and inherited dependencies are ready. Two calls that depend only on the same trigger can execute concurrently. Passing one action’s output to another establishes ordering. Use withPrerequisites to order work that doesn’t consume the dependency. Use dependentOn when another signal should preserve its value while waiting for the dependency.

Handle failures and retries

When an action fails, ordinary dependent actions don’t execute. Independent branches can continue. Use onFailure(actionSignal) when another action should handle the failure as data. Every custom action declares its retry policy before .handler(). maxAttempts includes the first attempt, defaults to 3, and accepts 1 through 10. replaySafety says whether an unknown interruption can safely repeat the handler; it may be constant or derived from validated input:

const request = defineAction("Call provider")
  .input(
    z.object({
      method: z.enum(["GET", "POST"]),
      url: z.url(),
    }),
  )
  .retry({
    maxAttempts: 3,
    replaySafety: ({ method }) => (method === "GET" ? "safe" : "unsafe"),
  })
  .handler(async ({ input }) => {
    const response = await fetch(input.url, { method: input.method })

    if (!response.ok) {
      throw new Error(`Provider request failed with ${response.status}`)
    }
  })

Declare .retry() after the final input schema. An ordinary handler error schedules another logical attempt only when replay is safe. The same error from an unsafe action becomes indeterminate because the provider may already have accepted the mutation. Set maxAttempts: 1 when an action must never make a fresh attempt. Throw RetryableActionError when the provider confirms that a fresh attempt is safe, optionally with an absolute retryAt from a provider Retry-After response. Throw TerminalActionError for permanent input or permission failures and IndeterminateActionError when the provider outcome is ambiguous. Integration authors can use retryableActionError, terminalActionError, and indeterminateActionError to classify an existing provider-specific error without replacing its identity. parseRetryAfter converts seconds or an HTTP date into the absolute time accepted by RetryableActionError. A provider time can delay the platform retry schedule but never shorten its exponential delay. Direct input or output validation failures are terminal immediately. Resolving a signal input happens before the action runs: if a transform or other signal expression fails, the action is skipped as a failed dependency and the error remains attributed to that signal evaluation. Separate actions don’t form one transaction.

Choose an integration account

Account-backed actions declare their service and permissions. Automate.ax resolves the selected integration account when the action executes. Credentials never appear in action inputs or signals. Pass a non-default account in the second argument, or create a reusable bound action with .usingAccount():

gmail.sendEmail(input, { account: "work" })

const sendFromWork = gmail.sendEmail.usingAccount("work")
sendFromWork(input)

Use fetchHttp for arbitrary unauthenticated HTTP requests. If Automate.ax doesn’t support an authenticated service, see Call an external API for the current credential tradeoffs.

Start

Concepts

Guides

Attach each action to one context

Call actions by service

Pass literal and signal inputs

Use action outputs as signals

Control action order

Handle failures and retries

Choose an integration account

​Attach each action to one context

​Call actions by service

​Pass literal and signal inputs

​Use action outputs as signals

​Control action order

​Handle failures and retries

​Choose an integration account

Attach each action to one context

Call actions by service

Pass literal and signal inputs

Use action outputs as signals

Control action order

Handle failures and retries

Choose an integration account