Automation

Runs don't have to be queued by hand. Agentfleet can start a workflow on a schedule, when a Service Bus event arrives, or when a webhook is called. Each binds a workflow and an agent to a trigger source and seeds each run's initial context. Each fires repeatedly while enabled and produces ordinary runs, fully observable and identical to hand-queued ones. Schedules and event triggers are managed on the Triggers page.

All three can pin a workflow version with workflowVersionNumber. Without a pin, each run uses the latest published version at the moment it starts. Updates replace every field, so an update that omits workflowVersionNumber unpins the automation.

Schedules

A schedule binds a Quartz cron expression to a workflow, firing it on a recurring cadence. The API is api/schedules.

Field	Purpose
Workflow & agent	What runs, and the agent it runs as.
Cron expression	When it fires. Validated at its own boundary, so an invalid cron can never reach a schedule.
Input template	Key/value pairs that seed the initial context of every run the schedule starts.
Workflow version	Optional pin. Without one, the latest published version at fire time.
Enabled	Gates firing. A disabled schedule keeps its definition but never fires.
Description	What the schedule is for.

A schedule is a durable definition: runtime state lives on each run it produces, so an enabled schedule fires as many times as its cron dictates. Each firing opens a task whose id becomes the run's task_id. Firing is idempotent per occurrence, and if the host was down over a fire time the schedule fires once on recovery rather than replaying every missed occurrence. You can enable, disable, update, and delete a schedule, and fire it now (PUT /api/schedules/fire) to trigger a run without waiting for the next cron tick. Scheduling:Enabled (default true) turns the scheduler off for an environment.

Event triggers

An event trigger binds a Service Bus event to a workflow, starting it when a matching event arrives. The API is api/eventtriggers.

Field	Purpose
Workflow & agent	What runs, and the agent it runs as.
Topic & subscription	The Service Bus source the trigger listens on.
Event type	The event type that fires the trigger. A trigger fires for exactly one event type.
Input mappings	Payload field → context key copies that seed each run. No expressions, only copies.
Required context keys	Inputs the workflow needs. Saving refuses a mapping that leaves one unmapped.
Condition	Optional JMESPath expression over the payload. The trigger fires only when it is truthy.
Workflow version	Optional pin.
Enabled	Gates firing.
Description	What the trigger is for.

The subscriber reads the event type from the message's EventType application property and expects a flat JSON object body. Every enabled trigger for that type whose condition holds starts one run. A redelivered message (same MessageId) never starts a second run, and an unknown event type or unreadable body is logged and completed rather than dead-lettered. A condition that fails at run time skips only that trigger.

The subscriber is off by default. Set ServiceBusTriggers:Enabled, the connection (ConnectionString, or FullyQualifiedNamespace with managed identity), Topic and Subscription. You can create and manage triggers with it off; they just don't fire. See the Service Bus triggers local development runbook, which also covers the separate review-outcome subscriber that resumes runs paused on a wait step.

Webhook triggers

A webhook trigger gives a workflow an authenticated HTTP endpoint for systems that can't publish to Service Bus. Manage them through api/webhooktriggers (create, update, enable, disable, delete, get, paged).

Field	Purpose
Workflow & agent	What runs, and the agent it runs as.
Authentication kind	Hmac or ClientCredentials (below).
Secret name / client id	The configured secret name for Hmac, or the allowed Authlink client for ClientCredentials.
Input mappings & required context keys	As for event triggers.
Condition	Optional JMESPath expression over the body.
Payload schema	Optional JSON Schema the body must satisfy.
Workflow version	Optional pin.

Callers deliver with POST /api/webhooks/{webhookTriggerId} and a JSON object body of at most 1 MiB.

• Hmac: the caller signs {timestamp}.{raw body} with HMAC-SHA256 and sends X-Agentfleet-Timestamp (Unix seconds) and X-Agentfleet-Signature: sha256=<hex>. The secret lives in configuration under WebhookTriggers:Secrets:<name> (at least 32 characters, from Key Vault), never on the trigger. A timestamp more than WebhookTriggers:TimestampToleranceSeconds (default 300) from the server clock is rejected, so a captured delivery cannot be replayed later.
• ClientCredentials: the caller sends Authorization: Bearer <token> from the client credentials grant, and the token's client must be the trigger's client id.

An optional Idempotency-Key header (up to 80 characters) makes retries safe: a repeated key returns the first delivery's run. The endpoint answers 202 with { workflowInstanceId, fired, alreadyAccepted } (fired: false when the condition did not hold), 400 for a body that fails the schema, mapping or condition, 401 when authentication fails, and 404 for an unknown or disabled trigger alike, so trigger ids cannot be probed. See the triggers runbook for a signing example.

Dead-letter fallback

A workflow can name a fallback workflow (PUT /api/workflows/fallback) that starts when one of its runs is dead-lettered, for example to notify someone or open a ticket. The fallback run receives deadLetteredWorkflowInstanceId, deadLetteredWorkflowId and failureReason as inputs, and runs as the fallback workflow's default agent (or else the failed run's agent). Each dead-lettered run starts at most one fallback, and a dead-lettered fallback never starts another.

Who started a run

Every run records what started it as trigger and triggerId, shown on the run's page, in the run summary API and in run events:

trigger	triggerId
Manual	null
Schedule	The schedule
Event	The event trigger
Webhook	The webhook trigger
Fallback	The dead-lettered run

Event-triggered runs act as the subscriber's system identity (ServiceBusTriggers:SystemUserId), and webhook runs as WebhookTriggers:SystemUserId, in the trigger's tenant. Both default to the platform identity.

Identity still applies

Automated runs are not privileged. A scheduled or triggered run executes under the same delegated-identity model as any other run: each step still performs a token exchange, scoped to that step's resource and tool. The difference is only in who initiates the run (a cron tick, an event or a webhook call instead of a person), not in what the run is allowed to do.

Related

• Runs: what a fired schedule or trigger produces.
• Run Inputs: the shape of the initial context they seed.
• REST API: the schedule and trigger endpoints.