Search docs.molo17.com

    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. It ships with Chronos 0.3.0 and Gluesync 2.3.

    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.