AI agent runs

Chronos can start a published Gluesync AI agent on a schedule, from a Core Hub platform event, from an incoming webhook, or as a step in a chained event. The API task type is ai_agent_run.

This task type is planned for Chronos 0.2.5 and is currently unreleased.

What runs

An AI agent run action identifies a published agent by its required agent_alias. The action is not tied to a data pipeline, so pipeline_id can be omitted or empty.

At execution time, Chronos sends the assembled input to Core Hub:

POST /api/ai/v1/agents/{alias}/runs

The alias is URL-encoded. The Core Hub request body is:

{
  "input": {},
  "agentVersion": 3,
  "idempotencyKey": "ticket-123",
  "correlationId": "chronos:42:7:fire-123"
}

Only input is always present. Chronos includes agentVersion, idempotencyKey, and correlationId when their values are available.

When the action must wait for completion, Chronos polls GET /api/ai/v1/runs/{id} every second until the run reaches SUCCEEDED, FAILED, CANCELLED, or AMBIGUOUS, or reaches the 120-second timeout. The timeout and one-second poll interval are fixed constants, not environment variables.

Use AI agent run actions in:

  • Schedules — start an agent on a recurring daily or cron schedule.

  • Platform events — pass a Core Hub event payload into an agent.

  • Webhook-triggered events — pass a caller-supplied JSON body into an agent.

  • Chained events — place an agent run before or after other Chronos actions.

Build the agent input

The simplest action needs only task_type and agent_alias:

{
  "task_type": "ai_agent_run",
  "agent_alias": "agent/daily-report"
}

Use these optional fields to build a richer run:

  • prompt_template — prompt text that can contain allow-listed {{dotted.path}} tokens.

  • payload_allow_list — event-payload paths that templates may read.

  • agent_input — a JSON object merged into the run input; string values can contain the same tokens.

  • idempotency_key — an optional key or key template forwarded to Core Hub.

Chronos adds source: "chronos" to the input. It also adds the rendered prompt and a fields object containing the allow-listed scalar values found in the event payload.

Payload allow-list

Every token in prompt_template, string values inside agent_input, and idempotency_key must appear in payload_allow_list. Chronos rejects the action when a token is not allow-listed.

Allow-list entries are safe ASCII identifier paths separated by dots, for example data.ticketId or customer.region. Paths containing .., _, or a component that starts with are rejected.

Only strings, numbers, and booleans are interpolated. Objects, arrays, missing values, and null values are not copied into the prompt or fields. A missing or non-scalar template value renders as an empty string.

For example, given this event body:

{
  "data": {
    "ticketId": 123,
    "priority": "high",
    "privateNotes": ["not", "copied"]
  }
}

and this action:

{
  "task_type": "ai_agent_run",
  "agent_alias": "agent/ticket-triage",
  "prompt_template": "Triage ticket {{data.ticketId}} with {{data.priority}} priority",
  "payload_allow_list": [
    "data.ticketId",
    "data.priority"
  ],
  "agent_input": {
    "queue": "support",
    "externalId": "ticket-{{data.ticketId}}"
  },
  "idempotency_key": "ticket-{{data.ticketId}}"
}

Chronos submits an input equivalent to:

{
  "queue": "support",
  "externalId": "ticket-123",
  "prompt": "Triage ticket 123 with high priority",
  "fields": {
    "ticketId": 123,
    "priority": "high"
  },
  "source": "chronos"
}

The privateNotes value is not available because it is not allow-listed and is not a scalar.

Trigger payload size

The JSON body sent to a trigger flow’s fire endpoint is limited to 64 KiB. Chronos returns 413 Request Entity Too Large when the body exceeds the limit. The body must be a JSON object; an empty body is treated as an empty object.

Keep the payload focused on the scalar fields needed by the agent. The allow-list controls which fields enter the agent input, but it does not increase the fire-body limit.

Prevent AI run loops

AI agents can emit platform events whose names start with AI_RUN_ or gluesync.ai.run.. Feeding one of those events directly into another ai_agent_run action can create an automation loop.

Chronos refuses that combination by default. Set allow_ai_run_loop to true only when one follow-up agent run is intentional. Even with that setting, Chronos permits only one hop: a platform event whose correlation ID already starts with chronos: is refused.

The loop guard applies to AI run platform events. It does not change schedules, incoming webhook-triggered events, or ordinary non-AI platform events.

API fields

Field Required Description

task_type

Yes

Set to ai_agent_run.

agent_alias

Yes

Alias of a published AI agent. An empty alias is rejected.

agent_version

No

Published agent version. Chronos sends it to Core Hub as agentVersion.

pipeline_id

No

Optional for AI agent runs. Omit it or send an empty string.

prompt_template

No

Prompt containing allow-listed {{dotted.path}} tokens.

payload_allow_list

No

Payload paths available for interpolation. Defaults to an empty list.

agent_input

No

JSON object added to the agent run input. String values can contain allow-listed tokens.

idempotency_key

No

Core Hub idempotency key. It can contain allow-listed tokens.

allow_ai_run_loop

No

Allow the first AI run platform-event hop. Defaults to false; a second chronos: hop is always refused.

execution_mode

Chained events only

Use sync to wait for the run result or async to continue after Core Hub accepts the run.

Schedule an agent run

POST /api/jobs

{
  "name": "Daily operations summary",
  "task_type": "ai_agent_run",
  "cron_expression": "0 7 * * *",
  "agent_alias": "agent/daily-report",
  "agent_version": 3,
  "agent_input": {
    "audience": "operations"
  },
  "idempotency_key": "daily-operations-report",
  "enabled": true
}

See Schedules for daily and cron scheduling options.

Run an agent from an event

Add an ai_agent_run event to a platform-event or webhook-triggered flow. This example uses an incoming fire body to populate the prompt:

POST /api/triggers/

{
  "name": "ticket-triage",
  "enabled": true,
  "events": [
    {
      "task_type": "ai_agent_run",
      "agent_alias": "agent/ticket-triage",
      "prompt_template": "Triage ticket {{data.ticketId}}",
      "payload_allow_list": ["data.ticketId"],
      "idempotency_key": "ticket-{{data.ticketId}}"
    }
  ]
}

Fire the flow with its secret token and a JSON body:

curl -X POST http://chronos:8000/api/triggers/42/fire \
  -H "X-Trigger-Token: sk_Jd8fkQ29Xm5..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"ticketId":123}}'

For trigger URLs, token handling, platform events, and synchronous fire requests, see Events and Webhooks.

Add an agent run to a chain

Use the same AI agent fields in a schedule’s chained_events array. Choose sync when the next action depends on the agent completing successfully.

{
  "task_type": "ai_agent_run",
  "agent_alias": "agent/reconciliation-review",
  "prompt_template": "Review reconciliation run {{data.runId}}",
  "payload_allow_list": ["data.runId"],
  "execution_mode": "sync"
}

See Chained events for execution modes and ordering.

Troubleshooting

Symptom What to check

Action is rejected when saved

agent_alias is non-empty; every template token is in payload_allow_list; allow-list paths do not contain .., __, or private components.

Prompt value is empty

The path exists in the event payload, is allow-listed, and resolves to a string, number, or boolean.

Fire returns 413

The complete JSON request body is no larger than 64 KiB.

Platform-event action is refused as a loop

The event is not an AI_RUN_* / gluesync.ai.run.* event, or allow_ai_run_loop is enabled for the first hop. Events with a chronos: correlation are always refused.

Run fails or times out

The alias refers to a published agent; Core Hub can start the agent; the run reaches SUCCEEDED within 120 seconds when Chronos waits for completion.

Related documentation